From 259aecb26bd8168abe92b72030c96d4f3bb869ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20S=CC=8Ckoda?= Date: Tue, 14 Aug 2012 22:16:36 +0200 Subject: [PATCH] MDL-34864 improve enrol_category phpdocs --- enrol/category/cli/sync.php | 8 +- enrol/category/db/access.php | 4 +- enrol/category/db/events.php | 6 +- enrol/category/db/install.php | 4 +- enrol/category/lang/en/enrol_category.php | 6 +- enrol/category/lib.php | 25 +++--- enrol/category/locallib.php | 92 ++++++++++++++--------- enrol/category/settings.php | 7 +- 8 files changed, 81 insertions(+), 71 deletions(-) diff --git a/enrol/category/cli/sync.php b/enrol/category/cli/sync.php index 56a4b82d4dd..7db80b80acc 100644 --- a/enrol/category/cli/sync.php +++ b/enrol/category/cli/sync.php @@ -1,5 +1,4 @@ array( 'captype' => 'write', 'contextlevel' => CONTEXT_SYSTEM, diff --git a/enrol/category/db/events.php b/enrol/category/db/events.php index 66194df447d..3a678664b0a 100644 --- a/enrol/category/db/events.php +++ b/enrol/category/db/events.php @@ -17,10 +17,10 @@ /** * Category enrolment plugin event handler definition. * - * @package enrol_category - * @category event + * @package enrol_category + * @category event * @copyright 2010 Petr Skoda {@link http://skodak.org} - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); diff --git a/enrol/category/db/install.php b/enrol/category/db/install.php index 0de987f41e0..834aa6779c7 100644 --- a/enrol/category/db/install.php +++ b/enrol/category/db/install.php @@ -1,5 +1,4 @@ . /** - * Strings for component 'enrol_category', language 'en', branch 'MOODLE_20_STABLE' + * Strings for component 'enrol_category', language 'en'. * - * @package enrol - * @subpackage category + * @package enrol_category * @copyright 2010 Petr Skoda {@link http://skodak.org} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ diff --git a/enrol/category/lib.php b/enrol/category/lib.php index ba60ba049f7..e6525e36b56 100644 --- a/enrol/category/lib.php +++ b/enrol/category/lib.php @@ -1,5 +1,4 @@ record_exists('user_enrolments', array('enrolid'=>$instance->id)); } @@ -55,8 +54,8 @@ class enrol_category_plugin extends enrol_plugin { * @return moodle_url page url */ public function get_newinstance_link($courseid) { - // instances are added automatically as necessary - return NULL; + // Instances are added automatically as necessary. + return null; } /** @@ -78,8 +77,8 @@ class enrol_category_plugin extends enrol_plugin { * Called after updating/inserting course. * * @param bool $inserted true if course just inserted - * @param object $course - * @param object $data form data + * @param stdClass $course + * @param stdClass $data form data * @return void */ public function course_updated($inserted, $course, $data) { @@ -89,10 +88,8 @@ class enrol_category_plugin extends enrol_plugin { return; } - // sync category enrols + // Sync category enrols. require_once("$CFG->dirroot/enrol/category/locallib.php"); enrol_category_sync_course($course); } } - - diff --git a/enrol/category/locallib.php b/enrol/category/locallib.php index 4cd7c5c8dc3..2c16f766203 100644 --- a/enrol/category/locallib.php +++ b/enrol/category/locallib.php @@ -1,5 +1,4 @@ contextid); if ($parentcontext->contextlevel != CONTEXT_COURSECAT) { return true; } - // make sure the role is to be actually synchronised - // please note we are ignoring overrides of the synchronised capability (for performance reasons in full sync) - $syscontext = get_context_instance(CONTEXT_SYSTEM); + // Make sure the role is to be actually synchronised, + // please note we are ignoring overrides of the synchronised capability (for performance reasons in full sync). + $syscontext = context_system::instance(); if (!$DB->record_exists('role_capabilities', array('contextid'=>$syscontext->id, 'roleid'=>$ra->roleid, 'capability'=>'enrol/category:synchronised', 'permission'=>CAP_ALLOW))) { return true; } - // add necessary enrol instances + // Add necessary enrol instances. $plugin = enrol_get_plugin('category'); $sql = "SELECT c.* FROM {course} c @@ -67,7 +72,7 @@ class enrol_category_handler { } $rs->close(); - // now look for missing enrols + // Now look for missing enrolments. $sql = "SELECT e.* FROM {course} c JOIN {context} ctx ON (ctx.instanceid = c.id AND ctx.contextlevel = :courselevel AND ctx.path LIKE :match) @@ -84,6 +89,12 @@ class enrol_category_handler { return true; } + /** + * Triggered when user role is unassigned. + * @static + * @param stdClass $ra + * @return bool + */ public static function role_unassigned($ra) { global $DB; @@ -91,14 +102,14 @@ class enrol_category_handler { return true; } - // only category level roles are interesting + // Only category level roles are interesting. $parentcontext = get_context_instance_by_id($ra->contextid); if ($parentcontext->contextlevel != CONTEXT_COURSECAT) { return true; } - // now this is going to be a bit slow, take all enrolments in child courses and verify each separately - $syscontext = get_context_instance(CONTEXT_SYSTEM); + // Now this is going to be a bit slow, take all enrolments in child courses and verify each separately. + $syscontext = context_system::instance(); if (!$roles = get_roles_with_capability('enrol/category:synchronised', CAP_ALLOW, $syscontext)) { return true; } @@ -117,9 +128,9 @@ class enrol_category_handler { $params['userid'] = $ra->userid; foreach ($rs as $instance) { - $coursecontext = get_context_instance(CONTEXT_COURSE, $instance->courseid); + $coursecontext = context_course::instance($instance->courseid); $contextids = get_parent_contexts($coursecontext); - array_pop($contextids); // remove system context, we are interested in categories only + array_pop($contextids); // Remove system context, we are interested in categories only. list($contextids, $contextparams) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, 'c'); $params = array_merge($params, $contextparams); @@ -128,7 +139,7 @@ class enrol_category_handler { FROM {role_assignments} ra WHERE ra.userid = :userid AND ra.contextid $contextids AND ra.roleid $roleids"; if (!$DB->record_exists_sql($sql, $params)) { - // user does not have any interesting role in any parent context, let's unenrol + // User does not have any interesting role in any parent context, let's unenrol. $plugin->unenrol_user($instance, $ra->userid); } } @@ -140,7 +151,7 @@ class enrol_category_handler { /** * Sync all category enrolments in one course - * @param int $courseid course id + * @param stdClass $course * @return void */ function enrol_category_sync_course($course) { @@ -152,11 +163,11 @@ function enrol_category_sync_course($course) { $plugin = enrol_get_plugin('category'); - $syscontext = get_context_instance(CONTEXT_SYSTEM); + $syscontext = context_system::instance(); $roles = get_roles_with_capability('enrol/category:synchronised', CAP_ALLOW, $syscontext); if (!$roles) { - //nothing to sync, so remove the instance completely if exists + // Nothing to sync, so remove the instance completely if exists. if ($instances = $DB->get_records('enrol', array('courseid'=>$course->id, 'enrol'=>'category'))) { foreach ($instances as $instance) { $plugin->delete_instance($instance); @@ -165,10 +176,10 @@ function enrol_category_sync_course($course) { return; } - // first find out if any parent category context contains interesting role assignments - $coursecontext = get_context_instance(CONTEXT_COURSE, $course->id); + // First find out if any parent category context contains interesting role assignments. + $coursecontext = context_course::instance($course->id); $contextids = get_parent_contexts($coursecontext); - array_pop($contextids); // remove system context, we are interested in categories only + array_pop($contextids); // Remove system context, we are interested in categories only. list($roleids, $params) = $DB->get_in_or_equal(array_keys($roles), SQL_PARAMS_NAMED, 'r'); list($contextids, $contextparams) = $DB->get_in_or_equal($contextids, SQL_PARAMS_NAMED, 'c'); @@ -180,7 +191,7 @@ function enrol_category_sync_course($course) { WHERE roleid $roleids AND contextid $contextids"; if (!$DB->record_exists_sql($sql, $params)) { if ($instances = $DB->get_records('enrol', array('courseid'=>$course->id, 'enrol'=>'category'))) { - // should be max one instance, but anyway + // Should be max one instance, but anyway. foreach ($instances as $instance) { $plugin->delete_instance($instance); } @@ -188,7 +199,7 @@ function enrol_category_sync_course($course) { return; } - // make sure the enrol instance exists - there should be always only one instance + // Make sure the enrol instance exists - there should be always only one instance. $delinstances = array(); if ($instances = $DB->get_records('enrol', array('courseid'=>$course->id, 'enrol'=>'category'))) { $instance = array_shift($instances); @@ -198,7 +209,7 @@ function enrol_category_sync_course($course) { $instance = $DB->get_record('enrol', array('id'=>$i)); } - // add new enrolments + // Add new enrolments. $sql = "SELECT ra.userid, ra.estart FROM (SELECT xra.userid, MIN(xra.timemodified) AS estart FROM {role_assignments} xra @@ -214,7 +225,7 @@ function enrol_category_sync_course($course) { } $rs->close(); - // remove unwanted enrolments + // Remove unwanted enrolments. $sql = "SELECT DISTINCT ue.userid FROM {user_enrolments} ue LEFT JOIN {role_assignments} ra ON (ra.roleid $roleids AND ra.contextid $contextids AND ra.userid = ue.userid) @@ -226,13 +237,24 @@ function enrol_category_sync_course($course) { $rs->close(); if ($delinstances) { - // we have to do this as the last step in order to prevent temporary unenrolment + // We have to do this as the last step in order to prevent temporary unenrolment. foreach ($delinstances as $delinstance) { $plugin->delete_instance($delinstance); } } } +/** + * Synchronise courses in all categories. + * + * It gets out-of-sync if: + * - you move course to different category + * - reorder categories + * - disable enrol_category and enable it again + * + * @param bool $verbose + * @return int exit code - 0 is ok, 1 means error, 2 if plugin disabled + */ function enrol_category_sync_full($verbose = false) { global $DB; @@ -241,14 +263,14 @@ function enrol_category_sync_full($verbose = false) { return 2; } - // we may need a lot of time here + // We may need a lot of time here. @set_time_limit(0); $plugin = enrol_get_plugin('category'); - $syscontext = get_context_instance(CONTEXT_SYSTEM); + $syscontext = context_system::instance(); - // any interesting roles worth synchronising? + // Any interesting roles worth synchronising? if (!$roles = get_roles_with_capability('enrol/category:synchronised', CAP_ALLOW, $syscontext)) { // yay, nothing to do, so let's remove all leftovers if ($verbose) { @@ -273,10 +295,10 @@ function enrol_category_sync_full($verbose = false) { $params['courselevel'] = CONTEXT_COURSE; $params['catlevel'] = CONTEXT_COURSECAT; - // first of all add necessary enrol instances to all courses + // First of all add necessary enrol instances to all courses. $parentcat = $DB->sql_concat("cat.path", "'/%'"); $parentcctx = $DB->sql_concat("cctx.path", "'/%'"); - // need whole course records to be used by add_instance(), use inner view (ci) to + // Need whole course records to be used by add_instance(), use inner view (ci) to // get distinct records only. // TODO: Moodle 2.1. Improve enrol API to accept courseid / courserec $sql = "SELECT c.* @@ -299,8 +321,8 @@ function enrol_category_sync_full($verbose = false) { } $rs->close(); - // now look for courses that do not have any interesting roles in parent contexts, - // but still have the instance and delete them + // Now look for courses that do not have any interesting roles in parent contexts, + // but still have the instance and delete them. $sql = "SELECT e.* FROM {enrol} e JOIN {context} ctx ON (ctx.instanceid = e.courseid AND ctx.contextlevel = :courselevel) @@ -316,7 +338,7 @@ function enrol_category_sync_full($verbose = false) { } $rs->close(); - // add missing enrolments + // Add missing enrolments. $sql = "SELECT e.*, cat.userid, cat.estart FROM {enrol} e JOIN {context} ctx ON (ctx.instanceid = e.courseid AND ctx.contextlevel = :courselevel) @@ -341,7 +363,7 @@ function enrol_category_sync_full($verbose = false) { } $rs->close(); - // remove stale enrolments + // Remove stale enrolments. $sql = "SELECT e.*, ue.userid FROM {enrol} e JOIN {context} ctx ON (ctx.instanceid = e.courseid AND ctx.contextlevel = :courselevel) diff --git a/enrol/category/settings.php b/enrol/category/settings.php index a8542672406..484c23b1d87 100644 --- a/enrol/category/settings.php +++ b/enrol/category/settings.php @@ -1,5 +1,4 @@ . /** - * category enrolment plugin settings and presets. + * Category enrolment plugin settings and presets. * - * @package enrol - * @subpackage category + * @package enrol_category * @copyright 2010 Petr Skoda {@link http://skodak.org} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -35,4 +33,3 @@ if ($ADMIN->fulltree) { //--- enrol instance defaults ---------------------------------------------------------------------------- } -