[Summary view]

Differences Between: [Versions 401 and 402] [Versions 401 and 403]

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