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 /**
  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 }