PHPDoc documentation

This commit is contained in:
PMKuipers 2023-08-27 17:00:23 +02:00
parent 6f67e5cb84
commit f0e3766957
8 changed files with 213 additions and 21 deletions

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License // You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>. // along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/** /**
* * Base class for aggregators
* @package local_treestudyplan * @package local_treestudyplan
* @copyright 2023 P.M. Kuipers * @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -27,8 +27,15 @@ defined('MOODLE_INTERNAL') || die();
require_once($CFG->libdir.'/externallib.php'); require_once($CFG->libdir.'/externallib.php');
/**
* Base class for aggregators
*/
abstract class aggregator { abstract class aggregator {
private const FALLBACK = "bistate"; /** Fallback aggregator if method not found
* @var string
* */
private const FALLBACK = "core";
/** @var string[] */
private static $methodsupported = []; private static $methodsupported = [];
/** /**
@ -187,7 +194,7 @@ abstract class aggregator {
/** /**
* Webservice structure for basic aggregator info * Webservice structure for basic aggregator info
* @param int $value Webservice requirement constant * @param int $value Webservice requirement constant
* @return mixed Webservice output structure * @return external_single_structure Webservice output structure
*/ */
public static function basic_structure($value = VALUE_REQUIRED) { public static function basic_structure($value = VALUE_REQUIRED) {
return new \external_single_structure([ return new \external_single_structure([

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License // You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>. // along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/** /**
* * Synchronize enrolled cohorts in courses with cohorts associated with studyplans these courses are in
* @package local_treestudyplan * @package local_treestudyplan
* @copyright 2023 P.M. Kuipers * @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -27,16 +27,34 @@ require_once($CFG->libdir.'/externallib.php');
use \local_treestudyplan\studyplan; use \local_treestudyplan\studyplan;
/**
* Task class to synchronize enrolled cohorts in courses with cohorts associated with studyplans these courses are in
*/
class cascadecohortsync { class cascadecohortsync {
/** Method to use for 'enrolment'
* @var string
*/
private const METHOD = "cohort"; private const METHOD = "cohort";
/** @var studyplan */
private $studyplan; private $studyplan;
/** @var int */
private $studyplanid; private $studyplanid;
/**
* Create a synchronization task for a studyplan
* @param studyplan $studyplan The studyplan to enrol students for
*/
public function __construct(studyplan $studyplan) { public function __construct(studyplan $studyplan) {
$this->studyplan = $studyplan; $this->studyplan = $studyplan;
$this->studyplanid = $studyplan->id(); $this->studyplanid = $studyplan->id();
} }
/**
* Remove a value from an array
* @param array $array The array to process
* @param mixed $value The value to remove
* @return array The array with the specified value removed
*/
private static function array_remove_value($array, $value) { private static function array_remove_value($array, $value) {
$a = []; $a = [];
foreach ($array as $v) { foreach ($array as $v) {
@ -47,6 +65,12 @@ class cascadecohortsync {
return $a; return $a;
} }
/**
* Get or create a group for the cohort to synch to this course
* @param int $courseid ID of the course
* @param string $groupname Name of the group
* @return int Id of the found or created group
*/
private static function uploadenrolmentmethods_get_group($courseid, $groupname) { private static function uploadenrolmentmethods_get_group($courseid, $groupname) {
// Function shamelessly copied from tool/uploadenrolmentmethods/locallib.php. // Function shamelessly copied from tool/uploadenrolmentmethods/locallib.php.
global $DB, $CFG; global $DB, $CFG;
@ -67,6 +91,9 @@ class cascadecohortsync {
return $groupid; return $groupid;
} }
/**
* Enroll all cohorts associated to the studyplan in the courses linked to this studyplan
*/
public function sync() { public function sync() {
global $DB; global $DB;
@ -214,6 +241,5 @@ class cascadecohortsync {
} }
} }
} }
} }
} }

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License // You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>. // along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/** /**
* * Synchronize enrolled users in courses with users associated with studyplans these courses are in
* @package local_treestudyplan * @package local_treestudyplan
* @copyright 2023 P.M. Kuipers * @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -27,14 +27,30 @@ require_once($CFG->libdir.'/externallib.php');
use \local_treestudyplan\studyplan; use \local_treestudyplan\studyplan;
/**
* Task class to synchronize enrolled users in courses with users associated with studyplans these courses are in
*/
class cascadeusersync { class cascadeusersync {
/**
* The method to use for enrolling students
* @var string
*/
private const METHOD = "manual"; private const METHOD = "manual";
/** @var studyplan */
private $studyplan; private $studyplan;
/**
* Create a synchronization task for a studyplan
* @param studyplan $studyplan The studyplan to enrol students for
*/
public function __construct(studyplan $studyplan) { public function __construct(studyplan $studyplan) {
$this->studyplan = $studyplan; $this->studyplan = $studyplan;
} }
/**
* Enroll all users associated to the studyplan in the courses linked to this studyplan
*/
public function sync() { public function sync() {
global $DB; global $DB;

View File

@ -14,20 +14,35 @@
// You should have received a copy of the GNU General Public License // You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>. // along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/** /**
* * Class to abstract information about (category) context for web service export
* @package local_treestudyplan * @package local_treestudyplan
* @copyright 2023 P.M. Kuipers * @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/ */
namespace local_treestudyplan; namespace local_treestudyplan;
use \context;
/**
* Class to abstract information about (category) context for web service export
*/
class contextinfo { class contextinfo {
/** @var context */
public $context; public $context;
public function __construct($context) {
/**
* Create new based on context
* @param context $context The context to describe
*/
public function __construct(context $context) {
$this->context = $context; $this->context = $context;
} }
/**
* Describe the result for the webservice model
* @param int $value Webservice requirement constant
* @return external_single_structure Webservice output structure
*/
public static function structure($value = VALUE_REQUIRED) { public static function structure($value = VALUE_REQUIRED) {
return new \external_single_structure([ return new \external_single_structure([
"name" => new \external_value(PARAM_TEXT, 'context name'), "name" => new \external_value(PARAM_TEXT, 'context name'),
@ -37,6 +52,10 @@ class contextinfo {
], 'context information', $value); ], 'context information', $value);
} }
/**
* Make the webservice result model
* @return array Webservice value
*/
public function model() { public function model() {
$ctxpath = array_reverse($this->context->get_parent_context_ids(true)); $ctxpath = array_reverse($this->context->get_parent_context_ids(true));
@ -55,11 +74,21 @@ 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 { public static function by_id($contextid): self {
return new self(self::context_by_id($contextid)); return new self(self::context_by_id($contextid));
} }
public static function context_by_id($contextid): \context { /**
* Find context by id, but also return system context for context id 0
* @param int $contextid Context id
* @return context The context
*/
private static function context_by_id($contextid): \context {
if ($contextid <= 1) { if ($contextid <= 1) {
$contextid = 1; $contextid = 1;
} }

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License // You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>. // along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/** /**
* * Generate random grades and feedback to initialize development environment
* @package local_treestudyplan * @package local_treestudyplan
* @copyright 2023 P.M. Kuipers * @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -23,10 +23,21 @@
namespace local_treestudyplan\local; namespace local_treestudyplan\local;
use Exception; use Exception;
/**
* Generate random grades and feedback to initialize development environment
*/
class gradegenerator { class gradegenerator {
/**
* Table to store ficional skill data for students
* @var array
*/
private $table = []; private $table = [];
/**
* Lorem ipsum text to use if fortune is not available
* @var string[]
*/
private static $loremipsum = [ private static $loremipsum = [
"Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"Etiam scelerisque ligula porttitor velit sollicitudin blandit.", "Etiam scelerisque ligula porttitor velit sollicitudin blandit.",
@ -85,6 +96,10 @@ class gradegenerator {
]; ];
/**
* Generate random feedback from fortune or internal loremipsum text
* @return string Randomized text to use as feedback
*/
private function generatedfeedback() { private function generatedfeedback() {
if (file_exists("/usr/games/fortune")) { if (file_exists("/usr/games/fortune")) {
// Get a fortune if it is available. // Get a fortune if it is available.
@ -95,10 +110,17 @@ class gradegenerator {
} }
} }
/**
* Constructor
*/
public function __construct() { public function __construct() {
} }
/**
* Register a new student in the skill table
* @param string $student Student identifier
*/
public function addstudent(string $student) { public function addstudent(string $student) {
if (!array_key_exists($student, $this->table)) { if (!array_key_exists($student, $this->table)) {
$this->table[$student] = [ $this->table[$student] = [
@ -109,6 +131,11 @@ class gradegenerator {
} }
} }
/**
* Add a specific skill for a student
* @param string $student Student identifier
* @param string $skill Skill identifier
*/
public function addskill(string $student, string $skill) { public function addskill(string $student, string $skill) {
$this->addstudent($student); $this->addstudent($student);
if (!array_key_exists($skill, $this->table[$student]["skills"])) { if (!array_key_exists($skill, $this->table[$student]["skills"])) {
@ -121,13 +148,25 @@ class gradegenerator {
} }
} }
// Below is mostly just for reference in the json file. /**
public function add_username_info(string $student, $firstname, $lastname) { * Register a firstname and lastname for a student identifier for reference in the json file.
* @param string $student Student identifier
* @param string $firstname First name for student
* @param string $lastname Last name for student
*/
public function add_username_info(string $student, string $firstname, string $lastname) {
$this->addstudent($student); $this->addstudent($student);
$this->table[$student]["firstname"] = $firstname; $this->table[$student]["firstname"] = $firstname;
$this->table[$student]["lastname"] = $lastname; $this->table[$student]["lastname"] = $lastname;
} }
/**
* Generate a number of random results for a given student and skill
* @param string $student Student identifier
* @param string $skill Skill identifier
* @param int $count Number of results to generate
* @return array Raw outcomes
*/
public function generateraw($student, $skill, $count ) { public function generateraw($student, $skill, $count ) {
$this->addskill($student, $skill); $this->addskill($student, $skill);
$int = $this->table[$student]["skills"][$skill]["intelligence"]; $int = $this->table[$student]["skills"][$skill]["intelligence"];
@ -166,7 +205,18 @@ class gradegenerator {
return $results; return $results;
} }
public function generate($student, $skill, array $gradeinfos ) { /**
* Generate results for a number of gradeinfo
* Returns (object)[ "gi" => <gradeinfo object>,
* "grade" => <randomized grade>
* "fb" => <randomized feedback>
* ];
* @param string $student Student identifier
* @param string $skill Skill identifier
* @param gradeinfo[] $gradeinfos
* @return stdClass[] List of gradeinfo related results ready to add
*/
public function generate(string $student, string $skill, array $gradeinfos ) {
global $DB; global $DB;
$table = "local_treestudyplan_gradecfg"; $table = "local_treestudyplan_gradecfg";
@ -267,24 +317,46 @@ class gradegenerator {
return $rlist; return $rlist;
} }
/**
* Get a fictional student's performance stats
* @param string $student Student identifier
* @return array Used stats for student
*/
public function getstats($student) { public function getstats($student) {
return $this->table[$student]; return $this->table[$student];
} }
/**
* Store skills table into a string
* @return string|null Json encoded string of the skills table
*/
public function serialize(): ?string { public function serialize(): ?string {
return json_encode([ return json_encode([
"table" => $this->table], JSON_PRETTY_PRINT); "table" => $this->table], JSON_PRETTY_PRINT);
} }
/**
* Load skills table from stored data
* @param string $data Json encoded string of the skills table
*/
public function unserialize(string $data): void { public function unserialize(string $data): void {
$o = json_decode($data, true); $o = json_decode($data, true);
$this->table = $o["table"]; $this->table = $o["table"];
} }
/**
* Store skills table to file
* @param string $filename The file to use
*/
public function to_file(string $filename) { public function to_file(string $filename) {
$filename = self::expand_tilde($filename); $filename = self::expand_tilde($filename);
file_put_contents($filename, $this->serialize()); file_put_contents($filename, $this->serialize());
} }
/**
* Load skills table from file
* @param string $filename The file to use
*/
public function from_file(string $filename) { public function from_file(string $filename) {
$filename = self::expand_tilde($filename); $filename = self::expand_tilde($filename);
if (file_exists($filename)) { if (file_exists($filename)) {
@ -298,6 +370,11 @@ class gradegenerator {
} }
} }
/**
* Internal function to properly handle the ~ symbol in unix context
* @param string $path A unix path
* @return string Unix path with ~ symbol properly expanded to user home dir
*/
private static function expand_tilde($path) { private static function expand_tilde($path) {
if (function_exists('posix_getuid') && strpos($path, '~') !== false) { if (function_exists('posix_getuid') && strpos($path, '~') !== false) {
$info = posix_getpwuid(posix_getuid()); $info = posix_getpwuid(posix_getuid());

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License // You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>. // along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/** /**
* * Form to edit invitations to view the user's studyplans
* @package local_treestudyplan * @package local_treestudyplan
* @copyright 2023 P.M. Kuipers * @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -25,9 +25,15 @@ defined('MOODLE_INTERNAL') || die();
require_once("$CFG->libdir/formslib.php"); require_once("$CFG->libdir/formslib.php");
require_once("$CFG->dirroot/local/treestudyplan/lib.php"); require_once("$CFG->dirroot/local/treestudyplan/lib.php");
/**
* Form to edit invitations to view the user's studyplans
*/
class reportinvite_form extends moodleform { class reportinvite_form extends moodleform {
// Add elements to form. // Add elements to form.
/**
* Setup form
*/
public function definition() { public function definition() {
global $CFG; global $CFG;
@ -54,11 +60,21 @@ class reportinvite_form extends moodleform {
$this->add_action_buttons(); $this->add_action_buttons();
} }
// Custom validation should be added here.
/**
* Custom validation should be added here.
* @param array $data Supplied user data
* @param array $files Any uploaded files
* @return array validation data
*/
public function validation($data, $files) { public function validation($data, $files) {
return array(); return array();
} }
/**
* Get supplied user data
* @return array The supplied data
*/
public function get_data() { public function get_data() {
global $DB, $USER; global $DB, $USER;

View File

@ -67,7 +67,7 @@ class success {
} }
/** /**
* Describe the result for the * Describe the result for the webservice model
* @return external_single_structure * @return external_single_structure
*/ */
public static function structure() { public static function structure() {
@ -80,7 +80,6 @@ class success {
/** /**
* Make the webservice result model * Make the webservice result model
*
* @return array Webservice value * @return array Webservice value
*/ */
public function model() { public function model() {

View File

@ -14,7 +14,7 @@
// You should have received a copy of the GNU General Public License // You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <https://www.gnu.org/licenses/>. // along with Moodle. If not, see <https://www.gnu.org/licenses/>.
/** /**
* * Class to find and cache which studyplans a teacher is teaching courses in
* @package local_treestudyplan * @package local_treestudyplan
* @copyright 2023 P.M. Kuipers * @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later * @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -22,9 +22,21 @@
namespace local_treestudyplan; namespace local_treestudyplan;
/**
* Class to find and cache which studyplans a teacher is teaching courses in
*/
class teachingfinder { class teachingfinder {
/**
* Table name used for caching teacher info
* @var string
*/
const TABLE = "local_treestudyplan_teachers"; const TABLE = "local_treestudyplan_teachers";
/**
* List all studyplans the vurrent user is teaching
* @return studyplan[] List of studyplans
*/
public static function list_my_plans() { public static function list_my_plans() {
global $USER, $DB; global $USER, $DB;
$userid = $USER->id; $userid = $USER->id;
@ -43,9 +55,10 @@ class teachingfinder {
} }
/** /**
* Find The active studyplans where the specified user is a teacher * Find The active studyplan pages where the specified user is a teacher
* (Has the mod/assign::grade capability in one of the linked courses) * (Has the mod/assign::grade capability in one of the linked courses)
* TODO: OPTIMIZE THIS CHECK!!! * @param int $userid The userid to check teacher rights for
* @return int[] List of page id's a teacher is teaching courses in
*/ */
public static function update_teaching_cache($userid) { public static function update_teaching_cache($userid) {
global $DB; global $DB;
@ -95,11 +108,20 @@ class teachingfinder {
return $list; return $list;
} }
/**
* List of recognized teacher id's
* @return intp[]
*/
public static function list_teacher_ids() { public static function list_teacher_ids() {
global $DB; global $DB;
return $DB->get_fieldset_sql("SELECT DISTINCT teacher_id FROM {".self::TABLE."}"); return $DB->get_fieldset_sql("SELECT DISTINCT teacher_id FROM {".self::TABLE."}");
} }
/**
* Get the last time of update for the specified teacher
* @param int $teacherid User id of teacher
* @return int Unix timestamp
*/
public static function get_update_time($teacherid): int { public static function get_update_time($teacherid): int {
global $DB; global $DB;
$r = $DB->get_field_sql("SELECT MIN(update_time) FROM {".self::TABLE."} WHERE teacher_id=:teacher_id", $r = $DB->get_field_sql("SELECT MIN(update_time) FROM {".self::TABLE."} WHERE teacher_id=:teacher_id",