[Summary view]

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]

   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  use core_external\external_api;
  18  use core_external\external_function_parameters;
  19  use core_external\external_multiple_structure;
  20  use core_external\external_single_structure;
  21  use core_external\external_value;
  22  
  23  /**
  24   * External course participation api.
  25   *
  26   * This api is mostly read only, the actual enrol and unenrol
  27   * support is in each enrol plugin.
  28   *
  29   * @package    enrol_manual
  30   * @category   external
  31   * @copyright  2011 Jerome Mouneyrac
  32   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  33   * @since Moodle 2.2
  34   */
  35  class enrol_manual_external extends external_api {
  36  
  37      /**
  38       * Returns description of method parameters.
  39       *
  40       * @return external_function_parameters
  41       * @since Moodle 2.2
  42       */
  43      public static function enrol_users_parameters() {
  44          return new external_function_parameters(
  45                  array(
  46                      'enrolments' => new external_multiple_structure(
  47                              new external_single_structure(
  48                                      array(
  49                                          'roleid' => new external_value(PARAM_INT, 'Role to assign to the user'),
  50                                          'userid' => new external_value(PARAM_INT, 'The user that is going to be enrolled'),
  51                                          'courseid' => new external_value(PARAM_INT, 'The course to enrol the user role in'),
  52                                          'timestart' => new external_value(PARAM_INT, 'Timestamp when the enrolment start', VALUE_OPTIONAL),
  53                                          'timeend' => new external_value(PARAM_INT, 'Timestamp when the enrolment end', VALUE_OPTIONAL),
  54                                          'suspend' => new external_value(PARAM_INT, 'set to 1 to suspend the enrolment', VALUE_OPTIONAL)
  55                                      )
  56                              )
  57                      )
  58                  )
  59          );
  60      }
  61  
  62      /**
  63       * Enrolment of users.
  64       *
  65       * Function throw an exception at the first error encountered.
  66       * @param array $enrolments  An array of user enrolment
  67       * @since Moodle 2.2
  68       */
  69      public static function enrol_users($enrolments) {
  70          global $DB, $CFG;
  71  
  72          require_once($CFG->libdir . '/enrollib.php');
  73  
  74          $params = self::validate_parameters(self::enrol_users_parameters(),
  75                  array('enrolments' => $enrolments));
  76  
  77          $transaction = $DB->start_delegated_transaction(); // Rollback all enrolment if an error occurs
  78                                                             // (except if the DB doesn't support it).
  79  
  80          // Retrieve the manual enrolment plugin.
  81          $enrol = enrol_get_plugin('manual');
  82          if (empty($enrol)) {
  83              throw new moodle_exception('manualpluginnotinstalled', 'enrol_manual');
  84          }
  85  
  86          foreach ($params['enrolments'] as $enrolment) {
  87              // Ensure the current user is allowed to run this function in the enrolment context.
  88              $context = context_course::instance($enrolment['courseid'], IGNORE_MISSING);
  89              self::validate_context($context);
  90  
  91              // Check that the user has the permission to manual enrol.
  92              require_capability('enrol/manual:enrol', $context);
  93  
  94              // Throw an exception if user is not able to assign the role.
  95              $roles = get_assignable_roles($context);
  96              if (!array_key_exists($enrolment['roleid'], $roles)) {
  97                  $errorparams = new stdClass();
  98                  $errorparams->roleid = $enrolment['roleid'];
  99                  $errorparams->courseid = $enrolment['courseid'];
 100                  $errorparams->userid = $enrolment['userid'];
 101                  throw new moodle_exception('wsusercannotassign', 'enrol_manual', '', $errorparams);
 102              }
 103  
 104              // Check manual enrolment plugin instance is enabled/exist.
 105              $instance = null;
 106              $enrolinstances = enrol_get_instances($enrolment['courseid'], true);
 107              foreach ($enrolinstances as $courseenrolinstance) {
 108                if ($courseenrolinstance->enrol == "manual") {
 109                    $instance = $courseenrolinstance;
 110                    break;
 111                }
 112              }
 113              if (empty($instance)) {
 114                $errorparams = new stdClass();
 115                $errorparams->courseid = $enrolment['courseid'];
 116                throw new moodle_exception('wsnoinstance', 'enrol_manual', $errorparams);
 117              }
 118  
 119              // Check that the plugin accept enrolment (it should always the case, it's hard coded in the plugin).
 120              if (!$enrol->allow_enrol($instance)) {
 121                  $errorparams = new stdClass();
 122                  $errorparams->roleid = $enrolment['roleid'];
 123                  $errorparams->courseid = $enrolment['courseid'];
 124                  $errorparams->userid = $enrolment['userid'];
 125                  throw new moodle_exception('wscannotenrol', 'enrol_manual', '', $errorparams);
 126              }
 127  
 128              // Finally proceed the enrolment.
 129              $enrolment['timestart'] = isset($enrolment['timestart']) ? $enrolment['timestart'] : 0;
 130              $enrolment['timeend'] = isset($enrolment['timeend']) ? $enrolment['timeend'] : 0;
 131              $enrolment['status'] = (isset($enrolment['suspend']) && !empty($enrolment['suspend'])) ?
 132                      ENROL_USER_SUSPENDED : ENROL_USER_ACTIVE;
 133  
 134              $enrol->enrol_user($instance, $enrolment['userid'], $enrolment['roleid'],
 135                      $enrolment['timestart'], $enrolment['timeend'], $enrolment['status']);
 136  
 137          }
 138  
 139          $transaction->allow_commit();
 140      }
 141  
 142      /**
 143       * Returns description of method result value.
 144       *
 145       * @return null
 146       * @since Moodle 2.2
 147       */
 148      public static function enrol_users_returns() {
 149          return null;
 150      }
 151  
 152      /**
 153       * Returns description of method parameters.
 154       *
 155       * @return external_function_parameters
 156       */
 157      public static function unenrol_users_parameters() {
 158          return new external_function_parameters(array(
 159              'enrolments' => new external_multiple_structure(
 160                  new external_single_structure(
 161                      array(
 162                          'userid' => new external_value(PARAM_INT, 'The user that is going to be unenrolled'),
 163                          'courseid' => new external_value(PARAM_INT, 'The course to unenrol the user from'),
 164                          'roleid' => new external_value(PARAM_INT, 'The user role', VALUE_OPTIONAL),
 165                      )
 166                  )
 167              )
 168          ));
 169      }
 170  
 171      /**
 172       * Unenrolment of users.
 173       *
 174       * @param array $enrolments an array of course user and role ids
 175       * @throws coding_exception
 176       * @throws dml_transaction_exception
 177       * @throws invalid_parameter_exception
 178       * @throws moodle_exception
 179       * @throws required_capability_exception
 180       * @throws restricted_context_exception
 181       */
 182      public static function unenrol_users($enrolments) {
 183          global $CFG, $DB;
 184          $params = self::validate_parameters(self::unenrol_users_parameters(), array('enrolments' => $enrolments));
 185          require_once($CFG->libdir . '/enrollib.php');
 186          $transaction = $DB->start_delegated_transaction(); // Rollback all enrolment if an error occurs.
 187          $enrol = enrol_get_plugin('manual');
 188          if (empty($enrol)) {
 189              throw new moodle_exception('manualpluginnotinstalled', 'enrol_manual');
 190          }
 191  
 192          foreach ($params['enrolments'] as $enrolment) {
 193              $context = context_course::instance($enrolment['courseid']);
 194              self::validate_context($context);
 195              require_capability('enrol/manual:unenrol', $context);
 196              $instance = $DB->get_record('enrol', array('courseid' => $enrolment['courseid'], 'enrol' => 'manual'));
 197              if (!$instance) {
 198                  throw new moodle_exception('wsnoinstance', 'enrol_manual', $enrolment);
 199              }
 200              $user = $DB->get_record('user', array('id' => $enrolment['userid']));
 201              if (!$user) {
 202                  throw new invalid_parameter_exception('User id not exist: '.$enrolment['userid']);
 203              }
 204              if (!$enrol->allow_unenrol($instance)) {
 205                  throw new moodle_exception('wscannotunenrol', 'enrol_manual', '', $enrolment);
 206              }
 207              $enrol->unenrol_user($instance, $enrolment['userid']);
 208          }
 209          $transaction->allow_commit();
 210      }
 211  
 212      /**
 213       * Returns description of method result value.
 214       *
 215       * @return null
 216       */
 217      public static function unenrol_users_returns() {
 218          return null;
 219      }
 220  
 221  }