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