moodle_local_treestudyplan/classes/studentstudyplanservice.php

584 lines
19 KiB
PHP
Raw Normal View History

<?php
2023-08-24 23:02:41 +02:00
// 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/>.
/**
2023-08-27 23:27:07 +02:00
* Webservice class for retrieving student studyplans
2023-08-24 23:02:41 +02:00
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
namespace local_treestudyplan;
2023-08-25 12:04:27 +02:00
defined('MOODLE_INTERNAL') || die();
require_once($CFG->libdir.'/externallib.php');
use \local_treestudyplan\local\helpers\webservicehelper;
require_once($CFG->libdir.'/badgeslib.php');
2023-08-27 23:27:07 +02:00
/**
* Webservice class for retrieving student studyplans
*/
2023-08-25 10:41:56 +02:00
class studentstudyplanservice extends \external_api {
2023-08-27 23:27:07 +02:00
/**
* Capability required to view studyplans of other users
* @var string
*/
const CAP_VIEWOTHER = "local/treestudyplan:viewuserreports";
/************************
* *
* list_user_studyplans *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function list_user_studyplans
*/
2023-08-28 08:51:52 +02:00
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),
]);
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function list_user_studyplans
*/
2023-08-28 11:26:14 +02:00
public static function list_user_studyplans_returns() : \external_description {
return new \external_multiple_structure(
studyplan::simple_structure()
);
}
2023-08-27 23:27:07 +02:00
/**
* 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);
2023-08-24 23:02:41 +02:00
foreach ($studyplans as $studyplan) {
2023-08-25 09:44:34 +02:00
// Only include studyplans in the context the user has permissions for.
2023-08-24 23:02:41 +02:00
if (webservicehelper::has_capabilities(self::CAP_VIEWOTHER, $studyplan->context(), false)) {
$list[] = $studyplan->simple_model($userid);
}
}
return $list;
}
/************************
* *
* get_user_studyplan *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function get_user_studyplan
2023-08-27 21:57:21 +02:00
*/
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'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function get_user_studyplan
2023-08-27 21:57:21 +02:00
*/
public static function get_user_studyplan_returns() : \external_description {
return studyplan::user_structure();
}
2023-08-27 23:27:07 +02:00
/**
* Get a specific studyplan for a given user
2023-08-27 23:27:07 +02:00
* @param int $userid ID of user to check specific info for
* @param int $studyplanid ID of studyplan to view
2023-08-27 23:27:07 +02:00
* @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->exist_for_user($userid)) {
return $studyplan->user_model($userid);
} else {
return null;
}
}
/************************
* *
* get_user_page *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function get_user_page
2023-08-27 21:57:21 +02:00
*/
public static function get_user_page_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"userid" => new \external_value(PARAM_INT, 'id of user'),
"pageid" => new \external_value(PARAM_INT, 'id of specific studyplan to provide'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function get_user_page
2023-08-27 21:57:21 +02:00
*/
public static function get_user_page_returns() : \external_description {
return studyplan::user_structure();
}
2023-08-27 23:27:07 +02:00
/**
* Get a specific studyplan page for a given user
2023-08-27 23:27:07 +02:00
* @param int $userid ID of user to check specific info for
* @param int $pageid ID of studyplan to view
2023-08-27 23:27:07 +02:00
* @return array
*/
public static function get_user_page($userid, $pageid) {
global $CFG, $DB;
$studyplan = studyplan::find_by_id($pageid);
2023-08-24 23:02:41 +02:00
webservicehelper::require_capabilities(self::CAP_VIEWOTHER, $studyplan->context());
if ($studyplan->exist_for_user($userid)) {
return $studyplan->user_model($userid);
2023-08-24 23:09:20 +02:00
} else {
return null;
}
}
/****************************
* *
* list_invited_studyplan *
* *
****************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function list_invited_studyplan
2023-08-27 21:57:21 +02:00
*/
public static function list_invited_studyplans_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"invitekey" => new \external_value(PARAM_RAW, 'invite key'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function list_invited_studyplan
2023-08-27 21:57:21 +02:00
*/
public static function list_invited_studyplans_returns() : \external_description {
return new \external_multiple_structure(
studyplan::simple_structure()
);
}
2023-08-27 23:27:07 +02:00
/**
* List available studyplans based on invite key
2023-08-27 23:27:07 +02:00
* @param int $invitekey Invitation key
* @return array
*/
public static function list_invited_studyplans($invitekey) {
global $DB;
2023-07-04 23:38:08 +02:00
2023-08-25 11:52:05 +02:00
$invite = $DB->get_record_select(
"local_treestudyplan_invit",
$DB->sql_compare_text("invitekey"). " = " . $DB->sql_compare_text(":invitekey"),
['invitekey' => $invitekey]
);
2023-08-24 23:02:41 +02:00
if (empty($invite)) {
return [];
}
2023-11-23 07:44:04 +01:00
// Do not validate the context in this instance to avoid requiring logins when this is not wanted
2023-07-04 23:38:08 +02:00
$userid = $invite->user_id;
$list = [];
$studyplans = studyplan::find_for_user($userid);
2023-08-24 23:02:41 +02:00
foreach ($studyplans as $studyplan) {
2023-11-13 22:18:28 +01:00
$list[] = $studyplan->simple_model($userid);
}
return $list;
}
/****************************
* *
* 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'),
"studyplanid" => new \external_value(PARAM_INT, 'studyplan_id'),
] );
}
/**
* Return value description for webservice function get_invited_studyplan
*/
public static function get_invited_studyplan_returns() : \external_description {
return studyplan::user_structure();
}
/**
* Get studyplan based on invite key and studyplan id
* @param string $invitekey Invitation key
* @param int $studyplanid ID of the studyplan to retrieve
* @return array
*/
public static function get_invited_studyplan($invitekey,$studyplanid) {
global $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 [];
}
2023-11-23 07:44:04 +01:00
// Do not validate the context in this instance to avoid requiring logins when this is not wanted
$studyplan = studyplan::find_by_id($studyplanid);
$userid = $invite->user_id;
if ($studyplan->exist_for_user($userid)) {
return $studyplan->user_model($userid);
} else {
throw new \moodle_exception("Invitation's user is not linked to this studyplan");
}
}
/****************************
* *
* get_invited_page *
* *
****************************/
/**
* Parameter description for webservice function get_invited_studyplan
*/
public static function get_invited_page_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"invitekey" => new \external_value(PARAM_RAW, 'invite key'),
"pageid" => new \external_value(PARAM_INT, 'studyplan page id'),
] );
}
/**
* Return value description for webservice function get_invited_studyplan
*/
public static function get_invited_page_returns() : \external_description {
return studyplanpage::user_structure();
}
/**
* Get studyplan based on invite key and studyplan id
* @param string $invitekey Invitation key
* @param int $pageid ID of the studyplan to retrieve
* @return array
*/
public static function get_invited_page($invitekey,$pageid) {
global $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 [];
}
2023-11-23 07:44:04 +01:00
// Do not validate the context in this instance to avoid requiring logins when this is not wanted
$page = studyplanpage::find_by_id($pageid);
$studyplan = $page->studyplan();
$userid = $invite->user_id;
if ($studyplan->exist_for_user($userid)) {
return $page->user_model($userid);
} else {
throw new \moodle_exception("Invitation's user is not linked to this studyplan");
}
}
/************************
* *
* list_own_studyplans *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function list_own_studyplans
*/
2023-08-28 08:51:52 +02:00
public static function list_own_studyplans_parameters() : \external_function_parameters {
return new \external_function_parameters([]);
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function list_own_studyplans
*/
2023-08-28 11:26:14 +02:00
public static function list_own_studyplans_returns() : \external_description {
return new \external_multiple_structure(
studyplan::simple_structure()
);
}
2023-08-27 23:27:07 +02:00
/**
* 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);
2023-08-24 23:02:41 +02:00
foreach ($studyplans as $studyplan) {
$list[] = $studyplan->simple_model($userid);
}
return $list;
}
/************************
* *
* get_own_studyplan *
* *
************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function get_own_studyplan
*/
2023-08-28 08:51:52 +02:00
public static function get_own_studyplan_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"studyplanid" => new \external_value(PARAM_INT, 'id of studyplan to retrieve'),
] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function get_own_studyplan
*/
2023-08-28 11:26:14 +02:00
public static function get_own_studyplan_returns() : \external_description {
return studyplan::user_structure();
}
2023-08-27 23:27:07 +02:00
/**
* Get a studyplans for the current user
* @param int $studyplanid Id of specific studyplan
2023-08-27 23:27:07 +02:00
* @return array
*/
public static function get_own_studyplan($studyplanid) {
2023-07-04 23:38:08 +02:00
global $USER;
// Validate this call in the system context.
\external_api::validate_context(\context_system::instance());
$userid = $USER->id;
$studyplan = studyplan::find_by_id($studyplanid);
if ($studyplan->exist_for_user($userid)) {
return debug::dump($studyplan->user_model($userid));
2023-08-24 23:09:20 +02:00
} else {
throw new \moodle_exception("You do not have access to this studyplan");
}
}
/************************
* *
* get_own_page *
* *
************************/
/**
* Parameter description for webservice function get_own_page
*/
public static function get_own_page_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"pageid" => new \external_value(PARAM_INT, 'id of studyplan to retrieve'),
] );
}
/**
* Return value description for webservice function get_own_page
*/
public static function get_own_page_returns() : \external_description {
return studyplan::user_structure();
}
/**
* Get studyplanpage for current user
* @param int $pagid ID of specific studyplan page
* @return array
*/
public static function get_own_page($pageid) {
global $USER;
// Validate this call in the system context.
\external_api::validate_context(\context_system::instance());
$userid = $USER->id;
$page = studyplanpage::find_by_id($pageid);
$studyplan = $page->studyplan();
if ($studyplan->exist_for_user($userid)) {
return $page->user_model($userid);
} else {
throw new \moodle_exception("You do not have access to this studyplan page");
}
}
/***************************
* *
* list_teaching_studyplans *
* *
***************************/
2023-08-27 21:57:21 +02:00
/**
* Parameter description for webservice function list_teaching_studyplans
2023-08-27 21:57:21 +02:00
*/
public static function list_teaching_studyplans_parameters() : \external_function_parameters {
return new \external_function_parameters( [] );
}
2023-08-27 21:57:21 +02:00
/**
* Return value description for webservice function list_teaching_studyplans
2023-08-27 21:57:21 +02:00
*/
public static function list_teaching_studyplans_returns() : \external_description {
return new \external_multiple_structure(
studyplan::simple_structure()
);
}
2023-08-27 23:27:07 +02:00
/**
* Get all or one studyplan the current user is teaching in
* @param int $id Optional specific id of studyplan
* @return array
*/
public static function list_teaching_studyplans() {
global $USER;
$userid = $USER->id;
2023-08-24 23:02:41 +02:00
\external_api::validate_context(\context_system::instance());
$studyplans = teachingfinder::list_my_plans();
$list = [];
foreach ($studyplans as $studyplan) {
$list[] = $studyplan->simple_model($userid);
}
return $list;
}
/***************************
* *
* get_teaching_studyplan *
* *
***************************/
/**
* Parameter description for webservice function get_teaching_studyplan
*/
public static function get_teaching_studyplan_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"studyplanid" => new \external_value(PARAM_INT, 'id of specific studyplan to provide', VALUE_DEFAULT),
] );
}
/**
* Return value description for webservice function get_teaching_studyplan
*/
public static function get_teaching_studyplan_returns() : \external_description {
return studyplan::editor_structure();
}
/**
* Get all or one studyplan the current user is teaching in
* @param int $studyplanid ID of studyplan to retrieve
* @return array
*/
public static function get_teaching_studyplan($studyplanid) {
global $USER;
$userid = $USER->id;
\external_api::validate_context(\context_system::instance());
$studyplan = studyplan::find_by_id($studyplanid);
if (teachingfinder::am_teaching_studyplan($studyplan)) {
return $studyplan->editor_model();
2023-08-24 23:09:20 +02:00
} else {
throw new \moodle_exception("You are not teaching in this studyplan");
}
}
/***************************
* *
* get_teaching_page *
* *
***************************/
/**
* Parameter description for webservice function get_teaching_page
*/
public static function get_teaching_page_parameters() : \external_function_parameters {
return new \external_function_parameters( [
"pageid" => new \external_value(PARAM_INT, 'id of specific studyplan page to provide', VALUE_DEFAULT),
] );
}
/**
* Return value description for webservice function get_teaching_page
*/
public static function get_teaching_page_returns() : \external_description {
return studyplanpage::editor_structure();
}
/**
* Get all or one studyplan the current user is teaching in
* @param int $studyplanid ID of studyplan to retrieve
* @return array
*/
public static function get_teaching_page($pageid) {
global $USER;
$userid = $USER->id;
\external_api::validate_context(\context_system::instance());
$page = studyplanpage::find_by_id($pageid);
$studyplan = $page->studyplan();
if (teachingfinder::am_teaching_studyplan($studyplan)) {
return $page->editor_model();
} else {
throw new \moodle_exception("You are not teaching in this studyplan");
}
}
2023-08-25 11:52:05 +02:00
}