enrol/meta/lib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * Meta course enrolment plugin.
  19  *
  20  * @package    enrol_meta
  21  * @copyright  2010 Petr Skoda {@link http://skodak.org}
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 defined('MOODLE_INTERNAL') || die();
  26
  27 /**
  28  * ENROL_META_CREATE_GROUP constant for automatically creating a group for a meta course.
  29  */
  30 define('ENROL_META_CREATE_GROUP', -1);
  31
  32 /**
  33  * Meta course enrolment plugin.
  34  * @author Petr Skoda
  35  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  36  */
  37 class enrol_meta_plugin extends enrol_plugin {
  38
  39     /**
  40      * Returns localised name of enrol instance
  41      *
  42      * @param stdClass $instance (null is accepted too)
  43      * @return string
  44      */
  45     public function get_instance_name($instance) {
  46         global $DB;
  47
  48         if (empty($instance)) {
  49             $enrol = $this->get_name();
  50             return get_string('pluginname', 'enrol_'.$enrol);
  51         } else if (empty($instance->name)) {
  52             $enrol = $this->get_name();
  53             $course = $DB->get_record('course', array('id'=>$instance->customint1));
  54             if ($course) {
  55                 $coursename = format_string(get_course_display_name_for_list($course));
  56             } else {
  57                 // Use course id, if course is deleted.
  58                 $coursename = $instance->customint1;
  59             }
  60             return get_string('pluginname', 'enrol_' . $enrol) . ' (' . $coursename . ')';
  61         } else {
  62             return format_string($instance->name);
  63         }
  64     }
  65
  66     /**
  67      * Returns true if we can add a new instance to this course.
  68      *
  69      * @param int $courseid
  70      * @return boolean
  71      */
  72     public function can_add_instance($courseid) {
  73         $context = context_course::instance($courseid, MUST_EXIST);
  74         if (!has_capability('moodle/course:enrolconfig', $context) or !has_capability('enrol/meta:config', $context)) {
  75             return false;
  76         }
  77         // Multiple instances supported - multiple parent courses linked.
  78         return true;
  79     }
  80
  81     /**
  82      * Does this plugin allow manual unenrolment of a specific user?
  83      * Yes, but only if user suspended...
  84      *
  85      * @param stdClass $instance course enrol instance
  86      * @param stdClass $ue record from user_enrolments table
  87      *
  88      * @return bool - true means user with 'enrol/xxx:unenrol' may unenrol this user, false means nobody may touch this user enrolment
  89      */
  90     public function allow_unenrol_user(stdClass $instance, stdClass $ue) {
  91         if ($ue->status == ENROL_USER_SUSPENDED) {
  92             return true;
  93         }
  94
  95         return false;
  96     }
  97
  98     /**
  99      * Called after updating/inserting course.
 100      *
 101      * @param bool $inserted true if course just inserted
 102      * @param stdClass $course
 103      * @param stdClass $data form data
 104      * @return void
 105      */
 106     public function course_updated($inserted, $course, $data) {
 107         // Meta sync updates are slow, if enrolments get out of sync teacher will have to wait till next cron.
 108         // We should probably add some sync button to the course enrol methods overview page.
 109     }
 110
 111     /**
 112      * Add new instance of enrol plugin.
 113      * @param object $course
 114      * @param array $fields instance fields
 115      * @return int id of last instance, null if can not be created
 116      */
 117     public function add_instance($course, array $fields = null) {
 118         global $CFG;
 119
 120         require_once("$CFG->dirroot/enrol/meta/locallib.php");
 121
 122         // Support creating multiple at once.
 123         if (isset($fields['customint1']) && is_array($fields['customint1'])) {
 124             $courses = array_unique($fields['customint1']);
 125         } else if (isset($fields['customint1'])) {
 126             $courses = array($fields['customint1']);
 127         } else {
 128             $courses = array(null); // Strange? Yes, but that's how it's working or instance is not created ever.
 129         }
 130         foreach ($courses as $courseid) {
 131             if (!empty($fields['customint2']) && $fields['customint2'] == ENROL_META_CREATE_GROUP) {
 132                 $context = context_course::instance($course->id);
 133                 require_capability('moodle/course:managegroups', $context);
 134                 $groupid = enrol_meta_create_new_group($course->id, $courseid);
 135                 $fields['customint2'] = $groupid;
 136             }
 137
 138             $fields['customint1'] = $courseid;
 139             $result = parent::add_instance($course, $fields);
 140         }
 141
 142         enrol_meta_sync($course->id);
 143
 144         return $result;
 145     }
 146
 147     /**
 148      * Update instance of enrol plugin.
 149      * @param stdClass $instance
 150      * @param stdClass $data modified instance fields
 151      * @return boolean
 152      */
 153     public function update_instance($instance, $data) {
 154         global $CFG;
 155
 156         require_once("$CFG->dirroot/enrol/meta/locallib.php");
 157
 158         if (!empty($data->customint2) && $data->customint2 == ENROL_META_CREATE_GROUP) {
 159             $context = context_course::instance($instance->courseid);
 160             require_capability('moodle/course:managegroups', $context);
 161             $groupid = enrol_meta_create_new_group($instance->courseid, $data->customint1);
 162             $data->customint2 = $groupid;
 163         }
 164
 165         $result = parent::update_instance($instance, $data);
 166
 167         enrol_meta_sync($instance->courseid);
 168
 169         return $result;
 170     }
 171
 172     /**
 173      * Update instance status
 174      *
 175      * @param stdClass $instance
 176      * @param int $newstatus ENROL_INSTANCE_ENABLED, ENROL_INSTANCE_DISABLED
 177      * @return void
 178      */
 179     public function update_status($instance, $newstatus) {
 180         global $CFG;
 181
 182         parent::update_status($instance, $newstatus);
 183
 184         require_once("$CFG->dirroot/enrol/meta/locallib.php");
 185         enrol_meta_sync($instance->courseid);
 186     }
 187
 188     /**
 189      * Is it possible to delete enrol instance via standard UI?
 190      *
 191      * @param stdClass $instance
 192      * @return bool
 193      */
 194     public function can_delete_instance($instance) {
 195         $context = context_course::instance($instance->courseid);
 196         return has_capability('enrol/meta:config', $context);
 197     }
 198
 199     /**
 200      * Is it possible to hide/show enrol instance via standard UI?
 201      *
 202      * @param stdClass $instance
 203      * @return bool
 204      */
 205     public function can_hide_show_instance($instance) {
 206         $context = context_course::instance($instance->courseid);
 207         return has_capability('enrol/meta:config', $context);
 208     }
 209
 210     /**
 211      * We are a good plugin and don't invent our own UI/validation code path.
 212      *
 213      * @return boolean
 214      */
 215     public function use_standard_editing_ui() {
 216         return true;
 217     }
 218
 219     /**
 220      * Return an array of valid options for the courses.
 221      *
 222      * @param stdClass $instance
 223      * @param context $coursecontext
 224      * @return array
 225      */
 226     protected function get_course_options($instance, $coursecontext) {
 227         global $DB;
 228
 229         if ($instance->id) {
 230             $where = 'WHERE c.id = :courseid';
 231             $params = array('courseid' => $instance->customint1);
 232             $existing = array();
 233         } else {
 234             $where = '';
 235             $params = array();
 236             $instanceparams = array('enrol' => 'meta', 'courseid' => $instance->courseid);
 237             $existing = $DB->get_records('enrol', $instanceparams, '', 'customint1, id');
 238         }
 239
 240         // TODO: this has to be done via ajax or else it will fail very badly on large sites!
 241         $courses = array();
 242         $select = ', ' . context_helper::get_preload_record_columns_sql('ctx');
 243         $join = "LEFT JOIN {context} ctx ON (ctx.instanceid = c.id AND ctx.contextlevel = :contextlevel)";
 244
 245         $sortorder = 'c.' . $this->get_config('coursesort', 'sortorder') . ' ASC';
 246
 247         $sql = "SELECT c.id, c.fullname, c.shortname, c.visible $select FROM {course} c $join $where ORDER BY $sortorder";
 248         $rs = $DB->get_recordset_sql($sql, array('contextlevel' => CONTEXT_COURSE) + $params);
 249         foreach ($rs as $c) {
 250             if ($c->id == SITEID or $c->id == $instance->courseid or isset($existing[$c->id])) {
 251                 continue;
 252             }
 253             context_helper::preload_from_record($c);
 254             $coursecontext = context_course::instance($c->id);
 255             if (!$c->visible and !has_capability('moodle/course:viewhiddencourses', $coursecontext)) {
 256                 continue;
 257             }
 258             if (!has_capability('enrol/meta:selectaslinked', $coursecontext)) {
 259                 continue;
 260             }
 261             $courses[$c->id] = $coursecontext->get_context_name(false);
 262         }
 263         $rs->close();
 264         return $courses;
 265     }
 266
 267     /**
 268      * Return an array of valid options for the groups.
 269      *
 270      * @param context $coursecontext
 271      * @return array
 272      */
 273     protected function get_group_options($coursecontext) {
 274         $groups = array(0 => get_string('none'));
 275         $courseid = $coursecontext->instanceid;
 276         if (has_capability('moodle/course:managegroups', $coursecontext)) {
 277             $groups[ENROL_META_CREATE_GROUP] = get_string('creategroup', 'enrol_meta');
 278         }
 279         foreach (groups_get_all_groups($courseid) as $group) {
 280             $groups[$group->id] = format_string($group->name, true, array('context' => $coursecontext));
 281         }
 282         return $groups;
 283     }
 284
 285     /**
 286      * Add elements to the edit instance form.
 287      *
 288      * @param stdClass $instance
 289      * @param MoodleQuickForm $mform
 290      * @param context $coursecontext
 291      * @return bool
 292      */
 293     public function edit_instance_form($instance, MoodleQuickForm $mform, $coursecontext) {
 294         global $DB;
 295
 296         $groups = $this->get_group_options($coursecontext);
 297         $existing = $DB->get_records('enrol', array('enrol' => 'meta', 'courseid' => $coursecontext->instanceid), '', 'customint1, id');
 298
 299         $excludelist = array($coursecontext->instanceid);
 300         foreach ($existing as $existinginstance) {
 301             $excludelist[] = $existinginstance->customint1;
 302         }
 303
 304         $options = array(
 305             'requiredcapabilities' => array('enrol/meta:selectaslinked'),
 306             'multiple' => empty($instance->id),  // We only accept multiple values on creation.
 307             'exclude' => $excludelist
 308         );
 309         $mform->addElement('course', 'customint1', get_string('linkedcourse', 'enrol_meta'), $options);
 310         $mform->addRule('customint1', get_string('required'), 'required', null, 'client');
 311         if (!empty($instance->id)) {
 312             $mform->freeze('customint1');
 313         }
 314
 315         $mform->addElement('select', 'customint2', get_string('addgroup', 'enrol_meta'), $groups);
 316     }
 317
 318     /**
 319      * Perform custom validation of the data used to edit the instance.
 320      *
 321      * @param array $data array of ("fieldname"=>value) of submitted data
 322      * @param array $files array of uploaded files "element_name"=>tmp_file_path
 323      * @param object $instance The instance loaded from the DB
 324      * @param context $context The context of the instance we are editing
 325      * @return array of "element_name"=>"error_description" if there are errors,
 326      *         or an empty array if everything is OK.
 327      * @return void
 328      */
 329     public function edit_instance_validation($data, $files, $instance, $context) {
 330         global $DB;
 331
 332         $errors = array();
 333         $thiscourseid = $context->instanceid;
 334
 335         if (!empty($data['customint1'])) {
 336             $coursesidarr = is_array($data['customint1']) ? $data['customint1'] : [$data['customint1']];
 337             list($coursesinsql, $coursesinparams) = $DB->get_in_or_equal($coursesidarr, SQL_PARAMS_NAMED, 'metacourseid');
 338             if ($coursesrecords = $DB->get_records_select('course', "id {$coursesinsql}",
 339                 $coursesinparams, '', 'id,visible')) {
 340                 // Cast NULL to 0 to avoid possible mess with the SQL.
 341                 $instanceid = $instance->id ?? 0;
 342
 343                 $existssql = "enrol = :meta AND courseid = :currentcourseid AND id != :id AND customint1 {$coursesinsql}";
 344                 $existsparams = [
 345                     'meta' => 'meta',
 346                     'currentcourseid' => $thiscourseid,
 347                     'id' => $instanceid
 348                 ];
 349                 $existsparams += $coursesinparams;
 350                 if ($DB->record_exists_select('enrol', $existssql, $existsparams)) {
 351                     // We may leave right here as further checks do not make sense in case we have existing enrol records
 352                     // with the parameters from above.
 353                     $errors['customint1'] = get_string('invalidcourseid', 'error');
 354                 } else {
 355                     foreach ($coursesrecords as $coursesrecord) {
 356                         $coursecontext = context_course::instance($coursesrecord->id);
 357                         if (!$coursesrecord->visible and !has_capability('moodle/course:viewhiddencourses', $coursecontext)) {
 358                             $errors['customint1'] = get_string('nopermissions', 'error',
 359                                 'moodle/course:viewhiddencourses');
 360                         } else if (!has_capability('enrol/meta:selectaslinked', $coursecontext)) {
 361                             $errors['customint1'] = get_string('nopermissions', 'error',
 362                                 'enrol/meta:selectaslinked');
 363                         } else if ($coursesrecord->id == SITEID or $coursesrecord->id == $thiscourseid) {
 364                             $errors['customint1'] = get_string('invalidcourseid', 'error');
 365                         }
 366                     }
 367                 }
 368             } else {
 369                 $errors['customint1'] = get_string('invalidcourseid', 'error');
 370             }
 371         } else {
 372             $errors['customint1'] = get_string('required');
 373         }
 374
 375         $validgroups = array_keys($this->get_group_options($context));
 376
 377         $tovalidate = array(
 378             'customint2' => $validgroups
 379         );
 380         $typeerrors = $this->validate_param_types($data, $tovalidate);
 381         $errors = array_merge($errors, $typeerrors);
 382
 383         return $errors;
 384     }
 385
 386     /**
 387      * Check if data is valid for a given enrolment plugin
 388      *
 389      * @param array $enrolmentdata enrolment data to validate.
 390      * @param int|null $courseid Course ID.
 391      * @return array Errors
 392      */
 393     public function validate_enrol_plugin_data(array $enrolmentdata, ?int $courseid = null): array {
 394         global $DB;
 395
 396         $errors = [];
 397         if (!enrol_is_enabled('meta')) {
 398             $errors['plugindisabled'] =
 399                 new lang_string('plugindisabled', 'plugin');
 400         }
 401
 402         if (isset($enrolmentdata['addtogroup'])) {
 403             $addtogroup = $enrolmentdata['addtogroup'];
 404             if (($addtogroup == 1) || ($addtogroup == 0)) {
 405                 if (isset($enrolmentdata['groupname'])) {
 406                     $errors['erroraddtogroupgroupname'] =
 407                         new lang_string('erroraddtogroupgroupname', 'group');
 408                 }
 409             } else {
 410                 $errors['erroraddtogroup'] =
 411                     new lang_string('erroraddtogroup', 'group');
 412             }
 413         }
 414
 415         if ($courseid) {
 416             $enrolmentdata = $this->fill_enrol_custom_fields($enrolmentdata, $courseid);
 417
 418             if (isset($enrolmentdata['groupname']) && $enrolmentdata['groupname']) {
 419                 $groupname = $enrolmentdata['groupname'];
 420                 if (!groups_get_group_by_name($courseid, $groupname)) {
 421                     $errors['errorinvalidgroup'] =
 422                         new lang_string('errorinvalidgroup', 'group', $groupname);
 423                 }
 424             }
 425         }
 426
 427         if (!isset($enrolmentdata['metacoursename'])) {
 428             $errors['missingmandatoryfields'] =
 429                 new lang_string('missingmandatoryfields', 'tool_uploadcourse',
 430                     'metacoursename');
 431         } else {
 432             $metacoursename = $enrolmentdata['metacoursename'];
 433             $metacourseid = $DB->get_field('course', 'id', ['shortname' => $metacoursename]);
 434
 435             if (!$metacourseid) {
 436                 $errors['unknownmetacourse'] =
 437                     new lang_string('unknownmetacourse', 'enrol_meta', $metacoursename);
 438             }
 439
 440             if ($courseid && ($courseid == $metacourseid)) {
 441                 $errors['samemetacourse'] =
 442                     new lang_string('samemetacourse', 'enrol_meta', $metacoursename);
 443             }
 444         }
 445         return $errors;
 446     }
 447
 448     /**
 449      * Fill custom fields data for a given enrolment plugin.
 450      *
 451      * @param array $enrolmentdata enrolment data.
 452      * @param int $courseid Course ID.
 453      * @return array Updated enrolment data with custom fields info.
 454      */
 455     public function fill_enrol_custom_fields(array $enrolmentdata, int $courseid): array {
 456         global $DB;
 457
 458         $metacoursename = $enrolmentdata['metacoursename'];
 459         $enrolmentdata['customint1'] =
 460             $DB->get_field('course', 'id', ['shortname' => $metacoursename]);
 461
 462         if (isset($enrolmentdata['addtogroup'])) {
 463             if ($enrolmentdata['addtogroup'] == 0) {
 464                 $enrolmentdata['customint2'] = 0;
 465             } else if ($enrolmentdata['addtogroup'] == 1) {
 466                 $enrolmentdata['customint2'] = ENROL_META_CREATE_GROUP;
 467             }
 468         } else if (isset($enrolmentdata['groupname'])) {
 469             $enrolmentdata['customint2'] = groups_get_group_by_name($courseid, $enrolmentdata['groupname']);
 470         }
 471         return $enrolmentdata + [
 472             'customint1' => null,
 473             'customint2' => null,
 474         ];
 475     }
 476
 477     /**
 478      * Check if enrolment plugin is supported in csv course upload.
 479      *
 480      * @return bool
 481      */
 482     public function is_csv_upload_supported(): bool {
 483         return true;
 484     }
 485
 486     /**
 487      * Finds matching instances for a given course.
 488      *
 489      * @param array $enrolmentdata enrolment data.
 490      * @param int $courseid Course ID.
 491      * @return stdClass|null Matching instance
 492      */
 493     public function find_instance(array $enrolmentdata, int $courseid) : ?stdClass {
 494         global $DB;
 495         $instances = enrol_get_instances($courseid, false);
 496
 497         $instance = null;
 498         if (isset($enrolmentdata['metacoursename'])) {
 499             $metacourseid = $DB->get_field('course', 'id', ['shortname' => $enrolmentdata['metacoursename']]);
 500             if ($metacourseid) {
 501                 foreach ($instances as $i) {
 502                     if ($i->enrol == 'meta' && $i->customint1 == $metacourseid) {
 503                         $instance = $i;
 504                         break;
 505                     }
 506                 }
 507             }
 508         }
 509         return $instance;
 510     }
 511
 512     /**
 513      * Add new instance of enrol plugin with custom settings,
 514      * called when adding new instance manually or when adding new course.
 515      * Used for example on course upload.
 516      *
 517      * Not all plugins support this.
 518      *
 519      * @param stdClass $course Course object
 520      * @param array|null $fields instance fields
 521      * @return int|null id of new instance or null if not supported
 522      */
 523     public function add_custom_instance(stdClass $course, ?array $fields = null): ?int {
 524         return $this->add_instance($course, $fields);
 525     }
 526
 527     /**
 528      * Restore instance and map settings.
 529      *
 530      * @param restore_enrolments_structure_step $step
 531      * @param stdClass $data
 532      * @param stdClass $course
 533      * @param int $oldid
 534      */
 535     public function restore_instance(restore_enrolments_structure_step $step, stdClass $data, $course, $oldid) {
 536         global $DB, $CFG;
 537
 538         if (!$step->get_task()->is_samesite()) {
 539             // No meta restore from other sites.
 540             $step->set_mapping('enrol', $oldid, 0);
 541             return;
 542         }
 543
 544         if (!empty($data->customint2)) {
 545             $data->customint2 = $step->get_mappingid('group', $data->customint2);
 546         }
 547
 548         if ($DB->record_exists('course', array('id' => $data->customint1))) {
 549             $instance = $DB->get_record('enrol', array('roleid' => $data->roleid, 'customint1' => $data->customint1,
 550                 'courseid' => $course->id, 'enrol' => $this->get_name()));
 551             if ($instance) {
 552                 $instanceid = $instance->id;
 553             } else {
 554                 $instanceid = $this->add_instance($course, (array)$data);
 555             }
 556             $step->set_mapping('enrol', $oldid, $instanceid);
 557
 558             require_once("$CFG->dirroot/enrol/meta/locallib.php");
 559             enrol_meta_sync($data->customint1);
 560
 561         } else {
 562             $step->set_mapping('enrol', $oldid, 0);
 563         }
 564     }
 565
 566     /**
 567      * Restore user enrolment.
 568      *
 569      * @param restore_enrolments_structure_step $step
 570      * @param stdClass $data
 571      * @param stdClass $instance
 572      * @param int $userid
 573      * @param int $oldinstancestatus
 574      */
 575     public function restore_user_enrolment(restore_enrolments_structure_step $step, $data, $instance, $userid, $oldinstancestatus) {
 576         global $DB;
 577
 578         if ($this->get_config('unenrolaction') != ENROL_EXT_REMOVED_SUSPENDNOROLES) {
 579             // Enrolments were already synchronised in restore_instance(), we do not want any suspended leftovers.
 580             return;
 581         }
 582
 583         // ENROL_EXT_REMOVED_SUSPENDNOROLES means all previous enrolments are restored
 584         // but without roles and suspended.
 585
 586         if (!$DB->record_exists('user_enrolments', array('enrolid' => $instance->id, 'userid' => $userid))) {
 587             $this->enrol_user($instance, $userid, null, $data->timestart, $data->timeend, ENROL_USER_SUSPENDED);
 588             if ($instance->customint2) {
 589                 groups_add_member($instance->customint2, $userid, 'enrol_meta', $instance->id);
 590             }
 591         }
 592     }
 593
 594     /**
 595      * Restore user group membership.
 596      * @param stdClass $instance
 597      * @param int $groupid
 598      * @param int $userid
 599      */
 600     public function restore_group_member($instance, $groupid, $userid) {
 601         // Nothing to do here, the group members are added in $this->restore_group_restored().
 602         return;
 603     }
 604
 605 }