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 17:00:23 +02:00
parent 6f67e5cb84
commit f0e3766957
8 changed files with 213 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
classes/aggregator.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/>.
/**
*
* Base class for aggregators
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @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');
/**
* Base class for aggregators
*/
abstract class aggregator {
private const FALLBACK = "bistate";
/** Fallback aggregator if method not found
* @var string
* */
private const FALLBACK = "core";
/** @var string[] */
private static $methodsupported = [];
/**
@ -187,7 +194,7 @@ abstract class aggregator {
/**
* Webservice structure for basic aggregator info
* @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) {
return new \external_single_structure([

30
classes/cascadecohortsync.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/>.
/**
*
* Synchronize enrolled cohorts in courses with cohorts associated with studyplans these courses are in
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @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;
/**
* Task class to synchronize enrolled cohorts in courses with cohorts associated with studyplans these courses are in
*/
class cascadecohortsync {
/** Method to use for 'enrolment'
* @var string
*/
private const METHOD = "cohort";
/** @var studyplan */
private $studyplan;
/** @var int */
private $studyplanid;
/**
* Create a synchronization task for a studyplan
* @param studyplan $studyplan The studyplan to enrol students for
*/
public function __construct(studyplan $studyplan) {
$this->studyplan = $studyplan;
$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) {
$a = [];
foreach ($array as $v) {
@ -47,6 +65,12 @@ class cascadecohortsync {
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) {
// Function shamelessly copied from tool/uploadenrolmentmethods/locallib.php.
global $DB, $CFG;
@ -67,6 +91,9 @@ class cascadecohortsync {
return $groupid;
}
/**
* Enroll all cohorts associated to the studyplan in the courses linked to this studyplan
*/
public function sync() {
global $DB;
@ -214,6 +241,5 @@ class cascadecohortsync {
}
}
}
}
}

18
classes/cascadeusersync.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/>.
/**
*
* Synchronize enrolled users in courses with users associated with studyplans these courses are in
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @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;
/**
* Task class to synchronize enrolled users in courses with users associated with studyplans these courses are in
*/
class cascadeusersync {
/**
* The method to use for enrolling students
* @var string
*/
private const METHOD = "manual";
/** @var studyplan */
private $studyplan;
/**
* Create a synchronization task for a studyplan
* @param studyplan $studyplan The studyplan to enrol students for
*/
public function __construct(studyplan $studyplan) {
$this->studyplan = $studyplan;
}
/**
* Enroll all users associated to the studyplan in the courses linked to this studyplan
*/
public function sync() {
global $DB;

35
classes/contextinfo.php
View File

@ -14,20 +14,35 @@
// 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 abstract information about (category) context for web service export
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
namespace local_treestudyplan;
use \context;
/**
* Class to abstract information about (category) context for web service export
*/
class contextinfo {
/** @var 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;
}
/**
* 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) {
return new \external_single_structure([
"name" => new \external_value(PARAM_TEXT, 'context name'),
@ -37,6 +52,10 @@ class contextinfo {
], 'context information', $value);
}
/**
* Make the webservice result model
* @return array Webservice value
*/
public function model() {
$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 {
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) {
$contextid = 1;
}

87
classes/local/gradegenerator.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/>.
/**
*
* Generate random grades and feedback to initialize development environment
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -23,10 +23,21 @@
namespace local_treestudyplan\local;
use Exception;
/**
* Generate random grades and feedback to initialize development environment
*/
class gradegenerator {
/**
* Table to store ficional skill data for students
* @var array
*/
private $table = [];
/**
* Lorem ipsum text to use if fortune is not available
* @var string[]
*/
private static $loremipsum = [
"Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
"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() {
if (file_exists("/usr/games/fortune")) {
// Get a fortune if it is available.
@ -95,10 +110,17 @@ class gradegenerator {
}
}
/**
* Constructor
*/
public function __construct() {
}
/**
* Register a new student in the skill table
* @param string $student Student identifier
*/
public function addstudent(string $student) {
if (!array_key_exists($student, $this->table)) {
$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) {
$this->addstudent($student);
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->table[$student]["firstname"] = $firstname;
$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 ) {
$this->addskill($student, $skill);
$int = $this->table[$student]["skills"][$skill]["intelligence"];
@ -166,7 +205,18 @@ class gradegenerator {
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;
$table = "local_treestudyplan_gradecfg";
@ -267,24 +317,46 @@ class gradegenerator {
return $rlist;
}
/**
* Get a fictional student's performance stats
* @param string $student Student identifier
* @return array Used stats for student
*/
public function getstats($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 {
return json_encode([
"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 {
$o = json_decode($data, true);
$this->table = $o["table"];
}
/**
* Store skills table to file
* @param string $filename The file to use
*/
public function to_file(string $filename) {
$filename = self::expand_tilde($filename);
file_put_contents($filename, $this->serialize());
}
/**
* Load skills table from file
* @param string $filename The file to use
*/
public function from_file(string $filename) {
$filename = self::expand_tilde($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) {
if (function_exists('posix_getuid') && strpos($path, '~') !== false) {
$info = posix_getpwuid(posix_getuid());

20
classes/reportinvite_form.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/>.
/**
*
* Form to edit invitations to view the user's studyplans
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @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->dirroot/local/treestudyplan/lib.php");
/**
* Form to edit invitations to view the user's studyplans
*/
class reportinvite_form extends moodleform {
// Add elements to form.
/**
* Setup form
*/
public function definition() {
global $CFG;
@ -54,11 +60,21 @@ class reportinvite_form extends moodleform {
$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) {
return array();
}
/**
* Get supplied user data
* @return array The supplied data
*/
public function get_data() {
global $DB, $USER;

3
classes/success.php
View File

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

28
classes/teachingfinder.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 find and cache which studyplans a teacher is teaching courses in
* @package local_treestudyplan
* @copyright 2023 P.M. Kuipers
* @license https://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@ -22,9 +22,21 @@
namespace local_treestudyplan;
/**
* Class to find and cache which studyplans a teacher is teaching courses in
*/
class teachingfinder {
/**
* Table name used for caching teacher info
* @var string
*/
const TABLE = "local_treestudyplan_teachers";
/**
* List all studyplans the vurrent user is teaching
* @return studyplan[] List of studyplans
*/
public static function list_my_plans() {
global $USER, $DB;
$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)
* 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) {
global $DB;
@ -95,11 +108,20 @@ class teachingfinder {
return $list;
}
/**
* List of recognized teacher id's
* @return intp[]
*/
public static function list_teacher_ids() {
global $DB;
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 {
global $DB;
$r = $DB->get_field_sql("SELECT MIN(update_time) FROM {".self::TABLE."} WHERE teacher_id=:teacher_id",