weekly release 2.3dev
[moodle.git] / lib / enrollib.php
CommitLineData
df997f84
PS
1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
19 * This library includes the basic parts of enrol api.
20 * It is available on each page.
21 *
78bfb562
PS
22 * @package core
23 * @subpackage enrol
24 * @copyright 2010 Petr Skoda {@link http://skodak.org}
25 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
df997f84
PS
26 */
27
78bfb562 28defined('MOODLE_INTERNAL') || die();
df997f84
PS
29
30/** Course enrol instance enabled. (used in enrol->status) */
31define('ENROL_INSTANCE_ENABLED', 0);
32
33/** Course enrol instance disabled, user may enter course if other enrol instance enabled. (used in enrol->status)*/
34define('ENROL_INSTANCE_DISABLED', 1);
35
36/** User is active participant (used in user_enrolments->status)*/
37define('ENROL_USER_ACTIVE', 0);
38
39/** User participation in course is suspended (used in user_enrolments->status) */
40define('ENROL_USER_SUSPENDED', 1);
41
bbfdff34 42/** @deprecated - enrol caching was reworked, use ENROL_MAX_TIMESTAMP instead */
df997f84
PS
43define('ENROL_REQUIRE_LOGIN_CACHE_PERIOD', 1800);
44
bbfdff34
PS
45/** The timestamp indicating forever */
46define('ENROL_MAX_TIMESTAMP', 2147483647);
47
34121765
PS
48/** When user disappears from external source, the enrolment is completely removed */
49define('ENROL_EXT_REMOVED_UNENROL', 0);
50
51/** When user disappears from external source, the enrolment is kept as is - one way sync */
52define('ENROL_EXT_REMOVED_KEEP', 1);
53
f2a9be5f
EL
54/** enrol plugin feature describing requested restore type */
55define('ENROL_RESTORE_TYPE', 'enrolrestore');
56/** User custom backup/restore class stored in backup/moodle2/ subdirectory */
57define('ENROL_RESTORE_CLASS', 'class');
58/** Restore all custom fields from enrol table without any changes and all user_enrolments records */
59define('ENROL_RESTORE_EXACT', 'exact');
60/** Restore enrol record like ENROL_RESTORE_EXACT, but no user enrolments */
61define('ENROL_RESTORE_NOUSERS', 'nousers');
62
34121765
PS
63/**
64 * When user disappears from external source, user enrolment is suspended, roles are kept as is.
65 * In some cases user needs a role with some capability to be visible in UI - suc has in gradebook,
66 * assignments, etc.
67 */
68define('ENROL_EXT_REMOVED_SUSPEND', 2);
69
70/**
71 * When user disappears from external source, the enrolment is suspended and roles assigned
72 * by enrol instance are removed. Please note that user may "disappear" from gradebook and other areas.
73 * */
74define('ENROL_EXT_REMOVED_SUSPENDNOROLES', 3);
75
df997f84
PS
76/**
77 * Returns instances of enrol plugins
bbfdff34 78 * @param bool $enabled return enabled only
df997f84
PS
79 * @return array of enrol plugins name=>instance
80 */
81function enrol_get_plugins($enabled) {
82 global $CFG;
83
84 $result = array();
85
86 if ($enabled) {
87 // sorted by enabled plugin order
88 $enabled = explode(',', $CFG->enrol_plugins_enabled);
89 $plugins = array();
90 foreach ($enabled as $plugin) {
91 $plugins[$plugin] = "$CFG->dirroot/enrol/$plugin";
92 }
93 } else {
94 // sorted alphabetically
95 $plugins = get_plugin_list('enrol');
96 ksort($plugins);
97 }
98
99 foreach ($plugins as $plugin=>$location) {
100 if (!file_exists("$location/lib.php")) {
101 continue;
102 }
103 include_once("$location/lib.php");
104 $class = "enrol_{$plugin}_plugin";
105 if (!class_exists($class)) {
106 continue;
107 }
108
109 $result[$plugin] = new $class();
110 }
111
112 return $result;
113}
114
115/**
116 * Returns instance of enrol plugin
117 * @param string $name name of enrol plugin ('manual', 'guest', ...)
118 * @return enrol_plugin
119 */
120function enrol_get_plugin($name) {
121 global $CFG;
122
aff24313
PS
123 $name = clean_param($name, PARAM_PLUGIN);
124
125 if (empty($name)) {
126 // ignore malformed or missing plugin names completely
df997f84
PS
127 return null;
128 }
129
130 $location = "$CFG->dirroot/enrol/$name";
131
132 if (!file_exists("$location/lib.php")) {
133 return null;
134 }
135 include_once("$location/lib.php");
136 $class = "enrol_{$name}_plugin";
137 if (!class_exists($class)) {
138 return null;
139 }
140
141 return new $class();
142}
143
144/**
145 * Returns enrolment instances in given course.
146 * @param int $courseid
147 * @param bool $enabled
148 * @return array of enrol instances
149 */
150function enrol_get_instances($courseid, $enabled) {
151 global $DB, $CFG;
152
153 if (!$enabled) {
154 return $DB->get_records('enrol', array('courseid'=>$courseid), 'sortorder,id');
155 }
156
157 $result = $DB->get_records('enrol', array('courseid'=>$courseid, 'status'=>ENROL_INSTANCE_ENABLED), 'sortorder,id');
158
79721bd3 159 $enabled = explode(',', $CFG->enrol_plugins_enabled);
df997f84
PS
160 foreach ($result as $key=>$instance) {
161 if (!in_array($instance->enrol, $enabled)) {
162 unset($result[$key]);
163 continue;
164 }
165 if (!file_exists("$CFG->dirroot/enrol/$instance->enrol/lib.php")) {
166 // broken plugin
167 unset($result[$key]);
168 continue;
169 }
170 }
171
172 return $result;
173}
174
175/**
176 * Checks if a given plugin is in the list of enabled enrolment plugins.
177 *
178 * @param string $enrol Enrolment plugin name
179 * @return boolean Whether the plugin is enabled
180 */
181function enrol_is_enabled($enrol) {
182 global $CFG;
183
184 if (empty($CFG->enrol_plugins_enabled)) {
185 return false;
186 }
187 return in_array($enrol, explode(',', $CFG->enrol_plugins_enabled));
188}
189
190/**
191 * Check all the login enrolment information for the given user object
192 * by querying the enrolment plugins
193 *
e922fe23
PS
194 * This function may be very slow, use only once after log-in or login-as.
195 *
196 * @param stdClass $user
df997f84
PS
197 * @return void
198 */
199function enrol_check_plugins($user) {
200 global $CFG;
201
202 if (empty($user->id) or isguestuser($user)) {
203 // shortcut - there is no enrolment work for guests and not-logged-in users
204 return;
205 }
206
bcb368d9
PS
207 // originally there was a broken admin test, but accidentally it was non-functional in 2.2,
208 // which proved it was actually not necessary.
e384d2dc 209
df997f84
PS
210 static $inprogress = array(); // To prevent this function being called more than once in an invocation
211
212 if (!empty($inprogress[$user->id])) {
213 return;
214 }
215
216 $inprogress[$user->id] = true; // Set the flag
217
218 $enabled = enrol_get_plugins(true);
219
220 foreach($enabled as $enrol) {
221 $enrol->sync_user_enrolments($user);
222 }
223
224 unset($inprogress[$user->id]); // Unset the flag
225}
226
181991e7
PS
227/**
228 * Do these two students share any course?
229 *
230 * The courses has to be visible and enrolments has to be active,
231 * timestart and timeend restrictions are ignored.
232 *
61ab8f07
SH
233 * This function calls {@see enrol_get_shared_courses()} setting checkexistsonly
234 * to true.
235 *
181991e7
PS
236 * @param stdClass|int $user1
237 * @param stdClass|int $user2
238 * @return bool
239 */
240function enrol_sharing_course($user1, $user2) {
61ab8f07 241 return enrol_get_shared_courses($user1, $user2, false, true);
181991e7
PS
242}
243
4b715423
SH
244/**
245 * Returns any courses shared by the two users
246 *
247 * The courses has to be visible and enrolments has to be active,
248 * timestart and timeend restrictions are ignored.
249 *
61ab8f07 250 * @global moodle_database $DB
4b715423
SH
251 * @param stdClass|int $user1
252 * @param stdClass|int $user2
61ab8f07
SH
253 * @param bool $preloadcontexts If set to true contexts for the returned courses
254 * will be preloaded.
255 * @param bool $checkexistsonly If set to true then this function will return true
256 * if the users share any courses and false if not.
257 * @return array|bool An array of courses that both users are enrolled in OR if
258 * $checkexistsonly set returns true if the users share any courses
259 * and false if not.
4b715423 260 */
61ab8f07 261function enrol_get_shared_courses($user1, $user2, $preloadcontexts = false, $checkexistsonly = false) {
4b715423
SH
262 global $DB, $CFG;
263
5b244e2b
HD
264 $user1 = isset($user1->id) ? $user1->id : $user1;
265 $user2 = isset($user2->id) ? $user2->id : $user2;
4b715423
SH
266
267 if (empty($user1) or empty($user2)) {
268 return false;
269 }
270
271 if (!$plugins = explode(',', $CFG->enrol_plugins_enabled)) {
272 return false;
273 }
274
275 list($plugins, $params) = $DB->get_in_or_equal($plugins, SQL_PARAMS_NAMED, 'ee');
276 $params['enabled'] = ENROL_INSTANCE_ENABLED;
277 $params['active1'] = ENROL_USER_ACTIVE;
278 $params['active2'] = ENROL_USER_ACTIVE;
279 $params['user1'] = $user1;
280 $params['user2'] = $user2;
281
282 $ctxselect = '';
283 $ctxjoin = '';
284 if ($preloadcontexts) {
285 list($ctxselect, $ctxjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
286 }
287
288 $sql = "SELECT c.* $ctxselect
289 FROM {course} c
290 JOIN (
291 SELECT DISTINCT c.id
292 FROM {enrol} e
293 JOIN {user_enrolments} ue1 ON (ue1.enrolid = e.id AND ue1.status = :active1 AND ue1.userid = :user1)
294 JOIN {user_enrolments} ue2 ON (ue2.enrolid = e.id AND ue2.status = :active2 AND ue2.userid = :user2)
295 JOIN {course} c ON (c.id = e.courseid AND c.visible = 1)
296 WHERE e.status = :enabled AND e.enrol $plugins
297 ) ec ON ec.id = c.id
298 $ctxjoin";
4b715423 299
61ab8f07
SH
300 if ($checkexistsonly) {
301 return $DB->record_exists_sql($sql, $params);
302 } else {
303 $courses = $DB->get_records_sql($sql, $params);
304 if ($preloadcontexts) {
305 array_map('context_instance_preload', $courses);
306 }
307 return $courses;
308 }
4b715423
SH
309}
310
df997f84
PS
311/**
312 * This function adds necessary enrol plugins UI into the course edit form.
313 *
314 * @param MoodleQuickForm $mform
315 * @param object $data course edit form data
316 * @param object $context context of existing course or parent category if course does not exist
317 * @return void
318 */
319function enrol_course_edit_form(MoodleQuickForm $mform, $data, $context) {
320 $plugins = enrol_get_plugins(true);
321 if (!empty($data->id)) {
322 $instances = enrol_get_instances($data->id, false);
323 foreach ($instances as $instance) {
324 if (!isset($plugins[$instance->enrol])) {
325 continue;
326 }
327 $plugin = $plugins[$instance->enrol];
328 $plugin->course_edit_form($instance, $mform, $data, $context);
329 }
330 } else {
331 foreach ($plugins as $plugin) {
332 $plugin->course_edit_form(NULL, $mform, $data, $context);
333 }
334 }
335}
336
337/**
338 * Validate course edit form data
339 *
340 * @param array $data raw form data
341 * @param object $context context of existing course or parent category if course does not exist
342 * @return array errors array
343 */
344function enrol_course_edit_validation(array $data, $context) {
345 $errors = array();
346 $plugins = enrol_get_plugins(true);
347
348 if (!empty($data['id'])) {
349 $instances = enrol_get_instances($data['id'], false);
350 foreach ($instances as $instance) {
351 if (!isset($plugins[$instance->enrol])) {
352 continue;
353 }
354 $plugin = $plugins[$instance->enrol];
355 $errors = array_merge($errors, $plugin->course_edit_validation($instance, $data, $context));
356 }
357 } else {
358 foreach ($plugins as $plugin) {
359 $errors = array_merge($errors, $plugin->course_edit_validation(NULL, $data, $context));
360 }
361 }
362
363 return $errors;
364}
365
366/**
367 * Update enrol instances after course edit form submission
368 * @param bool $inserted true means new course added, false course already existed
369 * @param object $course
370 * @param object $data form data
371 * @return void
372 */
373function enrol_course_updated($inserted, $course, $data) {
374 global $DB, $CFG;
375
376 $plugins = enrol_get_plugins(true);
377
378 foreach ($plugins as $plugin) {
379 $plugin->course_updated($inserted, $course, $data);
380 }
381}
382
383/**
384 * Add navigation nodes
385 * @param navigation_node $coursenode
386 * @param object $course
387 * @return void
388 */
389function enrol_add_course_navigation(navigation_node $coursenode, $course) {
6e4c374d 390 global $CFG;
df997f84
PS
391
392 $coursecontext = get_context_instance(CONTEXT_COURSE, $course->id);
393
394 $instances = enrol_get_instances($course->id, true);
395 $plugins = enrol_get_plugins(true);
396
397 // we do not want to break all course pages if there is some borked enrol plugin, right?
398 foreach ($instances as $k=>$instance) {
399 if (!isset($plugins[$instance->enrol])) {
400 unset($instances[$k]);
401 }
402 }
403
f5ce6b71 404 $usersnode = $coursenode->add(get_string('users'), null, navigation_node::TYPE_CONTAINER, null, 'users');
df997f84
PS
405
406 if ($course->id != SITEID) {
f5ce6b71 407 // list all participants - allows assigning roles, groups, etc.
df997f84
PS
408 if (has_capability('moodle/course:enrolreview', $coursecontext)) {
409 $url = new moodle_url('/enrol/users.php', array('id'=>$course->id));
f5ce6b71 410 $usersnode->add(get_string('enrolledusers', 'enrol'), $url, navigation_node::TYPE_SETTING, null, 'review', new pix_icon('i/users', ''));
df997f84
PS
411 }
412
413 // manage enrol plugin instances
414 if (has_capability('moodle/course:enrolconfig', $coursecontext) or has_capability('moodle/course:enrolreview', $coursecontext)) {
415 $url = new moodle_url('/enrol/instances.php', array('id'=>$course->id));
416 } else {
417 $url = NULL;
418 }
f5ce6b71 419 $instancesnode = $usersnode->add(get_string('enrolmentinstances', 'enrol'), $url, navigation_node::TYPE_SETTING, null, 'manageinstances');
df997f84
PS
420
421 // each instance decides how to configure itself or how many other nav items are exposed
422 foreach ($instances as $instance) {
423 if (!isset($plugins[$instance->enrol])) {
424 continue;
425 }
426 $plugins[$instance->enrol]->add_course_navigation($instancesnode, $instance);
427 }
428
429 if (!$url) {
430 $instancesnode->trim_if_empty();
431 }
432 }
433
434 // Manage groups in this course or even frontpage
435 if (($course->groupmode || !$course->groupmodeforce) && has_capability('moodle/course:managegroups', $coursecontext)) {
436 $url = new moodle_url('/group/index.php', array('id'=>$course->id));
437 $usersnode->add(get_string('groups'), $url, navigation_node::TYPE_SETTING, null, 'groups', new pix_icon('i/group', ''));
438 }
439
440 if (has_any_capability(array( 'moodle/role:assign', 'moodle/role:safeoverride','moodle/role:override', 'moodle/role:review'), $coursecontext)) {
441 // Override roles
442 if (has_capability('moodle/role:review', $coursecontext)) {
443 $url = new moodle_url('/admin/roles/permissions.php', array('contextid'=>$coursecontext->id));
444 } else {
445 $url = NULL;
446 }
f5ce6b71 447 $permissionsnode = $usersnode->add(get_string('permissions', 'role'), $url, navigation_node::TYPE_SETTING, null, 'override');
df997f84
PS
448
449 // Add assign or override roles if allowed
450 if ($course->id == SITEID or (!empty($CFG->adminsassignrolesincourse) and is_siteadmin())) {
451 if (has_capability('moodle/role:assign', $coursecontext)) {
452 $url = new moodle_url('/admin/roles/assign.php', array('contextid'=>$coursecontext->id));
f5ce6b71 453 $permissionsnode->add(get_string('assignedroles', 'role'), $url, navigation_node::TYPE_SETTING, null, 'roles', new pix_icon('i/roles', ''));
df997f84
PS
454 }
455 }
456 // Check role permissions
457 if (has_any_capability(array('moodle/role:assign', 'moodle/role:safeoverride','moodle/role:override', 'moodle/role:assign'), $coursecontext)) {
458 $url = new moodle_url('/admin/roles/check.php', array('contextid'=>$coursecontext->id));
f5ce6b71 459 $permissionsnode->add(get_string('checkpermissions', 'role'), $url, navigation_node::TYPE_SETTING, null, 'permissions', new pix_icon('i/checkpermissions', ''));
df997f84
PS
460 }
461 }
462
463 // Deal somehow with users that are not enrolled but still got a role somehow
464 if ($course->id != SITEID) {
465 //TODO, create some new UI for role assignments at course level
466 if (has_capability('moodle/role:assign', $coursecontext)) {
467 $url = new moodle_url('/enrol/otherusers.php', array('id'=>$course->id));
f5ce6b71 468 $usersnode->add(get_string('notenrolledusers', 'enrol'), $url, navigation_node::TYPE_SETTING, null, 'otherusers', new pix_icon('i/roles', ''));
df997f84
PS
469 }
470 }
471
472 // just in case nothing was actually added
473 $usersnode->trim_if_empty();
474
475 if ($course->id != SITEID) {
6813cdf7 476 if (isguestuser() or !isloggedin()) {
39ec18db 477 // guest account can not be enrolled - no links for them
6813cdf7 478 } else if (is_enrolled($coursecontext)) {
39ec18db 479 // unenrol link if possible
217d0397
PS
480 foreach ($instances as $instance) {
481 if (!isset($plugins[$instance->enrol])) {
482 continue;
483 }
484 $plugin = $plugins[$instance->enrol];
485 if ($unenrollink = $plugin->get_unenrolself_link($instance)) {
8ebbb06a
SH
486 $shortname = format_string($course->shortname, true, array('context' => $coursecontext));
487 $coursenode->add(get_string('unenrolme', 'core_enrol', $shortname), $unenrollink, navigation_node::TYPE_SETTING, null, 'unenrolself', new pix_icon('i/user', ''));
217d0397
PS
488 break;
489 //TODO. deal with multiple unenrol links - not likely case, but still...
490 }
df997f84 491 }
217d0397 492 } else {
39ec18db 493 // enrol link if possible
217d0397
PS
494 if (is_viewing($coursecontext)) {
495 // better not show any enrol link, this is intended for managers and inspectors
496 } else {
497 foreach ($instances as $instance) {
498 if (!isset($plugins[$instance->enrol])) {
499 continue;
500 }
501 $plugin = $plugins[$instance->enrol];
502 if ($plugin->show_enrolme_link($instance)) {
503 $url = new moodle_url('/enrol/index.php', array('id'=>$course->id));
8ebbb06a
SH
504 $shortname = format_string($course->shortname, true, array('context' => $coursecontext));
505 $coursenode->add(get_string('enrolme', 'core_enrol', $shortname), $url, navigation_node::TYPE_SETTING, null, 'enrolself', new pix_icon('i/user', ''));
217d0397
PS
506 break;
507 }
508 }
df997f84
PS
509 }
510 }
df997f84
PS
511 }
512}
513
514/**
515 * Returns list of courses current $USER is enrolled in and can access
516 *
517 * - $fields is an array of field names to ADD
518 * so name the fields you really need, which will
519 * be added and uniq'd
520 *
eb6f592a 521 * @param string|array $fields
df997f84
PS
522 * @param string $sort
523 * @param int $limit max number of courses
524 * @return array
525 */
526function enrol_get_my_courses($fields = NULL, $sort = 'visible DESC,sortorder ASC', $limit = 0) {
527 global $DB, $USER;
528
529 // Guest account does not have any courses
530 if (isguestuser() or !isloggedin()) {
531 return(array());
532 }
533
534 $basefields = array('id', 'category', 'sortorder',
535 'shortname', 'fullname', 'idnumber',
536 'startdate', 'visible',
537 'groupmode', 'groupmodeforce');
538
539 if (empty($fields)) {
540 $fields = $basefields;
541 } else if (is_string($fields)) {
542 // turn the fields from a string to an array
543 $fields = explode(',', $fields);
544 $fields = array_map('trim', $fields);
545 $fields = array_unique(array_merge($basefields, $fields));
546 } else if (is_array($fields)) {
547 $fields = array_unique(array_merge($basefields, $fields));
548 } else {
549 throw new coding_exception('Invalid $fileds parameter in enrol_get_my_courses()');
550 }
551 if (in_array('*', $fields)) {
552 $fields = array('*');
553 }
554
555 $orderby = "";
556 $sort = trim($sort);
557 if (!empty($sort)) {
558 $rawsorts = explode(',', $sort);
559 $sorts = array();
560 foreach ($rawsorts as $rawsort) {
561 $rawsort = trim($rawsort);
562 if (strpos($rawsort, 'c.') === 0) {
563 $rawsort = substr($rawsort, 2);
564 }
565 $sorts[] = trim($rawsort);
566 }
567 $sort = 'c.'.implode(',c.', $sorts);
568 $orderby = "ORDER BY $sort";
569 }
570
571 $wheres = array("c.id <> :siteid");
572 $params = array('siteid'=>SITEID);
573
574 if (isset($USER->loginascontext) and $USER->loginascontext->contextlevel == CONTEXT_COURSE) {
575 // list _only_ this course - anything else is asking for trouble...
576 $wheres[] = "courseid = :loginas";
577 $params['loginas'] = $USER->loginascontext->instanceid;
578 }
579
580 $coursefields = 'c.' .join(',c.', $fields);
581 list($ccselect, $ccjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
4129338c 582 $wheres = implode(" AND ", $wheres);
df997f84 583
4129338c
PS
584 //note: we can not use DISTINCT + text fields due to Oracle and MS limitations, that is why we have the subselect there
585 $sql = "SELECT $coursefields $ccselect
df997f84 586 FROM {course} c
4129338c
PS
587 JOIN (SELECT DISTINCT e.courseid
588 FROM {enrol} e
589 JOIN {user_enrolments} ue ON (ue.enrolid = e.id AND ue.userid = :userid)
590 WHERE ue.status = :active AND e.status = :enabled AND ue.timestart < :now1 AND (ue.timeend = 0 OR ue.timeend > :now2)
591 ) en ON (en.courseid = c.id)
df997f84 592 $ccjoin
4129338c 593 WHERE $wheres
df997f84
PS
594 $orderby";
595 $params['userid'] = $USER->id;
596 $params['active'] = ENROL_USER_ACTIVE;
597 $params['enabled'] = ENROL_INSTANCE_ENABLED;
598 $params['now1'] = round(time(), -2); // improves db caching
599 $params['now2'] = $params['now1'];
600
601 $courses = $DB->get_records_sql($sql, $params, 0, $limit);
602
603 // preload contexts and check visibility
604 foreach ($courses as $id=>$course) {
605 context_instance_preload($course);
606 if (!$course->visible) {
607 if (!$context = get_context_instance(CONTEXT_COURSE, $id)) {
55880bdd 608 unset($courses[$id]);
df997f84
PS
609 continue;
610 }
611 if (!has_capability('moodle/course:viewhiddencourses', $context)) {
55880bdd 612 unset($courses[$id]);
df997f84
PS
613 continue;
614 }
615 }
616 $courses[$id] = $course;
617 }
618
619 //wow! Is that really all? :-D
620
621 return $courses;
622}
623
bf423bb1
PS
624/**
625 * Returns course enrolment information icons.
626 *
627 * @param object $course
628 * @param array $instances enrol instances of this course, improves performance
629 * @return array of pix_icon
630 */
631function enrol_get_course_info_icons($course, array $instances = NULL) {
632 $icons = array();
633 if (is_null($instances)) {
634 $instances = enrol_get_instances($course->id, true);
635 }
636 $plugins = enrol_get_plugins(true);
637 foreach ($plugins as $name => $plugin) {
638 $pis = array();
639 foreach ($instances as $instance) {
640 if ($instance->status != ENROL_INSTANCE_ENABLED or $instance->courseid != $course->id) {
641 debugging('Invalid instances parameter submitted in enrol_get_info_icons()');
642 continue;
643 }
644 if ($instance->enrol == $name) {
645 $pis[$instance->id] = $instance;
646 }
647 }
648 if ($pis) {
649 $icons = array_merge($icons, $plugin->get_info_icons($pis));
650 }
651 }
652 return $icons;
653}
654
655/**
656 * Returns course enrolment detailed information.
657 *
658 * @param object $course
659 * @return array of html fragments - can be used to construct lists
660 */
661function enrol_get_course_description_texts($course) {
662 $lines = array();
663 $instances = enrol_get_instances($course->id, true);
664 $plugins = enrol_get_plugins(true);
665 foreach ($instances as $instance) {
64942a9d 666 if (!isset($plugins[$instance->enrol])) {
bf423bb1
PS
667 //weird
668 continue;
669 }
64942a9d 670 $plugin = $plugins[$instance->enrol];
bf423bb1
PS
671 $text = $plugin->get_description_text($instance);
672 if ($text !== NULL) {
673 $lines[] = $text;
674 }
675 }
676 return $lines;
677}
678
df997f84
PS
679/**
680 * Returns list of courses user is enrolled into.
681 *
682 * - $fields is an array of fieldnames to ADD
683 * so name the fields you really need, which will
684 * be added and uniq'd
685 *
686 * @param int $userid
687 * @param bool $onlyactive return only active enrolments in courses user may see
eb6f592a 688 * @param string|array $fields
df997f84
PS
689 * @param string $sort
690 * @return array
691 */
692function enrol_get_users_courses($userid, $onlyactive = false, $fields = NULL, $sort = 'visible DESC,sortorder ASC') {
693 global $DB;
694
695 // Guest account does not have any courses
87163782 696 if (isguestuser($userid) or empty($userid)) {
df997f84
PS
697 return(array());
698 }
699
700 $basefields = array('id', 'category', 'sortorder',
701 'shortname', 'fullname', 'idnumber',
702 'startdate', 'visible',
703 'groupmode', 'groupmodeforce');
704
705 if (empty($fields)) {
706 $fields = $basefields;
707 } else if (is_string($fields)) {
708 // turn the fields from a string to an array
709 $fields = explode(',', $fields);
710 $fields = array_map('trim', $fields);
711 $fields = array_unique(array_merge($basefields, $fields));
712 } else if (is_array($fields)) {
713 $fields = array_unique(array_merge($basefields, $fields));
714 } else {
715 throw new coding_exception('Invalid $fileds parameter in enrol_get_my_courses()');
716 }
717 if (in_array('*', $fields)) {
718 $fields = array('*');
719 }
720
721 $orderby = "";
722 $sort = trim($sort);
723 if (!empty($sort)) {
724 $rawsorts = explode(',', $sort);
725 $sorts = array();
726 foreach ($rawsorts as $rawsort) {
727 $rawsort = trim($rawsort);
728 if (strpos($rawsort, 'c.') === 0) {
729 $rawsort = substr($rawsort, 2);
730 }
731 $sorts[] = trim($rawsort);
732 }
733 $sort = 'c.'.implode(',c.', $sorts);
734 $orderby = "ORDER BY $sort";
735 }
736
df997f84
PS
737 $params = array('siteid'=>SITEID);
738
739 if ($onlyactive) {
4129338c 740 $subwhere = "WHERE ue.status = :active AND e.status = :enabled AND ue.timestart < :now1 AND (ue.timeend = 0 OR ue.timeend > :now2)";
df997f84
PS
741 $params['now1'] = round(time(), -2); // improves db caching
742 $params['now2'] = $params['now1'];
743 $params['active'] = ENROL_USER_ACTIVE;
744 $params['enabled'] = ENROL_INSTANCE_ENABLED;
4129338c
PS
745 } else {
746 $subwhere = "";
df997f84
PS
747 }
748
749 $coursefields = 'c.' .join(',c.', $fields);
750 list($ccselect, $ccjoin) = context_instance_preload_sql('c.id', CONTEXT_COURSE, 'ctx');
df997f84 751
4129338c
PS
752 //note: we can not use DISTINCT + text fields due to Oracle and MS limitations, that is why we have the subselect there
753 $sql = "SELECT $coursefields $ccselect
df997f84 754 FROM {course} c
4129338c
PS
755 JOIN (SELECT DISTINCT e.courseid
756 FROM {enrol} e
757 JOIN {user_enrolments} ue ON (ue.enrolid = e.id AND ue.userid = :userid)
758 $subwhere
759 ) en ON (en.courseid = c.id)
df997f84 760 $ccjoin
4129338c 761 WHERE c.id <> :siteid
df997f84 762 $orderby";
87163782 763 $params['userid'] = $userid;
df997f84
PS
764
765 $courses = $DB->get_records_sql($sql, $params);
766
767 // preload contexts and check visibility
768 foreach ($courses as $id=>$course) {
769 context_instance_preload($course);
770 if ($onlyactive) {
771 if (!$course->visible) {
772 if (!$context = get_context_instance(CONTEXT_COURSE, $id)) {
4a5aba7c 773 unset($courses[$id]);
df997f84
PS
774 continue;
775 }
776 if (!has_capability('moodle/course:viewhiddencourses', $context, $userid)) {
4a5aba7c 777 unset($courses[$id]);
df997f84
PS
778 continue;
779 }
780 }
781 }
782 $courses[$id] = $course;
783 }
784
785 //wow! Is that really all? :-D
786
787 return $courses;
788
789}
790
791/**
792 * Called when user is about to be deleted.
793 * @param object $user
794 * @return void
795 */
796function enrol_user_delete($user) {
797 global $DB;
798
799 $plugins = enrol_get_plugins(true);
800 foreach ($plugins as $plugin) {
801 $plugin->user_delete($user);
802 }
803
804 // force cleanup of all broken enrolments
805 $DB->delete_records('user_enrolments', array('userid'=>$user->id));
806}
807
582bae08
PS
808/**
809 * Called when course is about to be deleted.
bbfdff34 810 * @param stdClass $course
582bae08
PS
811 * @return void
812 */
813function enrol_course_delete($course) {
814 global $DB;
815
816 $instances = enrol_get_instances($course->id, false);
817 $plugins = enrol_get_plugins(true);
818 foreach ($instances as $instance) {
819 if (isset($plugins[$instance->enrol])) {
820 $plugins[$instance->enrol]->delete_instance($instance);
821 }
822 // low level delete in case plugin did not do it
823 $DB->delete_records('user_enrolments', array('enrolid'=>$instance->id));
824 $DB->delete_records('role_assignments', array('itemid'=>$instance->id, 'component'=>'enrol_'.$instance->enrol));
825 $DB->delete_records('user_enrolments', array('enrolid'=>$instance->id));
826 $DB->delete_records('enrol', array('id'=>$instance->id));
827 }
828}
829
df997f84
PS
830/**
831 * Try to enrol user via default internal auth plugin.
832 *
833 * For now this is always using the manual enrol plugin...
834 *
835 * @param $courseid
836 * @param $userid
837 * @param $roleid
838 * @param $timestart
839 * @param $timeend
840 * @return bool success
841 */
842function enrol_try_internal_enrol($courseid, $userid, $roleid = null, $timestart = 0, $timeend = 0) {
843 global $DB;
844
845 //note: this is hardcoded to manual plugin for now
846
847 if (!enrol_is_enabled('manual')) {
848 return false;
849 }
850
851 if (!$enrol = enrol_get_plugin('manual')) {
852 return false;
853 }
854 if (!$instances = $DB->get_records('enrol', array('enrol'=>'manual', 'courseid'=>$courseid, 'status'=>ENROL_INSTANCE_ENABLED), 'sortorder,id ASC')) {
855 return false;
856 }
857 $instance = reset($instances);
858
859 $enrol->enrol_user($instance, $userid, $roleid, $timestart, $timeend);
860
861 return true;
862}
863
45ff8a80
PS
864/**
865 * Is there a chance users might self enrol
866 * @param int $courseid
867 * @return bool
868 */
869function enrol_selfenrol_available($courseid) {
870 $result = false;
871
872 $plugins = enrol_get_plugins(true);
873 $enrolinstances = enrol_get_instances($courseid, true);
874 foreach($enrolinstances as $instance) {
875 if (!isset($plugins[$instance->enrol])) {
876 continue;
877 }
878 if ($instance->enrol === 'guest') {
879 // blacklist known temporary guest plugins
880 continue;
881 }
882 if ($plugins[$instance->enrol]->show_enrolme_link($instance)) {
883 $result = true;
884 break;
885 }
886 }
887
888 return $result;
889}
890
bbfdff34
PS
891/**
892 * This function returns the end of current active user enrolment.
893 *
894 * It deals correctly with multiple overlapping user enrolments.
895 *
896 * @param int $courseid
897 * @param int $userid
898 * @return int|bool timestamp when active enrolment ends, false means no active enrolment now, 0 means never
899 */
900function enrol_get_enrolment_end($courseid, $userid) {
901 global $DB;
902
903 $sql = "SELECT ue.*
904 FROM {user_enrolments} ue
905 JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
906 JOIN {user} u ON u.id = ue.userid
907 WHERE ue.userid = :userid AND ue.status = :active AND e.status = :enabled AND u.deleted = 0";
908 $params = array('enabled'=>ENROL_INSTANCE_ENABLED, 'active'=>ENROL_USER_ACTIVE, 'userid'=>$userid, 'courseid'=>$courseid);
909
910 if (!$enrolments = $DB->get_records_sql($sql, $params)) {
911 return false;
912 }
913
914 $changes = array();
915
916 foreach ($enrolments as $ue) {
917 $start = (int)$ue->timestart;
918 $end = (int)$ue->timeend;
919 if ($end != 0 and $end < $start) {
920 debugging('Invalid enrolment start or end in user_enrolment id:'.$ue->id);
921 continue;
922 }
923 if (isset($changes[$start])) {
924 $changes[$start] = $changes[$start] + 1;
925 } else {
926 $changes[$start] = 1;
927 }
928 if ($end === 0) {
929 // no end
930 } else if (isset($changes[$end])) {
931 $changes[$end] = $changes[$end] - 1;
932 } else {
933 $changes[$end] = -1;
934 }
935 }
936
937 // let's sort then enrolment starts&ends and go through them chronologically,
938 // looking for current status and the next future end of enrolment
939 ksort($changes);
940
941 $now = time();
942 $current = 0;
943 $present = null;
944
945 foreach ($changes as $time => $change) {
946 if ($time > $now) {
947 if ($present === null) {
948 // we have just went past current time
949 $present = $current;
950 if ($present < 1) {
951 // no enrolment active
952 return false;
953 }
954 }
955 if ($present !== null) {
956 // we are already in the future - look for possible end
957 if ($current + $change < 1) {
958 return $time;
959 }
960 }
961 }
962 $current += $change;
963 }
964
965 if ($current > 0) {
966 return 0;
967 } else {
968 return false;
969 }
970}
971
972
df997f84
PS
973/**
974 * All enrol plugins should be based on this class,
975 * this is also the main source of documentation.
976 */
977abstract class enrol_plugin {
978 protected $config = null;
979
980 /**
981 * Returns name of this enrol plugin
982 * @return string
983 */
984 public function get_name() {
bf423bb1 985 // second word in class is always enrol name, sorry, no fancy plugin names with _
df997f84
PS
986 $words = explode('_', get_class($this));
987 return $words[1];
988 }
989
990 /**
991 * Returns localised name of enrol instance
992 *
993 * @param object $instance (null is accepted too)
994 * @return string
995 */
996 public function get_instance_name($instance) {
997 if (empty($instance->name)) {
998 $enrol = $this->get_name();
999 return get_string('pluginname', 'enrol_'.$enrol);
1000 } else {
54475ccb
PS
1001 $context = get_context_instance(CONTEXT_COURSE, $instance->courseid);
1002 return format_string($instance->name, true, array('context'=>$context));
df997f84
PS
1003 }
1004 }
1005
bf423bb1
PS
1006 /**
1007 * Returns optional enrolment information icons.
1008 *
1009 * This is used in course list for quick overview of enrolment options.
1010 *
1011 * We are not using single instance parameter because sometimes
1012 * we might want to prevent icon repetition when multiple instances
1013 * of one type exist. One instance may also produce several icons.
1014 *
1015 * @param array $instances all enrol instances of this type in one course
1016 * @return array of pix_icon
1017 */
1018 public function get_info_icons(array $instances) {
1019 return array();
1020 }
1021
1022 /**
1023 * Returns optional enrolment instance description text.
1024 *
1025 * This is used in detailed course information.
1026 *
1027 *
1028 * @param object $instance
1029 * @return string short html text
1030 */
1031 public function get_description_text($instance) {
1032 return null;
1033 }
1034
df997f84
PS
1035 /**
1036 * Makes sure config is loaded and cached.
1037 * @return void
1038 */
1039 protected function load_config() {
1040 if (!isset($this->config)) {
1041 $name = $this->get_name();
820a8188 1042 $this->config = get_config("enrol_$name");
df997f84
PS
1043 }
1044 }
1045
1046 /**
1047 * Returns plugin config value
1048 * @param string $name
1049 * @param string $default value if config does not exist yet
1050 * @return string value or default
1051 */
1052 public function get_config($name, $default = NULL) {
1053 $this->load_config();
1054 return isset($this->config->$name) ? $this->config->$name : $default;
1055 }
1056
1057 /**
1058 * Sets plugin config value
1059 * @param string $name name of config
1060 * @param string $value string config value, null means delete
1061 * @return string value
1062 */
1063 public function set_config($name, $value) {
47811589 1064 $pluginname = $this->get_name();
df997f84
PS
1065 $this->load_config();
1066 if ($value === NULL) {
1067 unset($this->config->$name);
1068 } else {
1069 $this->config->$name = $value;
1070 }
47811589 1071 set_config($name, $value, "enrol_$pluginname");
df997f84
PS
1072 }
1073
1074 /**
1075 * Does this plugin assign protected roles are can they be manually removed?
1076 * @return bool - false means anybody may tweak roles, it does not use itemid and component when assigning roles
1077 */
1078 public function roles_protected() {
1079 return true;
1080 }
1081
91b99e80
PS
1082 /**
1083 * Does this plugin allow manual enrolments?
1084 *
1085 * @param stdClass $instance course enrol instance
1086 * All plugins allowing this must implement 'enrol/xxx:enrol' capability
1087 *
282b5cc7 1088 * @return bool - true means user with 'enrol/xxx:enrol' may enrol others freely, false means nobody may add more enrolments manually
91b99e80
PS
1089 */
1090 public function allow_enrol(stdClass $instance) {
1091 return false;
1092 }
1093
df997f84 1094 /**
282b5cc7 1095 * Does this plugin allow manual unenrolment of all users?
91b99e80 1096 * All plugins allowing this must implement 'enrol/xxx:unenrol' capability
df997f84 1097 *
282b5cc7
PS
1098 * @param stdClass $instance course enrol instance
1099 * @return bool - true means user with 'enrol/xxx:unenrol' may unenrol others freely, false means nobody may touch user_enrolments
df997f84
PS
1100 */
1101 public function allow_unenrol(stdClass $instance) {
1102 return false;
1103 }
1104
282b5cc7
PS
1105 /**
1106 * Does this plugin allow manual unenrolment of a specific user?
1107 * All plugins allowing this must implement 'enrol/xxx:unenrol' capability
1108 *
1109 * This is useful especially for synchronisation plugins that
1110 * do suspend instead of full unenrolment.
1111 *
1112 * @param stdClass $instance course enrol instance
1113 * @param stdClass $ue record from user_enrolments table, specifies user
1114 *
1115 * @return bool - true means user with 'enrol/xxx:unenrol' may unenrol this user, false means nobody may touch this user enrolment
1116 */
1117 public function allow_unenrol_user(stdClass $instance, stdClass $ue) {
1118 return $this->allow_unenrol($instance);
1119 }
1120
df997f84
PS
1121 /**
1122 * Does this plugin allow manual changes in user_enrolments table?
1123 *
91b99e80 1124 * All plugins allowing this must implement 'enrol/xxx:manage' capability
df997f84
PS
1125 *
1126 * @param stdClass $instance course enrol instance
1127 * @return bool - true means it is possible to change enrol period and status in user_enrolments table
1128 */
1129 public function allow_manage(stdClass $instance) {
1130 return false;
1131 }
1132
217d0397
PS
1133 /**
1134 * Does this plugin support some way to user to self enrol?
1135 *
1136 * @param stdClass $instance course enrol instance
1137 *
1138 * @return bool - true means show "Enrol me in this course" link in course UI
1139 */
1140 public function show_enrolme_link(stdClass $instance) {
1141 return false;
1142 }
1143
df997f84
PS
1144 /**
1145 * Attempt to automatically enrol current user in course without any interaction,
1146 * calling code has to make sure the plugin and instance are active.
1147 *
ed1d72ea
SH
1148 * This should return either a timestamp in the future or false.
1149 *
df997f84 1150 * @param stdClass $instance course enrol instance
df997f84
PS
1151 * @return bool|int false means not enrolled, integer means timeend
1152 */
1153 public function try_autoenrol(stdClass $instance) {
1154 global $USER;
1155
1156 return false;
1157 }
1158
1159 /**
1160 * Attempt to automatically gain temporary guest access to course,
1161 * calling code has to make sure the plugin and instance are active.
1162 *
ed1d72ea
SH
1163 * This should return either a timestamp in the future or false.
1164 *
df997f84 1165 * @param stdClass $instance course enrol instance
df997f84
PS
1166 * @return bool|int false means no guest access, integer means timeend
1167 */
1168 public function try_guestaccess(stdClass $instance) {
1169 global $USER;
1170
1171 return false;
1172 }
1173
1174 /**
1175 * Enrol user into course via enrol instance.
1176 *
1177 * @param stdClass $instance
1178 * @param int $userid
1179 * @param int $roleid optional role id
2a6dcb72
PS
1180 * @param int $timestart 0 means unknown
1181 * @param int $timeend 0 means forever
f2a9be5f 1182 * @param int $status default to ENROL_USER_ACTIVE for new enrolments, no change by default in updates
df997f84
PS
1183 * @return void
1184 */
f2a9be5f 1185 public function enrol_user(stdClass $instance, $userid, $roleid = NULL, $timestart = 0, $timeend = 0, $status = NULL) {
df997f84
PS
1186 global $DB, $USER, $CFG; // CFG necessary!!!
1187
1188 if ($instance->courseid == SITEID) {
1189 throw new coding_exception('invalid attempt to enrol into frontpage course!');
1190 }
1191
1192 $name = $this->get_name();
1193 $courseid = $instance->courseid;
1194
1195 if ($instance->enrol !== $name) {
1196 throw new coding_exception('invalid enrol instance!');
1197 }
1198 $context = get_context_instance(CONTEXT_COURSE, $instance->courseid, MUST_EXIST);
1199
1200 $inserted = false;
358fb4dc 1201 $updated = false;
df997f84 1202 if ($ue = $DB->get_record('user_enrolments', array('enrolid'=>$instance->id, 'userid'=>$userid))) {
d587f077 1203 //only update if timestart or timeend or status are different.
ae8c1f3d 1204 if ($ue->timestart != $timestart or $ue->timeend != $timeend or (!is_null($status) and $ue->status != $status)) {
df997f84
PS
1205 $ue->timestart = $timestart;
1206 $ue->timeend = $timeend;
d587f077 1207 if (!is_null($status)) {
ae8c1f3d 1208 $ue->status = $status;
d587f077 1209 }
6006774c 1210 $ue->modifierid = $USER->id;
df997f84
PS
1211 $ue->timemodified = time();
1212 $DB->update_record('user_enrolments', $ue);
358fb4dc
PS
1213
1214 $updated = true;
df997f84
PS
1215 }
1216 } else {
365a5941 1217 $ue = new stdClass();
df997f84 1218 $ue->enrolid = $instance->id;
ae8c1f3d 1219 $ue->status = is_null($status) ? ENROL_USER_ACTIVE : $status;
df997f84
PS
1220 $ue->userid = $userid;
1221 $ue->timestart = $timestart;
1222 $ue->timeend = $timeend;
6006774c 1223 $ue->modifierid = $USER->id;
2a6dcb72
PS
1224 $ue->timecreated = time();
1225 $ue->timemodified = $ue->timecreated;
df997f84
PS
1226 $ue->id = $DB->insert_record('user_enrolments', $ue);
1227
1228 $inserted = true;
1229 }
1230
df997f84
PS
1231 if ($inserted) {
1232 // add extra info and trigger event
1233 $ue->courseid = $courseid;
1234 $ue->enrol = $name;
1235 events_trigger('user_enrolled', $ue);
358fb4dc
PS
1236 } else if ($updated) {
1237 $ue->courseid = $courseid;
1238 $ue->enrol = $name;
1239 events_trigger('user_enrol_modified', $ue);
bbfdff34
PS
1240 // resets current enrolment caches
1241 $context->mark_dirty();
df997f84
PS
1242 }
1243
0c2701fd 1244 if ($roleid) {
bbfdff34 1245 // this must be done after the enrolment event so that the role_assigned event is triggered afterwards
0c2701fd
PS
1246 if ($this->roles_protected()) {
1247 role_assign($roleid, $userid, $context->id, 'enrol_'.$name, $instance->id);
1248 } else {
1249 role_assign($roleid, $userid, $context->id);
1250 }
1251 }
1252
bbfdff34 1253 // reset current user enrolment caching
df997f84
PS
1254 if ($userid == $USER->id) {
1255 if (isset($USER->enrol['enrolled'][$courseid])) {
1256 unset($USER->enrol['enrolled'][$courseid]);
1257 }
1258 if (isset($USER->enrol['tempguest'][$courseid])) {
1259 unset($USER->enrol['tempguest'][$courseid]);
e922fe23 1260 remove_temp_course_roles($context);
df997f84
PS
1261 }
1262 }
1263 }
1264
1265 /**
1266 * Store user_enrolments changes and trigger event.
1267 *
358fb4dc
PS
1268 * @param stdClass $instance
1269 * @param int $userid
df997f84
PS
1270 * @param int $status
1271 * @param int $timestart
1272 * @param int $timeend
1273 * @return void
1274 */
1275 public function update_user_enrol(stdClass $instance, $userid, $status = NULL, $timestart = NULL, $timeend = NULL) {
1276 global $DB, $USER;
1277
1278 $name = $this->get_name();
1279
1280 if ($instance->enrol !== $name) {
1281 throw new coding_exception('invalid enrol instance!');
1282 }
1283
1284 if (!$ue = $DB->get_record('user_enrolments', array('enrolid'=>$instance->id, 'userid'=>$userid))) {
1285 // weird, user not enrolled
1286 return;
1287 }
1288
1289 $modified = false;
1290 if (isset($status) and $ue->status != $status) {
1291 $ue->status = $status;
1292 $modified = true;
1293 }
1294 if (isset($timestart) and $ue->timestart != $timestart) {
1295 $ue->timestart = $timestart;
1296 $modified = true;
1297 }
1298 if (isset($timeend) and $ue->timeend != $timeend) {
1299 $ue->timeend = $timeend;
1300 $modified = true;
1301 }
1302
1303 if (!$modified) {
1304 // no change
1305 return;
1306 }
1307
1308 $ue->modifierid = $USER->id;
1309 $DB->update_record('user_enrolments', $ue);
bbfdff34 1310 context_course::instance($instance->courseid)->mark_dirty(); // reset enrol caches
df997f84
PS
1311
1312 // trigger event
1313 $ue->courseid = $instance->courseid;
1314 $ue->enrol = $instance->name;
358fb4dc 1315 events_trigger('user_enrol_modified', $ue);
df997f84
PS
1316 }
1317
1318 /**
1319 * Unenrol user from course,
1320 * the last unenrolment removes all remaining roles.
1321 *
1322 * @param stdClass $instance
1323 * @param int $userid
1324 * @return void
1325 */
1326 public function unenrol_user(stdClass $instance, $userid) {
1327 global $CFG, $USER, $DB;
1328
1329 $name = $this->get_name();
1330 $courseid = $instance->courseid;
1331
1332 if ($instance->enrol !== $name) {
1333 throw new coding_exception('invalid enrol instance!');
1334 }
1335 $context = get_context_instance(CONTEXT_COURSE, $instance->courseid, MUST_EXIST);
1336
1337 if (!$ue = $DB->get_record('user_enrolments', array('enrolid'=>$instance->id, 'userid'=>$userid))) {
1338 // weird, user not enrolled
1339 return;
1340 }
1341
1342 role_unassign_all(array('userid'=>$userid, 'contextid'=>$context->id, 'component'=>'enrol_'.$name, 'itemid'=>$instance->id));
1343 $DB->delete_records('user_enrolments', array('id'=>$ue->id));
1344
1345 // add extra info and trigger event
1346 $ue->courseid = $courseid;
1347 $ue->enrol = $name;
1348
1349 $sql = "SELECT 'x'
1350 FROM {user_enrolments} ue
1351 JOIN {enrol} e ON (e.id = ue.enrolid)
1352 WHERE ue.userid = :userid AND e.courseid = :courseid";
1353 if ($DB->record_exists_sql($sql, array('userid'=>$userid, 'courseid'=>$courseid))) {
1354 $ue->lastenrol = false;
1355 events_trigger('user_unenrolled', $ue);
1356 // user still has some enrolments, no big cleanup yet
1357 } else {
1358 // the big cleanup IS necessary!
1359
1360 require_once("$CFG->dirroot/group/lib.php");
1361 require_once("$CFG->libdir/gradelib.php");
1362
1363 // remove all remaining roles
1364 role_unassign_all(array('userid'=>$userid, 'contextid'=>$context->id), true, false);
1365
1366 //clean up ALL invisible user data from course if this is the last enrolment - groups, grades, etc.
1367 groups_delete_group_members($courseid, $userid);
1368
1369 grade_user_unenrol($courseid, $userid);
1370
1371 $DB->delete_records('user_lastaccess', array('userid'=>$userid, 'courseid'=>$courseid));
1372
7d2800fb 1373 $ue->lastenrol = true; // means user not enrolled any more
df997f84
PS
1374 events_trigger('user_unenrolled', $ue);
1375 }
bbfdff34
PS
1376
1377 // reset all enrol caches
1378 $context->mark_dirty();
1379
1380 // reset current user enrolment caching
df997f84
PS
1381 if ($userid == $USER->id) {
1382 if (isset($USER->enrol['enrolled'][$courseid])) {
1383 unset($USER->enrol['enrolled'][$courseid]);
1384 }
1385 if (isset($USER->enrol['tempguest'][$courseid])) {
1386 unset($USER->enrol['tempguest'][$courseid]);
e922fe23 1387 remove_temp_course_roles($context);
df997f84
PS
1388 }
1389 }
1390 }
1391
1392 /**
1393 * Forces synchronisation of user enrolments.
1394 *
1395 * This is important especially for external enrol plugins,
1396 * this function is called for all enabled enrol plugins
1397 * right after every user login.
1398 *
1399 * @param object $user user record
1400 * @return void
1401 */
1402 public function sync_user_enrolments($user) {
1403 // override if necessary
1404 }
1405
1406 /**
1407 * Returns link to page which may be used to add new instance of enrolment plugin in course.
1408 * @param int $courseid
1409 * @return moodle_url page url
1410 */
e25f2466 1411 public function get_newinstance_link($courseid) {
df997f84
PS
1412 // override for most plugins, check if instance already exists in cases only one instance is supported
1413 return NULL;
1414 }
1415
1416 /**
1417 * Is it possible to delete enrol instance via standard UI?
1418 *
1419 * @param object $instance
1420 * @return bool
1421 */
1422 public function instance_deleteable($instance) {
1423 return true;
1424 }
1425
1426 /**
1427 * Returns link to manual enrol UI if exists.
1428 * Does the access control tests automatically.
1429 *
1430 * @param object $instance
1431 * @return moodle_url
1432 */
1433 public function get_manual_enrol_link($instance) {
1434 return NULL;
1435 }
1436
1437 /**
1438 * Returns list of unenrol links for all enrol instances in course.
1439 *
217d0397 1440 * @param int $instance
bf423bb1 1441 * @return moodle_url or NULL if self unenrolment not supported
df997f84
PS
1442 */
1443 public function get_unenrolself_link($instance) {
1444 global $USER, $CFG, $DB;
1445
1446 $name = $this->get_name();
1447 if ($instance->enrol !== $name) {
1448 throw new coding_exception('invalid enrol instance!');
1449 }
1450
1451 if ($instance->courseid == SITEID) {
1452 return NULL;
1453 }
1454
1455 if (!enrol_is_enabled($name)) {
1456 return NULL;
1457 }
1458
1459 if ($instance->status != ENROL_INSTANCE_ENABLED) {
1460 return NULL;
1461 }
1462
df997f84
PS
1463 if (!file_exists("$CFG->dirroot/enrol/$name/unenrolself.php")) {
1464 return NULL;
1465 }
1466
217d0397
PS
1467 $context = get_context_instance(CONTEXT_COURSE, $instance->courseid, MUST_EXIST);
1468
df997f84
PS
1469 if (!has_capability("enrol/$name:unenrolself", $context)) {
1470 return NULL;
1471 }
1472
1473 if (!$DB->record_exists('user_enrolments', array('enrolid'=>$instance->id, 'userid'=>$USER->id, 'status'=>ENROL_USER_ACTIVE))) {
1474 return NULL;
1475 }
1476
1477 return new moodle_url("/enrol/$name/unenrolself.php", array('enrolid'=>$instance->id));;
1478 }
1479
1480 /**
1481 * Adds enrol instance UI to course edit form
1482 *
1483 * @param object $instance enrol instance or null if does not exist yet
1484 * @param MoodleQuickForm $mform
1485 * @param object $data
1486 * @param object $context context of existing course or parent category if course does not exist
1487 * @return void
1488 */
1489 public function course_edit_form($instance, MoodleQuickForm $mform, $data, $context) {
1490 // override - usually at least enable/disable switch, has to add own form header
1491 }
1492
1493 /**
1494 * Validates course edit form data
1495 *
1496 * @param object $instance enrol instance or null if does not exist yet
1497 * @param array $data
1498 * @param object $context context of existing course or parent category if course does not exist
1499 * @return array errors array
1500 */
1501 public function course_edit_validation($instance, array $data, $context) {
1502 return array();
1503 }
1504
1505 /**
1506 * Called after updating/inserting course.
1507 *
1508 * @param bool $inserted true if course just inserted
1509 * @param object $course
1510 * @param object $data form data
1511 * @return void
1512 */
1513 public function course_updated($inserted, $course, $data) {
eafb7a72
PS
1514 if ($inserted) {
1515 if ($this->get_config('defaultenrol')) {
1516 $this->add_default_instance($course);
1517 }
1518 }
df997f84
PS
1519 }
1520
1521 /**
eafb7a72 1522 * Add new instance of enrol plugin.
df997f84
PS
1523 * @param object $course
1524 * @param array instance fields
0848a196 1525 * @return int id of new instance, null if can not be created
df997f84
PS
1526 */
1527 public function add_instance($course, array $fields = NULL) {
1528 global $DB;
1529
1530 if ($course->id == SITEID) {
1531 throw new coding_exception('Invalid request to add enrol instance to frontpage.');
1532 }
1533
365a5941 1534 $instance = new stdClass();
df997f84
PS
1535 $instance->enrol = $this->get_name();
1536 $instance->status = ENROL_INSTANCE_ENABLED;
1537 $instance->courseid = $course->id;
1538 $instance->enrolstartdate = 0;
1539 $instance->enrolenddate = 0;
1540 $instance->timemodified = time();
1541 $instance->timecreated = $instance->timemodified;
1542 $instance->sortorder = $DB->get_field('enrol', 'COALESCE(MAX(sortorder), -1) + 1', array('courseid'=>$course->id));
1543
1544 $fields = (array)$fields;
1545 unset($fields['enrol']);
1546 unset($fields['courseid']);
1547 unset($fields['sortorder']);
1548 foreach($fields as $field=>$value) {
1549 $instance->$field = $value;
1550 }
1551
1552 return $DB->insert_record('enrol', $instance);
1553 }
1554
1555 /**
1556 * Add new instance of enrol plugin with default settings,
1557 * called when adding new instance manually or when adding new course.
1558 *
1559 * Not all plugins support this.
1560 *
1561 * @param object $course
1562 * @return int id of new instance or null if no default supported
1563 */
1564 public function add_default_instance($course) {
1565 return null;
1566 }
1567
af7177db
PS
1568 /**
1569 * Update instance status
1570 *
1571 * Override when plugin needs to do some action when enabled or disabled.
1572 *
1573 * @param stdClass $instance
1574 * @param int $newstatus ENROL_INSTANCE_ENABLED, ENROL_INSTANCE_DISABLED
1575 * @return void
1576 */
1577 public function update_status($instance, $newstatus) {
1578 global $DB;
1579
1580 $instance->status = $newstatus;
1581 $DB->update_record('enrol', $instance);
1582
1583 // invalidate all enrol caches
1584 $context = context_course::instance($instance->courseid);
1585 $context->mark_dirty();
1586 }
1587
df997f84
PS
1588 /**
1589 * Delete course enrol plugin instance, unenrol all users.
1590 * @param object $instance
1591 * @return void
1592 */
1593 public function delete_instance($instance) {
1594 global $DB;
1595
1596 $name = $this->get_name();
1597 if ($instance->enrol !== $name) {
1598 throw new coding_exception('invalid enrol instance!');
1599 }
1600
1601 //first unenrol all users
1602 $participants = $DB->get_recordset('user_enrolments', array('enrolid'=>$instance->id));
1603 foreach ($participants as $participant) {
1604 $this->unenrol_user($instance, $participant->userid);
1605 }
1606 $participants->close();
1607
1608 // now clean up all remainders that were not removed correctly
1609 $DB->delete_records('role_assignments', array('itemid'=>$instance->id, 'component'=>$name));
1610 $DB->delete_records('user_enrolments', array('enrolid'=>$instance->id));
1611
1612 // finally drop the enrol row
1613 $DB->delete_records('enrol', array('id'=>$instance->id));
af7177db
PS
1614
1615 // invalidate all enrol caches
1616 $context = context_course::instance($instance->courseid);
1617 $context->mark_dirty();
df997f84
PS
1618 }
1619
1620 /**
1621 * Creates course enrol form, checks if form submitted
1622 * and enrols user if necessary. It can also redirect.
1623 *
1624 * @param stdClass $instance
1625 * @return string html text, usually a form in a text box
1626 */
1627 public function enrol_page_hook(stdClass $instance) {
1628 return null;
1629 }
1630
1631 /**
1632 * Adds navigation links into course admin block.
1633 *
1634 * By defaults looks for manage links only.
1635 *
1636 * @param navigation_node $instancesnode
bbfdff34 1637 * @param stdClass $instance
2d4b1f3e 1638 * @return void
df997f84
PS
1639 */
1640 public function add_course_navigation($instancesnode, stdClass $instance) {
2d4b1f3e 1641 // usually adds manage users
df997f84
PS
1642 }
1643
1644 /**
2d4b1f3e
PS
1645 * Returns edit icons for the page with list of instances
1646 * @param stdClass $instance
1647 * @return array
df997f84 1648 */
2d4b1f3e
PS
1649 public function get_action_icons(stdClass $instance) {
1650 return array();
df997f84
PS
1651 }
1652
1653 /**
1654 * Reads version.php and determines if it is necessary
1655 * to execute the cron job now.
1656 * @return bool
1657 */
1658 public function is_cron_required() {
1659 global $CFG;
1660
1661 $name = $this->get_name();
1662 $versionfile = "$CFG->dirroot/enrol/$name/version.php";
365a5941 1663 $plugin = new stdClass();
df997f84
PS
1664 include($versionfile);
1665 if (empty($plugin->cron)) {
1666 return false;
1667 }
1668 $lastexecuted = $this->get_config('lastcron', 0);
1669 if ($lastexecuted + $plugin->cron < time()) {
1670 return true;
1671 } else {
1672 return false;
1673 }
1674 }
1675
1676 /**
1677 * Called for all enabled enrol plugins that returned true from is_cron_required().
1678 * @return void
1679 */
1680 public function cron() {
1681 }
1682
1683 /**
1684 * Called when user is about to be deleted
1685 * @param object $user
1686 * @return void
1687 */
1688 public function user_delete($user) {
1689 global $DB;
1690
1691 $sql = "SELECT e.*
1692 FROM {enrol} e
45fb2cf8
PS
1693 JOIN {user_enrolments} ue ON (ue.enrolid = e.id)
1694 WHERE e.enrol = :name AND ue.userid = :userid";
df997f84
PS
1695 $params = array('name'=>$this->get_name(), 'userid'=>$user->id);
1696
45fb2cf8 1697 $rs = $DB->get_recordset_sql($sql, $params);
df997f84
PS
1698 foreach($rs as $instance) {
1699 $this->unenrol_user($instance, $user->id);
1700 }
1701 $rs->close();
1702 }
df997f84 1703
b69ca6be
SH
1704 /**
1705 * Returns an enrol_user_button that takes the user to a page where they are able to
1706 * enrol users into the managers course through this plugin.
1707 *
1708 * Optional: If the plugin supports manual enrolments it can choose to override this
1709 * otherwise it shouldn't
1710 *
1711 * @param course_enrolment_manager $manager
1712 * @return enrol_user_button|false
1713 */
1714 public function get_manual_enrol_button(course_enrolment_manager $manager) {
1715 return false;
1716 }
291215f4
SH
1717
1718 /**
1719 * Gets an array of the user enrolment actions
1720 *
1721 * @param course_enrolment_manager $manager
1722 * @param stdClass $ue
1723 * @return array An array of user_enrolment_actions
1724 */
1725 public function get_user_enrolment_actions(course_enrolment_manager $manager, $ue) {
12a52d7c 1726 return array();
291215f4 1727 }
75ee207b
SH
1728
1729 /**
1730 * Returns true if the plugin has one or more bulk operations that can be performed on
1731 * user enrolments.
1732 *
f20edd52 1733 * @param course_enrolment_manager $manager
75ee207b
SH
1734 * @return bool
1735 */
f20edd52 1736 public function has_bulk_operations(course_enrolment_manager $manager) {
75ee207b
SH
1737 return false;
1738 }
1739
1740 /**
1741 * Return an array of enrol_bulk_enrolment_operation objects that define
1742 * the bulk actions that can be performed on user enrolments by the plugin.
1743 *
f20edd52 1744 * @param course_enrolment_manager $manager
75ee207b
SH
1745 * @return array
1746 */
f20edd52 1747 public function get_bulk_operations(course_enrolment_manager $manager) {
75ee207b
SH
1748 return array();
1749 }
4b715423 1750}