From 701f4d7363a21c7af492b6b3dab5486b6b052bbc Mon Sep 17 00:00:00 2001 From: PMKuipers Date: Mon, 28 Aug 2023 08:51:52 +0200 Subject: [PATCH] PHPDoc documentation --- classes/aggregator.php | 11 +- classes/associationservice.php | 64 ++++------ classes/badgeinfo.php | 6 +- classes/completion.php | 3 +- classes/contextinfo.php | 4 +- classes/corecompletioninfo.php | 24 +--- classes/courseinfo.php | 9 +- classes/courseservice.php | 42 ++---- classes/gradeinfo.php | 12 +- classes/period.php | 82 ++++++++++-- classes/studentstudyplanservice.php | 42 ++---- classes/studyitem.php | 9 +- classes/studyitemconnection.php | 7 +- classes/studyline.php | 7 +- classes/studyplan.php | 13 +- classes/studyplanpage.php | 27 ++-- classes/studyplanservice.php | 192 ++++++++++------------------ classes/success.php | 9 +- 18 files changed, 228 insertions(+), 335 deletions(-) diff --git a/classes/aggregator.php b/classes/aggregator.php index a079aec..01f4662 100644 --- a/classes/aggregator.php +++ b/classes/aggregator.php @@ -76,10 +76,9 @@ abstract class aggregator { * Create a new aggregatior object based on the specified method * @param mixed $method Aggregation method * @param mixed $configstr Configuration string for aggregator - * @return self Aggregator * @throws ValueError If method is not found */ - public static function create($method, $configstr) { + public static function create($method, $configstr) : self { if (self::supported($method)) { $agclass = self::aggregator_name($method); return new $agclass($configstr); @@ -93,9 +92,8 @@ abstract class aggregator { * but return a default aggregator if the method is not found * @param mixed $method Aggregation method * @param mixed $configstr Configuration string for aggregator - * @return self Aggregator */ - public static function create_or_default($method, $configstr) { + public static function create_or_default($method, $configstr) : self { try { return self::create($method, $configstr); } catch (\ValueError $x) { @@ -194,9 +192,8 @@ abstract class aggregator { /** * Webservice structure for basic aggregator info * @param int $value Webservice requirement constant - * @return \external_description Webservice output structure */ - public static function basic_structure($value = VALUE_REQUIRED) { + public static function basic_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "useRequiredGrades" => new \external_value(PARAM_BOOL, 'id of studyplan'), "useItemConditions" => new \external_value(PARAM_BOOL, 'name of studyplan'), @@ -219,7 +216,7 @@ abstract class aggregator { * @param int $value Webservice requirement constant * @return mixed Webservice output structure */ - public static function list_structure($value = VALUE_REQUIRED) { + public static function list_structure($value = VALUE_REQUIRED) : \external_description { return new \external_multiple_structure(new \external_single_structure([ "id" => new \external_value(PARAM_TEXT, 'id of aggregator'), "name" => new \external_value(PARAM_TEXT, 'name of agregator'), diff --git a/classes/associationservice.php b/classes/associationservice.php index 9246247..d201361 100644 --- a/classes/associationservice.php +++ b/classes/associationservice.php @@ -31,7 +31,7 @@ class associationservice extends \external_api { const CAP_EDIT = "local/treestudyplan:editstudyplan"; const CAP_VIEW = "local/treestudyplan:viewuserreports"; - public static function user_structure() { + public static function user_structure() : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'user id'), "username" => new \external_value(PARAM_TEXT, 'username'), @@ -53,7 +53,7 @@ class associationservice extends \external_api { ]; } - public static function cohort_structure() { + public static function cohort_structure() : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'cohort id'), "name" => new \external_value(PARAM_TEXT, 'name'), @@ -102,9 +102,8 @@ class associationservice extends \external_api { /** * Parameter description for webservice function list_cohort - * @return \external_function_parameters */ - public static function list_cohort_parameters() { + public static function list_cohort_parameters() : \external_function_parameters { return new \external_function_parameters( [ 'like' => new \external_value(PARAM_TEXT, 'search text', VALUE_OPTIONAL), 'exclude_id' => new \external_value(PARAM_INT, 'exclude members of this studyplan', VALUE_OPTIONAL), @@ -114,9 +113,8 @@ class associationservice extends \external_api { /** * Return value description for webservice function list_cohort - * @return \external_description */ - public static function list_cohort_returns() { + public static function list_cohort_returns() : \external_description { return new \external_multiple_structure(self::cohort_structure()); } @@ -156,9 +154,8 @@ class associationservice extends \external_api { /** * Parameter description for webservice function find_user - * @return \external_function_parameters */ - public static function find_user_parameters() { + public static function find_user_parameters() : \external_function_parameters { return new \external_function_parameters( [ 'like' => new \external_value(PARAM_TEXT, 'search text'), 'exclude_id' => new \external_value(PARAM_INT, 'exclude members of this studyplan', VALUE_OPTIONAL), @@ -168,9 +165,8 @@ class associationservice extends \external_api { /** * Return value description for webservice function find_user - * @return \external_description */ - public static function find_user_returns() { + public static function find_user_returns() : \external_description { return new \external_multiple_structure(self::user_structure()); } @@ -207,9 +203,8 @@ class associationservice extends \external_api { /** * Parameter description for webservice function connect_cohort - * @return \external_function_parameters */ - public static function connect_cohort_parameters() { + public static function connect_cohort_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), "cohort_id" => new \external_value(PARAM_INT, 'id of cohort to link', VALUE_OPTIONAL), @@ -218,9 +213,8 @@ class associationservice extends \external_api { /** * Return value description for webservice function connect_cohort - * @return \external_description */ - public static function connect_cohort_returns() { + public static function connect_cohort_returns() : \external_description { return new \external_single_structure([ "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'), "msg" => new \external_value(PARAM_TEXT, 'message'), @@ -251,9 +245,8 @@ class associationservice extends \external_api { /** * Parameter description for webservice function disconnect_cohort - * @return \external_function_parameters */ - public static function disconnect_cohort_parameters() { + public static function disconnect_cohort_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), "cohort_id" => new \external_value(PARAM_INT, 'id of cohort to link', VALUE_OPTIONAL), @@ -262,9 +255,8 @@ class associationservice extends \external_api { /** * Return value description for webservice function disconnect_cohort - * @return \external_description */ - public static function disconnect_cohort_returns() { + public static function disconnect_cohort_returns() : \external_description { return new \external_single_structure([ "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'), "msg" => new \external_value(PARAM_TEXT, 'message'), @@ -295,9 +287,8 @@ class associationservice extends \external_api { /** * Parameter description for webservice function connect_user - * @return \external_function_parameters */ - public static function connect_user_parameters() { + public static function connect_user_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), "user_id" => new \external_value(PARAM_INT, 'id of user to link', VALUE_OPTIONAL), @@ -306,9 +297,8 @@ class associationservice extends \external_api { /** * Return value description for webservice function connect_user - * @return \external_description */ - public static function connect_user_returns() { + public static function connect_user_returns() : \external_description { return new \external_single_structure([ "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'), "msg" => new \external_value(PARAM_TEXT, 'message'), @@ -338,9 +328,8 @@ class associationservice extends \external_api { /** * Parameter description for webservice function disconnect_user - * @return \external_function_parameters */ - public static function disconnect_user_parameters() { + public static function disconnect_user_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), "user_id" => new \external_value(PARAM_INT, 'id of user to link', VALUE_OPTIONAL), @@ -349,9 +338,8 @@ class associationservice extends \external_api { /** * Return value description for webservice function disconnect_user - * @return \external_description */ - public static function disconnect_user_returns() { + public static function disconnect_user_returns() : \external_description { return new \external_single_structure([ "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'), "msg" => new \external_value(PARAM_TEXT, 'message'), @@ -380,9 +368,8 @@ class associationservice extends \external_api { /** * Parameter description for webservice function associated_users - * @return \external_function_parameters */ - public static function associated_users_parameters() { + public static function associated_users_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), ] ); @@ -390,9 +377,8 @@ class associationservice extends \external_api { /** * Return value description for webservice function associated_users - * @return \external_description */ - public static function associated_users_returns() { + public static function associated_users_returns() : \external_description { return new \external_multiple_structure(self::user_structure()); } @@ -417,9 +403,8 @@ class associationservice extends \external_api { /** * Parameter description for webservice function associated_cohorts - * @return \external_function_parameters */ - public static function associated_cohorts_parameters() { + public static function associated_cohorts_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), ] ); @@ -427,9 +412,8 @@ class associationservice extends \external_api { /** * Return value description for webservice function associated_cohorts - * @return \external_description */ - public static function associated_cohorts_returns() { + public static function associated_cohorts_returns() : \external_description { return new \external_multiple_structure(self::cohort_structure()); } @@ -452,9 +436,8 @@ class associationservice extends \external_api { /** * Parameter description for webservice function all_associated - * @return \external_function_parameters */ - public static function all_associated_parameters() { + public static function all_associated_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), ] ); @@ -462,9 +445,8 @@ class associationservice extends \external_api { /** * Return value description for webservice function all_associated - * @return \external_description */ - public static function all_associated_returns() { + public static function all_associated_returns() : \external_description { return new \external_multiple_structure(self::user_structure()); } @@ -517,9 +499,8 @@ class associationservice extends \external_api { /** * Parameter description for webservice function cascade_cohortsync - * @return \external_function_parameters */ - public static function cascade_cohortsync_parameters() { + public static function cascade_cohortsync_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan', VALUE_OPTIONAL), ] ); @@ -527,9 +508,8 @@ class associationservice extends \external_api { /** * Return value description for webservice function cascade_cohortsync - * @return \external_description */ - public static function cascade_cohortsync_returns() { + public static function cascade_cohortsync_returns() : \external_description { return success::structure(); } diff --git a/classes/badgeinfo.php b/classes/badgeinfo.php index 5c1834d..f03f867 100644 --- a/classes/badgeinfo.php +++ b/classes/badgeinfo.php @@ -100,9 +100,8 @@ class badgeinfo { /** * Webservice structure for editor info * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function editor_structure($value = VALUE_REQUIRED) { + public static function editor_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of badge'), "infolink" => new \external_value(PARAM_TEXT, 'badge issue information link', VALUE_OPTIONAL), @@ -161,9 +160,8 @@ class badgeinfo { /** * Webservice structure for userinfo * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function user_structure($value = VALUE_REQUIRED) { + public static function user_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of badge'), "infolink" => new \external_value(PARAM_TEXT, 'badge issue information link', VALUE_OPTIONAL), diff --git a/classes/completion.php b/classes/completion.php index 6c2254c..0094819 100644 --- a/classes/completion.php +++ b/classes/completion.php @@ -74,9 +74,8 @@ class completion { /** * Webservice structure for basic info * @param int $value Webservice requirement constant - * @return \external_description Webservice output structure */ - public static function structure($value = VALUE_REQUIRED) { + public static function structure($value = VALUE_REQUIRED) : \external_description { return new \external_value( PARAM_TEXT, 'completion state (failed|incomplete|pending|progress|completed|good|excellent)', $value); diff --git a/classes/contextinfo.php b/classes/contextinfo.php index 9f42535..84a79a4 100644 --- a/classes/contextinfo.php +++ b/classes/contextinfo.php @@ -41,9 +41,8 @@ class contextinfo { /** * Describe the result for the webservice model * @param int $value Webservice requirement constant - * @return \external_description Webservice output structure */ - public static function structure($value = VALUE_REQUIRED) { + public static function structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "name" => new \external_value(PARAM_TEXT, 'context name'), "shortname" => new \external_value(PARAM_TEXT, 'context short name'), @@ -77,7 +76,6 @@ class contextinfo { /** * Make new Contextinfo for context id * @param int $contextid Context id - * @return self Contextinfo based on context id */ public static function by_id($contextid): self { return new self(self::context_by_id($contextid)); diff --git a/classes/corecompletioninfo.php b/classes/corecompletioninfo.php index 91ca216..d9ec7c8 100644 --- a/classes/corecompletioninfo.php +++ b/classes/corecompletioninfo.php @@ -121,9 +121,8 @@ class corecompletioninfo { /** * Webservice editor structure for completion_item * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function completion_item_editor_structure($value = VALUE_REQUIRED) { + public static function completion_item_editor_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'criteria id', VALUE_OPTIONAL), "title" => new \external_value(PARAM_TEXT, 'name of subitem', VALUE_OPTIONAL), @@ -141,9 +140,8 @@ class corecompletioninfo { /** * Webservice editor structure for completion_type * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function completion_type_editor_structure($value = VALUE_REQUIRED) { + public static function completion_type_editor_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "items" => new \external_multiple_structure(self::completion_item_editor_structure(), 'subitems', VALUE_OPTIONAL), "title" => new \external_value(PARAM_TEXT, 'optional title', VALUE_OPTIONAL), @@ -156,14 +154,12 @@ class corecompletioninfo { /** * Webservice editor structure for course completion * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ /** * Webservice structure for editor info * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function editor_structure($value = VALUE_REQUIRED) { + public static function editor_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "conditions" => new \external_multiple_structure(self::completion_type_editor_structure(), 'completion conditions'), "aggregation" => new \external_value(PARAM_TEXT, 'completion aggregation ["all", "any"]'), @@ -174,9 +170,8 @@ class corecompletioninfo { /** * Webservice user view structure for completion_item * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function completion_item_user_structure($value = VALUE_REQUIRED) { + public static function completion_item_user_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of completion', VALUE_OPTIONAL), "title" => new \external_value(PARAM_TEXT, 'name of subitem', VALUE_OPTIONAL), @@ -200,9 +195,8 @@ class corecompletioninfo { /** * Webservice user view structure for completion_type * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function completion_type_user_structure($value = VALUE_REQUIRED) { + public static function completion_type_user_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "items" => new \external_multiple_structure(self::completion_item_user_structure(), 'subitems', VALUE_OPTIONAL), "title" => new \external_value(PARAM_TEXT, 'optional title', VALUE_OPTIONAL), @@ -217,17 +211,11 @@ class corecompletioninfo { ], 'completion type', $value); } - /** - * Webservice user view structure for course completion - * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure - */ /** * Webservice structure for userinfo * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function user_structure($value = VALUE_REQUIRED) { + public static function user_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "progress" => new \external_value(PARAM_INT, 'completed sub-conditions'), "enabled" => new \external_value(PARAM_BOOL, "whether completion is enabled here"), diff --git a/classes/courseinfo.php b/classes/courseinfo.php index cb97584..9069a2d 100644 --- a/classes/courseinfo.php +++ b/classes/courseinfo.php @@ -236,9 +236,8 @@ class courseinfo { /** * Webservice structure for basic info * @param int $value Webservice requirement constant - * @return \external_description Webservice output structure */ - public static function simple_structure($value = VALUE_REQUIRED) { + public static function simple_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'linked course id'), "fullname" => new \external_value(PARAM_TEXT, 'linked course name'), @@ -268,9 +267,8 @@ class courseinfo { /** * Webservice structure for editor info * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function editor_structure($value = VALUE_REQUIRED) { + public static function editor_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'linked course id'), "fullname" => new \external_value(PARAM_TEXT, 'linked course name'), @@ -337,9 +335,8 @@ class courseinfo { /** * Webservice structure for userinfo * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function user_structure($value = VALUE_REQUIRED) { + public static function user_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'linked course id'), "fullname" => new \external_value(PARAM_TEXT, 'linked course name'), diff --git a/classes/courseservice.php b/classes/courseservice.php index a1c0ef1..ab75763 100644 --- a/classes/courseservice.php +++ b/classes/courseservice.php @@ -50,9 +50,8 @@ class courseservice extends \external_api { /** * Return value description for map_categories function - * @return \external_description */ - public static function map_categories_parameters() { + public static function map_categories_parameters() : \external_function_parameters { return new \external_function_parameters( [ "root_id" => new \external_value(PARAM_INT, 'root category to use as base', VALUE_DEFAULT), ] ); @@ -60,9 +59,8 @@ class courseservice extends \external_api { /** * Parameter description for map_categories function - * @return \external_description */ - public static function map_categories_returns() { + public static function map_categories_returns() : \external_description { return new \external_multiple_structure(static::map_category_structure(false)); } @@ -70,7 +68,6 @@ class courseservice extends \external_api { * Structure description for category map, used in a number of return descriptions * @param bool $lazy * @param int $value - * @return \external_description */ protected static function map_category_structure($lazy = false, $value = VALUE_REQUIRED) { $s = [ @@ -126,9 +123,8 @@ class courseservice extends \external_api { /** * Return value description for get_category function - * @return \external_description */ - public static function get_category_parameters() { + public static function get_category_parameters() : \external_function_parameters { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of category'), ] ); @@ -136,9 +132,8 @@ class courseservice extends \external_api { /** * Parameter description for get_category function - * @return \external_description */ - public static function get_category_returns() { + public static function get_category_returns() : \external_description { return static::map_category_structure(false); } @@ -190,9 +185,8 @@ class courseservice extends \external_api { /** * Return value description for list_accessible_categories function - * @return \external_description */ - public static function list_accessible_categories_parameters() { + public static function list_accessible_categories_parameters() : \external_function_parameters { return new \external_function_parameters( [ "operation" => new \external_value(PARAM_TEXT, 'type of operation ["view"|"edit"]', VALUE_DEFAULT), ] ); @@ -200,9 +194,8 @@ class courseservice extends \external_api { /** * Parameter description for list_accessible_categories function - * @return \external_description */ - public static function list_accessible_categories_returns() { + public static function list_accessible_categories_returns() : \external_description { return new \external_multiple_structure(static::map_category_structure(true)); } @@ -283,9 +276,8 @@ class courseservice extends \external_api { /** * Return value description for list_used_categories function - * @return \external_description */ - public static function list_used_categories_parameters() { + public static function list_used_categories_parameters() : \external_function_parameters { return new \external_function_parameters( [ "operation" => new \external_value(PARAM_TEXT, 'type of operation ["view"|"edit"]', VALUE_DEFAULT), ]); @@ -293,9 +285,8 @@ class courseservice extends \external_api { /** * Parameter description for list_used_categories function - * @return \external_description */ - public static function list_used_categories_returns() { + public static function list_used_categories_returns() : \external_description { return new \external_multiple_structure(static::map_category_structure(true)); } @@ -390,7 +381,7 @@ class courseservice extends \external_api { * Return value description for scan_grade_progress function * @return external_function_parameters */ - public static function scan_grade_progress_parameters() { + public static function scan_grade_progress_parameters() : \external_function_parameters { return new \external_function_parameters( [ "gradeitemid" => new \external_value(PARAM_INT, 'Grade item ID to scan progress for', VALUE_DEFAULT), "studyplanid" => new \external_value(PARAM_INT, 'Study plan id to check progress in', VALUE_DEFAULT), @@ -400,9 +391,8 @@ class courseservice extends \external_api { /** * Parameter description for scan_grade_progress function - * @return \external_description */ - public static function scan_grade_progress_returns() { + public static function scan_grade_progress_returns() : \external_description { return gradingscanner::structure(VALUE_REQUIRED); } @@ -435,9 +425,8 @@ class courseservice extends \external_api { /** * Return value description for scan_completion_progress function - * @return \external_description */ - public static function scan_completion_progress_parameters() { + public static function scan_completion_progress_parameters() : \external_function_parameters { return new \external_function_parameters( [ "criteriaid" => new \external_value(PARAM_INT, 'CriteriaID to scan progress for', VALUE_DEFAULT), "studyplanid" => new \external_value(PARAM_INT, 'Study plan id to check progress in', VALUE_DEFAULT), @@ -447,9 +436,8 @@ class courseservice extends \external_api { /** * Parameter description for scan_completion_progress function - * @return \external_description */ - public static function scan_completion_progress_returns() { + public static function scan_completion_progress_returns() : \external_description { return completionscanner::structure(VALUE_REQUIRED); } @@ -477,9 +465,8 @@ class courseservice extends \external_api { /** * Return value description for scan_badge_progress function - * @return \external_description */ - public static function scan_badge_progress_parameters() { + public static function scan_badge_progress_parameters() : \external_function_parameters { return new \external_function_parameters( [ "badgeid" => new \external_value(PARAM_INT, 'Badge to scan progress for', VALUE_DEFAULT), "studyplanid" => new \external_value(PARAM_INT, @@ -489,9 +476,8 @@ class courseservice extends \external_api { /** * Parameter description for scan_badge_progress function - * @return \external_description */ - public static function scan_badge_progress_returns() { + public static function scan_badge_progress_returns() : \external_description { return new \external_single_structure([ "total" => new \external_value(PARAM_INT, 'Total number of students scanned'), "issued" => new \external_value(PARAM_INT, 'Number of issued badges'), diff --git a/classes/gradeinfo.php b/classes/gradeinfo.php index a9d1f1b..8997e6f 100644 --- a/classes/gradeinfo.php +++ b/classes/gradeinfo.php @@ -251,14 +251,12 @@ class gradeinfo { /** * Webservice structure for editor info * @param int $value Webservice requirement constant - * @return \external_description Webservice output structure */ /** * Webservice structure for editor info * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function editor_structure($value = VALUE_REQUIRED) { + public static function editor_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'grade_item id'), "cmid" => new \external_value(PARAM_INT, 'course module id'), @@ -305,14 +303,12 @@ class gradeinfo { /** * Webservice structure for user info * @param int $value Webservice requirement constant - * @return \external_description Webservice output structure */ /** * Webservice structure for userinfo * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function user_structure($value = VALUE_REQUIRED) { + public static function user_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'grade_item id'), "cmid" => new \external_value(PARAM_INT, 'course module id'), @@ -423,7 +419,7 @@ class gradeinfo { * Get a list if all gradable activities in a given course * @param \stdClass $course Course database record * @param studyitem|null $studyitem Studyitem linked to the course which can be linked to created gradeinfo objects - * @return self[] Array of gradeinfo + * @return gradeinfo[] Array of gradeinfo */ public static function list_course_gradables($course, studyitem $studyitem = null) : array { $list = []; @@ -466,7 +462,7 @@ class gradeinfo { /** * List all gradables enabled for a given study item * @param studyitem $studyitem The studyitem to search for - * @return self[] Array of gradeinfo + * @return gradeinfo[] Array of gradeinfo */ public static function list_studyitem_gradables(studyitem $studyitem) : array { global $DB; diff --git a/classes/period.php b/classes/period.php index f3b573f..472f739 100644 --- a/classes/period.php +++ b/classes/period.php @@ -14,7 +14,7 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . /** - * + * Model class for period descriptions * @package local_treestudyplan * @copyright 2023 P.M. Kuipers * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -25,10 +25,19 @@ defined('MOODLE_INTERNAL') || die(); require_once($CFG->libdir.'/externallib.php'); +/** + * Model class for period descriptions + */ class period { /** @var string */ const TABLE = "local_treestudyplan_period"; + /** + * Cache all retrieved periods in this session + * @var array */ private static $cache = []; + /** + * Cache the collection of periods per page retrieved this session + * @var array */ private static $pagecache = []; /** @@ -41,15 +50,17 @@ class period { /** @var studyplanpage */ private $page; - public function aggregator() { - return $this->studyplan->aggregator(); + /** + * Shortcut to studyplan (page)'s aggregator + */ + public function aggregator() : aggregator { + return $this->page->aggregator(); } - // Cache constructors to avoid multiple creation events in one session. /** * Find record in database and return management object + * *Caches to avoid multiple creation events in one session. * @param int $id Id of database record - * @return self */ public static function find_by_id($id): self { if (!array_key_exists($id, self::$cache)) { @@ -60,6 +71,8 @@ class period { /** * Find a period by page and period number [1..$page->periods()] + * @param studyplanpage $page Studyplan page to find period for + * @param int $periodnr Period sequence nr [1..$page->periods()] */ public static function find(studyplanpage $page, $periodnr): self { global $DB; @@ -114,7 +127,12 @@ class period { return $period; } - // Cache constructors to avoid multiple creation events in one session. + + /** + * Find all periods registered to a studyplan in sequence + * @param studyplanpage $page Studyplan page to find periods for + * @return period[] + */ public static function find_for_page(studyplanpage $page): array { if (!array_key_exists($page->id(), self::$pagecache)) { $periods = []; @@ -147,10 +165,18 @@ class period { return $this->id; } + /** + * Return associated studyplan + * @return studyplan + */ public function studyplan() : studyplan { return $this->page->studyplan(); } + /** + * Return associated studyplan page + * @return studyplanpage + */ public function page() { return $this->page; } @@ -171,6 +197,10 @@ class period { return $this->r->fullname; } + /** + * Return period sequence number + * @return int + */ public function period() { return $this->r->period; } @@ -196,7 +226,11 @@ class period { } } - public static function structure($value = VALUE_REQUIRED) { + /** + * Webservice structure for basic info + * @param int $value Webservice requirement constant + */ + public static function structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of period'), "fullname" => new \external_value(PARAM_TEXT, 'Full name of period'), @@ -207,6 +241,10 @@ class period { ], 'Period info', $value); } + /** + * Webservice model for basic info + * @return array Webservice data model + */ public function model() { return [ 'id' => $this->r->id, @@ -219,8 +257,10 @@ class period { } /** - * Do not use directly to add periods, unless performing import - * The static find() and find_for_page() functions create the period if needed + * Add a new period for a studyplan page + * Use only when performing import! The static find() and find_for_page() functions create the period during normal operation + * @param array $fields Properties for ['page_id', 'fullname', 'shortname', 'period', 'startdate', 'enddate'] + * @return period */ public static function add($fields) { global $DB; @@ -248,7 +288,11 @@ class period { return self::find_by_id($id); // Make sure the new page is immediately cached. } - public function edit($fields) { + /** + * Edit period properties + * @param array $fields Properties for ['fullname', 'shortname', 'startdate', 'enddate'] + */ + public function edit($fields) : self { global $DB; $editable = ['fullname', 'shortname', 'startdate', 'enddate']; $info = ['id' => $this->id, ]; @@ -264,18 +308,30 @@ class period { return $this; } - public function delete() { + /** + * Delete period + */ + public function delete() : success { global $DB; $DB->delete_records(self::TABLE, ['id' => $this->id]); unset(self::$pagecache[$this->r->page_id]); // Invalidate the cache for this page. return success::success(); } - public static function page_structure($value = VALUE_REQUIRED) { + /** + * Webservice structure for list of periods in page + * @param int $value Webservice requirement constant + */ + public static function page_structure($value = VALUE_REQUIRED) : \external_description { return new \external_multiple_structure(self::structure(), "The periods in the page", $value); } - public static function page_model(studyplanpage $page) { + /** + * Webservice model list of periods in page + * @param studyplanpage $page The page to create the model for + * @return array Webservice data model + */ + public static function page_model(studyplanpage $page) : array { $model = []; foreach (self::find_for_page($page) as $p) { $model[] = $p->model(); diff --git a/classes/studentstudyplanservice.php b/classes/studentstudyplanservice.php index 34aa37d..de5e70d 100644 --- a/classes/studentstudyplanservice.php +++ b/classes/studentstudyplanservice.php @@ -45,9 +45,8 @@ class studentstudyplanservice extends \external_api { /** * Parameter description for webservice function list_user_studyplans - * @return \external_function_parameters */ - public static function list_user_studyplans_parameters() { + 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), ]); @@ -55,9 +54,8 @@ class studentstudyplanservice extends \external_api { /** * Return value description for webservice function list_user_studyplans - * @return \external_description */ - public static function list_user_studyplans_returns() { + public static function list_user_studyplans_returns() : \external_description { return new \external_multiple_structure( studyplan::simple_structure() ); @@ -90,9 +88,8 @@ class studentstudyplanservice extends \external_api { /** * Parameter description for webservice function get_user_studyplans - * @return \external_function_parameters */ - public static function get_user_studyplans_parameters() { + public static function get_user_studyplans_parameters() : \external_function_parameters { return new \external_function_parameters( [ "userid" => new \external_value(PARAM_INT, 'id of user'), ] ); @@ -100,9 +97,8 @@ class studentstudyplanservice extends \external_api { /** * Return value description for webservice function get_user_studyplans - * @return \external_description */ - public static function get_user_studyplans_returns() { + public static function get_user_studyplans_returns() : \external_description { return new \external_multiple_structure( studyplan::user_structure() ); @@ -137,9 +133,8 @@ class studentstudyplanservice extends \external_api { /** * Parameter description for webservice function get_user_studyplan - * @return \external_function_parameters */ - public static function get_user_studyplan_parameters() { + 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'), @@ -148,9 +143,8 @@ class studentstudyplanservice extends \external_api { /** * Return value description for webservice function get_user_studyplan - * @return \external_description */ - public static function get_user_studyplan_returns() { + public static function get_user_studyplan_returns() : \external_description { return studyplan::user_structure(); } @@ -181,9 +175,8 @@ class studentstudyplanservice extends \external_api { /** * Parameter description for webservice function get_invited_studyplan - * @return \external_function_parameters */ - public static function get_invited_studyplan_parameters() { + public static function get_invited_studyplan_parameters() : \external_function_parameters { return new \external_function_parameters( [ "invitekey" => new \external_value(PARAM_RAW, 'invite key'), ] ); @@ -191,9 +184,8 @@ class studentstudyplanservice extends \external_api { /** * Return value description for webservice function get_invited_studyplan - * @return \external_description */ - public static function get_invited_studyplan_returns() { + public static function get_invited_studyplan_returns() : \external_description { return new \external_multiple_structure( studyplan::user_structure() ); @@ -238,17 +230,15 @@ class studentstudyplanservice extends \external_api { /** * Parameter description for webservice function list_own_studyplans - * @return \external_function_parameters */ - public static function list_own_studyplans_parameters() { + public static function list_own_studyplans_parameters() : \external_function_parameters { return new \external_function_parameters([]); } /** * Return value description for webservice function list_own_studyplans - * @return \external_description */ - public static function list_own_studyplans_returns() { + public static function list_own_studyplans_returns() : \external_description { return new \external_multiple_structure( studyplan::simple_structure() ); @@ -278,9 +268,8 @@ class studentstudyplanservice extends \external_api { /** * Parameter description for webservice function get_own_studyplan - * @return \external_function_parameters */ - public static function get_own_studyplan_parameters() { + 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), ] ); @@ -288,9 +277,8 @@ class studentstudyplanservice extends \external_api { /** * Return value description for webservice function get_own_studyplan - * @return \external_description */ - public static function get_own_studyplan_returns() { + public static function get_own_studyplan_returns() : \external_description { return new \external_multiple_structure( studyplan::user_structure() ); @@ -335,9 +323,8 @@ class studentstudyplanservice extends \external_api { /** * Parameter description for webservice function get_teaching_studyplans - * @return \external_function_parameters */ - public static function get_teaching_studyplans_parameters() { + 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), ] ); @@ -345,9 +332,8 @@ class studentstudyplanservice extends \external_api { /** * Return value description for webservice function get_teaching_studyplans - * @return \external_description */ - public static function get_teaching_studyplans_returns() { + public static function get_teaching_studyplans_returns() : \external_description { return new \external_multiple_structure( studyplan::editor_structure() ); diff --git a/classes/studyitem.php b/classes/studyitem.php index f8dd99a..dc16bfb 100644 --- a/classes/studyitem.php +++ b/classes/studyitem.php @@ -72,7 +72,6 @@ class studyitem { /** * Find record in database and return management object * @param int $id Id of database record - * @return self */ public static function find_by_id($id): self { if (!array_key_exists($id, self::$studyitemcache)) { @@ -122,9 +121,8 @@ class studyitem { /** * Webservice structure for editor info * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function editor_structure($value = VALUE_REQUIRED) { + public static function editor_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of study item'), "type" => new \external_value(PARAM_TEXT, 'shortname of study item'), @@ -346,7 +344,7 @@ class studyitem { return $list; } - private static function link_structure($value = VALUE_REQUIRED) { + private static function link_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of study item'), "type" => new \external_value(PARAM_TEXT, 'type of study item'), @@ -373,9 +371,8 @@ class studyitem { /** * Webservice structure for userinfo * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function user_structure($value = VALUE_REQUIRED) { + public static function user_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of study item'), "type" => new \external_value(PARAM_TEXT, 'type of study item'), diff --git a/classes/studyitemconnection.php b/classes/studyitemconnection.php index 3ce01fe..778d802 100644 --- a/classes/studyitemconnection.php +++ b/classes/studyitemconnection.php @@ -55,9 +55,8 @@ class studyitemconnection { /** * Webservice structure for basic info * @param int $value Webservice requirement constant - * @return \external_description Webservice output structure */ - public static function structure($value = VALUE_REQUIRED) { + public static function structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ 'id' => new \external_value(PARAM_INT, 'id of connection'), 'from_id' => new \external_value(PARAM_INT, 'id of start item'), @@ -105,7 +104,7 @@ class studyitemconnection { /** * Get all connections originating at a given studyitem's id * @param int $itemid Id of the studyitem - * @return self[] + * @return studyitemconnection[] */ public static function find_outgoing($itemid) : array { global $DB; @@ -120,7 +119,7 @@ class studyitemconnection { /** * Get all connections terminating at a given studyitem's id * @param int $itemid Id of the studyitem - * @return self[] + * @return studyitemconnection[] */ public static function find_incoming($itemid) { global $DB; diff --git a/classes/studyline.php b/classes/studyline.php index 2616b20..e3bfc3c 100644 --- a/classes/studyline.php +++ b/classes/studyline.php @@ -79,7 +79,6 @@ class studyline { /** * Find record in database and return management object * @param int $id Id of database record - * @return self */ public static function find_by_id($id): self { if (!array_key_exists($id, self::$studylinecache)) { @@ -122,9 +121,8 @@ class studyline { /** * Webservice structure for editor info * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function editor_structure($value = VALUE_REQUIRED) { + public static function editor_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyline'), "name" => new \external_value(PARAM_TEXT, 'shortname of studyline'), @@ -295,9 +293,8 @@ class studyline { /** * Webservice structure for userinfo * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function user_structure($value = VALUE_REQUIRED) { + public static function user_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyline'), "name" => new \external_value(PARAM_TEXT, 'shortname of studyline'), diff --git a/classes/studyplan.php b/classes/studyplan.php index e334f80..09f702b 100644 --- a/classes/studyplan.php +++ b/classes/studyplan.php @@ -53,7 +53,6 @@ class studyplan { /** * Find record in database and return management object * @param int $id Id of database record - * @return self */ public static function find_by_id($id): self { if (!array_key_exists($id, self::$studyplancache)) { @@ -128,9 +127,8 @@ class studyplan { /** * Webservice structure for basic info * @param int $value Webservice requirement constant - * @return \external_description Webservice output structure */ - public static function simple_structure($value = VALUE_REQUIRED) { + public static function simple_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyplan'), "name" => new \external_value(PARAM_TEXT, 'name of studyplan'), @@ -172,9 +170,8 @@ class studyplan { /** * Webservice structure for editor info * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function editor_structure($value = VALUE_REQUIRED) { + public static function editor_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyplan'), "name" => new \external_value(PARAM_TEXT, 'name of studyplan'), @@ -494,9 +491,8 @@ class studyplan { /** * Webservice structure for userinfo * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function user_structure($value = VALUE_REQUIRED) { + public static function user_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyplan'), "name" => new \external_value(PARAM_TEXT, 'name of studyplan'), @@ -557,9 +553,8 @@ class studyplan { /** * Description of export structure for webservices - * @return \external_description */ - public static function export_structure() { + public static function export_structure() : \external_description { return new \external_single_structure([ "format" => new \external_value(PARAM_TEXT, 'format of studyplan export'), "content" => new \external_value(PARAM_TEXT, 'exported studyplan content'), diff --git a/classes/studyplanpage.php b/classes/studyplanpage.php index 29156a8..75ce92b 100644 --- a/classes/studyplanpage.php +++ b/classes/studyplanpage.php @@ -59,7 +59,6 @@ class studyplanpage { /** * Find record in database and return management object * @param int $id Id of database record - * @return self */ public static function find_by_id($id): self { if (!array_key_exists($id, self::$cache)) { @@ -142,9 +141,8 @@ class studyplanpage { /** * Webservice structure for basic info * @param int $value Webservice requirement constant - * @return \external_description Webservice output structure */ - public static function simple_structure($value = VALUE_REQUIRED) { + public static function simple_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyplan page'), "fullname" => new \external_value(PARAM_TEXT, 'name of studyplan page'), @@ -177,9 +175,8 @@ class studyplanpage { /** * Webservice structure for editor info * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function editor_structure($value = VALUE_REQUIRED) { + public static function editor_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyplan'), "fullname" => new \external_value(PARAM_TEXT, 'name of studyplan page'), @@ -222,9 +219,8 @@ class studyplanpage { /** * Add new study plan page * @param mixed $fields Parameter for new study plan page - * @return self */ - public static function add($fields) { + public static function add($fields) : self { global $CFG, $DB; if (!isset($fields['studyplan_id'])) { @@ -251,9 +247,8 @@ class studyplanpage { /** * Edit studyplan page * @param mixed $fields Parameters to change - * @return self */ - public function edit($fields) { + public function edit($fields) : self { global $DB; $editable = ['fullname', 'shortname', 'description', 'periods', 'startdate', 'enddate']; $info = ['id' => $this->id, ]; @@ -299,9 +294,8 @@ class studyplanpage { /** * Webservice structure for userinfo * @param int $value Webservice requirement constant - * @return \external_single_structure Webservice output structure */ - public static function user_structure($value = VALUE_REQUIRED) { + public static function user_structure($value = VALUE_REQUIRED) : \external_description { return new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of studyplan page'), "fullname" => new \external_value(PARAM_TEXT, 'name of studyplan page'), @@ -344,7 +338,7 @@ class studyplanpage { /** * Find list of pages belonging to a specified study plan * @param studyplan $plan Studyplan to search pages for - * @return self[] + * @return studyplanpage[] */ public static function find_studyplan_children(studyplan $plan) { global $DB; @@ -361,9 +355,8 @@ class studyplanpage { * Duplicate a studyplan page * @param int $pageid Id of the page to copy * @param studyplan $newstudyplan Studyplan to copy the page into - * @return self */ - public static function duplicate_page(int $pageid, studyplan $newstudyplan) { + public static function duplicate_page(int $pageid, studyplan $newstudyplan) : self { $ori = self::find_by_id($pageid); $new = $ori->duplicate($newstudyplan); return $new; @@ -372,9 +365,8 @@ class studyplanpage { /** * Duplicate this studyplan page * @param studyplan $newstudyplan Studyplan to copy the page into - * @return self */ - public function duplicate(studyplan $newstudyplan) { + public function duplicate(studyplan $newstudyplan) : self { // First duplicate the studyplan structure. $new = self::add([ 'studyplan_id' => $newstudyplan->id(), @@ -411,9 +403,8 @@ class studyplanpage { /** * Description of export structure for webservices - * @return \external_description */ - public static function export_structure() { + public static function export_structure() : \external_description { return new \external_single_structure([ "format" => new \external_value(PARAM_TEXT, 'format of studyplan export'), "content" => new \external_value(PARAM_TEXT, 'exported studyplan content'), diff --git a/classes/studyplanservice.php b/classes/studyplanservice.php index f377ba0..a369b0a 100644 --- a/classes/studyplanservice.php +++ b/classes/studyplanservice.php @@ -53,9 +53,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function list_studyplans - * @return \external_function_parameters */ - public static function list_studyplans_parameters() { + public static function list_studyplans_parameters() : \external_function_parameters { return new \external_function_parameters([ "context_id" => new \external_value(PARAM_INT, 'context to search in for studyplans', VALUE_DEFAULT), ]); @@ -63,9 +62,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function list_studyplans - * @return \external_description */ - public static function list_studyplans_returns() { + public static function list_studyplans_returns() : \external_description { return new \external_multiple_structure( studyplan::simple_structure() ); } @@ -99,9 +97,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function get_studyplan_map - * @return \external_function_parameters */ - public static function get_studyplan_map_parameters() { + public static function get_studyplan_map_parameters() : \external_function_parameters { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of a studyplan to check usage on', VALUE_REQUIRED), ] ); @@ -109,9 +106,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function get_studyplan_map - * @return \external_description */ - public static function get_studyplan_map_returns() { + public static function get_studyplan_map_returns() : \external_description { return studyplan::editor_structure(); } @@ -138,9 +134,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function get_studyline_map - * @return \external_function_parameters */ - public static function get_studyline_map_parameters() { + public static function get_studyline_map_parameters() : \external_function_parameters { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of a studyline to check usage on', VALUE_DEFAULT), ]); @@ -148,9 +143,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function get_studyline_map - * @return \external_description */ - public static function get_studyline_map_returns() { + public static function get_studyline_map_returns() : \external_description { return new \external_multiple_structure( studyline::editor_structure() ); } @@ -174,9 +168,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function add_studyplan - * @return \external_function_parameters */ - public static function add_studyplan_parameters() { + public static function add_studyplan_parameters() : \external_function_parameters { return new \external_function_parameters( [ "name" => new \external_value(PARAM_TEXT, 'name of studyplan'), "shortname" => new \external_value(PARAM_TEXT, 'shortname of studyplan'), @@ -193,9 +186,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function add_studyplan - * @return \external_description */ - public static function add_studyplan_returns() { + public static function add_studyplan_returns() : \external_description { return studyplan::simple_structure(); } @@ -242,9 +234,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function edit_studyplan - * @return \external_function_parameters */ - public static function edit_studyplan_parameters() { + public static function edit_studyplan_parameters() : \external_function_parameters { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of studyplan'), "name" => new \external_value(PARAM_TEXT, 'name of studyplan'), @@ -262,9 +253,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function edit_studyplan - * @return \external_description */ - public static function edit_studyplan_returns() { + public static function edit_studyplan_returns() : \external_description { return studyplan::simple_structure(); } @@ -316,9 +306,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function delete_studyplan - * @return \external_function_parameters */ - public static function delete_studyplan_parameters() { + public static function delete_studyplan_parameters() : \external_function_parameters { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of studyplan'), "force" => new \external_value(PARAM_BOOL, 'id of studyplan', VALUE_DEFAULT), @@ -327,9 +316,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function delete_studyplan - * @return \external_description */ - public static function delete_studyplan_returns() { + public static function delete_studyplan_returns() : \external_description { return success::structure(); } @@ -354,9 +342,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function add_studyline - * @return \external_function_parameters */ - public static function add_studyline_parameters() { + public static function add_studyline_parameters() : \external_function_parameters { return new \external_function_parameters( [ "page_id" => new \external_value(PARAM_INT, 'id of studyplan to add line to'), "name" => new \external_value(PARAM_TEXT, 'shortname of studyline'), @@ -368,9 +355,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function add_studyline - * @return \external_description */ - public static function add_studyline_returns() { + public static function add_studyline_returns() : \external_description { return studyline::editor_structure(); } @@ -406,9 +392,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function edit_studyline - * @return \external_function_parameters */ - public static function edit_studyline_parameters() { + public static function edit_studyline_parameters() : \external_function_parameters { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of studyline'), "name" => new \external_value(PARAM_TEXT, 'shortname of studyline'), @@ -419,9 +404,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function edit_studyline - * @return \external_description */ - public static function edit_studyline_returns() { + public static function edit_studyline_returns() : \external_description { return studyline::editor_structure(); } @@ -454,9 +438,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function delete_studyline - * @return \external_function_parameters */ - public static function delete_studyline_parameters() { + public static function delete_studyline_parameters() : \external_function_parameters { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of studyline'), ] ); @@ -464,9 +447,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function delete_studyline - * @return \external_description */ - public static function delete_studyline_returns() { + public static function delete_studyline_returns() : \external_description { return success::structure(); } @@ -491,9 +473,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function reorder_studylines - * @return \external_function_parameters */ - public static function reorder_studylines_parameters() { + public static function reorder_studylines_parameters() : \external_function_parameters { return new \external_function_parameters( [ "sequence" => new \external_multiple_structure( new \external_single_structure([ @@ -506,9 +487,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function reorder_studylines - * @return \external_description */ - public static function reorder_studylines_returns() { + public static function reorder_studylines_returns() : \external_description { return success::structure(); } @@ -539,9 +519,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function get_studyitem - * @return \external_function_parameters */ - public static function get_studyitem_parameters() { + public static function get_studyitem_parameters() : \external_function_parameters { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of a study item to retrieve'), ] ); @@ -549,9 +528,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function get_studyitem - * @return \external_description */ - public static function get_studyitem_returns() { + public static function get_studyitem_returns() : \external_description { return studyitem::editor_structure(); } @@ -575,9 +553,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function add_studyitem - * @return \external_function_parameters */ - public static function add_studyitem_parameters() { + public static function add_studyitem_parameters() : \external_function_parameters { return new \external_function_parameters( [ "line_id" => new \external_value(PARAM_INT, 'id of related study line'), "type" => new \external_value(PARAM_TEXT, 'type of study item'), @@ -595,9 +572,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function add_studyitem - * @return \external_description */ - public static function add_studyitem_returns() { + public static function add_studyitem_returns() : \external_description { return studyitem::editor_structure(); } @@ -634,9 +610,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function edit_studyitem - * @return \external_function_parameters */ - public static function edit_studyitem_parameters() { + public static function edit_studyitem_parameters() : \external_function_parameters { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of study item'), "conditions" => new \external_value(PARAM_TEXT, 'conditions for completion'), @@ -646,9 +621,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function edit_studyitem - * @return \external_description */ - public static function edit_studyitem_returns() { + public static function edit_studyitem_returns() : \external_description { return studyitem::editor_structure(); } @@ -684,9 +658,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function reorder_studyitems - * @return \external_function_parameters */ - public static function reorder_studyitems_parameters() { + public static function reorder_studyitems_parameters() : \external_function_parameters { return new \external_function_parameters( [ "items" => new \external_multiple_structure( new \external_single_structure([ @@ -701,9 +674,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function reorder_studyitems - * @return \external_description */ - public static function reorder_studyitems_returns() { + public static function reorder_studyitems_returns() : \external_description { return success::structure(); } @@ -729,9 +701,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function delete_studyitem - * @return \external_function_parameters */ - public static function delete_studyitem_parameters() { + public static function delete_studyitem_parameters() : \external_function_parameters { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of studyitem'), ] ); @@ -739,9 +710,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function delete_studyitem - * @return \external_description */ - public static function delete_studyitem_returns() { + public static function delete_studyitem_returns() : \external_description { return success::structure(); } @@ -765,9 +735,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function connect_studyitems - * @return \external_function_parameters */ - public static function connect_studyitems_parameters() { + public static function connect_studyitems_parameters() : \external_function_parameters { return new \external_function_parameters( [ "from_id" => new \external_value(PARAM_INT, 'id of studyitem connect start '), "to_id" => new \external_value(PARAM_INT, 'id ofstudyitem connect end'), @@ -776,9 +745,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function connect_studyitems - * @return \external_description */ - public static function connect_studyitems_returns() { + public static function connect_studyitems_returns() : \external_description { return studyitemconnection::structure(); } @@ -805,9 +773,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function disconnect_studyitems - * @return \external_function_parameters */ - public static function disconnect_studyitems_parameters() { + public static function disconnect_studyitems_parameters() : \external_function_parameters { return new \external_function_parameters( [ "from_id" => new \external_value(PARAM_INT, 'id of studyitem '), "to_id" => new \external_value(PARAM_INT, 'id of related study line'), @@ -816,9 +783,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function disconnect_studyitems - * @return \external_description */ - public static function disconnect_studyitems_returns() { + public static function disconnect_studyitems_returns() : \external_description { return success::structure(); } @@ -843,17 +809,15 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function list_badges - * @return \external_function_parameters */ - public static function list_badges_parameters() { + public static function list_badges_parameters() : \external_function_parameters { return new \external_function_parameters( [] ); } /** * Return value description for webservice function list_badges - * @return \external_description */ - public static function list_badges_returns() { + public static function list_badges_returns() : \external_description { return new \external_multiple_structure(badgeinfo::editor_structure()); } @@ -885,9 +849,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function include_grade - * @return \external_function_parameters */ - public static function include_grade_parameters() { + public static function include_grade_parameters() : \external_function_parameters { return new \external_function_parameters( [ "grade_id" => new \external_value(PARAM_INT, 'id of gradeitem '), "item_id" => new \external_value(PARAM_INT, 'id of studyitem '), @@ -898,9 +861,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function include_grade - * @return \external_description */ - public static function include_grade_returns() { + public static function include_grade_returns() : \external_description { return success::structure(); } @@ -940,17 +902,15 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function list_aggregators - * @return \external_function_parameters */ - public static function list_aggregators_parameters() { + public static function list_aggregators_parameters() : \external_function_parameters { return new \external_function_parameters([]); } /** * Return value description for webservice function list_aggregators - * @return \external_description */ - public static function list_aggregators_returns() { + public static function list_aggregators_returns() : \external_description { return aggregator::list_structure(); } @@ -971,9 +931,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function force_studyplan_scale - * @return \external_function_parameters */ - public static function force_studyplan_scale_parameters() { + public static function force_studyplan_scale_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan'), "scale_id" => new \external_value(PARAM_INT, 'scale_id to set'), @@ -982,9 +941,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function force_studyplan_scale - * @return \external_description */ - public static function force_studyplan_scale_returns() { + public static function force_studyplan_scale_returns() : \external_description { return new \external_multiple_structure(new \external_single_structure([ "course" => courseinfo::simple_structure(), "grades" => new \external_multiple_structure(new \external_single_structure([ @@ -1104,17 +1062,15 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function list_scales - * @return \external_function_parameters */ - public static function list_scales_parameters() { + public static function list_scales_parameters() : \external_function_parameters { return new \external_function_parameters( [] ); } /** * Return value description for webservice function list_scales - * @return \external_description */ - public static function list_scales_returns() { + public static function list_scales_returns() : \external_description { return new \external_multiple_structure(new \external_single_structure([ "id" => new \external_value(PARAM_INT, 'id of scale'), "name" => new \external_value(PARAM_TEXT, 'scale name'), @@ -1149,9 +1105,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function disable_autoenddate - * @return \external_function_parameters */ - public static function disable_autoenddate_parameters() { + public static function disable_autoenddate_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of studyplan'), ] ); @@ -1159,9 +1114,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function disable_autoenddate - * @return \external_description */ - public static function disable_autoenddate_returns() { + public static function disable_autoenddate_returns() : \external_description { return success::structure(); } @@ -1205,9 +1159,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function duplicate_plan - * @return \external_function_parameters */ - public static function duplicate_plan_parameters() { + public static function duplicate_plan_parameters() : \external_function_parameters { return new \external_function_parameters( [ "plan_id" => new \external_value(PARAM_INT, 'id of plan to copy '), "name" => new \external_value(PARAM_TEXT, 'name of copy '), @@ -1217,9 +1170,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function duplicate_plan - * @return \external_description */ - public static function duplicate_plan_returns() { + public static function duplicate_plan_returns() : \external_description { return studyplan::simple_structure(); } @@ -1245,9 +1197,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function export_plan - * @return \external_function_parameters */ - public static function export_plan_parameters() { + public static function export_plan_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of plan to export '), "format" => new \external_value(PARAM_TEXT, 'export format', VALUE_OPTIONAL), @@ -1256,9 +1207,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function export_plan - * @return \external_description */ - public static function export_plan_returns() { + public static function export_plan_returns() : \external_description { return studyplan::export_structure(); } @@ -1288,9 +1238,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function export_studylines - * @return \external_function_parameters */ - public static function export_studylines_parameters() { + public static function export_studylines_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of plan to export '), ] ); @@ -1298,9 +1247,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function export_studylines - * @return \external_description */ - public static function export_studylines_returns() { + public static function export_studylines_returns() : \external_description { return studyplan::export_structure(); } @@ -1327,9 +1275,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function import_plan - * @return \external_function_parameters */ - public static function import_plan_parameters() { + public static function import_plan_parameters() : \external_function_parameters { return new \external_function_parameters( [ "content" => new \external_value(PARAM_TEXT, 'import file content'), "format" => new \external_value(PARAM_TEXT, 'import format'), @@ -1339,9 +1286,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function import_plan - * @return \external_description */ - public static function import_plan_returns() { + public static function import_plan_returns() : \external_description { return success::structure(); } @@ -1368,9 +1314,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function import_studylines - * @return \external_function_parameters */ - public static function import_studylines_parameters() { + public static function import_studylines_parameters() : \external_function_parameters { return new \external_function_parameters( [ "studyplan_id" => new \external_value(PARAM_INT, 'id of plan to export '), "content" => new \external_value(PARAM_TEXT, 'import file content'), @@ -1380,9 +1325,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function import_studylines - * @return \external_description */ - public static function import_studylines_returns() { + public static function import_studylines_returns() : \external_description { return success::structure(); } @@ -1417,9 +1361,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function submit_cm_editform - * @return \external_function_parameters */ - public static function submit_cm_editform_parameters() { + public static function submit_cm_editform_parameters() : \external_function_parameters { return new \external_function_parameters( [ "cmid" => new \external_value(PARAM_INT, 'id of course module'), "formdata" => new \external_value(PARAM_RAW, 'url encoded form data'), @@ -1428,9 +1371,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function submit_cm_editform - * @return \external_description */ - public static function submit_cm_editform_returns() { + public static function submit_cm_editform_returns() : \external_description { return success::structure(); } @@ -1508,9 +1450,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function edit_period - * @return \external_function_parameters */ - public static function edit_period_parameters() { + public static function edit_period_parameters() : \external_function_parameters { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of study item'), "fullname" => new \external_value(PARAM_TEXT, 'Full name of period'), @@ -1522,9 +1463,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function edit_period - * @return \external_description */ - public static function edit_period_returns() { + public static function edit_period_returns() : \external_description { return period::structure(); } @@ -1560,9 +1500,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function course_period_timing - * @return \external_function_parameters */ - public static function course_period_timing_parameters() { + public static function course_period_timing_parameters() : \external_function_parameters { return new \external_function_parameters( [ "period_id" => new \external_value(PARAM_INT, 'Period number within page'), "course_id" => new \external_value(PARAM_INT, 'Id of course to adjust dates for'), @@ -1572,9 +1511,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function course_period_timing - * @return \external_description */ - public static function course_period_timing_returns() { + public static function course_period_timing_returns() : \external_description { return courseinfo::editor_structure(); } @@ -1640,9 +1578,8 @@ class studyplanservice extends \external_api { /** * Parameter description for webservice function set_studyitem_span - * @return \external_function_parameters */ - public static function set_studyitem_span_parameters() { + public static function set_studyitem_span_parameters() : \external_function_parameters { return new \external_function_parameters( [ "id" => new \external_value(PARAM_INT, 'id of study item'), "span" => new \external_value(PARAM_INT, 'span of item'), @@ -1651,9 +1588,8 @@ class studyplanservice extends \external_api { /** * Return value description for webservice function set_studyitem_span - * @return \external_description */ - public static function set_studyitem_span_returns() { + public static function set_studyitem_span_returns() : \external_description { return studyitem::editor_structure(); } diff --git a/classes/success.php b/classes/success.php index d4d0158..d56d4af 100644 --- a/classes/success.php +++ b/classes/success.php @@ -41,18 +41,16 @@ class success { /** * Create new successful result with optional message * @param string $msg Message to add to result - * @return self Succesful success object */ - public static function success($msg = "") { + public static function success($msg = "") : self { return new self(true, $msg); } /** * Create new failed result with optional message * @param string $msg Message to add to result - * @return self Failed success object */ - public static function fail($msg = "") { + public static function fail($msg = "") : self { return new self(false, $msg); } @@ -68,9 +66,8 @@ class success { /** * Describe the result for the webservice model - * @return \external_description */ - public static function structure() { + public static function structure() : \external_description { return new \external_single_structure([ "success" => new \external_value(PARAM_BOOL, 'operation completed succesfully'), "msg" => new \external_value(PARAM_TEXT, 'message'),