moodle_local_treestudyplan/classes/studentstudyplanservice.php

<?php
// This file is part of the Studyplan plugin for Moodle
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <https://www.gnu.org/licenses/>.
/**
 * Webservice class for retrieving student studyplans
 * @package    local_treestudyplan
 * @copyright  2023 P.M. Kuipers
 * @license    https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

namespace local_treestudyplan;
defined('MOODLE_INTERNAL') || die();

require_once($CFG->libdir.'/externallib.php');

use \local_treestudyplan\local\helpers\webservicehelper;

require_once($CFG->libdir.'/badgeslib.php');
/**
 * Webservice class for retrieving student studyplans
 */
class studentstudyplanservice extends \external_api {
    /**
     * Capability required to view studyplans of other users
     * @var string
     */
    const CAP_VIEWOTHER = "local/treestudyplan:viewuserreports";
    /************************
     *                      *
     * list_user_studyplans *
     *                      *
     ************************/

    /**
     * Parameter description for webservice function list_user_studyplans
     */
    public static function list_user_studyplans_parameters() : \external_function_parameters {
        return new \external_function_parameters([
            "userid" => new \external_value(PARAM_INT, 'id of student', VALUE_DEFAULT),
        ]);
    }

    /**
     * Return value description for webservice function list_user_studyplans
     */
    public static function list_user_studyplans_returns() : \external_description  {
        return new \external_multiple_structure(
            studyplan::simple_structure()
        );
    }

    /**
     * Return overview of the studyplans for a specific user
     * @param int $userid ID of user to check specific info for
     * @return array
     */
    public static function list_user_studyplans($userid) {
        global $CFG, $DB;

        $list = [];
        $studyplans = studyplan::find_for_user($userid);
        foreach ($studyplans as $studyplan) {
            // Only include studyplans in the context the user has permissions for.
            if (webservicehelper::has_capabilities(self::CAP_VIEWOTHER, $studyplan->context(), false)) {
                $list[] = $studyplan->simple_model();
            }
        }
        return $list;
    }

    /************************
     *                      *
     * get_user_studyplans  *
     *                      *
     ************************/

    /**
     * Parameter description for webservice function get_user_studyplans
     */
    public static function get_user_studyplans_parameters() : \external_function_parameters {
        return new \external_function_parameters( [
            "userid" => new \external_value(PARAM_INT, 'id of user'),
        ] );
    }

    /**
     * Return value description for webservice function get_user_studyplans
     */
    public static function get_user_studyplans_returns() : \external_description  {
        return new \external_multiple_structure(
            studyplan::user_structure()
        );
    }

    /**
     * Get the full studyplans for a specific user
     * @param int $userid ID of user to check specific info for
     * @return array
     */
    public static function get_user_studyplans($userid) {
        global $CFG, $DB;

        $studyplans = studyplan::find_for_user($userid);

        $map = [];
        foreach ($studyplans as $studyplan) {
            // Only include studyplans in the context the user has permissions for.
            if (webservicehelper::has_capabilities(self::CAP_VIEWOTHER, $studyplan->context(), false)) {
                $map[] = $studyplan->user_model($userid);
            }
        }

        return $map;
    }

    /************************
     *                      *
     * get_user_studyplan   *
     *                      *
     ************************/

    /**
     * Parameter description for webservice function get_user_studyplan
     */
    public static function get_user_studyplan_parameters() : \external_function_parameters {
        return new \external_function_parameters( [
            "userid" => new \external_value(PARAM_INT, 'id of user'),
            "studyplanid" => new \external_value(PARAM_INT, 'id of specific studyplan to provide'),
        ] );
    }

    /**
     * Return value description for webservice function get_user_studyplan
     */
    public static function get_user_studyplan_returns() : \external_description  {
        return studyplan::user_structure();
    }

    /**
     * Get a specific studyplan for a given user
     * @param int $userid ID of user to check specific info for
     * @param int $studyplanid ID of studyplan to view
     * @return array
     */
    public static function get_user_studyplan($userid, $studyplanid) {
        global $CFG, $DB;

        $studyplan = studyplan::find_by_id($studyplanid);
        webservicehelper::require_capabilities(self::CAP_VIEWOTHER, $studyplan->context());

        if ($studyplan->has_linked_user($userid)) {
            return $studyplan->user_model($userid);
        } else {
            return null;
        }
    }

    /****************************
     *                          *
     * get_invited_studyplan    *
     *                          *
     ****************************/

    /**
     * Parameter description for webservice function get_invited_studyplan
     */
    public static function get_invited_studyplan_parameters() : \external_function_parameters {
        return new \external_function_parameters( [
            "invitekey" => new \external_value(PARAM_RAW, 'invite key'),
        ] );
    }

