moodle/moodle
3
0
Fork 0
mirror of https://github.com/moodle/moodle.git synced 2025-08-04 16:36:37 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

MDL-34864 improve enrol_category phpdocs

Browse source
This commit is contained in:
Petr Škoda 2012-08-14 22:16:36 +02:00
parent 455748c882
commit 6c326e2b19
9 changed files with 77 additions and 68 deletions
Download patch file Download diff file Expand all files Collapse all files

6
enrol/category/cli/sync.php
View file

@ -1,5 +1,4 @@
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@ -26,8 +25,7 @@
* - you need to change the "www-data" to match the apache user account
* - use "su" if "sudo" not available
*
* @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
*/
@ -63,7 +61,7 @@ Example:
if (!enrol_is_enabled('category')) {
cli_error('enrol_category plugin is disabled, synchronisation stopped');
cli_error('enrol_category plugin is disabled, synchronisation stopped', 2);
}
$verbose = !empty($options['verbose']);

4
enrol/category/db/access.php
View file

@ -25,9 +25,9 @@
defined('MOODLE_INTERNAL') || die();
$capabilities = array(
// marks roles that have category role assignments synchronised to course enrolments
// Marks roles that have category role assignments synchronised to course enrolments
// overrides below system context are ignored (for performance reasons).
// by default his is not allowed in new installs, admins have to explicitly allow category enrolments
// By default his is not allowed in new installs, admins have to explicitly allow category enrolments.
'enrol/category:synchronised' => array(
'captype' => 'write',
'contextlevel' => CONTEXT_SYSTEM,

4
enrol/category/db/install.php
View file

@ -1,5 +1,4 @@
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@ -18,8 +17,7 @@
/**
* category enrolment plugin installation.
*
* @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
*/

6
enrol/category/lang/en/enrol_category.php
View file

@ -1,5 +1,4 @@
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@ -16,10 +15,9 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* 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
*/

21
enrol/category/lib.php
View file

@ -1,5 +1,4 @@
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@ -18,14 +17,14 @@
/**
* Category enrolment plugin.
*
* @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
*/
defined('MOODLE_INTERNAL') || die();
/**
* category enrolment plugin implementation.
* @author Petr Skoda
@ -36,7 +35,7 @@ class enrol_category_plugin extends enrol_plugin {
/**
* Is it possible to delete enrol instance via standard UI?
*
* @param object $instance
* @param stdClass $instance
* @return bool
*/
public function instance_deleteable($instance) {
@ -45,7 +44,7 @@ class enrol_category_plugin extends enrol_plugin {
if (!enrol_is_enabled('category')) {
return true;
}
// allow delete only when no synced users here
// Allow delete only when no synced users here.
return !$DB->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);
}
}

80
enrol/category/locallib.php
View file

@ -1,5 +1,4 @@
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@ -18,14 +17,14 @@
/**
* Local stuff for category enrolment plugin.
*
* @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
*/
defined('MOODLE_INTERNAL') || die();
/**
* Event handler for category enrolment plugin.
*
@ -33,6 +32,12 @@ defined('MOODLE_INTERNAL') || die();
* it may fail sometimes, so we always do a full sync in cron too.
*/
class enrol_category_handler {
/**
* Triggered when user is assigned a new role.
* @static
* @param stdClass $ra
* @return bool
*/
public static function role_assigned($ra) {
global $DB;
@ -40,20 +45,20 @@ 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;
}
// 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)
// 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,13 +102,13 @@ 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
// 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;
@ -119,7 +130,7 @@ class enrol_category_handler {
foreach ($rs as $instance) {
$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) {
@ -156,7 +167,7 @@ function enrol_category_sync_course($course) {
$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
// 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 = 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)

7
enrol/category/settings.php
View file

@ -1,5 +1,4 @@
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@ -16,10 +15,9 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
* 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 ----------------------------------------------------------------------------
}

3
enrol/category/version.php
View file

@ -17,8 +17,7 @@
/**
* Category enrolment plugin version specification.
*
* @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
*/