2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
19 * Web services utility functions and classes
21 * @package core_webservice
22 * @copyright 2009 Jerome Mouneyrac <jerome@moodle.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 require_once($CFG->libdir
.'/externallib.php');
29 * WEBSERVICE_AUTHMETHOD_USERNAME - username/password authentication (also called simple authentication)
31 define('WEBSERVICE_AUTHMETHOD_USERNAME', 0);
34 * WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN - most common token authentication (external app, mobile app...)
36 define('WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN', 1);
39 * WEBSERVICE_AUTHMETHOD_SESSION_TOKEN - token for embedded application (requires Moodle session)
41 define('WEBSERVICE_AUTHMETHOD_SESSION_TOKEN', 2);
44 * General web service library
46 * @package core_webservice
47 * @copyright 2010 Jerome Mouneyrac <jerome@moodle.com>
48 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
52 * Only update token last access once per this many seconds. (This constant controls update of
53 * the external tokens last access field. There is a similar define LASTACCESS_UPDATE_SECS
54 * which controls update of the web site last access fields.)
58 const TOKEN_LASTACCESS_UPDATE_SECS
= 60;
61 * Authenticate user (used by download/upload file scripts)
63 * @param string $token
64 * @return array - contains the authenticated user, token and service objects
66 public function authenticate_user($token) {
69 // web service must be enabled to use this script
70 if (!$CFG->enablewebservices
) {
71 throw new webservice_access_exception('Web services are not enabled in Advanced features.');
74 // Obtain token record
75 if (!$token = $DB->get_record('external_tokens', array('token' => $token))) {
76 //client may want to display login form => moodle_exception
77 throw new moodle_exception('invalidtoken', 'webservice');
80 $loginfaileddefaultparams = array(
82 'method' => WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN
,
84 'tokenid' => $token->id
88 // Validate token date
89 if ($token->validuntil
and $token->validuntil
< time()) {
90 $params = $loginfaileddefaultparams;
91 $params['other']['reason'] = 'token_expired';
92 $event = \core\event\webservice_login_failed
::create($params);
93 $event->add_record_snapshot('external_tokens', $token);
94 $event->set_legacy_logdata(array(SITEID
, 'webservice', get_string('tokenauthlog', 'webservice'), '',
95 get_string('invalidtimedtoken', 'webservice'), 0));
97 $DB->delete_records('external_tokens', array('token' => $token->token
));
98 throw new webservice_access_exception('Invalid token - token expired - check validuntil time for the token');
102 if ($token->iprestriction
and !address_in_subnet(getremoteaddr(), $token->iprestriction
)) {
103 $params = $loginfaileddefaultparams;
104 $params['other']['reason'] = 'ip_restricted';
105 $event = \core\event\webservice_login_failed
::create($params);
106 $event->add_record_snapshot('external_tokens', $token);
107 $event->set_legacy_logdata(array(SITEID
, 'webservice', get_string('tokenauthlog', 'webservice'), '',
108 get_string('failedtolog', 'webservice') . ": " . getremoteaddr(), 0));
110 throw new webservice_access_exception('Invalid token - IP:' . getremoteaddr()
111 . ' is not supported');
114 //retrieve user link to the token
115 $user = $DB->get_record('user', array('id' => $token->userid
, 'deleted' => 0), '*', MUST_EXIST
);
117 // let enrol plugins deal with new enrolments if necessary
118 enrol_check_plugins($user, false);
120 // setup user session to check capability
121 \core\session\manager
::set_user($user);
122 set_login_session_preferences();
124 //assumes that if sid is set then there must be a valid associated session no matter the token type
126 if (!\core\session\manager
::session_exists($token->sid
)) {
127 $DB->delete_records('external_tokens', array('sid' => $token->sid
));
128 throw new webservice_access_exception('Invalid session based token - session not found or expired');
132 // Cannot authenticate unless maintenance access is granted.
133 $hasmaintenanceaccess = has_capability('moodle/site:maintenanceaccess', context_system
::instance(), $user);
134 if (!empty($CFG->maintenance_enabled
) and !$hasmaintenanceaccess) {
135 //this is usually temporary, client want to implement code logic => moodle_exception
136 throw new moodle_exception('sitemaintenance', 'admin');
139 //retrieve web service record
140 $service = $DB->get_record('external_services', array('id' => $token->externalserviceid
, 'enabled' => 1));
141 if (empty($service)) {
142 // will throw exception if no token found
143 throw new webservice_access_exception('Web service is not available (it doesn\'t exist or might be disabled)');
146 //check if there is any required system capability
147 if ($service->requiredcapability
and !has_capability($service->requiredcapability
, context_system
::instance(), $user)) {
148 throw new webservice_access_exception('The capability ' . $service->requiredcapability
. ' is required.');
151 //specific checks related to user restricted service
152 if ($service->restrictedusers
) {
153 $authoriseduser = $DB->get_record('external_services_users', array('externalserviceid' => $service->id
, 'userid' => $user->id
));
155 if (empty($authoriseduser)) {
156 throw new webservice_access_exception(
157 'The user is not allowed for this service. First you need to allow this user on the '
158 . $service->name
. '\'s allowed users administration page.');
161 if (!empty($authoriseduser->validuntil
) and $authoriseduser->validuntil
< time()) {
162 throw new webservice_access_exception('Invalid service - service expired - check validuntil time for this allowed user');
165 if (!empty($authoriseduser->iprestriction
) and !address_in_subnet(getremoteaddr(), $authoriseduser->iprestriction
)) {
166 throw new webservice_access_exception('Invalid service - IP:' . getremoteaddr()
167 . ' is not supported - check this allowed user');
171 //only confirmed user should be able to call web service
172 if (empty($user->confirmed
)) {
173 $params = $loginfaileddefaultparams;
174 $params['other']['reason'] = 'user_unconfirmed';
175 $event = \core\event\webservice_login_failed
::create($params);
176 $event->add_record_snapshot('external_tokens', $token);
177 $event->set_legacy_logdata(array(SITEID
, 'webservice', 'user unconfirmed', '', $user->username
));
179 throw new moodle_exception('usernotconfirmed', 'moodle', '', $user->username
);
182 //check the user is suspended
183 if (!empty($user->suspended
)) {
184 $params = $loginfaileddefaultparams;
185 $params['other']['reason'] = 'user_suspended';
186 $event = \core\event\webservice_login_failed
::create($params);
187 $event->add_record_snapshot('external_tokens', $token);
188 $event->set_legacy_logdata(array(SITEID
, 'webservice', 'user suspended', '', $user->username
));
190 throw new moodle_exception('wsaccessusersuspended', 'moodle', '', $user->username
);
193 //check if the auth method is nologin (in this case refuse connection)
194 if ($user->auth
== 'nologin') {
195 $params = $loginfaileddefaultparams;
196 $params['other']['reason'] = 'nologin';
197 $event = \core\event\webservice_login_failed
::create($params);
198 $event->add_record_snapshot('external_tokens', $token);
199 $event->set_legacy_logdata(array(SITEID
, 'webservice', 'nologin auth attempt with web service', '', $user->username
));
201 throw new moodle_exception('wsaccessusernologin', 'moodle', '', $user->username
);
204 //Check if the user password is expired
205 $auth = get_auth_plugin($user->auth
);
206 if (!empty($auth->config
->expiration
) and $auth->config
->expiration
== 1) {
207 $days2expire = $auth->password_expire($user->username
);
208 if (intval($days2expire) < 0) {
209 $params = $loginfaileddefaultparams;
210 $params['other']['reason'] = 'password_expired';
211 $event = \core\event\webservice_login_failed
::create($params);
212 $event->add_record_snapshot('external_tokens', $token);
213 $event->set_legacy_logdata(array(SITEID
, 'webservice', 'expired password', '', $user->username
));
215 throw new moodle_exception('passwordisexpired', 'webservice');
220 self
::update_token_lastaccess($token);
222 return array('user' => $user, 'token' => $token, 'service' => $service);
226 * Updates the last access time for a token.
228 * @param \stdClass $token Token object (must include id, lastaccess fields)
229 * @param int $time Time of access (0 = use current time)
230 * @throws dml_exception If database error
232 public static function update_token_lastaccess($token, int $time = 0) {
239 // Only update the field if it is a different time from previous request,
240 // so as not to waste database effort.
241 if ($time >= $token->lastaccess + self
::TOKEN_LASTACCESS_UPDATE_SECS
) {
242 $DB->set_field('external_tokens', 'lastaccess', $time, array('id' => $token->id
));
247 * Allow user to call a service
249 * @param stdClass $user a user
251 public function add_ws_authorised_user($user) {
253 $user->timecreated
= time();
254 $DB->insert_record('external_services_users', $user);
258 * Disallow a user to call a service
260 * @param stdClass $user a user
261 * @param int $serviceid
263 public function remove_ws_authorised_user($user, $serviceid) {
265 $DB->delete_records('external_services_users',
266 array('externalserviceid' => $serviceid, 'userid' => $user->id
));
270 * Update allowed user settings (ip restriction, valid until...)
272 * @param stdClass $user
274 public function update_ws_authorised_user($user) {
276 $DB->update_record('external_services_users', $user);
280 * Return list of allowed users with their options (ip/timecreated / validuntil...)
281 * for a given service
283 * @param int $serviceid the service id to search against
284 * @return array $users
286 public function get_ws_authorised_users($serviceid) {
289 $params = array($CFG->siteguest
, $serviceid);
291 $userfields = \core_user\fields
::for_identity(context_system
::instance())->with_name()->excluding('id');
292 $fieldsql = $userfields->get_sql('u');
294 $sql = " SELECT u.id as id, esu.id as serviceuserid {$fieldsql->selects},
295 esu.iprestriction as iprestriction, esu.validuntil as validuntil,
296 esu.timecreated as timecreated
298 JOIN {external_services_users} esu ON esu.userid = u.id
300 WHERE u.id <> ? AND u.deleted = 0 AND u.confirmed = 1
301 AND esu.externalserviceid = ?";
303 $users = $DB->get_records_sql($sql, array_merge($fieldsql->params
, $params));
309 * Return an authorised user with their options (ip/timecreated / validuntil...)
311 * @param int $serviceid the service id to search against
312 * @param int $userid the user to search against
315 public function get_ws_authorised_user($serviceid, $userid) {
317 $params = array($CFG->siteguest
, $serviceid, $userid);
318 $sql = " SELECT u.id as id, esu.id as serviceuserid, u.email as email, u.firstname as firstname,
319 u.lastname as lastname,
320 esu.iprestriction as iprestriction, esu.validuntil as validuntil,
321 esu.timecreated as timecreated
322 FROM {user} u, {external_services_users} esu
323 WHERE u.id <> ? AND u.deleted = 0 AND u.confirmed = 1
324 AND esu.userid = u.id
325 AND esu.externalserviceid = ?
327 $user = $DB->get_record_sql($sql, $params);
332 * Generate all tokens of a specific user
334 * @param int $userid user id
336 public function generate_user_ws_tokens($userid) {
339 // generate a token for non admin if web service are enable and the user has the capability to create a token
340 if (!is_siteadmin() && has_capability('moodle/webservice:createtoken', context_system
::instance(), $userid) && !empty($CFG->enablewebservices
)) {
341 // for every service than the user is authorised on, create a token (if it doesn't already exist)
343 // get all services which are set to all user (no restricted to specific users)
344 $norestrictedservices = $DB->get_records('external_services', array('restrictedusers' => 0));
345 $serviceidlist = array();
346 foreach ($norestrictedservices as $service) {
347 $serviceidlist[] = $service->id
;
350 // get all services which are set to the current user (the current user is specified in the restricted user list)
351 $servicesusers = $DB->get_records('external_services_users', array('userid' => $userid));
352 foreach ($servicesusers as $serviceuser) {
353 if (!in_array($serviceuser->externalserviceid
,$serviceidlist)) {
354 $serviceidlist[] = $serviceuser->externalserviceid
;
358 // get all services which already have a token set for the current user
359 $usertokens = $DB->get_records('external_tokens', array('userid' => $userid, 'tokentype' => EXTERNAL_TOKEN_PERMANENT
));
360 $tokenizedservice = array();
361 foreach ($usertokens as $token) {
362 $tokenizedservice[] = $token->externalserviceid
;
365 // create a token for the service which have no token already
366 foreach ($serviceidlist as $serviceid) {
367 if (!in_array($serviceid, $tokenizedservice)) {
368 // create the token for this service
369 $newtoken = new stdClass();
370 $newtoken->token
= md5(uniqid(rand(),1));
371 // check that the user has capability on this service
372 $newtoken->tokentype
= EXTERNAL_TOKEN_PERMANENT
;
373 $newtoken->userid
= $userid;
374 $newtoken->externalserviceid
= $serviceid;
375 // TODO MDL-31190 find a way to get the context - UPDATE FOLLOWING LINE
376 $newtoken->contextid
= context_system
::instance()->id
;
377 $newtoken->creatorid
= $userid;
378 $newtoken->timecreated
= time();
379 // Generate the private token, it must be transmitted only via https.
380 $newtoken->privatetoken
= random_string(64);
382 $DB->insert_record('external_tokens', $newtoken);
391 * Return all tokens of a specific user
392 * + the service state (enabled/disabled)
393 * + the authorised user mode (restricted/not restricted)
395 * @param int $userid user id
398 public function get_user_ws_tokens($userid) {
400 //here retrieve token list (including linked users firstname/lastname and linked services name)
402 t.id, t.creatorid, t.token, u.firstname, u.lastname, s.id as wsid, s.name, s.enabled, s.restrictedusers, t.validuntil
404 {external_tokens} t, {user} u, {external_services} s
406 t.userid=? AND t.tokentype = ".EXTERNAL_TOKEN_PERMANENT
." AND s.id = t.externalserviceid AND t.userid = u.id";
407 $tokens = $DB->get_records_sql($sql, array( $userid));
412 * Return a token that has been created by the user (i.e. to created by an admin)
413 * If no tokens exist an exception is thrown
415 * The returned value is a stdClass:
418 * ->firstname user firstname
420 * ->name service name
422 * @param int $userid user id
423 * @param int $tokenid token id
426 public function get_created_by_user_ws_token($userid, $tokenid) {
429 t.id, t.token, u.firstname, u.lastname, s.name
431 {external_tokens} t, {user} u, {external_services} s
433 t.creatorid=? AND t.id=? AND t.tokentype = "
434 . EXTERNAL_TOKEN_PERMANENT
435 . " AND s.id = t.externalserviceid AND t.userid = u.id";
436 //must be the token creator
437 $token = $DB->get_record_sql($sql, array($userid, $tokenid), MUST_EXIST
);
442 * Return a token of an arbitrary user by tokenid, including details of the associated user and the service name.
443 * If no tokens exist an exception is thrown
445 * The returned value is a stdClass:
448 * ->firstname user firstname
450 * ->name service name
452 * @param int $tokenid token id
455 public function get_token_by_id_with_details($tokenid) {
457 $sql = "SELECT t.id, t.token, u.id AS userid, u.firstname, u.lastname, s.name, t.creatorid
458 FROM {external_tokens} t, {user} u, {external_services} s
459 WHERE t.id=? AND t.tokentype = ? AND s.id = t.externalserviceid AND t.userid = u.id";
460 $token = $DB->get_record_sql($sql, array($tokenid, EXTERNAL_TOKEN_PERMANENT
), MUST_EXIST
);
465 * Return a database token record for a token id
467 * @param int $tokenid token id
468 * @return object token
470 public function get_token_by_id($tokenid) {
472 return $DB->get_record('external_tokens', array('id' => $tokenid));
478 * @param int $tokenid token id
480 public function delete_user_ws_token($tokenid) {
482 $DB->delete_records('external_tokens', array('id'=>$tokenid));
486 * Delete all the tokens belonging to a user.
488 * @param int $userid the user id whose tokens must be deleted
490 public static function delete_user_ws_tokens($userid) {
492 $DB->delete_records('external_tokens', array('userid' => $userid));
497 * Also delete function references and authorised user references.
499 * @param int $serviceid service id
501 public function delete_service($serviceid) {
503 $DB->delete_records('external_services_users', array('externalserviceid' => $serviceid));
504 $DB->delete_records('external_services_functions', array('externalserviceid' => $serviceid));
505 $DB->delete_records('external_tokens', array('externalserviceid' => $serviceid));
506 $DB->delete_records('external_services', array('id' => $serviceid));
510 * Get a full database token record for a given token value
512 * @param string $token
513 * @throws moodle_exception if there is multiple result
515 public function get_user_ws_token($token) {
517 return $DB->get_record('external_tokens', array('token'=>$token), '*', MUST_EXIST
);
521 * Get the functions list of a service list (by id)
523 * @param array $serviceids service ids
524 * @return array of functions
526 public function get_external_functions($serviceids) {
528 if (!empty($serviceids)) {
529 list($serviceids, $params) = $DB->get_in_or_equal($serviceids);
531 FROM {external_functions} f
532 WHERE f.name IN (SELECT sf.functionname
533 FROM {external_services_functions} sf
534 WHERE sf.externalserviceid $serviceids)
535 ORDER BY f.name ASC";
536 $functions = $DB->get_records_sql($sql, $params);
538 $functions = array();
544 * Get the functions of a service list (by shortname). It can return only enabled functions if required.
546 * @param array $serviceshortnames service shortnames
547 * @param bool $enabledonly if true then only return functions for services that have been enabled
548 * @return array functions
550 public function get_external_functions_by_enabled_services($serviceshortnames, $enabledonly = true) {
552 if (!empty($serviceshortnames)) {
553 $enabledonlysql = $enabledonly?
' AND s.enabled = 1 ':'';
554 list($serviceshortnames, $params) = $DB->get_in_or_equal($serviceshortnames);
556 FROM {external_functions} f
557 WHERE f.name IN (SELECT sf.functionname
558 FROM {external_services_functions} sf, {external_services} s
559 WHERE s.shortname $serviceshortnames
560 AND sf.externalserviceid = s.id
561 " . $enabledonlysql . ")";
562 $functions = $DB->get_records_sql($sql, $params);
564 $functions = array();
570 * Get functions not included in a service
572 * @param int $serviceid service id
573 * @return array functions
575 public function get_not_associated_external_functions($serviceid) {
577 $select = "name NOT IN (SELECT s.functionname
578 FROM {external_services_functions} s
579 WHERE s.externalserviceid = :sid
582 $functions = $DB->get_records_select('external_functions',
583 $select, array('sid' => $serviceid), 'name');
589 * Get list of required capabilities of a service, sorted by functions
590 * Example of returned value:
593 * [core_group_create_groups] => Array
595 * [0] => moodle/course:managegroups
598 * [core_enrol_get_enrolled_users] => Array
600 * [0] => moodle/user:viewdetails
601 * [1] => moodle/user:viewhiddendetails
602 * [2] => moodle/course:useremail
603 * [3] => moodle/user:update
604 * [4] => moodle/site:accessallgroups
607 * @param int $serviceid service id
610 public function get_service_required_capabilities($serviceid) {
611 $functions = $this->get_external_functions(array($serviceid));
612 $requiredusercaps = array();
613 foreach ($functions as $function) {
614 $functioncaps = explode(',', $function->capabilities
);
615 if (!empty($functioncaps) and !empty($functioncaps[0])) {
616 foreach ($functioncaps as $functioncap) {
617 $requiredusercaps[$function->name
][] = trim($functioncap);
621 return $requiredusercaps;
625 * Get user capabilities (with context)
626 * Only useful for documentation purpose
627 * WARNING: do not use this "broken" function. It was created in the goal to display some capabilities
628 * required by users. In theory we should not need to display this kind of information
629 * as the front end does not display it itself. In pratice,
630 * admins would like the info, for more info you can follow: MDL-29962
632 * @deprecated since Moodle 3.11 in MDL-67748 without a replacement.
633 * @todo MDL-70187 Please delete this method completely in Moodle 4.3, thank you.
634 * @param int $userid user id
637 public function get_user_capabilities($userid) {
640 debugging('webservice::get_user_capabilities() has been deprecated.', DEBUG_DEVELOPER
);
642 //retrieve the user capabilities
643 $sql = "SELECT DISTINCT rc.id, rc.capability FROM {role_capabilities} rc, {role_assignments} ra
644 WHERE rc.roleid=ra.roleid AND ra.userid= ? AND rc.permission = ?";
645 $dbusercaps = $DB->get_records_sql($sql, array($userid, CAP_ALLOW
));
647 foreach ($dbusercaps as $usercap) {
648 $usercaps[$usercap->capability
] = true;
654 * Get missing user capabilities for the given service's functions.
656 * Every external function can declare some required capabilities to allow for easier setup of the web services.
657 * However, that is supposed to be used for informational admin report only. There is no automatic evaluation of
658 * the declared capabilities and the context of the capability evaluation is ignored. Also, actual capability
659 * evaluation is much more complex as it allows for overrides etc.
661 * Returned are capabilities that the given users do not seem to have assigned anywhere at the site and that should
662 * be checked by the admin.
664 * Do not use this method for anything else, particularly not for any security related checks. See MDL-29962 for the
665 * background of why we have this - there are arguments for dropping this feature completely.
667 * @param array $users List of users to check, consisting of objects, arrays or integer ids.
668 * @param int $serviceid The id of the external service to check.
669 * @return array List of missing capabilities: (int)userid => array of (string)capabilitynames
671 public function get_missing_capabilities_by_users(array $users, int $serviceid): array {
674 // The following are default capabilities for all authenticated users and we will assume them granted.
675 $commoncaps = get_default_capabilities('user');
677 // Get the list of additional capabilities required by the service.
679 foreach ($this->get_service_required_capabilities($serviceid) as $service => $caps) {
680 foreach ($caps as $cap) {
681 if (empty($commoncaps[$cap])) {
682 $servicecaps[$cap] = true;
687 // Bail out early if there's nothing to process.
688 if (empty($users) ||
empty($servicecaps)) {
692 // Prepare a list of user ids we want to check.
694 foreach ($users as $user) {
695 if (is_object($user) && isset($user->id
)) {
696 $userids[$user->id
] = true;
697 } else if (is_array($user) && isset($user['id'])) {
698 $userids[$user['id']] = true;
700 throw new coding_exception('Unexpected format of users list in webservice::get_missing_capabilities_by_users().');
704 // Prepare a matrix of missing capabilities x users - consider them all missing by default.
705 foreach (array_keys($userids) as $userid) {
706 foreach (array_keys($servicecaps) as $capname) {
707 $matrix[$userid][$capname] = true;
711 list($capsql, $capparams) = $DB->get_in_or_equal(array_keys($servicecaps), SQL_PARAMS_NAMED
, 'paramcap');
712 list($usersql, $userparams) = $DB->get_in_or_equal(array_keys($userids), SQL_PARAMS_NAMED
, 'paramuser');
714 $sql = "SELECT c.name AS capability, u.id AS userid
715 FROM {capabilities} c
716 JOIN {role_capabilities} rc ON c.name = rc.capability
717 JOIN {role_assignments} ra ON ra.roleid = rc.roleid
718 JOIN {user} u ON ra.userid = u.id
719 WHERE rc.permission = :capallow
721 AND u.id {$usersql}";
723 $params = $capparams +
$userparams +
[
724 'capallow' => CAP_ALLOW
,
727 $rs = $DB->get_recordset_sql($sql, $params);
729 foreach ($rs as $record) {
730 // If there was a potential role assignment found that might grant the user the given capability,
731 // remove it from the matrix. Again, we ignore all the contexts, prohibits, prevents and other details
732 // of the permissions evaluations. See the function docblock for details.
733 unset($matrix[$record->userid
][$record->capability
]);
738 foreach ($matrix as $userid => $caps) {
739 $matrix[$userid] = array_keys($caps);
740 if (empty($matrix[$userid])) {
741 unset($matrix[$userid]);
749 * Get an external service for a given service id
751 * @param int $serviceid service id
752 * @param int $strictness IGNORE_MISSING, MUST_EXIST...
753 * @return stdClass external service
755 public function get_external_service_by_id($serviceid, $strictness=IGNORE_MISSING
) {
757 $service = $DB->get_record('external_services',
758 array('id' => $serviceid), '*', $strictness);
763 * Get an external service for a given shortname
765 * @param string $shortname service shortname
766 * @param int $strictness IGNORE_MISSING, MUST_EXIST...
767 * @return stdClass external service
769 public function get_external_service_by_shortname($shortname, $strictness=IGNORE_MISSING
) {
771 $service = $DB->get_record('external_services',
772 array('shortname' => $shortname), '*', $strictness);
777 * Get an external function for a given function id
779 * @param int $functionid function id
780 * @param int $strictness IGNORE_MISSING, MUST_EXIST...
781 * @return stdClass external function
783 public function get_external_function_by_id($functionid, $strictness=IGNORE_MISSING
) {
785 $function = $DB->get_record('external_functions',
786 array('id' => $functionid), '*', $strictness);
791 * Add a function to a service
793 * @param string $functionname function name
794 * @param int $serviceid service id
796 public function add_external_function_to_service($functionname, $serviceid) {
798 $addedfunction = new stdClass();
799 $addedfunction->externalserviceid
= $serviceid;
800 $addedfunction->functionname
= $functionname;
801 $DB->insert_record('external_services_functions', $addedfunction);
806 * It generates the timecreated field automatically.
808 * @param stdClass $service
809 * @return serviceid integer
811 public function add_external_service($service) {
813 $service->timecreated
= time();
814 $serviceid = $DB->insert_record('external_services', $service);
820 * It modifies the timemodified automatically.
822 * @param stdClass $service
824 public function update_external_service($service) {
826 $service->timemodified
= time();
827 $DB->update_record('external_services', $service);
831 * Test whether an external function is already linked to a service
833 * @param string $functionname function name
834 * @param int $serviceid service id
835 * @return bool true if a matching function exists for the service, else false.
836 * @throws dml_exception if error
838 public function service_function_exists($functionname, $serviceid) {
840 return $DB->record_exists('external_services_functions',
841 array('externalserviceid' => $serviceid,
842 'functionname' => $functionname));
846 * Remove a function from a service
848 * @param string $functionname function name
849 * @param int $serviceid service id
851 public function remove_external_function_from_service($functionname, $serviceid) {
853 $DB->delete_records('external_services_functions',
854 array('externalserviceid' => $serviceid, 'functionname' => $functionname));
859 * Return a list with all the valid user tokens for the given user, it only excludes expired tokens.
861 * @param string $userid user id to retrieve tokens from
862 * @return array array of token entries
865 public static function get_active_tokens($userid) {
868 $sql = 'SELECT t.*, s.name as servicename FROM {external_tokens} t JOIN
869 {external_services} s ON t.externalserviceid = s.id WHERE
870 t.userid = :userid AND (COALESCE(t.validuntil, 0) = 0 OR t.validuntil > :now)';
871 $params = array('userid' => $userid, 'now' => time());
872 return $DB->get_records_sql($sql, $params);
877 * Exception indicating access control problem in web service call
878 * This exception should return general errors about web service setup.
879 * Errors related to the user like wrong username/password should not use it,
880 * you should not use this exception if you want to let the client implement
881 * some code logic against an access error.
883 * @package core_webservice
884 * @copyright 2009 Petr Skodak
885 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
887 class webservice_access_exception
extends moodle_exception
{
892 * @param string $debuginfo the debug info
894 function __construct($debuginfo) {
895 parent
::__construct('accessexception', 'webservice', '', null, $debuginfo);
900 * Check if a protocol is enabled
902 * @param string $protocol name of WS protocol ('rest', 'soap', ...)
903 * @return bool true if the protocol is enabled
905 function webservice_protocol_is_enabled($protocol) {
908 if (empty($CFG->enablewebservices
) ||
empty($CFG->webserviceprotocols
)) {
912 $active = explode(',', $CFG->webserviceprotocols
);
914 return(in_array($protocol, $active));
918 * Mandatory interface for all test client classes.
920 * @package core_webservice
921 * @copyright 2009 Petr Skodak
922 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
924 interface webservice_test_client_interface
{
927 * Execute test client WS request
929 * @param string $serverurl server url (including the token param)
930 * @param string $function web service function name
931 * @param array $params parameters of the web service function
934 public function simpletest($serverurl, $function, $params);
938 * Mandatory interface for all web service protocol classes
940 * @package core_webservice
941 * @copyright 2009 Petr Skodak
942 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
944 interface webservice_server_interface
{
947 * Process request from client.
949 public function run();
953 * Abstract web service base class.
955 * @package core_webservice
956 * @copyright 2009 Petr Skodak
957 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
959 abstract class webservice_server
implements webservice_server_interface
{
961 /** @var string Name of the web server plugin */
962 protected $wsname = null;
964 /** @var string Name of local user */
965 protected $username = null;
967 /** @var string Password of the local user */
968 protected $password = null;
970 /** @var int The local user */
971 protected $userid = null;
973 /** @var integer Authentication method one of WEBSERVICE_AUTHMETHOD_* */
974 protected $authmethod;
976 /** @var string Authentication token*/
977 protected $token = null;
979 /** @var stdClass Restricted context */
980 protected $restricted_context;
982 /** @var int Restrict call to one service id*/
983 protected $restricted_serviceid = null;
988 * @param integer $authmethod authentication method one of WEBSERVICE_AUTHMETHOD_*
990 public function __construct($authmethod) {
991 $this->authmethod
= $authmethod;
996 * Authenticate user using username+password or token.
997 * This function sets up $USER global.
998 * It is safe to use has_capability() after this.
999 * This method also verifies user is allowed to use this
1002 protected function authenticate_user() {
1005 if (!NO_MOODLE_COOKIES
) {
1006 throw new coding_exception('Cookies must be disabled in WS servers!');
1009 $loginfaileddefaultparams = array(
1011 'method' => $this->authmethod
,
1016 if ($this->authmethod
== WEBSERVICE_AUTHMETHOD_USERNAME
) {
1018 //we check that authentication plugin is enabled
1019 //it is only required by simple authentication
1020 if (!is_enabled_auth('webservice')) {
1021 throw new webservice_access_exception('The web service authentication plugin is disabled.');
1024 if (!$auth = get_auth_plugin('webservice')) {
1025 throw new webservice_access_exception('The web service authentication plugin is missing.');
1028 $this->restricted_context
= context_system
::instance();
1030 if (!$this->username
) {
1031 throw new moodle_exception('missingusername', 'webservice');
1034 if (!$this->password
) {
1035 throw new moodle_exception('missingpassword', 'webservice');
1038 if (!$auth->user_login_webservice($this->username
, $this->password
)) {
1040 // Log failed login attempts.
1041 $params = $loginfaileddefaultparams;
1042 $params['other']['reason'] = 'password';
1043 $params['other']['username'] = $this->username
;
1044 $event = \core\event\webservice_login_failed
::create($params);
1045 $event->set_legacy_logdata(array(SITEID
, 'webservice', get_string('simpleauthlog', 'webservice'), '' ,
1046 get_string('failedtolog', 'webservice').": ".$this->username
."/".$this->password
." - ".getremoteaddr() , 0));
1049 throw new moodle_exception('wrongusernamepassword', 'webservice');
1052 $user = $DB->get_record('user', array('username'=>$this->username
, 'mnethostid'=>$CFG->mnet_localhost_id
), '*', MUST_EXIST
);
1054 } else if ($this->authmethod
== WEBSERVICE_AUTHMETHOD_PERMANENT_TOKEN
){
1055 $user = $this->authenticate_by_token(EXTERNAL_TOKEN_PERMANENT
);
1057 $user = $this->authenticate_by_token(EXTERNAL_TOKEN_EMBEDDED
);
1060 // Cannot authenticate unless maintenance access is granted.
1061 $hasmaintenanceaccess = has_capability('moodle/site:maintenanceaccess', context_system
::instance(), $user);
1062 if (!empty($CFG->maintenance_enabled
) and !$hasmaintenanceaccess) {
1063 throw new moodle_exception('sitemaintenance', 'admin');
1066 //only confirmed user should be able to call web service
1067 if (!empty($user->deleted
)) {
1068 $params = $loginfaileddefaultparams;
1069 $params['other']['reason'] = 'user_deleted';
1070 $params['other']['username'] = $user->username
;
1071 $event = \core\event\webservice_login_failed
::create($params);
1072 $event->set_legacy_logdata(array(SITEID
, '', '', '', get_string('wsaccessuserdeleted', 'webservice',
1073 $user->username
) . " - ".getremoteaddr(), 0, $user->id
));
1075 throw new moodle_exception('wsaccessuserdeleted', 'webservice', '', $user->username
);
1078 //only confirmed user should be able to call web service
1079 if (empty($user->confirmed
)) {
1080 $params = $loginfaileddefaultparams;
1081 $params['other']['reason'] = 'user_unconfirmed';
1082 $params['other']['username'] = $user->username
;
1083 $event = \core\event\webservice_login_failed
::create($params);
1084 $event->set_legacy_logdata(array(SITEID
, '', '', '', get_string('wsaccessuserunconfirmed', 'webservice',
1085 $user->username
) . " - ".getremoteaddr(), 0, $user->id
));
1087 throw new moodle_exception('wsaccessuserunconfirmed', 'webservice', '', $user->username
);
1090 //check the user is suspended
1091 if (!empty($user->suspended
)) {
1092 $params = $loginfaileddefaultparams;
1093 $params['other']['reason'] = 'user_unconfirmed';
1094 $params['other']['username'] = $user->username
;
1095 $event = \core\event\webservice_login_failed
::create($params);
1096 $event->set_legacy_logdata(array(SITEID
, '', '', '', get_string('wsaccessusersuspended', 'webservice',
1097 $user->username
) . " - ".getremoteaddr(), 0, $user->id
));
1099 throw new moodle_exception('wsaccessusersuspended', 'webservice', '', $user->username
);
1102 //retrieve the authentication plugin if no previously done
1104 $auth = get_auth_plugin($user->auth
);
1107 // check if credentials have expired
1108 if (!empty($auth->config
->expiration
) and $auth->config
->expiration
== 1) {
1109 $days2expire = $auth->password_expire($user->username
);
1110 if (intval($days2expire) < 0 ) {
1111 $params = $loginfaileddefaultparams;
1112 $params['other']['reason'] = 'password_expired';
1113 $params['other']['username'] = $user->username
;
1114 $event = \core\event\webservice_login_failed
::create($params);
1115 $event->set_legacy_logdata(array(SITEID
, '', '', '', get_string('wsaccessuserexpired', 'webservice',
1116 $user->username
) . " - ".getremoteaddr(), 0, $user->id
));
1118 throw new moodle_exception('wsaccessuserexpired', 'webservice', '', $user->username
);
1122 //check if the auth method is nologin (in this case refuse connection)
1123 if ($user->auth
=='nologin') {
1124 $params = $loginfaileddefaultparams;
1125 $params['other']['reason'] = 'login';
1126 $params['other']['username'] = $user->username
;
1127 $event = \core\event\webservice_login_failed
::create($params);
1128 $event->set_legacy_logdata(array(SITEID
, '', '', '', get_string('wsaccessusernologin', 'webservice',
1129 $user->username
) . " - ".getremoteaddr(), 0, $user->id
));
1131 throw new moodle_exception('wsaccessusernologin', 'webservice', '', $user->username
);
1134 // now fake user login, the session is completely empty too
1135 enrol_check_plugins($user, false);
1136 \core\session\manager
::set_user($user);
1137 set_login_session_preferences();
1138 $this->userid
= $user->id
;
1140 if ($this->authmethod
!= WEBSERVICE_AUTHMETHOD_SESSION_TOKEN
&& !has_capability("webservice/$this->wsname:use", $this->restricted_context
)) {
1141 throw new webservice_access_exception("You are not allowed to use the {$this->wsname} protocol " .
1142 "(missing capability: webservice/{$this->wsname}:use)");
1145 external_api
::set_context_restriction($this->restricted_context
);
1149 * User authentication by token
1151 * @param string $tokentype token type (EXTERNAL_TOKEN_EMBEDDED or EXTERNAL_TOKEN_PERMANENT)
1152 * @return stdClass the authenticated user
1153 * @throws webservice_access_exception
1155 protected function authenticate_by_token($tokentype){
1158 $loginfaileddefaultparams = array(
1160 'method' => $this->authmethod
,
1165 if (!$token = $DB->get_record('external_tokens', array('token'=>$this->token
, 'tokentype'=>$tokentype))) {
1166 // Log failed login attempts.
1167 $params = $loginfaileddefaultparams;
1168 $params['other']['reason'] = 'invalid_token';
1169 $event = \core\event\webservice_login_failed
::create($params);
1170 $event->set_legacy_logdata(array(SITEID
, 'webservice', get_string('tokenauthlog', 'webservice'), '' ,
1171 get_string('failedtolog', 'webservice').": ".$this->token
. " - ".getremoteaddr() , 0));
1173 throw new moodle_exception('invalidtoken', 'webservice');
1176 if ($token->validuntil
and $token->validuntil
< time()) {
1177 $DB->delete_records('external_tokens', array('token'=>$this->token
, 'tokentype'=>$tokentype));
1178 throw new webservice_access_exception('Invalid token - token expired - check validuntil time for the token');
1181 if ($token->sid
){//assumes that if sid is set then there must be a valid associated session no matter the token type
1182 if (!\core\session\manager
::session_exists($token->sid
)){
1183 $DB->delete_records('external_tokens', array('sid'=>$token->sid
));
1184 throw new webservice_access_exception('Invalid session based token - session not found or expired');
1188 if ($token->iprestriction
and !address_in_subnet(getremoteaddr(), $token->iprestriction
)) {
1189 $params = $loginfaileddefaultparams;
1190 $params['other']['reason'] = 'ip_restricted';
1191 $params['other']['tokenid'] = $token->id
;
1192 $event = \core\event\webservice_login_failed
::create($params);
1193 $event->add_record_snapshot('external_tokens', $token);
1194 $event->set_legacy_logdata(array(SITEID
, 'webservice', get_string('tokenauthlog', 'webservice'), '' ,
1195 get_string('failedtolog', 'webservice').": ".getremoteaddr() , 0));
1197 throw new webservice_access_exception('Invalid service - IP:' . getremoteaddr()
1198 . ' is not supported - check this allowed user');
1201 $this->restricted_context
= context
::instance_by_id($token->contextid
);
1202 $this->restricted_serviceid
= $token->externalserviceid
;
1204 $user = $DB->get_record('user', array('id'=>$token->userid
), '*', MUST_EXIST
);
1207 webservice
::update_token_lastaccess($token);
1214 * Intercept some moodlewssettingXXX $_GET and $_POST parameter
1215 * that are related to the web service call and are not the function parameters
1217 protected function set_web_service_call_settings() {
1220 // Default web service settings.
1221 // Must be the same XXX key name as the external_settings::set_XXX function.
1222 // Must be the same XXX ws parameter name as 'moodlewssettingXXX'.
1223 $externalsettings = array(
1224 'raw' => array('default' => false, 'type' => PARAM_BOOL
),
1225 'fileurl' => array('default' => true, 'type' => PARAM_BOOL
),
1226 'filter' => array('default' => false, 'type' => PARAM_BOOL
),
1227 'lang' => array('default' => '', 'type' => PARAM_LANG
),
1228 'timezone' => array('default' => '', 'type' => PARAM_TIMEZONE
),
1231 // Load the external settings with the web service settings.
1232 $settings = external_settings
::get_instance();
1233 foreach ($externalsettings as $name => $settingdata) {
1235 $wsparamname = 'moodlewssetting' . $name;
1237 // Retrieve and remove the setting parameter from the request.
1238 $value = optional_param($wsparamname, $settingdata['default'], $settingdata['type']);
1239 unset($_GET[$wsparamname]);
1240 unset($_POST[$wsparamname]);
1242 $functioname = 'set_' . $name;
1243 $settings->$functioname($value);
1250 * Web Service server base class.
1252 * This class handles both simple and token authentication.
1254 * @package core_webservice
1255 * @copyright 2009 Petr Skodak
1256 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1258 abstract class webservice_base_server
extends webservice_server
{
1260 /** @var array The function parameters - the real values submitted in the request */
1261 protected $parameters = null;
1263 /** @var string The name of the function that is executed */
1264 protected $functionname = null;
1266 /** @var stdClass Full function description */
1267 protected $function = null;
1269 /** @var mixed Function return value */
1270 protected $returns = null;
1272 /** @var array List of methods and their information provided by the web service. */
1273 protected $servicemethods;
1275 /** @var array List of struct classes generated for the web service methods. */
1276 protected $servicestructs;
1279 * This method parses the request input, it needs to get:
1280 * 1/ user authentication - username+password or token
1282 * 3/ function parameters
1284 abstract protected function parse_request();
1287 * Send the result of function call to the WS client.
1289 abstract protected function send_response();
1292 * Send the error information to the WS client.
1294 * @param exception $ex
1296 abstract protected function send_error($ex=null);
1299 * Process request from client.
1303 public function run() {
1304 global $CFG, $USER, $SESSION;
1306 // we will probably need a lot of memory in some functions
1307 raise_memory_limit(MEMORY_EXTRA
);
1309 // set some longer timeout, this script is not sending any output,
1310 // this means we need to manually extend the timeout operations
1311 // that need longer time to finish
1312 external_api
::set_timeout();
1314 // set up exception handler first, we want to sent them back in correct format that
1315 // the other system understands
1316 // we do not need to call the original default handler because this ws handler does everything
1317 set_exception_handler(array($this, 'exception_handler'));
1319 // init all properties from the request data
1320 $this->parse_request();
1322 // authenticate user, this has to be done after the request parsing
1323 // this also sets up $USER and $SESSION
1324 $this->authenticate_user();
1326 // find all needed function info and make sure user may actually execute the function
1327 $this->load_function_info();
1329 // Log the web service request.
1332 'function' => $this->functionname
1335 $event = \core\event\webservice_function_called
::create($params);
1336 $event->set_legacy_logdata(array(SITEID
, 'webservice', $this->functionname
, '' , getremoteaddr() , 0, $this->userid
));
1339 // Do additional setup stuff.
1340 $settings = external_settings
::get_instance();
1341 $sessionlang = $settings->get_lang();
1342 if (!empty($sessionlang)) {
1343 $SESSION->lang
= $sessionlang;
1346 setup_lang_from_browser();
1348 if (empty($CFG->lang
)) {
1349 if (empty($SESSION->lang
)) {
1352 $CFG->lang
= $SESSION->lang
;
1356 // Change timezone only in sites where it isn't forced.
1357 $newtimezone = $settings->get_timezone();
1358 if (!empty($newtimezone) && (!isset($CFG->forcetimezone
) ||
$CFG->forcetimezone
== 99)) {
1359 $USER->timezone
= $newtimezone;
1362 // finally, execute the function - any errors are catched by the default exception handler
1365 // send the results back in correct format
1366 $this->send_response();
1369 $this->session_cleanup();
1375 * Specialised exception handler, we can not use the standard one because
1376 * it can not just print html to output.
1378 * @param exception $ex
1381 public function exception_handler($ex) {
1382 // detect active db transactions, rollback and log as error
1383 abort_all_db_transactions();
1385 // some hacks might need a cleanup hook
1386 $this->session_cleanup($ex);
1388 // now let the plugin send the exception to client
1389 $this->send_error($ex);
1391 // not much else we can do now, add some logging later
1396 * Future hook needed for emulated sessions.
1398 * @param exception $exception null means normal termination, $exception received when WS call failed
1400 protected function session_cleanup($exception=null) {
1401 if ($this->authmethod
== WEBSERVICE_AUTHMETHOD_USERNAME
) {
1402 // nothing needs to be done, there is no persistent session
1404 // close emulated session if used
1409 * Fetches the function description from database,
1410 * verifies user is allowed to use this function and
1411 * loads all paremeters and return descriptions.
1413 protected function load_function_info() {
1414 global $DB, $USER, $CFG;
1416 if (empty($this->functionname
)) {
1417 throw new invalid_parameter_exception('Missing function name');
1420 // function must exist
1421 $function = external_api
::external_function_info($this->functionname
);
1423 if ($this->restricted_serviceid
) {
1424 $params = array('sid1'=>$this->restricted_serviceid
, 'sid2'=>$this->restricted_serviceid
);
1425 $wscond1 = 'AND s.id = :sid1';
1426 $wscond2 = 'AND s.id = :sid2';
1433 // now let's verify access control
1435 // now make sure the function is listed in at least one service user is allowed to use
1436 // allow access only if:
1437 // 1/ entry in the external_services_users table if required
1438 // 2/ validuntil not reached
1439 // 3/ has capability if specified in service desc
1442 $sql = "SELECT s.*, NULL AS iprestriction
1443 FROM {external_services} s
1444 JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0 AND sf.functionname = :name1)
1445 WHERE s.enabled = 1 $wscond1
1449 SELECT s.*, su.iprestriction
1450 FROM {external_services} s
1451 JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1 AND sf.functionname = :name2)
1452 JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
1453 WHERE s.enabled = 1 AND (su.validuntil IS NULL OR su.validuntil < :now) $wscond2";
1454 $params = array_merge($params, array('userid'=>$USER->id
, 'name1'=>$function->name
, 'name2'=>$function->name
, 'now'=>time()));
1456 $rs = $DB->get_recordset_sql($sql, $params);
1457 // now make sure user may access at least one service
1458 $remoteaddr = getremoteaddr();
1460 foreach ($rs as $service) {
1461 if ($service->requiredcapability
and !has_capability($service->requiredcapability
, $this->restricted_context
)) {
1462 continue; // cap required, sorry
1464 if ($service->iprestriction
and !address_in_subnet($remoteaddr, $service->iprestriction
)) {
1465 continue; // wrong request source ip, sorry
1468 break; // one service is enough, no need to continue
1472 throw new webservice_access_exception(
1473 'Access to the function '.$this->functionname
.'() is not allowed.
1474 There could be multiple reasons for this:
1475 1. The service linked to the user token does not contain the function.
1476 2. The service is user-restricted and the user is not listed.
1477 3. The service is IP-restricted and the user IP is not listed.
1478 4. The service is time-restricted and the time has expired.
1479 5. The token is time-restricted and the time has expired.
1480 6. The service requires a specific capability which the user does not have.
1481 7. The function is called with username/password (no user token is sent)
1482 and none of the services has the function to allow the user.
1483 These settings can be found in Administration > Site administration
1484 > Server > Web services > External services and Manage tokens.');
1487 // we have all we need now
1488 $this->function = $function;
1492 * Execute previously loaded function using parameters parsed from the request data.
1494 protected function execute() {
1495 // validate params, this also sorts the params properly, we need the correct order in the next part
1496 $params = call_user_func(array($this->function->classname
, 'validate_parameters'), $this->function->parameters_desc
, $this->parameters
);
1497 $params = array_values($params);
1499 // Allow any Moodle plugin a chance to override this call. This is a convenient spot to
1500 // make arbitrary behaviour customisations, for example to affect the mobile app behaviour.
1501 // The overriding plugin could call the 'real' function first and then modify the results,
1502 // or it could do a completely separate thing.
1503 $callbacks = get_plugins_with_function('override_webservice_execution');
1504 foreach ($callbacks as $plugintype => $plugins) {
1505 foreach ($plugins as $plugin => $callback) {
1506 $result = $callback($this->function, $params);
1507 if ($result !== false) {
1508 // If the callback returns anything other than false, we assume it replaces the
1510 $this->returns
= $result;
1517 $this->returns
= call_user_func_array(array($this->function->classname
, $this->function->methodname
), $params);
1521 * Load the virtual class needed for the web service.
1523 * Initialises the virtual class that contains the web service functions that the user is allowed to use.
1524 * The web service function will be available if the user:
1525 * - is validly registered in the external_services_users table.
1526 * - has the required capability.
1527 * - meets the IP restriction requirement.
1528 * This virtual class can be used by web service protocols such as SOAP, especially when generating WSDL.
1530 protected function init_service_class() {
1533 // Initialise service methods and struct classes.
1534 $this->servicemethods
= array();
1535 $this->servicestructs
= array();
1540 if ($this->restricted_serviceid
) {
1541 $params = array('sid1' => $this->restricted_serviceid
, 'sid2' => $this->restricted_serviceid
);
1542 $wscond1 = 'AND s.id = :sid1';
1543 $wscond2 = 'AND s.id = :sid2';
1546 $sql = "SELECT s.*, NULL AS iprestriction
1547 FROM {external_services} s
1548 JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 0)
1549 WHERE s.enabled = 1 $wscond1
1553 SELECT s.*, su.iprestriction
1554 FROM {external_services} s
1555 JOIN {external_services_functions} sf ON (sf.externalserviceid = s.id AND s.restrictedusers = 1)
1556 JOIN {external_services_users} su ON (su.externalserviceid = s.id AND su.userid = :userid)
1557 WHERE s.enabled = 1 AND (su.validuntil IS NULL OR su.validuntil < :now) $wscond2";
1558 $params = array_merge($params, array('userid' => $USER->id
, 'now' => time()));
1560 $serviceids = array();
1561 $remoteaddr = getremoteaddr();
1563 // Query list of external services for the user.
1564 $rs = $DB->get_recordset_sql($sql, $params);
1566 // Check which service ID to include.
1567 foreach ($rs as $service) {
1568 if (isset($serviceids[$service->id
])) {
1569 continue; // Service already added.
1571 if ($service->requiredcapability
and !has_capability($service->requiredcapability
, $this->restricted_context
)) {
1572 continue; // Cap required, sorry.
1574 if ($service->iprestriction
and !address_in_subnet($remoteaddr, $service->iprestriction
)) {
1575 continue; // Wrong request source ip, sorry.
1577 $serviceids[$service->id
] = $service->id
;
1581 // Generate the virtual class name.
1582 $classname = 'webservices_virtual_class_000000';
1583 while (class_exists($classname)) {
1586 $this->serviceclass
= $classname;
1588 // Get the list of all available external functions.
1589 $wsmanager = new webservice();
1590 $functions = $wsmanager->get_external_functions($serviceids);
1592 // Generate code for the virtual methods for this web service.
1594 foreach ($functions as $function) {
1595 $methods .= $this->get_virtual_method_code($function);
1600 * Virtual class web services for user id $USER->id in context {$this->restricted_context->id}.
1606 // Load the virtual class definition into memory.
1611 * Generates a struct class.
1613 * @param external_single_structure $structdesc The basis of the struct class to be generated.
1614 * @return string The class name of the generated struct class.
1616 protected function generate_simple_struct_class(external_single_structure
$structdesc) {
1619 $propeties = array();
1621 foreach ($structdesc->keys
as $name => $fieldsdesc) {
1622 $type = $this->get_phpdoc_type($fieldsdesc);
1623 $propertytype = array('type' => $type);
1624 if (empty($fieldsdesc->allownull
) ||
$fieldsdesc->allownull
== NULL_ALLOWED
) {
1625 $propertytype['nillable'] = true;
1627 $propeties[$name] = $propertytype;
1628 $fields[] = ' /** @var ' . $type . ' $' . $name . '*/';
1629 $fields[] = ' public $' . $name .';';
1631 $fieldsstr = implode("\n", $fields);
1633 // We do this after the call to get_phpdoc_type() to avoid duplicate class creation.
1634 $classname = 'webservices_struct_class_000000';
1635 while (class_exists($classname)) {
1640 * Virtual struct class for web services for user id $USER->id in context {$this->restricted_context->id}.
1646 // Load into memory.
1649 // Prepare struct info.
1650 $structinfo = new stdClass();
1651 $structinfo->classname
= $classname;
1652 $structinfo->properties
= $propeties;
1653 // Add the struct info the the list of service struct classes.
1654 $this->servicestructs
[] = $structinfo;
1660 * Returns a virtual method code for a web service function.
1662 * @param stdClass $function a record from external_function
1663 * @return string The PHP code of the virtual method.
1664 * @throws coding_exception
1665 * @throws moodle_exception
1667 protected function get_virtual_method_code($function) {
1668 $function = external_api
::external_function_info($function);
1670 // Parameters and their defaults for the method signature.
1671 $paramanddefaults = array();
1672 // Parameters for external lib call.
1674 $paramdesc = array();
1675 // The method's input parameters and their respective types.
1676 $inputparams = array();
1677 // The method's output parameters and their respective types.
1678 $outputparams = array();
1680 foreach ($function->parameters_desc
->keys
as $name => $keydesc) {
1681 $param = '$' . $name;
1682 $paramanddefault = $param;
1683 if ($keydesc->required
== VALUE_OPTIONAL
) {
1684 // It does not make sense to declare a parameter VALUE_OPTIONAL. VALUE_OPTIONAL is used only for array/object key.
1685 throw new moodle_exception('erroroptionalparamarray', 'webservice', '', $name);
1686 } else if ($keydesc->required
== VALUE_DEFAULT
) {
1687 // Need to generate the default, if there is any.
1688 if ($keydesc instanceof external_value
) {
1689 if ($keydesc->default === null) {
1690 $paramanddefault .= ' = null';
1692 switch ($keydesc->type
) {
1694 $default = (int)$keydesc->default;
1697 $default = $keydesc->default;
1700 $default = $keydesc->default;
1703 $default = "'$keydesc->default'";
1705 $paramanddefault .= " = $default";
1708 // Accept empty array as default.
1709 if (isset($keydesc->default) && is_array($keydesc->default) && empty($keydesc->default)) {
1710 $paramanddefault .= ' = array()';
1712 // For the moment we do not support default for other structure types.
1713 throw new moodle_exception('errornotemptydefaultparamarray', 'webservice', '', $name);
1719 $paramanddefaults[] = $paramanddefault;
1720 $type = $this->get_phpdoc_type($keydesc);
1721 $inputparams[$name]['type'] = $type;
1723 $paramdesc[] = '* @param ' . $type . ' $' . $name . ' ' . $keydesc->desc
;
1725 $paramanddefaults = implode(', ', $paramanddefaults);
1726 $paramdescstr = implode("\n ", $paramdesc);
1728 $serviceclassmethodbody = $this->service_class_method_body($function, $params);
1730 if (empty($function->returns_desc
)) {
1731 $return = '* @return void';
1733 $type = $this->get_phpdoc_type($function->returns_desc
);
1734 $outputparams['return']['type'] = $type;
1735 $return = '* @return ' . $type . ' ' . $function->returns_desc
->desc
;
1738 // Now create the virtual method that calls the ext implementation.
1741 * $function->description.
1746 public function $function->name($paramanddefaults) {
1747 $serviceclassmethodbody
1751 // Prepare the method information.
1752 $methodinfo = new stdClass();
1753 $methodinfo->name
= $function->name
;
1754 $methodinfo->inputparams
= $inputparams;
1755 $methodinfo->outputparams
= $outputparams;
1756 $methodinfo->description
= $function->description
;
1757 // Add the method information into the list of service methods.
1758 $this->servicemethods
[] = $methodinfo;
1764 * Get the phpdoc type for an external_description object.
1765 * external_value => int, double or string
1766 * external_single_structure => object|struct, on-fly generated stdClass name.
1767 * external_multiple_structure => array
1769 * @param mixed $keydesc The type description.
1770 * @return string The PHP doc type of the external_description object.
1772 protected function get_phpdoc_type($keydesc) {
1774 if ($keydesc instanceof external_value
) {
1775 switch ($keydesc->type
) {
1776 case PARAM_BOOL
: // 0 or 1 only for now.
1786 } else if ($keydesc instanceof external_single_structure
) {
1787 $type = $this->generate_simple_struct_class($keydesc);
1788 } else if ($keydesc instanceof external_multiple_structure
) {
1796 * Generates the method body of the virtual external function.
1798 * @param stdClass $function a record from external_function.
1799 * @param array $params web service function parameters.
1800 * @return string body of the method for $function ie. everything within the {} of the method declaration.
1802 protected function service_class_method_body($function, $params) {
1803 // Cast the param from object to array (validate_parameters except array only).
1806 if (!empty($params)) {
1807 foreach ($params as $paramtocast) {
1808 // Clean the parameter from any white space.
1809 $paramtocast = trim($paramtocast);
1810 $castingcode .= " $paramtocast = json_decode(json_encode($paramtocast), true);\n";
1812 $paramsstr = implode(', ', $params);
1815 $descriptionmethod = $function->methodname
. '_returns()';
1816 $callforreturnvaluedesc = $function->classname
. '::' . $descriptionmethod;
1818 $methodbody = <<<EOD
1820 if ($callforreturnvaluedesc == null) {
1821 $function->classname::$function->methodname($paramsstr);
1824 return external_api::clean_returnvalue($callforreturnvaluedesc, $function->classname::$function->methodname($paramsstr));
1831 * Early WS exception handler.
1832 * It handles exceptions during setup and returns the Exception text in the WS format.
1833 * If a raise function is found nothing is returned. Throws Exception otherwise.
1835 * @param Exception $ex Raised exception.
1838 function early_ws_exception_handler(Exception
$ex): void
{
1839 if (function_exists('raise_early_ws_exception')) {
1840 raise_early_ws_exception($ex);