Miqra-Engineering/moodle_local_treestudyplan
2
0
Fork 0
Code Issues 13 Pull Requests Packages Projects Releases 4 Wiki Activity

PHPDoc documentation

Browse Source
This commit is contained in:
PMKuipers 2023-08-27 21:23:39 +02:00
parent f0e3766957
commit 0f255458cb
10 changed files with 377 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
classes/courseinfo.php
View File

@ -34,6 +34,7 @@ use \grade_scale;
use \grade_outcome;
class courseinfo {
/** @var string */
const TABLE = 'course';
private $course;

154
classes/courseservice.php
View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Webservice related to courses
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -30,27 +30,48 @@ use \local_treestudyplan\associationservice;
use \local_treestudyplan\local\helpers\webservicehelper;
use \local_treestudyplan\completionscanner;
use \local_treestudyplan\gradingscanner;
use \core_course_category;
/**
* Webservice related to courses
*/
class courseservice extends \external_api {
/**
* Capability required to edit study plans
* @var string
*/
const CAP_EDIT = "local/treestudyplan:editstudyplan";
/**
* Capability required to view studyplans (for other users)
* @var string
*/
const CAP_VIEW = "local/treestudyplan:viewuserreports";
/************************
* *
* list_courses *
* *
************************/
/**
* Return value description for map_categories function
* @return \external_description
*/
public static function map_categories_parameters() {
return new \external_function_parameters( [
"root_id" => new \external_value(PARAM_INT, 'root category to use as base', VALUE_DEFAULT),
] );
}
/**
* Parameter description for map_categories function
* @return \external_description
*/
public static function map_categories_returns() {
return new \external_multiple_structure(static::map_category_structure(false));
}
/**
* 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 = [
"id" => new \external_value(PARAM_INT, 'course category id'),
@ -68,6 +89,12 @@ class courseservice extends \external_api {
return new \external_single_structure($s, "CourseCat info", $value);
}
/**
* Get a category map, and optionally specify a root category to search for
* User's top category will be used if none specified
* @param int $rootid Optional starting category for the map
* @return array
*/
public static function map_categories($rootid = 0) {
global $CFG, $DB;
@ -97,22 +124,41 @@ class courseservice extends \external_api {
return $list;
}
/**
* Return value description for get_category function
* @return \external_description
*/
public static function get_category_parameters() {
return new \external_function_parameters( [
"id" => new \external_value(PARAM_INT, 'id of category'),
] );
}
/**
* Parameter description for get_category function
* @return \external_description
*/
public static function get_category_returns() {
return static::map_category_structure(false);
}
/**
* Get category info by id
* @param mixed $id
* @return array
*/
public static function get_category($id) {
$cat = \core_course_category::get($id);
return static::map_category($cat);
}
protected static function map_category(\core_course_category $cat, $lazy = false) {
/**
* Create a category map, given a specific category
* @param core_course_category $cat The category to scan
* @param bool $lazy If lazy loading, do not scan child categories
* @return array
*/
protected static function map_category(core_course_category $cat, $lazy = false) {
global $DB;
$catcontext = $cat->get_context();
$ctxinfo = new contextinfo($catcontext);
@ -142,16 +188,29 @@ class courseservice extends \external_api {
return $model;
}
/**
* Return value description for list_accessible_categories function
* @return \external_description
*/
public static function list_accessible_categories_parameters() {
return new \external_function_parameters( [
"operation" => new \external_value(PARAM_TEXT, 'type of operation ["view"|"edit"]', VALUE_DEFAULT), ]
);
}
/**
* Parameter description for list_accessible_categories function
* @return \external_description
*/
public static function list_accessible_categories_returns() {
return new \external_multiple_structure(static::map_category_structure(true));
}
/**
* [Description for list_accessible_categories]
* @param string $operation
* @return array
*/
public static function list_accessible_categories($operation = "edit") {
if ($operation == "edit") {
$capability = self::CAP_EDIT;
@ -170,7 +229,13 @@ class courseservice extends \external_api {
}
public static function categories_by_capability($capability, \core_course_category $parent = null) {
/**
* [Description for categories_by_capability]
* @param mixed $capability
* @param core_course_category|null $parent
* @return array
*/
public static function categories_by_capability($capability, core_course_category $parent = null) {
// List the categories in which the user has a specific capability.
$list = [];
// Initialize parent if needed.
@ -199,7 +264,12 @@ class courseservice extends \external_api {
return $list;
}
protected static function recursive_child_categories(\core_course_category $parent) {
/**
* Recursively create a list of all categories unter a specified parent
* @param core_course_category $parent
* @return core_course_category[]
*/
protected static function recursive_child_categories(core_course_category $parent) {
$list = [];
$children = $parent->get_children();
foreach ($children as $child) {
@ -211,16 +281,29 @@ class courseservice extends \external_api {
return $list;
}
/**
* Return value description for list_used_categories function
* @return \external_description
*/
public static function list_used_categories_parameters() {
return new \external_function_parameters( [
"operation" => new \external_value(PARAM_TEXT, 'type of operation ["view"|"edit"]', VALUE_DEFAULT),
]);
}
/**
* Parameter description for list_used_categories function
* @return \external_description
*/
public static function list_used_categories_returns() {
return new \external_multiple_structure(static::map_category_structure(true));
}
/**
* List all categories available to the current user for editing or viewing studyplans
* @param string $operation The operation to scan usage for [edit, view]
* @return array
*/
public static function list_used_categories($operation = 'edit') {
global $DB;
if ($operation == "edit") {
@ -255,6 +338,12 @@ class courseservice extends \external_api {
return $list;
}
/**
* List all categories available to the current user for editing or viewing studyplans and add information about their usage
* (Not a webservice function)
* @param string $operation
* @return stdClass[]
*/
public static function list_accessible_categories_with_usage($operation = 'edit') {
global $DB;
if ($operation == "edit") {
@ -292,11 +381,15 @@ class courseservice extends \external_api {
}
/**************************************
*
*
* Progress scanners for teacherview
*
*
**************************************/
/**
* Return value description for scan_grade_progress function
* @return external_function_parameters
*/
public static function scan_grade_progress_parameters() {
return new \external_function_parameters( [
"gradeitemid" => new \external_value(PARAM_INT, 'Grade item ID to scan progress for', VALUE_DEFAULT),
@ -305,10 +398,20 @@ class courseservice extends \external_api {
]);
}
/**
* Parameter description for scan_grade_progress function
* @return \external_description
*/
public static function scan_grade_progress_returns() {
return gradingscanner::structure(VALUE_REQUIRED);
}
/**
* Scan grade item for progress statistics
* @param mixed $gradeitemid Grade item id
* @param mixed $studyplanid Id of studyitem the grade is selected in
* @return array
*/
public static function scan_grade_progress($gradeitemid, $studyplanid) {
global $DB;
// Verify access to the study plan.
@ -330,6 +433,10 @@ class courseservice extends \external_api {
return $scanner->model();
}
/**
* Return value description for scan_completion_progress function
* @return \external_description
*/
public static function scan_completion_progress_parameters() {
return new \external_function_parameters( [
"criteriaid" => new \external_value(PARAM_INT, 'CriteriaID to scan progress for', VALUE_DEFAULT),
@ -338,10 +445,21 @@ class courseservice extends \external_api {
]);
}
/**
* Parameter description for scan_completion_progress function
* @return \external_description
*/
public static function scan_completion_progress_returns() {
return completionscanner::structure(VALUE_REQUIRED);
}
/**
* Scan criterium for progress statistics
* @param mixed $criteriaid Id of criterium
* @param mixed $studyplanid Id of studyplan relevant to this criteria
* @param mixed $courseid Id of course this cirteria is related to
* @return array
*/
public static function scan_completion_progress($criteriaid, $studyplanid, $courseid) {
global $DB;
// Verify access to the study plan.
@ -357,6 +475,10 @@ class courseservice extends \external_api {
return $scanner->model();
}
/**
* Return value description for scan_badge_progress function
* @return \external_description
*/
public static function scan_badge_progress_parameters() {
return new \external_function_parameters( [
"badgeid" => new \external_value(PARAM_INT, 'Badge to scan progress for', VALUE_DEFAULT),
@ -365,6 +487,10 @@ class courseservice extends \external_api {
]);
}
/**
* Parameter description for scan_badge_progress function
* @return \external_description
*/
public static function scan_badge_progress_returns() {
return new \external_single_structure([
"total" => new \external_value(PARAM_INT, 'Total number of students scanned'),
@ -372,6 +498,12 @@ class courseservice extends \external_api {
]);
}
/**
* Scan badge for completion progress statistica
* @param mixed $badgeid ID of the badge
* @param mixed $studyplanid ID of the relevant study plan
* @return array
*/
public static function scan_badge_progress($badgeid, $studyplanid) {
global $DB;
// Check access to the study plan.

142
classes/gradeinfo.php
View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Collect, process and display information about gradable items
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -29,34 +29,60 @@ require_once($CFG->dirroot.'/course/lib.php');
use core_course\local\repository\caching_content_item_readonly_repository;
use core_course\local\repository\content_item_readonly_repository;
use core_course\local\entity\content_item;
use \grade_item;
use \grade_scale;
use \grade_outcome;
use \core_plugin_manager;
/**
* Collect, process and display information about gradable items
*/
class gradeinfo {
/** @var studyitem */
private $studyitem = null;
/** @var int */
private $id;
/** @var grade_item */
private $gradeitem;
/** @var string */
private $icon;
/** @var string */
private $link;
/** @var string */
private $gradinglink;
/** @var grade_scale*/
private $scale;
/** @var grade_outcome*/
private $outcome;
/** @var bool*/
private $hidden = false;
/** @var string */
private $name;
/** @var string */
private $typename;
/** @var int */
private $section;
/** @var int */
private $sectionorder;
/** @var int */
private $cmid;
/** @var int */
private $coursesort;
/** @var array */
private static $contentitems = null;
/** @var gradingscanner */
private $gradingscanner;
/** @var array */
private static $sections = [];
/**
* Get the sequence of activities for a given section id
* @param mixed $sectionid Id of section
* @return int[] Sequence of cms in a section
*/
protected static function get_sectionsequence($sectionid) {
global $DB;
if (!array_key_exists($sectionid, self::$sections)) {
@ -65,19 +91,34 @@ class gradeinfo {
return self::$sections[$sectionid];
}
public function get_gradeitem() {
/**
* Get the grade_item
* @return grade_item
*/
public function get_gradeitem() : grade_item {
return $this->gradeitem;
}
public function get_gradingscanner() {
/**
* Get the gradingscanner
* @return gradingscanner
*/
public function get_gradingscanner() : gradingscanner{
return $this->gradingscanner;
}
public function get_scale() {
/**
* Get the grade's scale if applicable
* @return grade_scale|null
*/
public function get_scale() : ?grade_scale{
return $this->scale;
}
protected static function get_contentitems() {
/**
* Get content items (activity icons) from the repository
* @return content_item[]
*/
protected static function get_contentitems() : array {
global $PAGE;
if (empty(static::$contentitems)) {
$PAGE->set_context(\context_system::instance());
@ -86,7 +127,12 @@ class gradeinfo {
return static::$contentitems;
}
public static function get_contentitem($name) {
/**
* Get specific contentitem (activity icons) by name
* @param mixed $name Name of content item
* @return content_item|null
*/
public static function get_contentitem($name) : ?content_item {
$contentitems = static::get_contentitems();
for ($i = 0; $i < count($contentitems); $i++) {
if ($contentitems[$i]->get_name() == $name) {
@ -96,7 +142,13 @@ class gradeinfo {
return null;
}
public static function get_coursecontext_by_id($id) {
/**
* Get a specific course context from grade item id
* @param int $id Grade item id
* @return context_course
* @throws InvalidArgumentException if grade id is not found
*/
public static function get_coursecontext_by_id($id) : \context_course {
$gi = grade_item::fetch(["id" => $id]);
if (!$gi || course_module_instance_pending_deletion($gi->courseid, $gi->itemmodule, $gi->iteminstance)) {
throw new \InvalidArgumentException ("Grade {$id} not found in database");
@ -104,6 +156,11 @@ class gradeinfo {
return \context_course::instance($gi->courseid);;
}
/**
* Create new object around a grade_item
* @param int $id Grade item id of the grade item to use as base
* @param studyitem|null $studyitem Studyitem containg the course that references this grade
*/
public function __construct($id, studyitem $studyitem = null) {
global $DB;
$this->studyitem = $studyitem;
@ -157,7 +214,11 @@ class gradeinfo {
}
public function is_selected() {
/**
* Check if this gradable item is selected in the studyitem
* @return bool
*/
public function is_selected() : bool {
global $DB;
if ($this->studyitem) {
// Check if selected for this studyitem.
@ -170,6 +231,10 @@ class gradeinfo {
return(false);
}
/**
* Check if this gradable item is marked required in the studyitem
* @return bool
*/
public function is_required() {
global $DB;
if ($this->studyitem) {
@ -183,6 +248,11 @@ class gradeinfo {
return(false);
}
/**
* 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) {
return new \external_single_structure([
"id" => new \external_value(PARAM_INT, 'grade_item id'),
@ -199,6 +269,11 @@ class gradeinfo {
], 'referenced course information', $value);
}
/**
* Webservice model for editor info
* @param studyitem $studyitem Related studyitem to check for
* @return array Webservice data model
*/
public function editor_model(studyitem $studyitem = null) {
$model = [
"id" => $this->id,
@ -222,6 +297,11 @@ class gradeinfo {
return $model;
}
/**
* Webservice structure for user info
* @param int $value Webservice requirement constant
* @return external_single_structure Webservice output structure
*/
public static function user_structure($value = VALUE_REQUIRED) {
return new \external_single_structure([
"id" => new \external_value(PARAM_INT, 'grade_item id'),
@ -240,6 +320,11 @@ class gradeinfo {
], 'referenced course information', $value);
}
/**
* Webservice model for user info
* @param int $userid ID of user to check specific info for
* @return array Webservice data model
*/
public function user_model($userid) {
global $DB;
$grade = $this->gradeitem->get_final($userid);
@ -282,7 +367,11 @@ class gradeinfo {
return $model;
}
public function export_model() {
/**
* Export essential information for export
* @return array information model
*/
public function export_model() : array {
return [
"name" => $this->name,
"type" => $this->gradeitem->itemmodule,
@ -290,6 +379,12 @@ class gradeinfo {
"required" => $this->is_required(),
];
}
/**
* Import data from exported model into database
* @param studyitem $item Studyitem related to this gradable
* @param array $model Model data previously exported
*/
public static function import(studyitem $item, array $model) {
if ($item->type() == studyitem::COURSE) {
$courseid = $item->courseid();
@ -314,7 +409,13 @@ class gradeinfo {
}
}
public static function list_course_gradables($course, studyitem $studyitem = null) {
/**
* 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
*/
public static function list_course_gradables($course, studyitem $studyitem = null) : array {
$list = [];
if (method_exists("\course_modinfo", "get_array_of_activities")) {
@ -352,7 +453,12 @@ class gradeinfo {
return $list;
}
public static function list_studyitem_gradables(studyitem $studyitem) {
/**
* List all gradables enabled for a given study item
* @param studyitem $studyitem The studyitem to search for
* @return self[] Array of gradeinfo
*/
public static function list_studyitem_gradables(studyitem $studyitem) : array{
global $DB;
$table = 'local_treestudyplan_gradeinc';
$list = [];
@ -378,6 +484,16 @@ class gradeinfo {
return $list;
}
/**
* Webservice executor to include grade with studyitem or not.
* if both $inclue and $required are false, any existing DB record will be removed
* @param int $gradeid ID of the grade_item
* @param int $itemid ID of the study item
* @param bool $include Select grade_item for studyitem or not
* @param bool $required Mark grade_item as required or not
* @return success Always returns successful success object
*/
public static function include_grade(int $gradeid, int $itemid, bool $include, bool $required = false) {
global $DB;
$table = 'local_treestudyplan_gradeinc';

7
classes/period.php
View File

@ -26,12 +26,19 @@ defined('MOODLE_INTERNAL') || die();
require_once($CFG->libdir.'/externallib.php');
class period {
/** @var string */
const TABLE = "local_treestudyplan_period";
private static $cache = [];
private static $pagecache = [];
/**
* Holds database record
* @var stdClass
*/
private $r; // Holds database record.
/** @var int */
private $id;
/** @var studyplanpage */
private $page;
public function aggregator() {

7
classes/studyitem.php
View File

@ -38,11 +38,18 @@ class studyitem {
public const TABLE = "local_treestudyplan_item";
private static $studyitemcache = [];
/**
* Holds database record
* @var stdClass
*/
private $r; // Holds database record.
/** @var int */
private $id;
private $courseinfo = null;
private $studyline;
/** @var aggragator[] */
/** @var aggragator */
private $aggregator;
public function context(): \context {

73
classes/studyitemconnection.php
View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/**
*
* Class to manage connection lines between study items
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -25,18 +25,38 @@ defined('MOODLE_INTERNAL') || die();
require_once($CFG->libdir.'/externallib.php');
/**
* Class to manage connection lines between study items
*/
class studyitemconnection {
/**
* Database table for this model
* @var string */
const TABLE = "local_treestudyplan_connect";
/**
* Holds database record
* @var stdClass
*/
private $r;
/** @var int */
private $id;
/**
* Construct new object based on database object
* @param stdClass $r Database record
*/
protected function __construct($r) {
$this->r = $r;
$this->id = $r->id;
}
/**
* Webservice structure for basic info
* @param int $value Webservice requirement constant
* @return external_single_structure Webservice output structure
*/
public static function structure($value = VALUE_REQUIRED) {
return new \external_single_structure([
'id' => new \external_value(PARAM_INT, 'id of connection'),
@ -45,27 +65,49 @@ class studyitemconnection {
], '', $value);
}
/**
* Webservice model for basic info
* @return array Webservice data model
*/
public function model() {
return ['id' => $this->r->id, 'from_id' => $this->r->from_id, 'to_id' => $this->r->to_id];
}
public function from_item() {
/**
* Get originating studyitem for this connection
*/
public function from_item() : studyitem {
return studyitem::find_by_id($this->r->from_id);
}
public function to_item() {
/**
* Get target studyitem for this connection
*/
public function to_item() : studyitem {
return studyitem::find_by_id($this->r->to_id);
}
public function from_id() {
/**
* Get originating studyitem id for this connection
*/
public function from_id() : int {
return $this->r->from_id;
}
public function to_id() {
/**
* Get target studyitem id for this connection
*/
public function to_id() :int {
return $this->r->to_id;
}
public static function find_outgoing($itemid) {
/**
* Get all connections originating at a given studyitem's id
* @param int $itemid Id of the studyitem
* @return self[]
*/
public static function find_outgoing($itemid) : array {
global $DB;
$list = [];
$connout = $DB->get_records(self::TABLE, ['from_id' => $itemid]);
@ -75,6 +117,11 @@ class studyitemconnection {
return $list;
}
/**
* Get all connections terminating at a given studyitem's id
* @param int $itemid Id of the studyitem
* @return self[]
*/
public static function find_incoming($itemid) {
global $DB;
$list = [];
@ -85,6 +132,11 @@ class studyitemconnection {
return $list;
}
/**
* Create a new connection between two study items
* @param int $fromid Id of the originating studyitem
* @param int $toid Id of the target studyitem
*/
public static function connect($fromid, $toid) {
global $DB;
@ -103,6 +155,11 @@ class studyitemconnection {
}
}
/**
* Delete a connection between two study items
* @param int $fromid Id of the originating studyitem
* @param int $toid Id of the target studyitem
*/
public static function disconnect($fromid, $toid) {
global $DB;
@ -118,6 +175,10 @@ class studyitemconnection {
}
}
/**
* Clear all connection to and from a given studyitem
* @param int $id Id of the studyitem
*/
public static function clear($id) {
global $DB;
$DB->delete_records(self::TABLE, ['from_id' => $id]);

7
classes/studyline.php
View File

@ -47,9 +47,16 @@ class studyline {
private static $studylinecache = [];
/**
* Holds database record
* @var stdClass
*/
private $r; // Holds database record.
/** @var int */
private $id;
/** @var studyplanpage */
private $page;
/** @var studyplan*/
private $studyplan;
public function context(): \context {

8
classes/studyplan.php
View File

@ -27,14 +27,22 @@ require_once($CFG->libdir.'/externallib.php');
class studyplan {
/** @var string */
const TABLE = "local_treestudyplan";
private static $studyplancache = [];
/**
* Holds database record
* @var stdClass
*/
private $r; // Holds database record.
/** @var int */
private $id;
/** @var aggragator */
private $aggregator;
private $context = null; // Hold context object once retrieved.
private $linkeduserids = null; // Cache lookup of linked users (saves queries).
/** @var studyplanpage[] */
private $pagecache = null;
public function aggregator() {

7
classes/studyplanpage.php
View File

@ -27,11 +27,18 @@ require_once($CFG->libdir.'/externallib.php');
class studyplanpage {
/** @var string */
const TABLE = "local_treestudyplan_page";
private static $cache = [];
/**
* Holds database record
* @var stdClass
*/
private $r; // Holds database record.
/** @var int */
private $id;
/** @var studyplan*/
private $studyplan;
public function aggregator() {

1
classes/teachingfinder.php
View File

@ -30,6 +30,7 @@ class teachingfinder {
* Table name used for caching teacher info
* @var string
*/
/** @var string */
const TABLE = "local_treestudyplan_teachers";