enrol/manual/externallib.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 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 }