MDL-63683 enrol: Fix plugin settings when no role has student archetype
[moodle.git] / enrol / mnet / enrol.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/>.
17 /**
18  * Implements the XML-RPC methods this plugin publishes to MNet peers
19  *
20  * This file must be named enrol.php because current MNet framework has the
21  * filename hardcoded in XML-RPC path and we want to be compatible with
22  * Moodle 1.x MNet clients. There is a proposal in MDL-21993 to allow
23  * map XMP-RPC calls to whatever file, function, class or methods. Once this
24  * is fixed, this file will be probably renamed to mnetlib.php (which could
25  * be a common name of a plugin library containing functions/methods callable
26  * via MNet framework.
27  *
28  * @package    enrol_mnet
29  * @copyright  2010 David Mudrak <david@moodle.com>
30  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
31  */
33 defined('MOODLE_INTERNAL') || die();
35 /**
36  * MNet server-side methods that are part of mnetservice_enrol
37  *
38  * The weird name of the class tries to follow a pattern
39  * {plugintype}_{pluginnname}_mnetservice_{servicename}
40  *
41  * Class methods are compatible with API 1 of the service used by Moodle 1.x
42  * and 2.0 peers. The API version might become a part of class name but it is
43  * not neccessary due to how xml-rcp methods are/will be mapped to php methods.
44  */
45 class enrol_mnet_mnetservice_enrol {
47     /**
48      * Returns list of courses that we offer to the caller for remote enrolment of their users
49      *
50      * Since Moodle 2.0, courses are made available for MNet peers by creating an instance
51      * of enrol_mnet plugin for the course. Hidden courses are not returned. If there are two
52      * instances - one specific for the host and one for 'All hosts', the setting of the specific
53      * one is used. The id of the peer is kept in customint1, no other custom fields are used.
54      *
55      * @uses mnet_remote_client Callable via XML-RPC only
56      * @return array
57      */
58     public function available_courses() {
59         global $CFG, $DB;
60         require_once($CFG->libdir.'/filelib.php');
62         if (!$client = get_mnet_remote_client()) {
63             die('Callable via XML-RPC only');
64         }
66         // we call our id as 'remoteid' because it will be sent to the peer
67         // the column aliases are required by MNet protocol API for clients 1.x and 2.0
68         $sql = "SELECT c.id AS remoteid, c.fullname, c.shortname, c.idnumber, c.summary, c.summaryformat,
69                        c.sortorder, c.startdate, cat.id AS cat_id, cat.name AS cat_name,
70                        cat.description AS cat_description, cat.descriptionformat AS cat_descriptionformat,
71                        e.cost, e.currency, e.roleid AS defaultroleid, r.name AS defaultrolename,
72                        e.customint1
73                   FROM {enrol} e
74             INNER JOIN {course} c ON c.id = e.courseid
75             INNER JOIN {course_categories} cat ON cat.id = c.category
76             INNER JOIN {role} r ON r.id = e.roleid
77                  WHERE e.enrol = 'mnet'
78                        AND (e.customint1 = 0 OR e.customint1 = ?)
79                        AND c.visible = 1
80               ORDER BY cat.sortorder, c.sortorder, c.shortname";
82         $rs = $DB->get_recordset_sql($sql, array($client->id));
84         $courses = array();
85         foreach ($rs as $course) {
86             // use the record if it does not exist yet or is host-specific
87             if (empty($courses[$course->remoteid]) or ($course->customint1 > 0)) {
88                 unset($course->customint1); // the client does not need to know this
89                 $context = context_course::instance($course->remoteid);
90                 // Rewrite file URLs so that they are correct
91                 $course->summary = file_rewrite_pluginfile_urls($course->summary, 'pluginfile.php', $context->id, 'course', 'summary', false);
92                 $courses[$course->remoteid] = $course;
93             }
94         }
95         $rs->close();
97         return array_values($courses); // can not use keys for backward compatibility
98     }
100     /**
101      * This method has never been implemented in Moodle MNet API
102      *
103      * @uses mnet_remote_client Callable via XML-RPC only
104      * @return array empty array
105      */
106     public function user_enrolments() {
107         global $CFG, $DB;
109         if (!$client = get_mnet_remote_client()) {
110             die('Callable via XML-RPC only');
111         }
112         return array();
113     }
115     /**
116      * Enrol remote user to our course
117      *
118      * If we do not have local record for the remote user in our database,
119      * it gets created here.
120      *
121      * @uses mnet_remote_client Callable via XML-RPC only
122      * @param array $userdata user details {@see mnet_fields_to_import()}
123      * @param int $courseid our local course id
124      * @return bool true if the enrolment has been successful, throws exception otherwise
125      */
126     public function enrol_user(array $userdata, $courseid) {
127         global $CFG, $DB;
128         require_once(__DIR__.'/lib.php');
130         if (!$client = get_mnet_remote_client()) {
131             die('Callable via XML-RPC only');
132         }
134         if (empty($userdata['username'])) {
135             throw new mnet_server_exception(5021, 'emptyusername', 'enrol_mnet');
136         }
138         // do we know the remote user?
139         $user = $DB->get_record('user', array('username'=>$userdata['username'], 'mnethostid'=>$client->id));
141         if ($user === false) {
142             // here we could check the setting if the enrol_mnet is allowed to auto-register
143             // users {@link http://tracker.moodle.org/browse/MDL-21327}
144             $user = mnet_strip_user((object)$userdata, mnet_fields_to_import($client));
145             $user->mnethostid = $client->id;
146             $user->auth = 'mnet';
147             $user->confirmed = 1;
148             try {
149                 $user->id = $DB->insert_record('user', $user);
150             } catch (Exception $e) {
151                 throw new mnet_server_exception(5011, 'couldnotcreateuser', 'enrol_mnet');
152             }
153         }
155         if (! $course = $DB->get_record('course', array('id'=>$courseid))) {
156             throw new mnet_server_exception(5012, 'coursenotfound', 'enrol_mnet');
157         }
159         $courses = $this->available_courses();
160         $isavailable = false;
161         foreach ($courses as $available) {
162             if ($available->remoteid == $course->id) {
163                 $isavailable = true;
164                 break;
165             }
166         }
167         if (!$isavailable) {
168             throw new mnet_server_exception(5013, 'courseunavailable', 'enrol_mnet');
169         }
171         // try to load host specific enrol_mnet instance first
172         $instance = $DB->get_record('enrol', array('courseid'=>$course->id, 'enrol'=>'mnet', 'customint1'=>$client->id), '*', IGNORE_MISSING);
174         if ($instance === false) {
175             // if not found, try to load instance for all hosts
176             $instance = $DB->get_record('enrol', array('courseid'=>$course->id, 'enrol'=>'mnet', 'customint1'=>0), '*', IGNORE_MISSING);
177         }
179         if ($instance === false) {
180             // this should not happen as the course was returned by {@see self::available_courses()}
181             throw new mnet_server_exception(5017, 'noenrolinstance', 'enrol_mnet');
182         }
184         if (!$enrol = enrol_get_plugin('mnet')) {
185             throw new mnet_server_exception(5018, 'couldnotinstantiate', 'enrol_mnet');
186         }
188         try {
189             $enrol->enrol_user($instance, $user->id, $instance->roleid, time());
191         } catch (Exception $e) {
192             throw new mnet_server_exception(5019, 'couldnotenrol', 'enrol_mnet', $e->getMessage());
193         }
195         return true;
196     }
198     /**
199      * Unenrol remote user from our course
200      *
201      * Only users enrolled via enrol_mnet plugin can be unenrolled remotely. If the
202      * remote user is enrolled into the local course via some other enrol plugin
203      * (enrol_manual for example), the remote host can't touch such enrolment. Please
204      * do not report this behaviour as bug, it is a feature ;-)
205      *
206      * @uses mnet_remote_client Callable via XML-RPC only
207      * @param string $username of the remote user
208      * @param int $courseid of our local course
209      * @return bool true if the unenrolment has been successful, throws exception otherwise
210      */
211     public function unenrol_user($username, $courseid) {
212         global $CFG, $DB;
214         if (!$client = get_mnet_remote_client()) {
215             die('Callable via XML-RPC only');
216         }
218         $user = $DB->get_record('user', array('username'=>$username, 'mnethostid'=>$client->id));
220         if ($user === false) {
221             throw new mnet_server_exception(5014, 'usernotfound', 'enrol_mnet');
222         }
224         if (! $course = $DB->get_record('course', array('id'=>$courseid))) {
225             throw new mnet_server_exception(5012, 'coursenotfound', 'enrol_mnet');
226         }
228         $courses = $this->available_courses();
229         $isavailable = false;
230         foreach ($courses as $available) {
231             if ($available->remoteid == $course->id) {
232                 $isavailable = true;
233                 break;
234             }
235         }
236         if (!$isavailable) {
237             // if they can not enrol, they can not unenrol
238             throw new mnet_server_exception(5013, 'courseunavailable', 'enrol_mnet');
239         }
241         // try to load host specific enrol_mnet instance first
242         $instance = $DB->get_record('enrol', array('courseid'=>$course->id, 'enrol'=>'mnet', 'customint1'=>$client->id), '*', IGNORE_MISSING);
244         if ($instance === false) {
245             // if not found, try to load instance for all hosts
246             $instance = $DB->get_record('enrol', array('courseid'=>$course->id, 'enrol'=>'mnet', 'customint1'=>0), '*', IGNORE_MISSING);
247             $instanceforall = true;
248         }
250         if ($instance === false) {
251             // this should not happen as the course was returned by {@see self::available_courses()}
252             throw new mnet_server_exception(5017, 'noenrolinstance', 'enrol_mnet');
253         }
255         if (!$enrol = enrol_get_plugin('mnet')) {
256             throw new mnet_server_exception(5018, 'couldnotinstantiate', 'enrol_mnet');
257         }
259         if ($DB->record_exists('user_enrolments', array('enrolid'=>$instance->id, 'userid'=>$user->id))) {
260             try {
261                 $enrol->unenrol_user($instance, $user->id);
263             } catch (Exception $e) {
264                 throw new mnet_server_exception(5020, 'couldnotunenrol', 'enrol_mnet', $e->getMessage());
265             }
266         }
268         if (empty($instanceforall)) {
269             // if the user was enrolled via 'All hosts' instance and the specific one
270             // was created after that, the first enrolment would be kept.
271             $instance = $DB->get_record('enrol', array('courseid'=>$course->id, 'enrol'=>'mnet', 'customint1'=>0), '*', IGNORE_MISSING);
273             if ($instance) {
274                 // repeat the same procedure for 'All hosts' instance, too. Note that as the host specific
275                 // instance exists, it will be used for the future enrolments
277                 if ($DB->record_exists('user_enrolments', array('enrolid'=>$instance->id, 'userid'=>$user->id))) {
278                     try {
279                         $enrol->unenrol_user($instance, $user->id);
281                     } catch (Exception $e) {
282                         throw new mnet_server_exception(5020, 'couldnotunenrol', 'enrol_mnet', $e->getMessage());
283                     }
284                 }
285             }
286         }
288         return true;
289     }
291     /**
292      * Returns a list of users from the client server who are enrolled in our course
293      *
294      * Suitable instance of enrol_mnet must be created in the course. This method will not
295      * return any information about the enrolments in courses that are not available for
296      * remote enrolment, even if their users are enrolled into them via other plugin
297      * (note the difference from {@link self::user_enrolments()}).
298      *
299      * This method will return enrolment information for users from hosts regardless
300      * the enrolment plugin. It does not matter if the user was enrolled remotely by
301      * their admin or locally. Once the course is available for remote enrolments, we
302      * will tell them everything about their users.
303      *
304      * In Moodle 1.x the returned array used to be indexed by username. The side effect
305      * of MDL-19219 fix is that we do not need to use such index and therefore we can
306      * return all enrolment records. MNet clients 1.x will only use the last record for
307      * the student, if she is enrolled via multiple plugins.
308      *
309      * @uses mnet_remote_client Callable via XML-RPC only
310      * @param int $courseid ID of our course
311      * @param string|array $roles comma separated list of role shortnames (or array of them)
312      * @return array
313      */
314     public function course_enrolments($courseid, $roles=null) {
315         global $DB, $CFG;
317         if (!$client = get_mnet_remote_client()) {
318             die('Callable via XML-RPC only');
319         }
321         $sql = "SELECT u.username, r.shortname, r.name, e.enrol, ue.timemodified
322                   FROM {user_enrolments} ue
323                   JOIN {user} u ON ue.userid = u.id
324                   JOIN {enrol} e ON ue.enrolid = e.id
325                   JOIN {role} r ON e.roleid = r.id
326                  WHERE u.mnethostid = :mnethostid
327                        AND e.courseid = :courseid
328                        AND u.id <> :guestid
329                        AND u.confirmed = 1
330                        AND u.deleted = 0";
331         $params['mnethostid'] = $client->id;
332         $params['courseid'] = $courseid;
333         $params['guestid'] = $CFG->siteguest;
335         if (!is_null($roles)) {
336             if (!is_array($roles)) {
337                 $roles = explode(',', $roles);
338             }
339             $roles = array_map('trim', $roles);
340             list($rsql, $rparams) = $DB->get_in_or_equal($roles, SQL_PARAMS_NAMED);
341             $sql .= " AND r.shortname $rsql";
342             $params = array_merge($params, $rparams);
343         }
345         list($sort, $sortparams) = users_order_by_sql('u');
346         $sql .= " ORDER BY $sort";
348         $rs = $DB->get_recordset_sql($sql, array_merge($params, $sortparams));
349         $list = array();
350         foreach ($rs as $record) {
351             $list[] = $record;
352         }
353         $rs->close();
355         return $list;
356     }