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