MDL-53169 database: use bound empty strings for cross-db
[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
7a7b8a1f 54/** @deprecated since 2.4 not used any more, migrate plugin to new restore methods */
f2a9be5f 55define('ENROL_RESTORE_TYPE', 'enrolrestore');
f2a9be5f 56
34121765
PS
57/**
58 * When user disappears from external source, user enrolment is suspended, roles are kept as is.
59 * In some cases user needs a role with some capability to be visible in UI - suc has in gradebook,
60 * assignments, etc.
61 */
62define('ENROL_EXT_REMOVED_SUSPEND', 2);
63
64/**
65 * When user disappears from external source, the enrolment is suspended and roles assigned
66 * by enrol instance are removed. Please note that user may "disappear" from gradebook and other areas.
67 * */
68define('ENROL_EXT_REMOVED_SUSPENDNOROLES', 3);
69
0ab8b337
SL
70/**
71 * Do not send email.
72 */
73define('ENROL_DO_NOT_SEND_EMAIL', 0);
74
75/**
76 * Send email from course contact.
77 */
78define('ENROL_SEND_EMAIL_FROM_COURSE_CONTACT', 1);
79
80/**
81 * Send email from enrolment key holder.
82 */
83define('ENROL_SEND_EMAIL_FROM_KEY_HOLDER', 2);
84
85/**
86 * Send email from no reply address.
87 */
88define('ENROL_SEND_EMAIL_FROM_NOREPLY', 3);
89
fd0a43be
JP
90/** Edit enrolment action. */
91define('ENROL_ACTION_EDIT', 'editenrolment');
92
93/** Unenrol action. */
94define('ENROL_ACTION_UNENROL', 'unenrol');
95
df997f84
PS
96/**
97 * Returns instances of enrol plugins
bbfdff34 98 * @param bool $enabled return enabled only
df997f84
PS
99 * @return array of enrol plugins name=>instance
100 */
101function enrol_get_plugins($enabled) {
102 global $CFG;
103
104 $result = array();
105
106 if ($enabled) {
107 // sorted by enabled plugin order
108 $enabled = explode(',', $CFG->enrol_plugins_enabled);
109 $plugins = array();
110 foreach ($enabled as $plugin) {
111 $plugins[$plugin] = "$CFG->dirroot/enrol/$plugin";
112 }
113 } else {
114 // sorted alphabetically
bd3b3bba 115 $plugins = core_component::get_plugin_list('enrol');
df997f84
PS
116 ksort($plugins);
117 }
118
119 foreach ($plugins as $plugin=>$location) {
df997f84
PS
120 $class = "enrol_{$plugin}_plugin";
121 if (!class_exists($class)) {
d432e0f7
MA
122 if (!file_exists("$location/lib.php")) {
123 continue;
124 }
125 include_once("$location/lib.php");
126 if (!class_exists($class)) {
127 continue;
128 }
df997f84
PS
129 }
130
131 $result[$plugin] = new $class();
132 }
133
134 return $result;
135}
136
137/**
138 * Returns instance of enrol plugin
139 * @param string $name name of enrol plugin ('manual', 'guest', ...)
140 * @return enrol_plugin
141 */
142function enrol_get_plugin($name) {
143 global $CFG;
144
aff24313
PS
145 $name = clean_param($name, PARAM_PLUGIN);
146
147 if (empty($name)) {
148 // ignore malformed or missing plugin names completely
df997f84
PS
149 return null;
150 }
151
152 $location = "$CFG->dirroot/enrol/$name";
153
df997f84
PS
154 $class = "enrol_{$name}_plugin";
155 if (!class_exists($class)) {
ef97f1a2
MA
156 if (!file_exists("$location/lib.php")) {
157 return null;
158 }
159 include_once("$location/lib.php");
160 if (!class_exists($class)) {
161 return null;
162 }
df997f84
PS
163 }
164
165 return new $class();
166}
167
168/**
169 * Returns enrolment instances in given course.
170 * @param int $courseid
171 * @param bool $enabled
172 * @return array of enrol instances
173 */
174function enrol_get_instances($courseid, $enabled) {
175 global $DB, $CFG;
176
177 if (!$enabled) {
178 return $DB->get_records('enrol', array('courseid'=>$courseid), 'sortorder,id');
179 }
180
181 $result = $DB->get_records('enrol', array('courseid'=>$courseid, 'status'=>ENROL_INSTANCE_ENABLED), 'sortorder,id');
182
79721bd3 183 $enabled = explode(',', $CFG->enrol_plugins_enabled);
df997f84
PS
184 foreach ($result as $key=>$instance) {
185 if (!in_array($instance->enrol, $enabled)) {
186 unset($result[$key]);
187 continue;
188 }
189 if (!file_exists("$CFG->dirroot/enrol/$instance->enrol/lib.php")) {
190 // broken plugin
191 unset($result[$key]);
192 continue;
193 }
194 }
195
196 return $result;
197}
198
199/**
200 * Checks if a given plugin is in the list of enabled enrolment plugins.
201 *
202 * @param string $enrol Enrolment plugin name
203 * @return boolean Whether the plugin is enabled
204 */
205function enrol_is_enabled($enrol) {
206 global $CFG;
207
208 if (empty($CFG->enrol_plugins_enabled)) {
209 return false;
210 }
211 return in_array($enrol, explode(',', $CFG->enrol_plugins_enabled));
212}
213
214/**
215 * Check all the login enrolment information for the given user object
216 * by querying the enrolment plugins
217 *
e922fe23
PS
218 * This function may be very slow, use only once after log-in or login-as.
219 *
220 * @param stdClass $user
df997f84
PS
221 * @return void
222 */
223function enrol_check_plugins($user) {
224 global $CFG;
225
226 if (empty($user->id) or isguestuser($user)) {
227 // shortcut - there is no enrolment work for guests and not-logged-in users
228 return;
229 }
230
bcb368d9
PS
231 // originally there was a broken admin test, but accidentally it was non-functional in 2.2,
232 // which proved it was actually not necessary.
e384d2dc 233
df997f84
PS
234 static $inprogress = array(); // To prevent this function being called more than once in an invocation
235
236 if (!empty($inprogress[$user->id])) {
237 return;
238 }
239
240 $inprogress[$user->id] = true; // Set the flag
241
242 $enabled = enrol_get_plugins(true);
243
244 foreach($enabled as $enrol) {
245 $enrol->sync_user_enrolments($user);
246 }
247
248 unset($inprogress[$user->id]); // Unset the flag
249}
250
181991e7
PS
251/**
252 * Do these two students share any course?
253 *
254 * The courses has to be visible and enrolments has to be active,
255 * timestart and timeend restrictions are ignored.
256 *
61ab8f07
SH
257 * This function calls {@see enrol_get_shared_courses()} setting checkexistsonly
258 * to true.
259 *
181991e7
PS
260 * @param stdClass|int $user1
261 * @param stdClass|int $user2
262 * @return bool
263 */
264function enrol_sharing_course($user1, $user2) {
61ab8f07 265 return enrol_get_shared_courses($user1, $user2, false, true);
181991e7
PS
266}
267
4b715423
SH
268/**
269 * Returns any courses shared by the two users
270 *
271 * The courses has to be visible and enrolments has to be active,
272 * timestart and timeend restrictions are ignored.
273 *
61ab8f07 274 * @global moodle_database $DB
4b715423
SH
275 * @param stdClass|int $user1
276 * @param stdClass|int $user2
61ab8f07
SH
277 * @param bool $preloadcontexts If set to true contexts for the returned courses
278 * will be preloaded.
279 * @param bool $checkexistsonly If set to true then this function will return true
280 * if the users share any courses and false if not.
281 * @return array|bool An array of courses that both users are enrolled in OR if
282 * $checkexistsonly set returns true if the users share any courses
283 * and false if not.
4b715423 284 */
61ab8f07 285function enrol_get_shared_courses($user1, $user2, $preloadcontexts = false, $checkexistsonly = false) {
4b715423
SH
286 global $DB, $CFG;
287
5b244e2b
HD
288 $user1 = isset($user1->id) ? $user1->id : $user1;
289 $user2 = isset($user2->id) ? $user2->id : $user2;
4b715423
SH
290
291 if (empty($user1) or empty($user2)) {
292 return false;
293 }
294
295 if (!$plugins = explode(',', $CFG->enrol_plugins_enabled)) {
296 return false;
297 }
298
499d3775 299 list($plugins1, $params1) = $DB->get_in_or_equal($plugins, SQL_PARAMS_NAMED, 'ee1');
300 list($plugins2, $params2) = $DB->get_in_or_equal($plugins, SQL_PARAMS_NAMED, 'ee2');
301 $params = array_merge($params1, $params2);
302 $params['enabled1'] = ENROL_INSTANCE_ENABLED;
303 $params['enabled2'] = ENROL_INSTANCE_ENABLED;
4b715423
SH
304 $params['active1'] = ENROL_USER_ACTIVE;
305 $params['active2'] = ENROL_USER_ACTIVE;
306 $params['user1'] = $user1;
307 $params['user2'] = $user2;
308
309 $ctxselect = '';
310 $ctxjoin = '';
311 if ($preloadcontexts) {
2e4c0c91
FM
312 $ctxselect = ', ' . context_helper::get_preload_record_columns_sql('ctx');
313 $ctxjoin = "LEFT JOIN {context} ctx ON (ctx.instanceid = c.id AND ctx.contextlevel = :contextlevel)";
314 $params['contextlevel'] = CONTEXT_COURSE;
4b715423
SH
315 }
316
317 $sql = "SELECT c.* $ctxselect
318 FROM {course} c
319 JOIN (
320 SELECT DISTINCT c.id
499d3775 321 FROM {course} c
322 JOIN {enrol} e1 ON (c.id = e1.courseid AND e1.status = :enabled1 AND e1.enrol $plugins1)
323 JOIN {user_enrolments} ue1 ON (ue1.enrolid = e1.id AND ue1.status = :active1 AND ue1.userid = :user1)
324 JOIN {enrol} e2 ON (c.id = e2.courseid AND e2.status = :enabled2 AND e2.enrol $plugins2)
325 JOIN {user_enrolments} ue2 ON (ue2.enrolid = e2.id AND ue2.status = :active2 AND ue2.userid = :user2)
326 WHERE c.visible = 1
4b715423
SH
327 ) ec ON ec.id = c.id
328 $ctxjoin";
4b715423 329
61ab8f07
SH
330 if ($checkexistsonly) {
331 return $DB->record_exists_sql($sql, $params);
332 } else {
333 $courses = $DB->get_records_sql($sql, $params);
334 if ($preloadcontexts) {
a55ad8f8 335 array_map('context_helper::preload_from_record', $courses);
61ab8f07
SH
336 }
337 return $courses;
338 }
4b715423
SH
339}
340
df997f84
PS
341/**
342 * This function adds necessary enrol plugins UI into the course edit form.
343 *
344 * @param MoodleQuickForm $mform
345 * @param object $data course edit form data
346 * @param object $context context of existing course or parent category if course does not exist
347 * @return void
348 */
349function enrol_course_edit_form(MoodleQuickForm $mform, $data, $context) {
350 $plugins = enrol_get_plugins(true);
351 if (!empty($data->id)) {
352 $instances = enrol_get_instances($data->id, false);
353 foreach ($instances as $instance) {
354 if (!isset($plugins[$instance->enrol])) {
355 continue;
356 }
357 $plugin = $plugins[$instance->enrol];
358 $plugin->course_edit_form($instance, $mform, $data, $context);
359 }
360 } else {
361 foreach ($plugins as $plugin) {
362 $plugin->course_edit_form(NULL, $mform, $data, $context);
363 }
364 }
365}
366
367/**
368 * Validate course edit form data
369 *
370 * @param array $data raw form data
371 * @param object $context context of existing course or parent category if course does not exist
372 * @return array errors array
373 */
374function enrol_course_edit_validation(array $data, $context) {
375 $errors = array();
376 $plugins = enrol_get_plugins(true);
377
378 if (!empty($data['id'])) {
379 $instances = enrol_get_instances($data['id'], false);
380 foreach ($instances as $instance) {
381 if (!isset($plugins[$instance->enrol])) {
382 continue;
383 }
384 $plugin = $plugins[$instance->enrol];
385 $errors = array_merge($errors, $plugin->course_edit_validation($instance, $data, $context));
386 }
387 } else {
388 foreach ($plugins as $plugin) {
389 $errors = array_merge($errors, $plugin->course_edit_validation(NULL, $data, $context));
390 }
391 }
392
393 return $errors;
394}
395
396/**
397 * Update enrol instances after course edit form submission
398 * @param bool $inserted true means new course added, false course already existed
399 * @param object $course
400 * @param object $data form data
401 * @return void
402 */
403function enrol_course_updated($inserted, $course, $data) {
404 global $DB, $CFG;
405
406 $plugins = enrol_get_plugins(true);
407
408 foreach ($plugins as $plugin) {
409 $plugin->course_updated($inserted, $course, $data);
410 }
411}
412
413/**
414 * Add navigation nodes
415 * @param navigation_node $coursenode
416 * @param object $course
417 * @return void
418 */
419function enrol_add_course_navigation(navigation_node $coursenode, $course) {
6e4c374d 420 global $CFG;
df997f84 421
b0c6dc1c 422 $coursecontext = context_course::instance($course->id);
df997f84
PS
423
424 $instances = enrol_get_instances($course->id, true);
425 $plugins = enrol_get_plugins(true);
426
427 // we do not want to break all course pages if there is some borked enrol plugin, right?
428 foreach ($instances as $k=>$instance) {
429 if (!isset($plugins[$instance->enrol])) {
430 unset($instances[$k]);
431 }
432 }
433
f5ce6b71 434 $usersnode = $coursenode->add(get_string('users'), null, navigation_node::TYPE_CONTAINER, null, 'users');
df997f84
PS
435
436 if ($course->id != SITEID) {
f5ce6b71 437 // list all participants - allows assigning roles, groups, etc.
df997f84 438 if (has_capability('moodle/course:enrolreview', $coursecontext)) {
4b50765b 439 $url = new moodle_url('/user/index.php', array('id'=>$course->id));
c42651d6 440 $usersnode->add(get_string('enrolledusers', 'enrol'), $url, navigation_node::TYPE_SETTING, null, 'review', new pix_icon('i/enrolusers', ''));
df997f84
PS
441 }
442
443 // manage enrol plugin instances
444 if (has_capability('moodle/course:enrolconfig', $coursecontext) or has_capability('moodle/course:enrolreview', $coursecontext)) {
445 $url = new moodle_url('/enrol/instances.php', array('id'=>$course->id));
446 } else {
447 $url = NULL;
448 }
f5ce6b71 449 $instancesnode = $usersnode->add(get_string('enrolmentinstances', 'enrol'), $url, navigation_node::TYPE_SETTING, null, 'manageinstances');
df997f84
PS
450
451 // each instance decides how to configure itself or how many other nav items are exposed
452 foreach ($instances as $instance) {
453 if (!isset($plugins[$instance->enrol])) {
454 continue;
455 }
456 $plugins[$instance->enrol]->add_course_navigation($instancesnode, $instance);
457 }
458
459 if (!$url) {
460 $instancesnode->trim_if_empty();
461 }
462 }
463
464 // Manage groups in this course or even frontpage
465 if (($course->groupmode || !$course->groupmodeforce) && has_capability('moodle/course:managegroups', $coursecontext)) {
466 $url = new moodle_url('/group/index.php', array('id'=>$course->id));
467 $usersnode->add(get_string('groups'), $url, navigation_node::TYPE_SETTING, null, 'groups', new pix_icon('i/group', ''));
468 }
469
470 if (has_any_capability(array( 'moodle/role:assign', 'moodle/role:safeoverride','moodle/role:override', 'moodle/role:review'), $coursecontext)) {
471 // Override roles
472 if (has_capability('moodle/role:review', $coursecontext)) {
473 $url = new moodle_url('/admin/roles/permissions.php', array('contextid'=>$coursecontext->id));
474 } else {
475 $url = NULL;
476 }
f5ce6b71 477 $permissionsnode = $usersnode->add(get_string('permissions', 'role'), $url, navigation_node::TYPE_SETTING, null, 'override');
df997f84
PS
478
479 // Add assign or override roles if allowed
480 if ($course->id == SITEID or (!empty($CFG->adminsassignrolesincourse) and is_siteadmin())) {
481 if (has_capability('moodle/role:assign', $coursecontext)) {
482 $url = new moodle_url('/admin/roles/assign.php', array('contextid'=>$coursecontext->id));
fbb207c5 483 $permissionsnode->add(get_string('assignedroles', 'role'), $url, navigation_node::TYPE_SETTING, null, 'roles', new pix_icon('i/assignroles', ''));
df997f84
PS
484 }
485 }
486 // Check role permissions
77690b69 487 if (has_any_capability(array('moodle/role:assign', 'moodle/role:safeoverride', 'moodle/role:override'), $coursecontext)) {
df997f84 488 $url = new moodle_url('/admin/roles/check.php', array('contextid'=>$coursecontext->id));
f5ce6b71 489 $permissionsnode->add(get_string('checkpermissions', 'role'), $url, navigation_node::TYPE_SETTING, null, 'permissions', new pix_icon('i/checkpermissions', ''));
df997f84
PS
490 }
491 }
492
493 // Deal somehow with users that are not enrolled but still got a role somehow
494 if ($course->id != SITEID) {
495 //TODO, create some new UI for role assignments at course level
288e7b09 496 if (has_capability('moodle/course:reviewotherusers', $coursecontext)) {
df997f84 497 $url = new moodle_url('/enrol/otherusers.php', array('id'=>$course->id));
fbb207c5 498 $usersnode->add(get_string('notenrolledusers', 'enrol'), $url, navigation_node::TYPE_SETTING, null, 'otherusers', new pix_icon('i/assignroles', ''));
df997f84
PS
499 }
500 }
501
502 // just in case nothing was actually added
503 $usersnode->trim_if_empty();
504
505 if ($course->id != SITEID) {
6813cdf7 506 if (isguestuser() or !isloggedin()) {
39ec18db 507 // guest account can not be enrolled - no links for them
6813cdf7 508 } else if (is_enrolled($coursecontext)) {
39ec18db 509 // unenrol link if possible
217d0397
PS
510 foreach ($instances as $instance) {
511 if (!isset($plugins[$instance->enrol])) {
512 continue;
513 }
514 $plugin = $plugins[$instance->enrol];
515 if ($unenrollink = $plugin->get_unenrolself_link($instance)) {
8ebbb06a
SH
516 $shortname = format_string($course->shortname, true, array('context' => $coursecontext));
517 $coursenode->add(get_string('unenrolme', 'core_enrol', $shortname), $unenrollink, navigation_node::TYPE_SETTING, null, 'unenrolself', new pix_icon('i/user', ''));
217d0397
PS
518 break;
519 //TODO. deal with multiple unenrol links - not likely case, but still...
520 }
df997f84 521 }
217d0397 522 } else {
39ec18db 523 // enrol link if possible
217d0397
PS
524 if (is_viewing($coursecontext)) {
525 // better not show any enrol link, this is intended for managers and inspectors
526 } else {
527 foreach ($instances as $instance) {
528 if (!isset($plugins[$instance->enrol])) {
529 continue;
530 }
531 $plugin = $plugins[$instance->enrol];
532 if ($plugin->show_enrolme_link($instance)) {
533 $url = new moodle_url('/enrol/index.php', array('id'=>$course->id));
8ebbb06a
SH
534 $shortname = format_string($course->shortname, true, array('context' => $coursecontext));
535 $coursenode->add(get_string('enrolme', 'core_enrol', $shortname), $url, navigation_node::TYPE_SETTING, null, 'enrolself', new pix_icon('i/user', ''));
217d0397
PS
536 break;
537 }
538 }
df997f84
PS
539 }
540 }
df997f84
PS
541 }
542}
543
544/**
545 * Returns list of courses current $USER is enrolled in and can access
546 *
547 * - $fields is an array of field names to ADD
548 * so name the fields you really need, which will
549 * be added and uniq'd
550 *
22ef1550 551 * If $allaccessible is true, this will additionally return courses that the current user is not
552 * enrolled in, but can access because they are open to the user for other reasons (course view
553 * permission, currently viewing course as a guest, or course allows guest access without
554 * password).
555 *
eb6f592a 556 * @param string|array $fields
df997f84
PS
557 * @param string $sort
558 * @param int $limit max number of courses
1ef06b43 559 * @param array $courseids the list of course ids to filter by
22ef1550 560 * @param bool $allaccessible Include courses user is not enrolled in, but can access
df997f84
PS
561 * @return array
562 */
966cbed6 563function enrol_get_my_courses($fields = null, $sort = 'visible DESC,sortorder ASC',
22ef1550 564 $limit = 0, $courseids = [], $allaccessible = false) {
565 global $DB, $USER, $CFG;
df997f84 566
22ef1550 567 // Guest account does not have any enrolled courses.
568 if (!$allaccessible && (isguestuser() or !isloggedin())) {
569 return array();
df997f84
PS
570 }
571
572 $basefields = array('id', 'category', 'sortorder',
573 'shortname', 'fullname', 'idnumber',
574 'startdate', 'visible',
4a3fb71c 575 'groupmode', 'groupmodeforce', 'cacherev');
df997f84
PS
576
577 if (empty($fields)) {
578 $fields = $basefields;
579 } else if (is_string($fields)) {
580 // turn the fields from a string to an array
581 $fields = explode(',', $fields);
582 $fields = array_map('trim', $fields);
583 $fields = array_unique(array_merge($basefields, $fields));
584 } else if (is_array($fields)) {
585 $fields = array_unique(array_merge($basefields, $fields));
586 } else {
587 throw new coding_exception('Invalid $fileds parameter in enrol_get_my_courses()');
588 }
589 if (in_array('*', $fields)) {
590 $fields = array('*');
591 }
592
593 $orderby = "";
594 $sort = trim($sort);
595 if (!empty($sort)) {
596 $rawsorts = explode(',', $sort);
597 $sorts = array();
598 foreach ($rawsorts as $rawsort) {
599 $rawsort = trim($rawsort);
600 if (strpos($rawsort, 'c.') === 0) {
601 $rawsort = substr($rawsort, 2);
602 }
603 $sorts[] = trim($rawsort);
604 }
605 $sort = 'c.'.implode(',c.', $sorts);
606 $orderby = "ORDER BY $sort";
607 }
608
609 $wheres = array("c.id <> :siteid");
610 $params = array('siteid'=>SITEID);
611
612 if (isset($USER->loginascontext) and $USER->loginascontext->contextlevel == CONTEXT_COURSE) {
613 // list _only_ this course - anything else is asking for trouble...
614 $wheres[] = "courseid = :loginas";
615 $params['loginas'] = $USER->loginascontext->instanceid;
616 }
617
618 $coursefields = 'c.' .join(',c.', $fields);
2e4c0c91
FM
619 $ccselect = ', ' . context_helper::get_preload_record_columns_sql('ctx');
620 $ccjoin = "LEFT JOIN {context} ctx ON (ctx.instanceid = c.id AND ctx.contextlevel = :contextlevel)";
621 $params['contextlevel'] = CONTEXT_COURSE;
4129338c 622 $wheres = implode(" AND ", $wheres);
df997f84 623
1ef06b43
RW
624 if (!empty($courseids)) {
625 list($courseidssql, $courseidsparams) = $DB->get_in_or_equal($courseids, SQL_PARAMS_NAMED);
626 $wheres = sprintf("%s AND c.id %s", $wheres, $courseidssql);
627 $params = array_merge($params, $courseidsparams);
628 }
629
22ef1550 630 $courseidsql = "";
631 // Logged-in, non-guest users get their enrolled courses.
632 if (!isguestuser() && isloggedin()) {
633 $courseidsql .= "
634 SELECT DISTINCT e.courseid
635 FROM {enrol} e
636 JOIN {user_enrolments} ue ON (ue.enrolid = e.id AND ue.userid = :userid)
637 WHERE ue.status = :active AND e.status = :enabled AND ue.timestart < :now1
638 AND (ue.timeend = 0 OR ue.timeend > :now2)";
639 $params['userid'] = $USER->id;
640 $params['active'] = ENROL_USER_ACTIVE;
641 $params['enabled'] = ENROL_INSTANCE_ENABLED;
642 $params['now1'] = round(time(), -2); // Improves db caching.
643 $params['now2'] = $params['now1'];
644 }
645
646 // When including non-enrolled but accessible courses...
647 if ($allaccessible) {
648 if (is_siteadmin()) {
649 // Site admins can access all courses.
650 $courseidsql = "SELECT DISTINCT c2.id AS courseid FROM {course} c2";
651 } else {
652 // If we used the enrolment as well, then this will be UNIONed.
653 if ($courseidsql) {
654 $courseidsql .= " UNION ";
655 }
656
657 // Include courses with guest access and no password.
658 $courseidsql .= "
659 SELECT DISTINCT e.courseid
660 FROM {enrol} e
7ab09932
EL
661 WHERE e.enrol = 'guest' AND e.password = :emptypass AND e.status = :enabled2";
662 $params['emptypass'] = '';
22ef1550 663 $params['enabled2'] = ENROL_INSTANCE_ENABLED;
664
665 // Include courses where the current user is currently using guest access (may include
666 // those which require a password).
667 $courseids = [];
668 $accessdata = get_user_accessdata($USER->id);
669 foreach ($accessdata['ra'] as $contextpath => $roles) {
670 if (array_key_exists($CFG->guestroleid, $roles)) {
671 // Work out the course id from context path.
672 $context = context::instance_by_id(preg_replace('~^.*/~', '', $contextpath));
673 if ($context instanceof context_course) {
674 $courseids[$context->instanceid] = true;
675 }
676 }
677 }
678
679 // Include courses where the current user has moodle/course:view capability.
680 $courses = get_user_capability_course('moodle/course:view', null, false);
681 if (!$courses) {
682 $courses = [];
683 }
684 foreach ($courses as $course) {
685 $courseids[$course->id] = true;
686 }
687
688 // If there are any in either category, list them individually.
689 if ($courseids) {
690 list ($allowedsql, $allowedparams) = $DB->get_in_or_equal(
691 array_keys($courseids), SQL_PARAMS_NAMED);
692 $courseidsql .= "
693 UNION
694 SELECT DISTINCT c3.id AS courseid
695 FROM {course} c3
696 WHERE c3.id $allowedsql";
697 $params = array_merge($params, $allowedparams);
698 }
699 }
700 }
701
702 // Note: we can not use DISTINCT + text fields due to Oracle and MS limitations, that is why
703 // we have the subselect there.
4129338c 704 $sql = "SELECT $coursefields $ccselect
df997f84 705 FROM {course} c
22ef1550 706 JOIN ($courseidsql) en ON (en.courseid = c.id)
df997f84 707 $ccjoin
4129338c 708 WHERE $wheres
df997f84 709 $orderby";
df997f84
PS
710
711 $courses = $DB->get_records_sql($sql, $params, 0, $limit);
712
713 // preload contexts and check visibility
714 foreach ($courses as $id=>$course) {
db314f34 715 context_helper::preload_from_record($course);
df997f84 716 if (!$course->visible) {
b0c6dc1c 717 if (!$context = context_course::instance($id, IGNORE_MISSING)) {
55880bdd 718 unset($courses[$id]);
df997f84
PS
719 continue;
720 }
721 if (!has_capability('moodle/course:viewhiddencourses', $context)) {
55880bdd 722 unset($courses[$id]);
df997f84
PS
723 continue;
724 }
725 }
726 $courses[$id] = $course;
727 }
728
729 //wow! Is that really all? :-D
730
731 return $courses;
732}
733
bf423bb1
PS
734/**
735 * Returns course enrolment information icons.
736 *
737 * @param object $course
738 * @param array $instances enrol instances of this course, improves performance
739 * @return array of pix_icon
740 */
741function enrol_get_course_info_icons($course, array $instances = NULL) {
742 $icons = array();
743 if (is_null($instances)) {
744 $instances = enrol_get_instances($course->id, true);
745 }
746 $plugins = enrol_get_plugins(true);
747 foreach ($plugins as $name => $plugin) {
748 $pis = array();
749 foreach ($instances as $instance) {
750 if ($instance->status != ENROL_INSTANCE_ENABLED or $instance->courseid != $course->id) {
751 debugging('Invalid instances parameter submitted in enrol_get_info_icons()');
752 continue;
753 }
754 if ($instance->enrol == $name) {
755 $pis[$instance->id] = $instance;
756 }
757 }
758 if ($pis) {
759 $icons = array_merge($icons, $plugin->get_info_icons($pis));
760 }
761 }
762 return $icons;
763}
764
765/**
766 * Returns course enrolment detailed information.
767 *
768 * @param object $course
769 * @return array of html fragments - can be used to construct lists
770 */
771function enrol_get_course_description_texts($course) {
772 $lines = array();
773 $instances = enrol_get_instances($course->id, true);
774 $plugins = enrol_get_plugins(true);
775 foreach ($instances as $instance) {
64942a9d 776 if (!isset($plugins[$instance->enrol])) {
bf423bb1
PS
777 //weird
778 continue;
779 }
64942a9d 780 $plugin = $plugins[$instance->enrol];
bf423bb1
PS
781 $text = $plugin->get_description_text($instance);
782 if ($text !== NULL) {
783 $lines[] = $text;
784 }
785 }
786 return $lines;
787}
788
df997f84
PS
789/**
790 * Returns list of courses user is enrolled into.
9ffd29ce 791 * (Note: use enrol_get_all_users_courses if you want to use the list wihtout any cap checks )
df997f84
PS
792 *
793 * - $fields is an array of fieldnames to ADD
794 * so name the fields you really need, which will
795 * be added and uniq'd
796 *
797 * @param int $userid
798 * @param bool $onlyactive return only active enrolments in courses user may see
eb6f592a 799 * @param string|array $fields
df997f84
PS
800 * @param string $sort
801 * @return array
802 */
803function enrol_get_users_courses($userid, $onlyactive = false, $fields = NULL, $sort = 'visible DESC,sortorder ASC') {
804 global $DB;
805
9ffd29ce
AA
806 $courses = enrol_get_all_users_courses($userid, $onlyactive, $fields, $sort);
807
808 // preload contexts and check visibility
809 if ($onlyactive) {
810 foreach ($courses as $id=>$course) {
db314f34 811 context_helper::preload_from_record($course);
9ffd29ce
AA
812 if (!$course->visible) {
813 if (!$context = context_course::instance($id)) {
814 unset($courses[$id]);
815 continue;
816 }
817 if (!has_capability('moodle/course:viewhiddencourses', $context, $userid)) {
818 unset($courses[$id]);
819 continue;
820 }
821 }
822 }
823 }
824
825 return $courses;
826
827}
828
05f6da14
829/**
830 * Can user access at least one enrolled course?
831 *
832 * Cheat if necessary, but find out as fast as possible!
833 *
834 * @param int|stdClass $user null means use current user
835 * @return bool
836 */
837function enrol_user_sees_own_courses($user = null) {
838 global $USER;
839
840 if ($user === null) {
841 $user = $USER;
842 }
843 $userid = is_object($user) ? $user->id : $user;
844
845 // Guest account does not have any courses
846 if (isguestuser($userid) or empty($userid)) {
847 return false;
848 }
849
850 // Let's cheat here if this is the current user,
851 // if user accessed any course recently, then most probably
852 // we do not need to query the database at all.
853 if ($USER->id == $userid) {
854 if (!empty($USER->enrol['enrolled'])) {
855 foreach ($USER->enrol['enrolled'] as $until) {
856 if ($until > time()) {
857 return true;
858 }
859 }
860 }
861 }
862
863 // Now the slow way.
864 $courses = enrol_get_all_users_courses($userid, true);
865 foreach($courses as $course) {
866 if ($course->visible) {
867 return true;
868 }
869 context_helper::preload_from_record($course);
870 $context = context_course::instance($course->id);
871 if (has_capability('moodle/course:viewhiddencourses', $context, $user)) {
872 return true;
873 }
874 }
875
876 return false;
877}
878
9ffd29ce
AA
879/**
880 * Returns list of courses user is enrolled into without any capability checks
881 * - $fields is an array of fieldnames to ADD
882 * so name the fields you really need, which will
883 * be added and uniq'd
884 *
885 * @param int $userid
886 * @param bool $onlyactive return only active enrolments in courses user may see
887 * @param string|array $fields
888 * @param string $sort
889 * @return array
890 */
891function enrol_get_all_users_courses($userid, $onlyactive = false, $fields = NULL, $sort = 'visible DESC,sortorder ASC') {
892 global $DB;
893
df997f84 894 // Guest account does not have any courses
87163782 895 if (isguestuser($userid) or empty($userid)) {
df997f84
PS
896 return(array());
897 }
898
899 $basefields = array('id', 'category', 'sortorder',
9ffd29ce
AA
900 'shortname', 'fullname', 'idnumber',
901 'startdate', 'visible',
8eb15a38 902 'defaultgroupingid',
9ffd29ce 903 'groupmode', 'groupmodeforce');
df997f84
PS
904
905 if (empty($fields)) {
906 $fields = $basefields;
907 } else if (is_string($fields)) {
908 // turn the fields from a string to an array
909 $fields = explode(',', $fields);
910 $fields = array_map('trim', $fields);
911 $fields = array_unique(array_merge($basefields, $fields));
912 } else if (is_array($fields)) {
913 $fields = array_unique(array_merge($basefields, $fields));
914 } else {
915 throw new coding_exception('Invalid $fileds parameter in enrol_get_my_courses()');
916 }
917 if (in_array('*', $fields)) {
918 $fields = array('*');
919 }
920
921 $orderby = "";
922 $sort = trim($sort);
923 if (!empty($sort)) {
924 $rawsorts = explode(',', $sort);
925 $sorts = array();
926 foreach ($rawsorts as $rawsort) {
927 $rawsort = trim($rawsort);
928 if (strpos($rawsort, 'c.') === 0) {
929 $rawsort = substr($rawsort, 2);
930 }
931 $sorts[] = trim($rawsort);
932 }
933 $sort = 'c.'.implode(',c.', $sorts);
934 $orderby = "ORDER BY $sort";
935 }
936
df997f84
PS
937 $params = array('siteid'=>SITEID);
938
939 if ($onlyactive) {
4129338c 940 $subwhere = "WHERE ue.status = :active AND e.status = :enabled AND ue.timestart < :now1 AND (ue.timeend = 0 OR ue.timeend > :now2)";
df997f84
PS
941 $params['now1'] = round(time(), -2); // improves db caching
942 $params['now2'] = $params['now1'];
943 $params['active'] = ENROL_USER_ACTIVE;
944 $params['enabled'] = ENROL_INSTANCE_ENABLED;
4129338c
PS
945 } else {
946 $subwhere = "";
df997f84
PS
947 }
948
949 $coursefields = 'c.' .join(',c.', $fields);
2e4c0c91
FM
950 $ccselect = ', ' . context_helper::get_preload_record_columns_sql('ctx');
951 $ccjoin = "LEFT JOIN {context} ctx ON (ctx.instanceid = c.id AND ctx.contextlevel = :contextlevel)";
952 $params['contextlevel'] = CONTEXT_COURSE;
df997f84 953
4129338c
PS
954 //note: we can not use DISTINCT + text fields due to Oracle and MS limitations, that is why we have the subselect there
955 $sql = "SELECT $coursefields $ccselect
df997f84 956 FROM {course} c
4129338c
PS
957 JOIN (SELECT DISTINCT e.courseid
958 FROM {enrol} e
959 JOIN {user_enrolments} ue ON (ue.enrolid = e.id AND ue.userid = :userid)
960 $subwhere
961 ) en ON (en.courseid = c.id)
df997f84 962 $ccjoin
4129338c 963 WHERE c.id <> :siteid
df997f84 964 $orderby";
87163782 965 $params['userid'] = $userid;
df997f84
PS
966
967 $courses = $DB->get_records_sql($sql, $params);
968
df997f84 969 return $courses;
df997f84
PS
970}
971
9ffd29ce
AA
972
973
df997f84
PS
974/**
975 * Called when user is about to be deleted.
976 * @param object $user
977 * @return void
978 */
979function enrol_user_delete($user) {
980 global $DB;
981
982 $plugins = enrol_get_plugins(true);
983 foreach ($plugins as $plugin) {
984 $plugin->user_delete($user);
985 }
986
987 // force cleanup of all broken enrolments
988 $DB->delete_records('user_enrolments', array('userid'=>$user->id));
989}
990
582bae08
PS
991/**
992 * Called when course is about to be deleted.
bbfdff34 993 * @param stdClass $course
582bae08
PS
994 * @return void
995 */
996function enrol_course_delete($course) {
997 global $DB;
998
999 $instances = enrol_get_instances($course->id, false);
1000 $plugins = enrol_get_plugins(true);
1001 foreach ($instances as $instance) {
1002 if (isset($plugins[$instance->enrol])) {
1003 $plugins[$instance->enrol]->delete_instance($instance);
1004 }
1005 // low level delete in case plugin did not do it
1006 $DB->delete_records('user_enrolments', array('enrolid'=>$instance->id));
1007 $DB->delete_records('role_assignments', array('itemid'=>$instance->id, 'component'=>'enrol_'.$instance->enrol));
1008 $DB->delete_records('user_enrolments', array('enrolid'=>$instance->id));
1009 $DB->delete_records('enrol', array('id'=>$instance->id));
1010 }
1011}
1012
df997f84
PS
1013/**
1014 * Try to enrol user via default internal auth plugin.
1015 *
1016 * For now this is always using the manual enrol plugin...
1017 *
1018 * @param $courseid
1019 * @param $userid
1020 * @param $roleid
1021 * @param $timestart
1022 * @param $timeend
1023 * @return bool success
1024 */
1025function enrol_try_internal_enrol($courseid, $userid, $roleid = null, $timestart = 0, $timeend = 0) {
1026 global $DB;
1027
1028 //note: this is hardcoded to manual plugin for now
1029
1030 if (!enrol_is_enabled('manual')) {
1031 return false;
1032 }
1033
1034 if (!$enrol = enrol_get_plugin('manual')) {
1035 return false;
1036 }
1037 if (!$instances = $DB->get_records('enrol', array('enrol'=>'manual', 'courseid'=>$courseid, 'status'=>ENROL_INSTANCE_ENABLED), 'sortorder,id ASC')) {
1038 return false;
1039 }
1040 $instance = reset($instances);
1041
1042 $enrol->enrol_user($instance, $userid, $roleid, $timestart, $timeend);
1043
1044 return true;
1045}
1046
45ff8a80
PS
1047/**
1048 * Is there a chance users might self enrol
1049 * @param int $courseid
1050 * @return bool
1051 */
1052function enrol_selfenrol_available($courseid) {
1053 $result = false;
1054
1055 $plugins = enrol_get_plugins(true);
1056 $enrolinstances = enrol_get_instances($courseid, true);
1057 foreach($enrolinstances as $instance) {
1058 if (!isset($plugins[$instance->enrol])) {
1059 continue;
1060 }
1061 if ($instance->enrol === 'guest') {
1062 // blacklist known temporary guest plugins
1063 continue;
1064 }
1065 if ($plugins[$instance->enrol]->show_enrolme_link($instance)) {
1066 $result = true;
1067 break;
1068 }
1069 }
1070
1071 return $result;
1072}
1073
bbfdff34
PS
1074/**
1075 * This function returns the end of current active user enrolment.
1076 *
1077 * It deals correctly with multiple overlapping user enrolments.
1078 *
1079 * @param int $courseid
1080 * @param int $userid
1081 * @return int|bool timestamp when active enrolment ends, false means no active enrolment now, 0 means never
1082 */
1083function enrol_get_enrolment_end($courseid, $userid) {
1084 global $DB;
1085
1086 $sql = "SELECT ue.*
1087 FROM {user_enrolments} ue
1088 JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
1089 JOIN {user} u ON u.id = ue.userid
1090 WHERE ue.userid = :userid AND ue.status = :active AND e.status = :enabled AND u.deleted = 0";
1091 $params = array('enabled'=>ENROL_INSTANCE_ENABLED, 'active'=>ENROL_USER_ACTIVE, 'userid'=>$userid, 'courseid'=>$courseid);
1092
1093 if (!$enrolments = $DB->get_records_sql($sql, $params)) {
1094 return false;
1095 }
1096
1097 $changes = array();
1098
1099 foreach ($enrolments as $ue) {
1100 $start = (int)$ue->timestart;
1101 $end = (int)$ue->timeend;
1102 if ($end != 0 and $end < $start) {
1103 debugging('Invalid enrolment start or end in user_enrolment id:'.$ue->id);
1104 continue;
1105 }
1106 if (isset($changes[$start])) {
1107 $changes[$start] = $changes[$start] + 1;
1108 } else {
1109 $changes[$start] = 1;
1110 }
1111 if ($end === 0) {
1112 // no end
1113 } else if (isset($changes[$end])) {
1114 $changes[$end] = $changes[$end] - 1;
1115 } else {
1116 $changes[$end] = -1;
1117 }
1118 }
1119
1120 // let's sort then enrolment starts&ends and go through them chronologically,
1121 // looking for current status and the next future end of enrolment
1122 ksort($changes);
1123
1124 $now = time();
1125 $current = 0;
1126 $present = null;
1127
1128 foreach ($changes as $time => $change) {
1129 if ($time > $now) {
1130 if ($present === null) {
1131 // we have just went past current time
1132 $present = $current;
1133 if ($present < 1) {
1134 // no enrolment active
1135 return false;
1136 }
1137 }
1138 if ($present !== null) {
1139 // we are already in the future - look for possible end
1140 if ($current + $change < 1) {
1141 return $time;
1142 }
1143 }
1144 }
1145 $current += $change;
1146 }
1147
1148 if ($current > 0) {
1149 return 0;
1150 } else {
1151 return false;
1152 }
1153}
1154
12c92bca
PS
1155/**
1156 * Is current user accessing course via this enrolment method?
1157 *
1158 * This is intended for operations that are going to affect enrol instances.
1159 *
1160 * @param stdClass $instance enrol instance
1161 * @return bool
1162 */
1163function enrol_accessing_via_instance(stdClass $instance) {
1164 global $DB, $USER;
1165
1166 if (empty($instance->id)) {
1167 return false;
1168 }
1169
1170 if (is_siteadmin()) {
1171 // Admins may go anywhere.
1172 return false;
1173 }
1174
1175 return $DB->record_exists('user_enrolments', array('userid'=>$USER->id, 'enrolid'=>$instance->id));
1176}
1177
9f5170e9
JB
1178/**
1179 * Returns true if user is enrolled (is participating) in course
1180 * this is intended for students and teachers.
1181 *
1182 * Since 2.2 the result for active enrolments and current user are cached.
1183 *
9f5170e9
JB
1184 * @param context $context
1185 * @param int|stdClass $user if null $USER is used, otherwise user object or id expected
1186 * @param string $withcapability extra capability name
1187 * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
1188 * @return bool
1189 */
1190function is_enrolled(context $context, $user = null, $withcapability = '', $onlyactive = false) {
1191 global $USER, $DB;
1192
9121bb2d 1193 // First find the course context.
9f5170e9
JB
1194 $coursecontext = $context->get_course_context();
1195
9121bb2d 1196 // Make sure there is a real user specified.
9f5170e9
JB
1197 if ($user === null) {
1198 $userid = isset($USER->id) ? $USER->id : 0;
1199 } else {
1200 $userid = is_object($user) ? $user->id : $user;
1201 }
1202
1203 if (empty($userid)) {
9121bb2d 1204 // Not-logged-in!
9f5170e9
JB
1205 return false;
1206 } else if (isguestuser($userid)) {
9121bb2d 1207 // Guest account can not be enrolled anywhere.
9f5170e9
JB
1208 return false;
1209 }
1210
9121bb2d
JB
1211 // Note everybody participates on frontpage, so for other contexts...
1212 if ($coursecontext->instanceid != SITEID) {
1213 // Try cached info first - the enrolled flag is set only when active enrolment present.
9f5170e9
JB
1214 if ($USER->id == $userid) {
1215 $coursecontext->reload_if_dirty();
1216 if (isset($USER->enrol['enrolled'][$coursecontext->instanceid])) {
1217 if ($USER->enrol['enrolled'][$coursecontext->instanceid] > time()) {
1218 if ($withcapability and !has_capability($withcapability, $context, $userid)) {
1219 return false;
1220 }
1221 return true;
1222 }
1223 }
1224 }
1225
1226 if ($onlyactive) {
9121bb2d 1227 // Look for active enrolments only.
9f5170e9
JB
1228 $until = enrol_get_enrolment_end($coursecontext->instanceid, $userid);
1229
1230 if ($until === false) {
1231 return false;
1232 }
1233
1234 if ($USER->id == $userid) {
1235 if ($until == 0) {
1236 $until = ENROL_MAX_TIMESTAMP;
1237 }
1238 $USER->enrol['enrolled'][$coursecontext->instanceid] = $until;
1239 if (isset($USER->enrol['tempguest'][$coursecontext->instanceid])) {
1240 unset($USER->enrol['tempguest'][$coursecontext->instanceid]);
1241 remove_temp_course_roles($coursecontext);
1242 }
1243 }
1244
1245 } else {
9121bb2d 1246 // Any enrolment is good for us here, even outdated, disabled or inactive.
9f5170e9
JB
1247 $sql = "SELECT 'x'
1248 FROM {user_enrolments} ue
1249 JOIN {enrol} e ON (e.id = ue.enrolid AND e.courseid = :courseid)
1250 JOIN {user} u ON u.id = ue.userid
1251 WHERE ue.userid = :userid AND u.deleted = 0";
9121bb2d 1252 $params = array('userid' => $userid, 'courseid' => $coursecontext->instanceid);
9f5170e9
JB
1253 if (!$DB->record_exists_sql($sql, $params)) {
1254 return false;
1255 }
1256 }
1257 }
1258
1259 if ($withcapability and !has_capability($withcapability, $context, $userid)) {
1260 return false;
1261 }
1262
1263 return true;
1264}
1265
9121bb2d
JB
1266/**
1267 * Returns an array of joins, wheres and params that will limit the group of
1268 * users to only those enrolled and with given capability (if specified).
1269 *
8b0d254f
JB
1270 * Note this join will return duplicate rows for users who have been enrolled
1271 * several times (e.g. as manual enrolment, and as self enrolment). You may
1272 * need to use a SELECT DISTINCT in your query (see get_enrolled_sql for example).
1273 *
9121bb2d
JB
1274 * @param context $context
1275 * @param string $prefix optional, a prefix to the user id column
10c4fce5
JB
1276 * @param string|array $capability optional, may include a capability name, or array of names.
1277 * If an array is provided then this is the equivalent of a logical 'OR',
1278 * i.e. the user needs to have one of these capabilities.
9121bb2d
JB
1279 * @param int $group optional, 0 indicates no current group, otherwise the group id
1280 * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
1281 * @param bool $onlysuspended inverse of onlyactive, consider only suspended enrolments
bb1c6f85 1282 * @param int $enrolid The enrolment ID. If not 0, only users enrolled using this enrolment method will be returned.
9121bb2d
JB
1283 * @return \core\dml\sql_join Contains joins, wheres, params
1284 */
1285function get_enrolled_with_capabilities_join(context $context, $prefix = '', $capability = '', $group = 0,
bb1c6f85 1286 $onlyactive = false, $onlysuspended = false, $enrolid = 0) {
9121bb2d
JB
1287 $uid = $prefix . 'u.id';
1288 $joins = array();
1289 $wheres = array();
1290
bb1c6f85 1291 $enrolledjoin = get_enrolled_join($context, $uid, $onlyactive, $onlysuspended, $enrolid);
9121bb2d
JB
1292 $joins[] = $enrolledjoin->joins;
1293 $wheres[] = $enrolledjoin->wheres;
1294 $params = $enrolledjoin->params;
1295
1296 if (!empty($capability)) {
1297 $capjoin = get_with_capability_join($context, $capability, $uid);
1298 $joins[] = $capjoin->joins;
1299 $wheres[] = $capjoin->wheres;
1300 $params = array_merge($params, $capjoin->params);
1301 }
1302
1303 if ($group) {
90595390 1304 $groupjoin = groups_get_members_join($group, $uid);
9121bb2d
JB
1305 $joins[] = $groupjoin->joins;
1306 $params = array_merge($params, $groupjoin->params);
1307 }
1308
1309 $joins = implode("\n", $joins);
1310 $wheres[] = "{$prefix}u.deleted = 0";
1311 $wheres = implode(" AND ", $wheres);
1312
1313 return new \core\dml\sql_join($joins, $wheres, $params);
1314}
1315
9f5170e9
JB
1316/**
1317 * Returns array with sql code and parameters returning all ids
1318 * of users enrolled into course.
1319 *
1320 * This function is using 'eu[0-9]+_' prefix for table names and parameters.
1321 *
9f5170e9
JB
1322 * @param context $context
1323 * @param string $withcapability
1324 * @param int $groupid 0 means ignore groups, any other value limits the result by group id
1325 * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
1326 * @param bool $onlysuspended inverse of onlyactive, consider only suspended enrolments
bb1c6f85 1327 * @param int $enrolid The enrolment ID. If not 0, only users enrolled using this enrolment method will be returned.
9f5170e9
JB
1328 * @return array list($sql, $params)
1329 */
bb1c6f85
JP
1330function get_enrolled_sql(context $context, $withcapability = '', $groupid = 0, $onlyactive = false, $onlysuspended = false,
1331 $enrolid = 0) {
9f5170e9 1332
9121bb2d 1333 // Use unique prefix just in case somebody makes some SQL magic with the result.
9f5170e9
JB
1334 static $i = 0;
1335 $i++;
9121bb2d 1336 $prefix = 'eu' . $i . '_';
9f5170e9 1337
9121bb2d 1338 $capjoin = get_enrolled_with_capabilities_join(
bb1c6f85 1339 $context, $prefix, $withcapability, $groupid, $onlyactive, $onlysuspended, $enrolid);
9121bb2d
JB
1340
1341 $sql = "SELECT DISTINCT {$prefix}u.id
1342 FROM {user} {$prefix}u
1343 $capjoin->joins
1344 WHERE $capjoin->wheres";
1345
1346 return array($sql, $capjoin->params);
1347}
1348
1349/**
1350 * Returns array with sql joins and parameters returning all ids
1351 * of users enrolled into course.
1352 *
1353 * This function is using 'ej[0-9]+_' prefix for table names and parameters.
1354 *
1355 * @throws coding_exception
1356 *
1357 * @param context $context
1358 * @param string $useridcolumn User id column used the calling query, e.g. u.id
1359 * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
1360 * @param bool $onlysuspended inverse of onlyactive, consider only suspended enrolments
bb1c6f85 1361 * @param int $enrolid The enrolment ID. If not 0, only users enrolled using this enrolment method will be returned.
9121bb2d
JB
1362 * @return \core\dml\sql_join Contains joins, wheres, params
1363 */
bb1c6f85 1364function get_enrolled_join(context $context, $useridcolumn, $onlyactive = false, $onlysuspended = false, $enrolid = 0) {
9121bb2d
JB
1365 // Use unique prefix just in case somebody makes some SQL magic with the result.
1366 static $i = 0;
1367 $i++;
1368 $prefix = 'ej' . $i . '_';
1369
1370 // First find the course context.
9f5170e9
JB
1371 $coursecontext = $context->get_course_context();
1372
1373 $isfrontpage = ($coursecontext->instanceid == SITEID);
1374
1375 if ($onlyactive && $onlysuspended) {
1376 throw new coding_exception("Both onlyactive and onlysuspended are set, this is probably not what you want!");
1377 }
1378 if ($isfrontpage && $onlysuspended) {
1379 throw new coding_exception("onlysuspended is not supported on frontpage; please add your own early-exit!");
1380 }
1381
1382 $joins = array();
1383 $wheres = array();
1384 $params = array();
1385
9121bb2d 1386 $wheres[] = "1 = 1"; // Prevent broken where clauses later on.
9f5170e9 1387
9121bb2d
JB
1388 // Note all users are "enrolled" on the frontpage, but for others...
1389 if (!$isfrontpage) {
9f5170e9
JB
1390 $where1 = "{$prefix}ue.status = :{$prefix}active AND {$prefix}e.status = :{$prefix}enabled";
1391 $where2 = "{$prefix}ue.timestart < :{$prefix}now1 AND ({$prefix}ue.timeend = 0 OR {$prefix}ue.timeend > :{$prefix}now2)";
bb1c6f85
JP
1392
1393 $enrolconditions = array(
1394 "{$prefix}e.id = {$prefix}ue.enrolid",
1395 "{$prefix}e.courseid = :{$prefix}courseid",
1396 );
1397 if ($enrolid) {
1398 $enrolconditions[] = "{$prefix}e.id = :{$prefix}enrolid";
1399 $params[$prefix . 'enrolid'] = $enrolid;
1400 }
1401 $enrolconditionssql = implode(" AND ", $enrolconditions);
1402 $ejoin = "JOIN {enrol} {$prefix}e ON ($enrolconditionssql)";
1403
9f5170e9
JB
1404 $params[$prefix.'courseid'] = $coursecontext->instanceid;
1405
1406 if (!$onlysuspended) {
9121bb2d 1407 $joins[] = "JOIN {user_enrolments} {$prefix}ue ON {$prefix}ue.userid = $useridcolumn";
9f5170e9
JB
1408 $joins[] = $ejoin;
1409 if ($onlyactive) {
1410 $wheres[] = "$where1 AND $where2";
1411 }
1412 } else {
1413 // Suspended only where there is enrolment but ALL are suspended.
1414 // Consider multiple enrols where one is not suspended or plain role_assign.
1415 $enrolselect = "SELECT DISTINCT {$prefix}ue.userid FROM {user_enrolments} {$prefix}ue $ejoin WHERE $where1 AND $where2";
9121bb2d 1416 $joins[] = "JOIN {user_enrolments} {$prefix}ue1 ON {$prefix}ue1.userid = $useridcolumn";
bb1c6f85
JP
1417 $enrolconditions = array(
1418 "{$prefix}e1.id = {$prefix}ue1.enrolid",
1419 "{$prefix}e1.courseid = :{$prefix}_e1_courseid",
1420 );
1421 if ($enrolid) {
1422 $enrolconditions[] = "{$prefix}e1.id = :{$prefix}e1.enrolid";
1423 $params[$prefix . 'e1.enrolid'] = $enrolid;
1424 }
1425 $enrolconditionssql = implode(" AND ", $enrolconditions);
1426 $joins[] = "JOIN {enrol} {$prefix}e1 ON ($enrolconditionssql)";
9f5170e9 1427 $params["{$prefix}_e1_courseid"] = $coursecontext->instanceid;
9121bb2d 1428 $wheres[] = "$useridcolumn NOT IN ($enrolselect)";
9f5170e9
JB
1429 }
1430
1431 if ($onlyactive || $onlysuspended) {
9121bb2d
JB
1432 $now = round(time(), -2); // Rounding helps caching in DB.
1433 $params = array_merge($params, array($prefix . 'enabled' => ENROL_INSTANCE_ENABLED,
1434 $prefix . 'active' => ENROL_USER_ACTIVE,
1435 $prefix . 'now1' => $now, $prefix . 'now2' => $now));
9f5170e9
JB
1436 }
1437 }
1438
1439 $joins = implode("\n", $joins);
9121bb2d 1440 $wheres = implode(" AND ", $wheres);
9f5170e9 1441
9121bb2d 1442 return new \core\dml\sql_join($joins, $wheres, $params);
9f5170e9
JB
1443}
1444
1445/**
1446 * Returns list of users enrolled into course.
1447 *
9f5170e9
JB
1448 * @param context $context
1449 * @param string $withcapability
1450 * @param int $groupid 0 means ignore groups, any other value limits the result by group id
1451 * @param string $userfields requested user record fields
1452 * @param string $orderby
1453 * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set).
1454 * @param int $limitnum return a subset comprising this many records (optional, required if $limitfrom is set).
1455 * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
1456 * @return array of user records
1457 */
1458function get_enrolled_users(context $context, $withcapability = '', $groupid = 0, $userfields = 'u.*', $orderby = null,
1459 $limitfrom = 0, $limitnum = 0, $onlyactive = false) {
1460 global $DB;
1461
1462 list($esql, $params) = get_enrolled_sql($context, $withcapability, $groupid, $onlyactive);
1463 $sql = "SELECT $userfields
1464 FROM {user} u
1465 JOIN ($esql) je ON je.id = u.id
1466 WHERE u.deleted = 0";
1467
1468 if ($orderby) {
1469 $sql = "$sql ORDER BY $orderby";
1470 } else {
1471 list($sort, $sortparams) = users_order_by_sql('u');
1472 $sql = "$sql ORDER BY $sort";
1473 $params = array_merge($params, $sortparams);
1474 }
1475
1476 return $DB->get_records_sql($sql, $params, $limitfrom, $limitnum);
1477}
1478
1479/**
1480 * Counts list of users enrolled into course (as per above function)
1481 *
9f5170e9
JB
1482 * @param context $context
1483 * @param string $withcapability
1484 * @param int $groupid 0 means ignore groups, any other value limits the result by group id
1485 * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
1486 * @return array of user records
1487 */
1488function count_enrolled_users(context $context, $withcapability = '', $groupid = 0, $onlyactive = false) {
1489 global $DB;
1490
9121bb2d
JB
1491 $capjoin = get_enrolled_with_capabilities_join(
1492 $context, '', $withcapability, $groupid, $onlyactive);
1493
9f5170e9
JB
1494 $sql = "SELECT count(u.id)
1495 FROM {user} u
9121bb2d
JB
1496 $capjoin->joins
1497 WHERE $capjoin->wheres AND u.deleted = 0";
9f5170e9 1498
9121bb2d 1499 return $DB->count_records_sql($sql, $capjoin->params);
9f5170e9 1500}
bbfdff34 1501
0ab8b337
SL
1502/**
1503 * Send welcome email "from" options.
1504 *
1505 * @return array list of from options
1506 */
1507function enrol_send_welcome_email_options() {
1508 return [
1509 ENROL_DO_NOT_SEND_EMAIL => get_string('no'),
1510 ENROL_SEND_EMAIL_FROM_COURSE_CONTACT => get_string('sendfromcoursecontact', 'enrol'),
1511 ENROL_SEND_EMAIL_FROM_KEY_HOLDER => get_string('sendfromkeyholder', 'enrol'),
1512 ENROL_SEND_EMAIL_FROM_NOREPLY => get_string('sendfromnoreply', 'enrol')
1513 ];
1514}
1515
5719f2ca
JP
1516/**
1517 * Serve the user enrolment form as a fragment.
1518 *
1519 * @param array $args List of named arguments for the fragment loader.
1520 * @return string
1521 */
1522function enrol_output_fragment_user_enrolment_form($args) {
1523 global $CFG, $DB;
1524
1525 $args = (object) $args;
1526 $context = $args->context;
1527 require_capability('moodle/course:enrolreview', $context);
1528
1529 $ueid = $args->ueid;
1530 $userenrolment = $DB->get_record('user_enrolments', ['id' => $ueid], '*', MUST_EXIST);
1531 $customdata = [
1532 'ue' => $userenrolment,
1533 'modal' => true,
1534 ];
1535
1536 // Set the data if applicable.
1537 $data = [];
1538 if (isset($args->formdata)) {
1539 $serialiseddata = json_decode($args->formdata);
1540 parse_str($serialiseddata, $data);
1541 }
1542
1543 require_once("$CFG->dirroot/enrol/editenrolment_form.php");
1544 $mform = new \enrol_user_enrolment_form(null, $customdata, 'post', '', null, true, $data);
1545
1546 if (!empty($data)) {
1547 $mform->set_data($data);
1548 $mform->is_validated();
1549 }
1550
1551 return $mform->render();
1552}
1553
fba40526
DM
1554/**
1555 * Returns the course where a user enrolment belong to.
1556 *
1557 * @param int $ueid user_enrolments id
1558 * @return stdClass
1559 */
1560function enrol_get_course_by_user_enrolment_id($ueid) {
1561 global $DB;
1562 $sql = "SELECT c.* FROM {user_enrolments} ue
1563 JOIN {enrol} e ON e.id = ue.enrolid
1564 JOIN {course} c ON c.id = e.courseid
1565 WHERE ue.id = :ueid";
1566 return $DB->get_record_sql($sql, array('ueid' => $ueid));
1567}
1568
8970ff91
DM
1569/**
1570 * Return all users enrolled in a course.
1571 *
58f86c4c 1572 * @param int $courseid Course id or false if using $uefilter (user enrolment ids may belong to different courses)
8970ff91 1573 * @param bool $onlyactive consider only active enrolments in enabled plugins and time restrictions
413f19bc
DM
1574 * @param array $usersfilter Limit the results obtained to this list of user ids. $uefilter compatibility not guaranteed.
1575 * @param array $uefilter Limit the results obtained to this list of user enrolment ids. $usersfilter compatibility not guaranteed.
1576 * @return stdClass[]
8970ff91 1577 */
58f86c4c 1578function enrol_get_course_users($courseid = false, $onlyactive = false, $usersfilter = array(), $uefilter = array()) {
8970ff91
DM
1579 global $DB;
1580
58f86c4c
DM
1581 if (!$courseid && !$usersfilter && !$uefilter) {
1582 throw new \coding_exception('You should specify at least 1 filter: courseid, users or user enrolments');
1583 }
1584
1585 $sql = "SELECT ue.id AS ueid, ue.status AS uestatus, ue.enrolid AS ueenrolid, ue.timestart AS uetimestart,
1586 ue.timeend AS uetimeend, ue.modifierid AS uemodifierid, ue.timecreated AS uetimecreated,
1587 ue.timemodified AS uetimemodified,
1588 u.* FROM {user_enrolments} ue
8970ff91
DM
1589 JOIN {enrol} e ON e.id = ue.enrolid
1590 JOIN {user} u ON ue.userid = u.id
58f86c4c
DM
1591 WHERE ";
1592 $params = array();
1593
1594 if ($courseid) {
1595 $conditions[] = "e.courseid = :courseid";
1596 $params['courseid'] = $courseid;
1597 }
8970ff91
DM
1598
1599 if ($onlyactive) {
413f19bc
DM
1600 $conditions[] = "ue.status = :active AND e.status = :enabled AND ue.timestart < :now1 AND " .
1601 "(ue.timeend = 0 OR ue.timeend > :now2)";
1602 // Improves db caching.
1603 $params['now1'] = round(time(), -2);
8970ff91
DM
1604 $params['now2'] = $params['now1'];
1605 $params['active'] = ENROL_USER_ACTIVE;
1606 $params['enabled'] = ENROL_INSTANCE_ENABLED;
8970ff91 1607 }
58f86c4c
DM
1608
1609 if ($usersfilter) {
1610 list($usersql, $userparams) = $DB->get_in_or_equal($usersfilter, SQL_PARAMS_NAMED);
1611 $conditions[] = "ue.userid $usersql";
1612 $params = $params + $userparams;
1613 }
1614
1615 if ($uefilter) {
b3d68794 1616 list($uesql, $ueparams) = $DB->get_in_or_equal($uefilter, SQL_PARAMS_NAMED);
58f86c4c
DM
1617 $conditions[] = "ue.id $uesql";
1618 $params = $params + $ueparams;
1619 }
1620
1621 return $DB->get_records_sql($sql . ' ' . implode(' AND ', $conditions), $params);
8970ff91
DM
1622}
1623
df997f84 1624/**
413f19bc
DM
1625 * Enrolment plugins abstract class.
1626 *
df997f84
PS
1627 * All enrol plugins should be based on this class,
1628 * this is also the main source of documentation.
413f19bc
DM
1629 *
1630 * @copyright 2010 Petr Skoda {@link http://skodak.org}
1631 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
df997f84
PS
1632 */
1633abstract class enrol_plugin {
1634 protected $config = null;
1635
1636 /**
1637 * Returns name of this enrol plugin
1638 * @return string
1639 */
1640 public function get_name() {
bf423bb1 1641 // second word in class is always enrol name, sorry, no fancy plugin names with _
df997f84
PS
1642 $words = explode('_', get_class($this));
1643 return $words[1];
1644 }
1645
1646 /**
1647 * Returns localised name of enrol instance
1648 *
1649 * @param object $instance (null is accepted too)
1650 * @return string
1651 */
1652 public function get_instance_name($instance) {
1653 if (empty($instance->name)) {
1654 $enrol = $this->get_name();
1655 return get_string('pluginname', 'enrol_'.$enrol);
1656 } else {
b0c6dc1c 1657 $context = context_course::instance($instance->courseid);
54475ccb 1658 return format_string($instance->name, true, array('context'=>$context));
df997f84
PS
1659 }
1660 }
1661
bf423bb1
PS
1662 /**
1663 * Returns optional enrolment information icons.
1664 *
1665 * This is used in course list for quick overview of enrolment options.
1666 *
1667 * We are not using single instance parameter because sometimes
1668 * we might want to prevent icon repetition when multiple instances
1669 * of one type exist. One instance may also produce several icons.
1670 *
1671 * @param array $instances all enrol instances of this type in one course
1672 * @return array of pix_icon
1673 */
1674 public function get_info_icons(array $instances) {
1675 return array();
1676 }
1677
1678 /**
1679 * Returns optional enrolment instance description text.
1680 *
1681 * This is used in detailed course information.
1682 *
1683 *
1684 * @param object $instance
1685 * @return string short html text
1686 */
1687 public function get_description_text($instance) {
1688 return null;
1689 }
1690
df997f84
PS
1691 /**
1692 * Makes sure config is loaded and cached.
1693 * @return void
1694 */
1695 protected function load_config() {
1696 if (!isset($this->config)) {
1697 $name = $this->get_name();
820a8188 1698 $this->config = get_config("enrol_$name");
df997f84
PS
1699 }
1700 }
1701
1702 /**
1703 * Returns plugin config value
1704 * @param string $name
1705 * @param string $default value if config does not exist yet
1706 * @return string value or default
1707 */
1708 public function get_config($name, $default = NULL) {
1709 $this->load_config();
1710 return isset($this->config->$name) ? $this->config->$name : $default;
1711 }
1712
1713 /**
1714 * Sets plugin config value
1715 * @param string $name name of config
1716 * @param string $value string config value, null means delete
1717 * @return string value
1718 */
1719 public function set_config($name, $value) {
47811589 1720 $pluginname = $this->get_name();
df997f84
PS
1721 $this->load_config();
1722 if ($value === NULL) {
1723 unset($this->config->$name);
1724 } else {
1725 $this->config->$name = $value;
1726 }
47811589 1727 set_config($name, $value, "enrol_$pluginname");
df997f84
PS
1728 }
1729
1730 /**
1731 * Does this plugin assign protected roles are can they be manually removed?
1732 * @return bool - false means anybody may tweak roles, it does not use itemid and component when assigning roles
1733 */
1734 public function roles_protected() {
1735 return true;
1736 }
1737
91b99e80
PS
1738 /**
1739 * Does this plugin allow manual enrolments?
1740 *
1741 * @param stdClass $instance course enrol instance
1742 * All plugins allowing this must implement 'enrol/xxx:enrol' capability
1743 *
282b5cc7 1744 * @return bool - true means user with 'enrol/xxx:enrol' may enrol others freely, false means nobody may add more enrolments manually
91b99e80
PS
1745 */
1746 public function allow_enrol(stdClass $instance) {
1747 return false;
1748 }
1749
df997f84 1750 /**
282b5cc7 1751 * Does this plugin allow manual unenrolment of all users?
91b99e80 1752 * All plugins allowing this must implement 'enrol/xxx:unenrol' capability
df997f84 1753 *
282b5cc7
PS
1754 * @param stdClass $instance course enrol instance
1755 * @return bool - true means user with 'enrol/xxx:unenrol' may unenrol others freely, false means nobody may touch user_enrolments
df997f84
PS
1756 */
1757 public function allow_unenrol(stdClass $instance) {
1758 return false;
1759 }
1760
282b5cc7
PS
1761 /**
1762 * Does this plugin allow manual unenrolment of a specific user?
1763 * All plugins allowing this must implement 'enrol/xxx:unenrol' capability
1764 *
1765 * This is useful especially for synchronisation plugins that
1766 * do suspend instead of full unenrolment.
1767 *
1768 * @param stdClass $instance course enrol instance
1769 * @param stdClass $ue record from user_enrolments table, specifies user
1770 *
1771 * @return bool - true means user with 'enrol/xxx:unenrol' may unenrol this user, false means nobody may touch this user enrolment
1772 */
1773 public function allow_unenrol_user(stdClass $instance, stdClass $ue) {
1774 return $this->allow_unenrol($instance);
1775 }
1776
df997f84
PS
1777 /**
1778 * Does this plugin allow manual changes in user_enrolments table?
1779 *
91b99e80 1780 * All plugins allowing this must implement 'enrol/xxx:manage' capability
df997f84
PS
1781 *
1782 * @param stdClass $instance course enrol instance
1783 * @return bool - true means it is possible to change enrol period and status in user_enrolments table
1784 */
1785 public function allow_manage(stdClass $instance) {
1786 return false;
1787 }
1788
217d0397
PS
1789 /**
1790 * Does this plugin support some way to user to self enrol?
1791 *
1792 * @param stdClass $instance course enrol instance
1793 *
1794 * @return bool - true means show "Enrol me in this course" link in course UI
1795 */
1796 public function show_enrolme_link(stdClass $instance) {
1797 return false;
1798 }
1799
df997f84
PS
1800 /**
1801 * Attempt to automatically enrol current user in course without any interaction,
1802 * calling code has to make sure the plugin and instance are active.
1803 *
ed1d72ea
SH
1804 * This should return either a timestamp in the future or false.
1805 *
df997f84 1806 * @param stdClass $instance course enrol instance
df997f84
PS
1807 * @return bool|int false means not enrolled, integer means timeend
1808 */
1809 public function try_autoenrol(stdClass $instance) {
1810 global $USER;
1811
1812 return false;
1813 }
1814
1815 /**
1816 * Attempt to automatically gain temporary guest access to course,
1817 * calling code has to make sure the plugin and instance are active.
1818 *
ed1d72ea
SH
1819 * This should return either a timestamp in the future or false.
1820 *
df997f84 1821 * @param stdClass $instance course enrol instance
df997f84
PS
1822 * @return bool|int false means no guest access, integer means timeend
1823 */
1824 public function try_guestaccess(stdClass $instance) {
1825 global $USER;
1826
1827 return false;
1828 }
1829
1830 /**
1831 * Enrol user into course via enrol instance.
1832 *
1833 * @param stdClass $instance
1834 * @param int $userid
1835 * @param int $roleid optional role id
2a6dcb72
PS
1836 * @param int $timestart 0 means unknown
1837 * @param int $timeend 0 means forever
f2a9be5f 1838 * @param int $status default to ENROL_USER_ACTIVE for new enrolments, no change by default in updates
ef8a733a 1839 * @param bool $recovergrades restore grade history
df997f84
PS
1840 * @return void
1841 */
ef8a733a 1842 public function enrol_user(stdClass $instance, $userid, $roleid = null, $timestart = 0, $timeend = 0, $status = null, $recovergrades = null) {
df997f84
PS
1843 global $DB, $USER, $CFG; // CFG necessary!!!
1844
1845 if ($instance->courseid == SITEID) {
1846 throw new coding_exception('invalid attempt to enrol into frontpage course!');
1847 }
1848
1849 $name = $this->get_name();
1850 $courseid = $instance->courseid;
1851
1852 if ($instance->enrol !== $name) {
1853 throw new coding_exception('invalid enrol instance!');
1854 }
b0c6dc1c 1855 $context = context_course::instance($instance->courseid, MUST_EXIST);
ef8a733a
CF
1856 if (!isset($recovergrades)) {
1857 $recovergrades = $CFG->recovergradesdefault;
1858 }
df997f84
PS
1859
1860 $inserted = false;
358fb4dc 1861 $updated = false;
df997f84 1862 if ($ue = $DB->get_record('user_enrolments', array('enrolid'=>$instance->id, 'userid'=>$userid))) {
d587f077 1863 //only update if timestart or timeend or status are different.
ae8c1f3d 1864 if ($ue->timestart != $timestart or $ue->timeend != $timeend or (!is_null($status) and $ue->status != $status)) {
bb78e249 1865 $this->update_user_enrol($instance, $userid, $status, $timestart, $timeend);
df997f84
PS
1866 }
1867 } else {
365a5941 1868 $ue = new stdClass();
df997f84 1869 $ue->enrolid = $instance->id;
ae8c1f3d 1870 $ue->status = is_null($status) ? ENROL_USER_ACTIVE : $status;
df997f84
PS
1871 $ue->userid = $userid;
1872 $ue->timestart = $timestart;
1873 $ue->timeend = $timeend;
6006774c 1874 $ue->modifierid = $USER->id;
2a6dcb72
PS
1875 $ue->timecreated = time();
1876 $ue->timemodified = $ue->timecreated;
df997f84
PS
1877 $ue->id = $DB->insert_record('user_enrolments', $ue);
1878
1879 $inserted = true;
1880 }
1881
df997f84 1882 if ($inserted) {
bb78e249
RT
1883 // Trigger event.
1884 $event = \core\event\user_enrolment_created::create(
1885 array(
1886 'objectid' => $ue->id,
1887 'courseid' => $courseid,
1888 'context' => $context,
1889 'relateduserid' => $ue->userid,
1890 'other' => array('enrol' => $name)
1891 )
1892 );
1893 $event->trigger();
5667e602
MG
1894 // Check if course contacts cache needs to be cleared.
1895 require_once($CFG->libdir . '/coursecatlib.php');
1896 coursecat::user_enrolment_changed($courseid, $ue->userid,
1897 $ue->status, $ue->timestart, $ue->timeend);
df997f84
PS
1898 }
1899
0c2701fd 1900 if ($roleid) {
bbfdff34 1901 // this must be done after the enrolment event so that the role_assigned event is triggered afterwards
0c2701fd
PS
1902 if ($this->roles_protected()) {
1903 role_assign($roleid, $userid, $context->id, 'enrol_'.$name, $instance->id);
1904 } else {
1905 role_assign($roleid, $userid, $context->id);
1906 }
1907 }
1908
ef8a733a
CF
1909 // Recover old grades if present.
1910 if ($recovergrades) {
1911 require_once("$CFG->libdir/gradelib.php");
1912 grade_recover_history_grades($userid, $courseid);
1913 }
1914
bbfdff34 1915 // reset current user enrolment caching
df997f84
PS
1916 if ($userid == $USER->id) {
1917 if (isset($USER->enrol['enrolled'][$courseid])) {
1918 unset($USER->enrol['enrolled'][$courseid]);
1919 }
1920 if (isset($USER->enrol['tempguest'][$courseid])) {
1921 unset($USER->enrol['tempguest'][$courseid]);
e922fe23 1922 remove_temp_course_roles($context);
df997f84
PS
1923 }
1924 }
1925 }
1926
1927 /**
1928 * Store user_enrolments changes and trigger event.
1929 *
358fb4dc
PS
1930 * @param stdClass $instance
1931 * @param int $userid
df997f84
PS
1932 * @param int $status
1933 * @param int $timestart
1934 * @param int $timeend
1935 * @return void
1936 */
1937 public function update_user_enrol(stdClass $instance, $userid, $status = NULL, $timestart = NULL, $timeend = NULL) {
5667e602 1938 global $DB, $USER, $CFG;
df997f84
PS
1939
1940 $name = $this->get_name();
1941
1942 if ($instance->enrol !== $name) {
1943 throw new coding_exception('invalid enrol instance!');
1944 }
1945
1946 if (!$ue = $DB->get_record('user_enrolments', array('enrolid'=>$instance->id, 'userid'=>$userid))) {
1947 // weird, user not enrolled
1948 return;
1949 }
1950
1951 $modified = false;
1952 if (isset($status) and $ue->status != $status) {
1953 $ue->status = $status;
1954 $modified = true;
1955 }
1956 if (isset($timestart) and $ue->timestart != $timestart) {
1957 $ue->timestart = $timestart;
1958 $modified = true;
1959 }
1960 if (isset($timeend) and $ue->timeend != $timeend) {
1961 $ue->timeend = $timeend;
1962 $modified = true;
1963 }
1964
1965 if (!$modified) {
1966 // no change
1967 return;
1968 }
1969
1970 $ue->modifierid = $USER->id;
ed63ffc7 1971 $ue->timemodified = time();
df997f84 1972 $DB->update_record('user_enrolments', $ue);
bbfdff34 1973 context_course::instance($instance->courseid)->mark_dirty(); // reset enrol caches
df997f84 1974
eeb9ee8e 1975 // Invalidate core_access cache for get_suspended_userids.
03ecddb4 1976 cache_helper::invalidate_by_definition('core', 'suspended_userids', array(), array($instance->courseid));
eeb9ee8e 1977
bb78e249
RT
1978 // Trigger event.
1979 $event = \core\event\user_enrolment_updated::create(
1980 array(
1981 'objectid' => $ue->id,
1982 'courseid' => $instance->courseid,
1983 'context' => context_course::instance($instance->courseid),
1984 'relateduserid' => $ue->userid,
1985 'other' => array('enrol' => $name)
1986 )
1987 );
1988 $event->trigger();
5667e602
MG
1989
1990 require_once($CFG->libdir . '/coursecatlib.php');
1991 coursecat::user_enrolment_changed($instance->courseid, $ue->userid,
1992 $ue->status, $ue->timestart, $ue->timeend);
df997f84
PS
1993 }
1994
1995 /**
1996 * Unenrol user from course,
1997 * the last unenrolment removes all remaining roles.
1998 *
1999 * @param stdClass $instance
2000 * @param int $userid
2001 * @return void
2002 */
2003 public function unenrol_user(stdClass $instance, $userid) {
2004 global $CFG, $USER, $DB;
7881024e 2005 require_once("$CFG->dirroot/group/lib.php");
df997f84
PS
2006
2007 $name = $this->get_name();
2008 $courseid = $instance->courseid;
2009
2010 if ($instance->enrol !== $name) {
2011 throw new coding_exception('invalid enrol instance!');
2012 }
b0c6dc1c 2013 $context = context_course::instance($instance->courseid, MUST_EXIST);
df997f84
PS
2014
2015 if (!$ue = $DB->get_record('user_enrolments', array('enrolid'=>$instance->id, 'userid'=>$userid))) {
2016 // weird, user not enrolled
2017 return;
2018 }
2019
7881024e
PS
2020 // Remove all users groups linked to this enrolment instance.
2021 if ($gms = $DB->get_records('groups_members', array('userid'=>$userid, 'component'=>'enrol_'.$name, 'itemid'=>$instance->id))) {
2022 foreach ($gms as $gm) {
2023 groups_remove_member($gm->groupid, $gm->userid);
2024 }
2025 }
2026
df997f84
PS
2027 role_unassign_all(array('userid'=>$userid, 'contextid'=>$context->id, 'component'=>'enrol_'.$name, 'itemid'=>$instance->id));
2028 $DB->delete_records('user_enrolments', array('id'=>$ue->id));
2029
2030 // add extra info and trigger event
2031 $ue->courseid = $courseid;
2032 $ue->enrol = $name;
2033
2034 $sql = "SELECT 'x'
2035 FROM {user_enrolments} ue
2036 JOIN {enrol} e ON (e.id = ue.enrolid)
7881024e 2037 WHERE ue.userid = :userid AND e.courseid = :courseid";
df997f84
PS
2038 if ($DB->record_exists_sql($sql, array('userid'=>$userid, 'courseid'=>$courseid))) {
2039 $ue->lastenrol = false;
7881024e 2040
df997f84
PS
2041 } else {
2042 // the big cleanup IS necessary!
df997f84
PS
2043 require_once("$CFG->libdir/gradelib.php");
2044
2045 // remove all remaining roles
2046 role_unassign_all(array('userid'=>$userid, 'contextid'=>$context->id), true, false);
2047
2048 //clean up ALL invisible user data from course if this is the last enrolment - groups, grades, etc.
2049 groups_delete_group_members($courseid, $userid);
2050
2051 grade_user_unenrol($courseid, $userid);
2052
2053 $DB->delete_records('user_lastaccess', array('userid'=>$userid, 'courseid'=>$courseid));
2054
7d2800fb 2055 $ue->lastenrol = true; // means user not enrolled any more
df997f84 2056 }
bb78e249
RT
2057 // Trigger event.
2058 $event = \core\event\user_enrolment_deleted::create(
2059 array(
2060 'courseid' => $courseid,
2061 'context' => $context,
2062 'relateduserid' => $ue->userid,
4fb6600e 2063 'objectid' => $ue->id,
bb78e249
RT
2064 'other' => array(
2065 'userenrolment' => (array)$ue,
2066 'enrol' => $name
2067 )
2068 )
2069 );
2070 $event->trigger();
bbfdff34
PS
2071 // reset all enrol caches
2072 $context->mark_dirty();
2073
5667e602
MG
2074 // Check if courrse contacts cache needs to be cleared.
2075 require_once($CFG->libdir . '/coursecatlib.php');
2076 coursecat::user_enrolment_changed($courseid, $ue->userid, ENROL_USER_SUSPENDED);
2077
bbfdff34 2078 // reset current user enrolment caching
df997f84
PS
2079 if ($userid == $USER->id) {
2080 if (isset($USER->enrol['enrolled'][$courseid])) {
2081 unset($USER->enrol['enrolled'][$courseid]);
2082 }
2083 if (isset($USER->enrol['tempguest'][$courseid])) {
2084 unset($USER->enrol['tempguest'][$courseid]);
e922fe23 2085 remove_temp_course_roles($context);
df997f84
PS
2086 }
2087 }
2088 }
2089
2090 /**
2091 * Forces synchronisation of user enrolments.
2092 *
2093 * This is important especially for external enrol plugins,
2094 * this function is called for all enabled enrol plugins
2095 * right after every user login.
2096 *
2097 * @param object $user user record
2098 * @return void
2099 */
2100 public function sync_user_enrolments($user) {
2101 // override if necessary
2102 }
2103
60010fd6
DW
2104 /**
2105 * This returns false for backwards compatibility, but it is really recommended.
2106 *
2107 * @since Moodle 3.1
2108 * @return boolean
2109 */
2110 public function use_standard_editing_ui() {
2111 return false;
2112 }
2113
2114 /**
2115 * Return whether or not, given the current state, it is possible to add a new instance
2116 * of this enrolment plugin to the course.
2117 *
2118 * Default implementation is just for backwards compatibility.
2119 *
2120 * @param int $courseid
2121 * @return boolean
2122 */
2123 public function can_add_instance($courseid) {
2124 $link = $this->get_newinstance_link($courseid);
2125 return !empty($link);
2126 }
2127
51c736f0
DW
2128 /**
2129 * Return whether or not, given the current state, it is possible to edit an instance
2130 * of this enrolment plugin in the course. Used by the standard editing UI
2131 * to generate a link to the edit instance form if editing is allowed.
2132 *
2133 * @param stdClass $instance
2134 * @return boolean
2135 */
2136 public function can_edit_instance($instance) {
2137 $context = context_course::instance($instance->courseid);
2138
2139 return has_capability('enrol/' . $instance->enrol . ':config', $context);
2140 }
2141
df997f84
PS
2142 /**
2143 * Returns link to page which may be used to add new instance of enrolment plugin in course.
2144 * @param int $courseid
2145 * @return moodle_url page url
2146 */
e25f2466 2147 public function get_newinstance_link($courseid) {
df997f84
PS
2148 // override for most plugins, check if instance already exists in cases only one instance is supported
2149 return NULL;
2150 }
2151
2152 /**
ee9e079d 2153 * @deprecated since Moodle 2.8 MDL-35864 - please use can_delete_instance() instead.
df997f84
PS
2154 */
2155 public function instance_deleteable($instance) {
648cddcb
AA
2156 throw new coding_exception('Function enrol_plugin::instance_deleteable() is deprecated, use
2157 enrol_plugin::can_delete_instance() instead');
ee9e079d
DN
2158 }
2159
2160 /**
2161 * Is it possible to delete enrol instance via standard UI?
2162 *
b5a289c4 2163 * @param stdClass $instance
ee9e079d
DN
2164 * @return bool
2165 */
2166 public function can_delete_instance($instance) {
2167 return false;
df997f84
PS
2168 }
2169
b5a289c4
DNA
2170 /**
2171 * Is it possible to hide/show enrol instance via standard UI?
2172 *
2173 * @param stdClass $instance
2174 * @return bool
2175 */
2176 public function can_hide_show_instance($instance) {
2177 debugging("The enrolment plugin '".$this->get_name()."' should override the function can_hide_show_instance().", DEBUG_DEVELOPER);
2178 return true;
2179 }
2180
df997f84
PS
2181 /**
2182 * Returns link to manual enrol UI if exists.
2183 * Does the access control tests automatically.
2184 *
2185 * @param object $instance
2186 * @return moodle_url
2187 */
2188 public function get_manual_enrol_link($instance) {
2189 return NULL;
2190 }
2191
2192 /**
2193 * Returns list of unenrol links for all enrol instances in course.
2194 *
217d0397 2195 * @param int $instance
bf423bb1 2196 * @return moodle_url or NULL if self unenrolment not supported
df997f84
PS
2197 */
2198 public function get_unenrolself_link($instance) {
2199 global $USER, $CFG, $DB;
2200
2201 $name = $this->get_name();
2202 if ($instance->enrol !== $name) {
2203 throw new coding_exception('invalid enrol instance!');
2204 }
2205
2206 if ($instance->courseid == SITEID) {
2207 return NULL;
2208 }
2209
2210 if (!enrol_is_enabled($name)) {
2211 return NULL;
2212 }
2213
2214 if ($instance->status != ENROL_INSTANCE_ENABLED) {
2215 return NULL;
2216 }
2217
df997f84
PS
2218 if (!file_exists("$CFG->dirroot/enrol/$name/unenrolself.php")) {
2219 return NULL;
2220 }
2221
b0c6dc1c 2222 $context = context_course::instance($instance->courseid, MUST_EXIST);
217d0397 2223
df997f84
PS
2224 if (!has_capability("enrol/$name:unenrolself", $context)) {
2225 return NULL;
2226 }
2227
2228 if (!$DB->record_exists('user_enrolments', array('enrolid'=>$instance->id, 'userid'=>$USER->id, 'status'=>ENROL_USER_ACTIVE))) {
2229 return NULL;
2230 }
2231
0e35ba6f 2232 return new moodle_url("/enrol/$name/unenrolself.php", array('enrolid'=>$instance->id));
df997f84
PS
2233 }
2234
2235 /**
2236 * Adds enrol instance UI to course edit form
2237 *
2238 * @param object $instance enrol instance or null if does not exist yet
2239 * @param MoodleQuickForm $mform
2240 * @param object $data
2241 * @param object $context context of existing course or parent category if course does not exist
2242 * @return void
2243 */
2244 public function course_edit_form($instance, MoodleQuickForm $mform, $data, $context) {
2245 // override - usually at least enable/disable switch, has to add own form header
2246 }
2247
60010fd6
DW
2248 /**
2249 * Adds form elements to add/edit instance form.
2250 *
2251 * @since Moodle 3.1
2252 * @param object $instance enrol instance or null if does not exist yet
2253 * @param MoodleQuickForm $mform
2254 * @param context $context
2255 * @return void
2256 */
2257 public function edit_instance_form($instance, MoodleQuickForm $mform, $context) {
2258 // Do nothing by default.
2259 }
2260
2261 /**
2262 * Perform custom validation of the data used to edit the instance.
2263 *
2264 * @since Moodle 3.1
2265 * @param array $data array of ("fieldname"=>value) of submitted data
2266 * @param array $files array of uploaded files "element_name"=>tmp_file_path
2267 * @param object $instance The instance data loaded from the DB.
2268 * @param context $context The context of the instance we are editing
2269 * @return array of "element_name"=>"error_description" if there are errors,
2270 * or an empty array if everything is OK.
2271 */
2272 public function edit_instance_validation($data, $files, $instance, $context) {
2273 // No errors by default.
2274 debugging('enrol_plugin::edit_instance_validation() is missing. This plugin has no validation!', DEBUG_DEVELOPER);
2275 return array();
2276 }
2277
df997f84
PS
2278 /**
2279 * Validates course edit form data
2280 *
2281 * @param object $instance enrol instance or null if does not exist yet
2282 * @param array $data
2283 * @param object $context context of existing course or parent category if course does not exist
2284 * @return array errors array
2285 */
2286 public function course_edit_validation($instance, array $data, $context) {
2287 return array();
2288 }
2289
2290 /**
2291 * Called after updating/inserting course.
2292 *
2293 * @param bool $inserted true if course just inserted
2294 * @param object $course
2295 * @param object $data form data
2296 * @return void
2297 */
2298 public function course_updated($inserted, $course, $data) {
eafb7a72
PS
2299 if ($inserted) {
2300 if ($this->get_config('defaultenrol')) {
2301 $this->add_default_instance($course);
2302 }
2303 }
df997f84
PS
2304 }
2305
2306 /**
eafb7a72 2307 * Add new instance of enrol plugin.
df997f84
PS
2308 * @param object $course
2309 * @param array instance fields
0848a196 2310 * @return int id of new instance, null if can not be created
df997f84
PS
2311 */
2312 public function add_instance($course, array $fields = NULL) {
2313 global $DB;
2314
2315 if ($course->id == SITEID) {
2316 throw new coding_exception('Invalid request to add enrol instance to frontpage.');
2317 }
2318
365a5941 2319 $instance = new stdClass();
df997f84
PS
2320 $instance->enrol = $this->get_name();
2321 $instance->status = ENROL_INSTANCE_ENABLED;
2322 $instance->courseid = $course->id;
2323 $instance->enrolstartdate = 0;
2324 $instance->enrolenddate = 0;
2325 $instance->timemodified = time();
2326 $instance->timecreated = $instance->timemodified;
2327 $instance->sortorder = $DB->get_field('enrol', 'COALESCE(MAX(sortorder), -1) + 1', array('courseid'=>$course->id));
2328
2329 $fields = (array)$fields;
2330 unset($fields['enrol']);
2331 unset($fields['courseid']);
2332 unset($fields['sortorder']);
2333 foreach($fields as $field=>$value) {
2334 $instance->$field = $value;
2335 }
2336
080c7d47
MG
2337 $instance->id = $DB->insert_record('enrol', $instance);
2338
2339 \core\event\enrol_instance_created::create_from_record($instance)->trigger();
2340
2341 return $instance->id;
df997f84
PS
2342 }
2343
60010fd6
DW
2344 /**
2345 * Update instance of enrol plugin.
2346 *
2347 * @since Moodle 3.1
2348 * @param stdClass $instance
2349 * @param stdClass $data modified instance fields
2350 * @return boolean
2351 */
2352 public function update_instance($instance, $data) {
2353 global $DB;
2354 $properties = array('status', 'name', 'password', 'customint1', 'customint2', 'customint3',
2355 'customint4', 'customint5', 'customint6', 'customint7', 'customint8',
2356 'customchar1', 'customchar2', 'customchar3', 'customdec1', 'customdec2',
2357 'customtext1', 'customtext2', 'customtext3', 'customtext4', 'roleid',
2358 'enrolperiod', 'expirynotify', 'notifyall', 'expirythreshold',
2359 'enrolstartdate', 'enrolenddate', 'cost', 'currency');
2360
2361 foreach ($properties as $key) {
2362 if (isset($data->$key)) {
2363 $instance->$key = $data->$key;
2364 }
2365 }
2366 $instance->timemodified = time();
2367
2368 $update = $DB->update_record('enrol', $instance);
2369 if ($update) {
2370 \core\event\enrol_instance_updated::create_from_record($instance)->trigger();
2371 }
2372 return $update;
2373 }
2374
df997f84
PS
2375 /**
2376 * Add new instance of enrol plugin with default settings,
2377 * called when adding new instance manually or when adding new course.
2378 *
2379 * Not all plugins support this.
2380 *
2381 * @param object $course
2382 * @return int id of new instance or null if no default supported
2383 */
2384 public function add_default_instance($course) {
2385 return null;
2386 }
2387
af7177db
PS
2388 /**
2389 * Update instance status
2390 *
2391 * Override when plugin needs to do some action when enabled or disabled.
2392 *
2393 * @param stdClass $instance
2394 * @param int $newstatus ENROL_INSTANCE_ENABLED, ENROL_INSTANCE_DISABLED
2395 * @return void
2396 */
2397 public function update_status($instance, $newstatus) {
2398 global $DB;
2399
2400 $instance->status = $newstatus;
2401 $DB->update_record('enrol', $instance);
2402
af7177db 2403 $context = context_course::instance($instance->courseid);
080c7d47
MG
2404 \core\event\enrol_instance_updated::create_from_record($instance)->trigger();
2405
2406 // Invalidate all enrol caches.
af7177db
PS
2407 $context->mark_dirty();
2408 }
2409
df997f84
PS
2410 /**
2411 * Delete course enrol plugin instance, unenrol all users.
2412 * @param object $instance
2413 * @return void
2414 */
2415 public function delete_instance($instance) {
2416 global $DB;
2417
2418 $name = $this->get_name();
2419 if ($instance->enrol !== $name) {
2420 throw new coding_exception('invalid enrol instance!');
2421 }
2422
2423 //first unenrol all users
2424 $participants = $DB->get_recordset('user_enrolments', array('enrolid'=>$instance->id));
2425 foreach ($participants as $participant) {
2426 $this->unenrol_user($instance, $participant->userid);
2427 }
2428 $participants->close();
2429
2430 // now clean up all remainders that were not removed correctly
a1cedcc9
PS
2431 $DB->delete_records('groups_members', array('itemid'=>$instance->id, 'component'=>'enrol_'.$name));
2432 $DB->delete_records('role_assignments', array('itemid'=>$instance->id, 'component'=>'enrol_'.$name));
df997f84
PS
2433 $DB->delete_records('user_enrolments', array('enrolid'=>$instance->id));
2434
2435 // finally drop the enrol row
2436 $DB->delete_records('enrol', array('id'=>$instance->id));
af7177db 2437
af7177db 2438 $context = context_course::instance($instance->courseid);
080c7d47
MG
2439 \core\event\enrol_instance_deleted::create_from_record($instance)->trigger();
2440
2441 // Invalidate all enrol caches.
af7177db 2442 $context->mark_dirty();
df997f84
PS
2443 }
2444
2445 /**
2446 * Creates course enrol form, checks if form submitted
2447 * and enrols user if necessary. It can also redirect.
2448 *
2449 * @param stdClass $instance
2450 * @return string html text, usually a form in a text box
2451 */
2452 public function enrol_page_hook(stdClass $instance) {
2453 return null;
2454 }
2455
85d1c53a
RT
2456 /**
2457 * Checks if user can self enrol.
2458 *
2459 * @param stdClass $instance enrolment instance
cc1b5015
RT
2460 * @param bool $checkuserenrolment if true will check if user enrolment is inactive.
2461 * used by navigation to improve performance.
2462 * @return bool|string true if successful, else error message or false
85d1c53a 2463 */
cc1b5015 2464 public function can_self_enrol(stdClass $instance, $checkuserenrolment = true) {
85d1c53a
RT
2465 return false;
2466 }
2467
2468 /**
2469 * Return information for enrolment instance containing list of parameters required
2470 * for enrolment, name of enrolment plugin etc.
2471 *
2472 * @param stdClass $instance enrolment instance
2473 * @return array instance info.
2474 */
2475 public function get_enrol_info(stdClass $instance) {
2476 return null;
2477 }
2478
df997f84
PS
2479 /**
2480 * Adds navigation links into course admin block.
2481 *
2482 * By defaults looks for manage links only.
2483 *
2484 * @param navigation_node $instancesnode
bbfdff34 2485 * @param stdClass $instance
2d4b1f3e 2486 * @return void
df997f84
PS
2487 */
2488 public function add_course_navigation($instancesnode, stdClass $instance) {
f7589515
DW
2489 if ($this->use_standard_editing_ui()) {
2490 $context = context_course::instance($instance->courseid);
2491 $cap = 'enrol/' . $instance->enrol . ':config';
2492 if (has_capability($cap, $context)) {
2493 $linkparams = array('courseid' => $instance->courseid, 'id' => $instance->id, 'type' => $instance->enrol);
2494 $managelink = new moodle_url('/enrol/editinstance.php', $linkparams);
2495 $instancesnode->add($this->get_instance_name($instance), $managelink, navigation_node::TYPE_SETTING);
2496 }
2497 }
df997f84
PS
2498 }
2499
2500 /**
2d4b1f3e
PS
2501 * Returns edit icons for the page with list of instances
2502 * @param stdClass $instance
2503 * @return array
df997f84 2504 */
2d4b1f3e 2505 public function get_action_icons(stdClass $instance) {
51c736f0
DW
2506 global $OUTPUT;
2507
2508 $icons = array();
2509 if ($this->use_standard_editing_ui()) {
2510 $linkparams = array('courseid' => $instance->courseid, 'id' => $instance->id, 'type' => $instance->enrol);
2511 $editlink = new moodle_url("/enrol/editinstance.php", $linkparams);
2512 $icons[] = $OUTPUT->action_icon($editlink, new pix_icon('t/edit', get_string('edit'), 'core',
2513 array('class' => 'iconsmall')));
2514 }
2515 return $icons;
df997f84
PS
2516 }
2517
2518 /**
2519 * Reads version.php and determines if it is necessary
2520 * to execute the cron job now.
2521 * @return bool
2522 */
2523 public function is_cron_required() {
2524 global $CFG;
2525
2526 $name = $this->get_name();
2527 $versionfile = "$CFG->dirroot/enrol/$name/version.php";
365a5941 2528 $plugin = new stdClass();
df997f84
PS
2529 include($versionfile);
2530 if (empty($plugin->cron)) {
2531 return false;
2532 }
2533 $lastexecuted = $this->get_config('lastcron', 0);
2534 if ($lastexecuted + $plugin->cron < time()) {
2535 return true;
2536 } else {
2537 return false;
2538 }
2539 }
2540
2541 /**
2542 * Called for all enabled enrol plugins that returned true from is_cron_required().
2543 * @return void
2544 */
2545 public function cron() {
2546 }
2547
2548 /**
2549 * Called when user is about to be deleted
2550 * @param object $user
2551 * @return void
2552 */
2553 public function user_delete($user) {
2554 global $DB;
2555
2556 $sql = "SELECT e.*
2557 FROM {enrol} e
45fb2cf8
PS
2558 JOIN {user_enrolments} ue ON (ue.enrolid = e.id)
2559 WHERE e.enrol = :name AND ue.userid = :userid";
df997f84
PS
2560 $params = array('name'=>$this->get_name(), 'userid'=>$user->id);
2561
45fb2cf8 2562 $rs = $DB->get_recordset_sql($sql, $params);
df997f84
PS
2563 foreach($rs as $instance) {
2564 $this->unenrol_user($instance, $user->id);
2565 }
2566 $rs->close();
2567 }
df997f84 2568
b69ca6be
SH
2569 /**
2570 * Returns an enrol_user_button that takes the user to a page where they are able to
2571 * enrol users into the managers course through this plugin.
2572 *
2573 * Optional: If the plugin supports manual enrolments it can choose to override this
2574 * otherwise it shouldn't
2575 *
2576 * @param course_enrolment_manager $manager
2577 * @return enrol_user_button|false
2578 */
2579 public function get_manual_enrol_button(course_enrolment_manager $manager) {
2580 return false;
2581 }
291215f4
SH
2582
2583 /**
2584 * Gets an array of the user enrolment actions
2585 *
2586 * @param course_enrolment_manager $manager
2587 * @param stdClass $ue
2588 * @return array An array of user_enrolment_actions
2589 */
2590 public function get_user_enrolment_actions(course_enrolment_manager $manager, $ue) {
12a52d7c 2591 return array();
291215f4 2592 }
75ee207b
SH
2593
2594 /**
2595 * Returns true if the plugin has one or more bulk operations that can be performed on
2596 * user enrolments.
2597 *
f20edd52 2598 * @param course_enrolment_manager $manager
75ee207b
SH
2599 * @return bool
2600 */
f20edd52 2601 public function has_bulk_operations(course_enrolment_manager $manager) {
75ee207b
SH
2602 return false;
2603 }
2604
2605 /**
2606 * Return an array of enrol_bulk_enrolment_operation objects that define
2607 * the bulk actions that can be performed on user enrolments by the plugin.
2608 *
f20edd52 2609 * @param course_enrolment_manager $manager
75ee207b
SH
2610 * @return array
2611 */
f20edd52 2612 public function get_bulk_operations(course_enrolment_manager $manager) {
75ee207b
SH
2613 return array();
2614 }
7a7b8a1f 2615
d8f22c49
PS
2616 /**
2617 * Do any enrolments need expiration processing.
2618 *
2619 * Plugins that want to call this functionality must implement 'expiredaction' config setting.
2620 *
2621 * @param progress_trace $trace
2622 * @param int $courseid one course, empty mean all
2623 * @return bool true if any data processed, false if not
2624 */
2625 public function process_expirations(progress_trace $trace, $courseid = null) {
2626 global $DB;
2627
2628 $name = $this->get_name();
2629 if (!enrol_is_enabled($name)) {
2630 $trace->finished();
2631 return false;
2632 }
2633
2634 $processed = false;
2635 $params = array();
2636 $coursesql = "";
2637 if ($courseid) {
2638 $coursesql = "AND e.courseid = :courseid";
2639 }
2640
2641 // Deal with expired accounts.
2642 $action = $this->get_config('expiredaction', ENROL_EXT_REMOVED_KEEP);
2643
2644 if ($action == ENROL_EXT_REMOVED_UNENROL) {
2645 $instances = array();
2646 $sql = "SELECT ue.*, e.courseid, c.id AS contextid
2647 FROM {user_enrolments} ue
2648 JOIN {enrol} e ON (e.id = ue.enrolid AND e.enrol = :enrol)
2649 JOIN {context} c ON (c.instanceid = e.courseid AND c.contextlevel = :courselevel)
2650 WHERE ue.timeend > 0 AND ue.timeend < :now $coursesql";
2651 $params = array('now'=>time(), 'courselevel'=>CONTEXT_COURSE, 'enrol'=>$name, 'courseid'=>$courseid);
2652
2653 $rs = $DB->get_recordset_sql($sql, $params);
2654 foreach ($rs as $ue) {
2655 if (!$processed) {
2656 $trace->output("Starting processing of enrol_$name expirations...");
2657 $processed = true;
2658 }
2659 if (empty($instances[$ue->enrolid])) {
2660 $instances[$ue->enrolid] = $DB->get_record('enrol', array('id'=>$ue->enrolid));
2661 }
2662 $instance = $instances[$ue->enrolid];
2663 if (!$this->roles_protected()) {
2664 // Let's just guess what extra roles are supposed to be removed.
2665 if ($instance->roleid) {
2666 role_unassign($instance->roleid, $ue->userid, $ue->contextid);
2667 }
2668 }
2669 // The unenrol cleans up all subcontexts if this is the only course enrolment for this user.
2670 $this->unenrol_user($instance, $ue->userid);
2671 $trace->output("Unenrolling expired user $ue->userid from course $instance->courseid", 1);
2672 }
2673 $rs->close();
2674 unset($instances);
2675
2676 } else if ($action == ENROL_EXT_REMOVED_SUSPENDNOROLES or $action == ENROL_EXT_REMOVED_SUSPEND) {
2677 $instances = array();
2678 $sql = "SELECT ue.*, e.courseid, c.id AS contextid
2679 FROM {user_enrolments} ue
2680 JOIN {enrol} e ON (e.id = ue.enrolid AND e.enrol = :enrol)
2681 JOIN {context} c ON (c.instanceid = e.courseid AND c.contextlevel = :courselevel)
2682 WHERE ue.timeend > 0 AND ue.timeend < :now
2683 AND ue.status = :useractive $coursesql";
2684 $params = array('now'=>time(), 'courselevel'=>CONTEXT_COURSE, 'useractive'=>ENROL_USER_ACTIVE, 'enrol'=>$name, 'courseid'=>$courseid);
2685 $rs = $DB->get_recordset_sql($sql, $params);
2686 foreach ($rs as $ue) {
2687 if (!$processed) {
2688 $trace->output("Starting processing of enrol_$name expirations...");
2689 $processed = true;
2690 }
2691 if (empty($instances[$ue->enrolid])) {
2692 $instances[$ue->enrolid] = $DB->get_record('enrol', array('id'=>$ue->enrolid));
2693 }
2694 $instance = $instances[$ue->enrolid];
2695
2696 if ($action == ENROL_EXT_REMOVED_SUSPENDNOROLES) {
2697 if (!$this->roles_protected()) {
2698 // Let's just guess what roles should be removed.
2699 $count = $DB->count_records('role_assignments', array('userid'=>$ue->userid, 'contextid'=>$ue->contextid));
2700 if ($count == 1) {
2701 role_unassign_all(array('userid'=>$ue->userid, 'contextid'=>$ue->contextid, 'component'=>'', 'itemid'=>0));
2702
2703 } else if ($count > 1 and $instance->roleid) {
2704 role_unassign($instance->roleid, $ue->userid, $ue->contextid, '', 0);
2705 }
2706 }
2707 // In any case remove all roles that belong to this instance and user.
2708 role_unassign_all(array('userid'=>$ue->userid, 'contextid'=>$ue->contextid, 'component'=>'enrol_'.$name, 'itemid'=>$instance->id), true);
2709 // Final cleanup of subcontexts if there are no more course roles.
2710 if (0 == $DB->count_records('role_assignments', array('userid'=>$ue->userid, 'contextid'=>$ue->contextid))) {
2711 role_unassign_all(array('userid'=>$ue->userid, 'contextid'=>$ue->contextid, 'component'=>'', 'itemid'=>0), true);
2712 }
2713 }
2714
2715 $this->update_user_enrol($instance, $ue->userid, ENROL_USER_SUSPENDED);
2716 $trace->output("Suspending expired user $ue->userid in course $instance->courseid", 1);
2717 }
2718 $rs->close();
2719 unset($instances);
2720
2721 } else {
2722 // ENROL_EXT_REMOVED_KEEP means no changes.
2723 }
2724
2725 if ($processed) {
2726 $trace->output("...finished processing of enrol_$name expirations");
2727 } else {
2728 $trace->output("No expired enrol_$name enrolments detected");
2729 }
2730 $trace->finished();
2731
2732 return $processed;
2733 }
2734
8c04252c
PS
2735 /**
2736 * Send expiry notifications.
2737 *
2738 * Plugin that wants to have expiry notification MUST implement following:
2739 * - expirynotifyhour plugin setting,
2740 * - configuration options in instance edit form (expirynotify, notifyall and expirythreshold),
2741 * - notification strings (expirymessageenrollersubject, expirymessageenrollerbody,
2742 * expirymessageenrolledsubject and expirymessageenrolledbody),
2743 * - expiry_notification provider in db/messages.php,
2744 * - upgrade code that sets default thresholds for existing courses (should be 1 day),
2745 * - something that calls this method, such as cron.
2746 *
5d549ffc 2747 * @param progress_trace $trace (accepts bool for backwards compatibility only)
8c04252c 2748 */
5d549ffc 2749 public function send_expiry_notifications($trace) {
8c04252c
PS
2750 global $DB, $CFG;
2751
d8f22c49
PS
2752 $name = $this->get_name();
2753 if (!enrol_is_enabled($name)) {
2754 $trace->finished();
2755 return;
2756 }
2757
8c04252c
PS
2758 // Unfortunately this may take a long time, it should not be interrupted,
2759 // otherwise users get duplicate notification.
2760
3ef7279f 2761 core_php_time_limit::raise();
8c04252c
PS
2762 raise_memory_limit(MEMORY_HUGE);
2763
8c04252c
PS
2764
2765 $expirynotifylast = $this->get_config('expirynotifylast', 0);
2766 $expirynotifyhour = $this->get_config('expirynotifyhour');
2767 if (is_null($expirynotifyhour)) {
2768 debugging("send_expiry_notifications() in $name enrolment plugin needs expirynotifyhour setting");
5d549ffc 2769 $trace->finished();
8c04252c
PS
2770 return;
2771 }
2772
5d549ffc
PS
2773 if (!($trace instanceof progress_trace)) {
2774 $trace = $trace ? new text_progress_trace() : new null_progress_trace();
2775 debugging('enrol_plugin::send_expiry_notifications() now expects progress_trace instance as parameter!', DEBUG_DEVELOPER);
2776 }
2777
8c04252c
PS
2778 $timenow = time();
2779 $notifytime = usergetmidnight($timenow, $CFG->timezone) + ($expirynotifyhour * 3600);
2780
2781 if ($expirynotifylast > $notifytime) {
5d549ffc
PS
2782 $trace->output($name.' enrolment expiry notifications were already sent today at '.userdate($expirynotifylast, '', $CFG->timezone).'.');
2783 $trace->finished();
8c04252c 2784 return;
5d549ffc 2785
8c04252c 2786 } else if ($timenow < $notifytime) {
5d549ffc
PS
2787 $trace->output($name.' enrolment expiry notifications will be sent at '.userdate($notifytime, '', $CFG->timezone).'.');
2788 $trace->finished();
8c04252c
PS
2789 return;
2790 }
2791
5d549ffc 2792 $trace->output('Processing '.$name.' enrolment expiration notifications...');
8c04252c
PS
2793
2794 // Notify users responsible for enrolment once every day.
2795 $sql = "SELECT ue.*, e.expirynotify, e.notifyall, e.expirythreshold, e.courseid, c.fullname
2796 FROM {user_enrolments} ue
2797 JOIN {enrol} e ON (e.id = ue.enrolid AND e.enrol = :name AND e.expirynotify > 0 AND e.status = :enabled)
2798 JOIN {course} c ON (c.id = e.courseid)
2799 JOIN {user} u ON (u.id = ue.userid AND u.deleted = 0 AND u.suspended = 0)
2800 WHERE ue.status = :active AND ue.timeend > 0 AND ue.timeend > :now1 AND ue.timeend < (e.expirythreshold + :now2)
2801 ORDER BY ue.enrolid ASC, u.lastname ASC, u.firstname ASC, u.id ASC";
2802 $params = array('enabled'=>ENROL_INSTANCE_ENABLED, 'active'=>ENROL_USER_ACTIVE, 'now1'=>$timenow, 'now2'=>$timenow, 'name'=>$name);
2803
2804 $rs = $DB->get_recordset_sql($sql, $params);
2805
2806 $lastenrollid = 0;
2807 $users = array();
2808
2809 foreach($rs as $ue) {
2810 if ($lastenrollid and $lastenrollid != $ue->enrolid) {
5d549ffc 2811 $this->notify_expiry_enroller($lastenrollid, $users, $trace);
8c04252c
PS
2812 $users = array();
2813 }
2814 $lastenrollid = $ue->enrolid;
2815
2816 $enroller = $this->get_enroller($ue->enrolid);
2817 $context = context_course::instance($ue->courseid);
2818
2819 $user = $DB->get_record('user', array('id'=>$ue->userid));
2820
2821 $users[] = array('fullname'=>fullname($user, has_capability('moodle/site:viewfullnames', $context, $enroller)), 'timeend'=>$ue->timeend);
2822
2823 if (!$ue->notifyall) {
2824 continue;
2825 }
2826
2827 if ($ue->timeend - $ue->expirythreshold + 86400 < $timenow) {
2828 // Notify enrolled users only once at the start of the threshold.
5d549ffc 2829 $trace->output("user $ue->userid was already notified that enrolment in course $ue->courseid expires on ".userdate($ue->timeend, '', $CFG->timezone), 1);
8c04252c
PS
2830 continue;
2831 }
2832
5d549ffc 2833 $this->notify_expiry_enrolled($user, $ue, $trace);
8c04252c
PS
2834 }
2835 $rs->close();
2836
2837 if ($lastenrollid and $users) {
5d549ffc 2838 $this->notify_expiry_enroller($lastenrollid, $users, $trace);
8c04252c
PS
2839 }
2840
5d549ffc
PS
2841 $trace->output('...notification processing finished.');
2842 $trace->finished();
2843
8c04252c
PS
2844 $this->set_config('expirynotifylast', $timenow);
2845 }
2846
2847 /**
2848 * Returns the user who is responsible for enrolments for given instance.
2849 *
2850 * Override if plugin knows anybody better than admin.
2851 *
2852 * @param int $instanceid enrolment instance id
2853 * @return stdClass user record
2854 */
2855 protected function get_enroller($instanceid) {
2856 return get_admin();
2857 }
2858
2859 /**
2860 * Notify user about incoming expiration of their enrolment,
2861 * it is called only if notification of enrolled users (aka students) is enabled in course.
2862 *
2863 * This is executed only once for each expiring enrolment right
2864 * at the start of the expiration threshold.
2865 *
2866 * @param stdClass $user
2867 * @param stdClass $ue
5d549ffc 2868 * @param progress_trace $trace
8c04252c 2869 */
5d549ffc 2870 protected function notify_expiry_enrolled($user, $ue, progress_trace $trace) {
c484af5a 2871 global $CFG;
8c04252c
PS
2872
2873 $name = $this->get_name();
2874
c484af5a 2875 $oldforcelang = force_current_language($user->lang);
8c04252c
PS
2876
2877 $enroller = $this->get_enroller($ue->enrolid);
2878 $context = context_course::instance($ue->courseid);
2879
2880 $a = new stdClass();
2881 $a->course = format_string($ue->fullname, true, array('context'=>$context));
2882 $a->user = fullname($user, true);
2883 $a->timeend = userdate($ue->timeend, '', $user->timezone);
2884 $a->enroller = fullname($enroller, has_capability('moodle/site:viewfullnames', $context, $user));
2885
2886 $subject = get_string('expirymessageenrolledsubject', 'enrol_'.$name, $a);
2887 $body = get_string('expirymessageenrolledbody', 'enrol_'.$name, $a);
2888
cc350fd9 2889 $message = new \core\message\message();
880fc15b 2890 $message->courseid = $ue->courseid;
8c04252c
PS
2891 $message->notification = 1;
2892 $message->component = 'enrol_'.$name;
2893 $message->name = 'expiry_notification';
2894 $message->userfrom = $enroller;
2895 $message->userto = $user;
2896 $message->subject = $subject;
2897 $message->fullmessage = $body;
2898 $message->fullmessageformat = FORMAT_MARKDOWN;
2899 $message->fullmessagehtml = markdown_to_html($body);
2900 $message->smallmessage = $subject;
2901 $message->contexturlname = $a->course;
2902 $message->contexturl = (string)new moodle_url('/course/view.php', array('id'=>$ue->courseid));
2903
2904 if (message_send($message)) {
5d549ffc 2905 $trace->output("notifying user $ue->userid that enrolment in course $ue->courseid expires on ".userdate($ue->timeend, '', $CFG->timezone), 1);
8c04252c 2906 } else {
5d549ffc 2907 $trace->output("error notifying user $ue->userid that enrolment in course $ue->courseid expires on ".userdate($ue->timeend, '', $CFG->timezone), 1);
8c04252c
PS
2908 }
2909
c484af5a 2910 force_current_language($oldforcelang);
8c04252c
PS
2911 }
2912
2913 /**
2914 * Notify person responsible for enrolments that some user enrolments will be expired soon,
2915 * it is called only if notification of enrollers (aka teachers) is enabled in course.
2916 *
2917 * This is called repeatedly every day for each course if there are any pending expiration
2918 * in the expiration threshold.
2919 *
2920 * @param int $eid
2921 * @param array $users
5d549ffc 2922 * @param progress_trace $trace
8c04252c 2923 */
5d549ffc 2924 protected function notify_expiry_enroller($eid, $users, progress_trace $trace) {
c484af5a 2925 global $DB;
8c04252c
PS
2926
2927 $name = $this->get_name();
2928
2929 $instance = $DB->get_record('enrol', array('id'=>$eid, 'enrol'=>$name));
2930 $context = context_course::instance($instance->courseid);
2931 $course = $DB->get_record('course', array('id'=>$instance->courseid));
2932
2933 $enroller = $this->get_enroller($instance->id);
2934 $admin = get_admin();
2935
c484af5a 2936 $oldforcelang = force_current_language($enroller->lang);
8c04252c
PS
2937
2938 foreach($users as $key=>$info) {
2939 $users[$key] = '* '.$info['fullname'].' - '.userdate($info['timeend'], '', $enroller->timezone);
2940 }
2941
2942 $a = new stdClass();
2943 $a->course = format_string($course->fullname, true, array('context'=>$context));
2944 $a->threshold = get_string('numdays', '', $instance->expirythreshold / (60*60*24));
2945 $a->users = implode("\n", $users);
4b50765b 2946 $a->extendurl = (string)new moodle_url('/user/index.php', array('id'=>$instance->courseid));
8c04252c
PS
2947
2948 $subject = get_string('expirymessageenrollersubject', 'enrol_'.$name, $a);
2949 $body = get_string('expirymessageenrollerbody', 'enrol_'.$name, $a);
2950
cc350fd9 2951 $message = new \core\message\message();
880fc15b 2952 $message->courseid = $course->id;
8c04252c
PS
2953 $message->notification = 1;
2954 $message->component = 'enrol_'.$name;
2955 $message->name = 'expiry_notification';
2956 $message->userfrom = $admin;
2957 $message->userto = $enroller;
2958 $message->subject = $subject;
2959 $message->fullmessage = $body;
2960 $message->fullmessageformat = FORMAT_MARKDOWN;
2961 $message->fullmessagehtml = markdown_to_html($body);
2962 $message->smallmessage = $subject;
2963 $message->contexturlname = $a->course;
2964 $message->contexturl = $a->extendurl;
2965
2966 if (message_send($message)) {
5d549ffc 2967 $trace->output("notifying user $enroller->id about all expiring $name enrolments in course $instance->courseid", 1);
8c04252c 2968 } else {
5d549ffc 2969 $trace->output("error notifying user $enroller->id about all expiring $name enrolments in course $instance->courseid", 1);
8c04252c
PS
2970 }
2971
c484af5a 2972 force_current_language($oldforcelang);
8c04252c
PS
2973 }
2974
f6199295
MP
2975 /**
2976 * Backup execution step hook to annotate custom fields.
2977 *
2978 * @param backup_enrolments_execution_step $step
2979 * @param stdClass $enrol
2980 */
2981 public function backup_annotate_custom_fields(backup_enrolments_execution_step $step, stdClass $enrol) {
2982 // Override as necessary to annotate custom fields in the enrol table.
2983 }
2984
7a7b8a1f
PS
2985 /**
2986 * Automatic enrol sync executed during restore.
2987 * Useful for automatic sync by course->idnumber or course category.
2988 * @param stdClass $course course record
2989 */
2990 public function restore_sync_course($course) {
2991 // Override if necessary.
2992 }
2993
2994 /**
2995 * Restore instance and map settings.
2996 *
2997 * @param restore_enrolments_structure_step $step
2998 * @param stdClass $data
2999 * @param stdClass $course
3000 * @param int $oldid
3001 */
3002 public function restore_instance(restore_enrolments_structure_step $step, stdClass $data, $course, $oldid) {
3003 // Do not call this from overridden methods, restore and set new id there.
3004 $step->set_mapping('enrol', $oldid, 0);
3005 }
3006
3007 /**
3008 * Restore user enrolment.
3009 *
3010 * @param restore_enrolments_structure_step $step
3011 * @param stdClass $data
3012 * @param stdClass $instance
3013 * @param int $oldinstancestatus
3014 * @param int $userid
3015 */
3016 public function restore_user_enrolment(restore_enrolments_structure_step $step, $data, $instance, $userid, $oldinstancestatus) {
3017 // Override as necessary if plugin supports restore of enrolments.
3018 }
3019
3020 /**
3021 * Restore role assignment.
3022 *
3023 * @param stdClass $instance
3024 * @param int $roleid
3025 * @param int $userid
3026 * @param int $contextid
3027 */
3028 public function restore_role_assignment($instance, $roleid, $userid, $contextid) {
3029 // No role assignment by default, override if necessary.
3030 }
7881024e
PS
3031
3032 /**
3033 * Restore user group membership.
3034 * @param stdClass $instance
3035 * @param int $groupid
3036 * @param int $userid
3037 */
3038 public function restore_group_member($instance, $groupid, $userid) {
3039 // Implement if you want to restore protected group memberships,
3040 // usually this is not necessary because plugins should be able to recreate the memberships automatically.
3041 }
60010fd6
DW
3042
3043 /**
3044 * Returns defaults for new instances.
3045 * @since Moodle 3.1
3046 * @return array
3047 */
3048 public function get_instance_defaults() {
3049 return array();
3050 }
3051
3052 /**
3053 * Validate a list of parameter names and types.
3054 * @since Moodle 3.1
3055 *
3056 * @param array $data array of ("fieldname"=>value) of submitted data
3057 * @param array $rules array of ("fieldname"=>PARAM_X types - or "fieldname"=>array( list of valid options )
3058 * @return array of "element_name"=>"error_description" if there are errors,
3059 * or an empty array if everything is OK.
3060 */
3061 public function validate_param_types($data, $rules) {
3062 $errors = array();
3063 $invalidstr = get_string('invaliddata', 'error');
3064 foreach ($rules as $fieldname => $rule) {
3065 if (is_array($rule)) {
3066 if (!in_array($data[$fieldname], $rule)) {
3067 $errors[$fieldname] = $invalidstr;
3068 }
3069 } else {
3070 if ($data[$fieldname] != clean_param($data[$fieldname], $rule)) {
3071 $errors[$fieldname] = $invalidstr;
3072 }
3073 }
3074 }
3075 return $errors;
3076 }
4b715423 3077}