    /**
     * Return value description for webservice function get_invited_studyplan
     */
    public static function get_invited_studyplan_returns() : \external_description  {
        return new \external_multiple_structure(
            studyplan::user_structure()
        );
    }

    /**
     * Get studyplan based on invite key
     * @param int $invitekey Invitation key
     * @return array
     */
    public static function get_invited_studyplan($invitekey) {
        global $CFG, $DB;

        $invite = $DB->get_record_select(
                        "local_treestudyplan_invit",
                        $DB->sql_compare_text("invitekey"). " = " . $DB->sql_compare_text(":invitekey"),
                        ['invitekey' => $invitekey]
                    );

        if (empty($invite)) {
            return [];
        }

        // Validate context now.
        \external_api::validate_context(\context_system::instance());

        $userid = $invite->user_id;

        $map = [];
        $studyplans = studyplan::find_for_user($userid);
        foreach ($studyplans as $studyplan) {
            $map[] = $studyplan->user_model($userid);
        }
        return $map;
    }

    /************************
     *                      *
     * list_own_studyplans *
     *                      *
     ************************/

    /**
     * Parameter description for webservice function list_own_studyplans
     */
    public static function list_own_studyplans_parameters() : \external_function_parameters {
        return new \external_function_parameters([]);
    }

    /**
     * Return value description for webservice function list_own_studyplans
     */
    public static function list_own_studyplans_returns() : \external_description  {
        return new \external_multiple_structure(
            studyplan::simple_structure()
        );
    }

    /**
     * Return overview of the studyplans the current user is linked to
     * @return array
     */
    public static function list_own_studyplans() {
        global $CFG, $DB, $USER;
        $userid = $USER->id;

        $list = [];
        $studyplans = studyplan::find_for_user($userid);
        foreach ($studyplans as $studyplan) {
            $list[] = $studyplan->simple_model();
        }
        return $list;
    }

    /************************
     *                      *
     * get_own_studyplan   *
     *                      *
     ************************/

    /**
     * Parameter description for webservice function get_own_studyplan
     */
    public static function get_own_studyplan_parameters() : \external_function_parameters {
        return new \external_function_parameters( [
            "id" => new \external_value(PARAM_INT, 'id of specific studyplan to provide', VALUE_DEFAULT),
        ] );
    }

    /**
     * Return value description for webservice function get_own_studyplan
     */
    public static function get_own_studyplan_returns() : \external_description  {
        return new \external_multiple_structure(
            studyplan::user_structure()
        );
    }

    /**
     * Get all studyplans for current user or a specific one
     * @param int $id Optional id of specific studyplan
     * @return array
     */
    public static function get_own_studyplan($id = null) {
        global $USER;

        // Validate this call in the system context.
        \external_api::validate_context(\context_system::instance());

        $userid = $USER->id;

        $studyplans = studyplan::find_for_user($userid);

        if (isset($id) && $id > 0) {
            if (isset($studyplans[$id])) {
                $studyplan = $studyplans[$id];
                return [$studyplan->user_model($userid)];
            } else {
                return [];
            }
        } else {
            $map = [];
            foreach ($studyplans as $studyplan) {
                $map[] = $studyplan->user_model($userid);
            }
            return $map;
        }
    }

    /***************************
     *                         *
     * get_teaching_studyplans *
     *                         *
     ***************************/

    /**
     * Parameter description for webservice function get_teaching_studyplans
     */
    public static function get_teaching_studyplans_parameters() : \external_function_parameters {
        return new \external_function_parameters( [
            "id" => new \external_value(PARAM_INT, 'id of specific studyplan to provide', VALUE_DEFAULT),
        ] );
    }

    /**
     * Return value description for webservice function get_teaching_studyplans
     */
    public static function get_teaching_studyplans_returns() : \external_description  {
        return new \external_multiple_structure(
            studyplan::editor_structure()
        );
    }

    /**
     * Get all or one studyplan the current user is teaching in
     * @param int $id Optional specific id of studyplan
     * @return array
     */
    public static function get_teaching_studyplans($id = null) {
        global $CFG, $DB, $USER;
        $userid = $USER->id;

        \external_api::validate_context(\context_system::instance());
        $studyplans = teachingfinder::list_my_plans();

        if (isset($id) && $id > 0) {
            if (isset($studyplans[$id])) {
                $studyplan = $studyplans[$id];
                return [$studyplan->editor_model($userid)];
            } else {
                return [];
            }
        } else {
            $map = [];
            foreach ($studyplans as $studyplan) {
                $map[] = $studyplan->editor_model($userid);
            }
            return $map;
        }
    }
}