From 8647711201907a5c0a557c53b92b578445bb9c06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A1bio=20Souto?= Date: Mon, 7 May 2012 12:09:09 +0100 Subject: [PATCH 1/2] MDL-29938 implement core_user_get_users as unification unifies core_user_get_users_by_id and get_course_user_profiles Conflicts: user/lib.php --- lang/en/webservice.php | 1 + lib/db/services.php | 9 ++ user/externallib.php | 303 +++++++++++++++++++++++++++++++++++++++++ user/lib.php | 62 ++++++++- 4 files changed, 374 insertions(+), 1 deletion(-) diff --git a/lang/en/webservice.php b/lang/en/webservice.php index 24150073ea9..e99b57228bb 100644 --- a/lang/en/webservice.php +++ b/lang/en/webservice.php @@ -118,6 +118,7 @@ $string['missingusername'] = 'Missing username'; $string['missingversionfile'] = 'Coding error: version.php file is missing for the component {$a}'; $string['mobilewsdisabled'] = 'Disabled'; $string['mobilewsenabled'] = 'Enabled'; +$string['nocapabilitytouseparameter'] = 'The user does not have the required capability to use the parameter {$a}'; $string['nofunctions'] = 'This service has no functions.'; $string['norequiredcapability'] = 'No required capability'; $string['notoken'] = 'The token list is empty.'; diff --git a/lib/db/services.php b/lib/db/services.php index ac1b79bbc94..333f3b9cc9c 100644 --- a/lib/db/services.php +++ b/lib/db/services.php @@ -282,6 +282,15 @@ $functions = array( 'capabilities'=> 'moodle/user:viewdetails, moodle/user:viewhiddendetails, moodle/course:useremail, moodle/user:update', ), + 'core_user_get_users' => array( + 'classname' => 'core_user_external', + 'methodname' => 'get_users', + 'classpath' => 'user/externallib.php', + 'description' => 'Get users by key/value', + 'type' => 'read', + 'capabilities'=> 'moodle/user:viewdetails, moodle/user:viewhiddendetails, moodle/course:useremail, moodle/user:update', + ), + 'core_user_get_users_by_id' => array( 'classname' => 'core_user_external', 'methodname' => 'get_users_by_id', diff --git a/user/externallib.php b/user/externallib.php index 4ea18553c22..683291eba44 100644 --- a/user/externallib.php +++ b/user/externallib.php @@ -368,6 +368,309 @@ class core_user_external extends external_api { return null; } + /** + * Returns description of method parameters + * + * @return external_function_parameters + * @since Moodle 2.3 + */ + public static function get_users_parameters() { + return new external_function_parameters( + array( + 'criteria' => new external_multiple_structure( + new external_single_structure( + array( + 'key' => new external_value(PARAM_ALPHA, 'the user column to search, expected keys (value format) are: + "id" (int) the user id, + "fullname" (string) the user full name (ATTENTION: searching by fullname can be extremely slow!), + "idnumber" (string) the user idnumber, + "username" (string) the user username, + "email" (string) the user email (ATTENTION: searching by email can be extremely slow!), + "auth" (plugin) the user auth plugin'), + 'value' => new external_value(PARAM_RAW, 'the value to match') + ) + ), VALUE_DEFAULT, array() + , 'the key/value pairs to be considered in user search. If several are specified, they will be AND\'ed together'), + 'limitfrom' => new external_value(PARAM_INT, 'return a subset of users, starting at this point', VALUE_DEFAULT, 0), + 'limitnum' => new external_value(PARAM_INT, 'return a subset comprising this many records in total', VALUE_DEFAULT, 30), + ) + ); + } + + /** + * Get user information, filtered by key/value pairs. + * This function can work in three different ways. + * 1. Specify several times a key (fullname => 'user1', fullname => 'user2', ...) ... + * This will most likely return a user per key, which is useful for getting several different users at the same time. + * 2. Specifiy different keys only once (fullname => 'user1', auth => 'manual', ...) ... + * This is useful for restricting search results + * 3. Without criteria, which is useful for returning all the users to which you have access to details. + * + * @param array $criteria key/value pairs to consider in user search, AND'ed together. + * @return array An array of arrays containg user profiles that match the given criteria. + * @since Moodle 2.3 + */ + public static function get_users($criteria = array(), $limitfrom = 0, $limitnum = 30) { + global $CFG, $USER, $DB; + require_once($CFG->dirroot . "/user/lib.php"); + + $params = self::validate_parameters(self::get_users_parameters(), + array('criteria' => $criteria, 'limitfrom' => $limitfrom, 'limitnum' => $limitnum)); + + // This array will keep all the users that are allowed to be searched, according to the current user's privileges. + $allowedusers = array(); + + // This array will keep the results to be returned. + $result = array(); + if (!empty($params['criteria'])) { + + // Check if the specified criteria is a legal case. + // There are two legal situations. + // 1. Multiple times the same criteria key. (diverse = false). + // 2. Different criteria keys but only one occurance for each key (diverse = true). + // For any other case we throw an exception. + $diversecriteria = self::is_diverse_criteria($params['criteria']); + + if ($diversecriteria) { + $allowedusers = self::filter_users_to_criteria($params['criteria']); + } else { + foreach ($params['criteria'] as $crit) { + $allowedusers = $allowedusers + self::filter_users_to_criteria(array('criteria' => $crit)); + } + } + } + + // In this situation, since there are no users that can be searched, there is no point to proceed further. + if (empty($allowedusers) and !empty($params['criteria'])) { + return $result; + } + + // Paginate the allowed users to save on the JOIN below. + $alloweduserschunks = array_chunk($allowedusers, $params['limitnum'], true); + $allowedusers = $alloweduserschunks[$params['limitfrom']]; + + // The following query is performed to save multiple get_context_instance SQL requests. + list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx'); + $conditions = array(); + if (!empty($params['criteria'])) { + list($uin, $conditions) = $DB->get_in_or_equal(array_keys($allowedusers), SQL_PARAMS_NAMED); + $usersql = "SELECT u.* $uselect + FROM {user} u $ujoin + WHERE u.id $uin"; + $usersql .= " ORDER BY u.id ASC"; + $users = $DB->get_recordset_sql($usersql, $conditions); + } else { + $usersql = "SELECT u.* $uselect + FROM {user} u $ujoin + ORDER BY u.id ASC"; + $users = $DB->get_recordset_sql($usersql, $conditions, $params['limitfrom'], $params['limitnum']); + } + + foreach ($users as $user) { + context_helper::preload_from_record($user); + $usercontext = context_user::instance($user->id); + self::validate_context($usercontext); + + $userdetails = user_get_user_details_courses($user); + + if ($userdetails != null) { + // Fields matching permissions from /user/editadvanced.php. + $hasuserupdatecap = has_capability('moodle/user:update', context_system::instance()); + $currentuser = ($user->id == $USER->id); + + if ($currentuser or $hasuserupdatecap) { + $userarray['auth'] = $user->auth; + $userarray['confirmed'] = $user->confirmed; + $userarray['idnumber'] = $user->idnumber; + $userarray['lang'] = $user->lang; + $userarray['theme'] = $user->theme; + $userarray['timezone'] = $user->timezone; + $userarray['mailformat'] = $user->mailformat; + } + + $result[] = $userdetails; + } + } + return $result; + } + + /** + * Auxiliary for webservice get_users. + * Allows to do a first filtering of users, according to some criteria. + * + * @static + * @param $params The specified webservice parameters. + * @return array An array containing the user identifiers. + * @throws moodle_exception + */ + private static function filter_users_to_criteria($params) { + global $DB, $USER; + $result = array(); + $firstcriteria = true; + foreach ($params as $crit) { + $key = trim($crit['key']); + $siteadmin = is_siteadmin($USER); + $value = null; + switch ($key) { + case 'id': + $value = clean_param($crit['value'], PARAM_INT); + if (!empty($result) || $firstcriteria) { + // We add the users since later the function that gets user details will perform complex capability checks. + $returnedusers = $DB->get_records('user', array('id' => $value), 'id ASC', 'id'); + $result = $firstcriteria ? $returnedusers : array_intersect_key($result, $returnedusers); + } + break; + case 'idnumber': + if (has_capability('moodle/user:update', context_system::instance())) { + $value = clean_param($crit['value'], PARAM_RAW); + if (!empty($result) || $firstcriteria) { + $returnedusers = $DB->get_records('user', array('idnumber' => $value), 'id ASC', 'id'); + $result = $firstcriteria ? $returnedusers : array_intersect_key($result, $returnedusers); + } + } else { + throw new moodle_exception('nocapabilitytouseparameter', 'webservice', '', $key); + } + break; + case 'username': + if ($siteadmin || ($USER->username == $value)) { + $value = clean_param($crit['value'], PARAM_USERNAME); + if (!empty($result) || $firstcriteria) { + $returnedusers = $DB->get_records('user', array('username' => $value), 'id ASC', 'id'); + $result = $firstcriteria ? $returnedusers : array_intersect_key($result, $returnedusers); + } + } else { + throw new moodle_exception('nocapabilitytouseparameter', 'webservice', '', $key); + } + break; + case 'fullname': + $value = clean_param($crit['value'], PARAM_NOTAGS); + $fullname = $DB->sql_fullname(); + if (!empty($result) || $firstcriteria) { + $returnedusers = $DB->get_records_select('user', $DB->sql_like($fullname, ':searchfullname', false), array('searchfullname' => "$value"), 'id ASC', 'id'); + $result = $firstcriteria ? $returnedusers : array_intersect_key($result, $returnedusers); + } + break; + case 'email': + $value = clean_param($crit['value'], PARAM_EMAIL); + // We add the users since later the function that gets user details will perform complex capability checks. + if (!empty($result) || $firstcriteria) { + $returnedusers = $DB->get_records_select('user', $DB->sql_like('email', ':searchemail', false), array('searchemail' => "$value"), 'id ASC', 'id'); + $result = $firstcriteria ? $returnedusers : array_intersect_key($result, $returnedusers); + } + break; + case 'auth': + if (has_capability('moodle/user:update', context_system::instance())) { + $value = clean_param($crit['value'], PARAM_PLUGIN); + if (!empty($result) || $firstcriteria) { + $returnedusers = $DB->get_records('user', array('auth' => $value), 'id ASC', 'id'); + $result = $firstcriteria ? $returnedusers : array_intersect_key($result, $returnedusers); + } + } else { + throw new moodle_exception('nocapabilitytouseparameter', 'webservice', '', $key); + } + break; + default: + throw new moodle_exception('invalidextparam', 'webservice', '', $key); + } + $firstcriteria = false; + } + return $result; + } + + /** + * Auxiliary function for webservice get_users. + * Returns the type of criteria specified, which can be one of two types. + * 1. Multiple times the same criteria key. + * 2. Different criteria keys but only one occurance for each key. + * + * @param $criteria The criteria + * @return bool T if the criteria is diverse (case 2.) F otherwise (case 1.) + * @throws moodle_exceptioninvalidkey If the criteria keys are incorrectly specified. + */ + private static function is_diverse_criteria($criteria) { + $result = false; + $criteriacount = array(); + + foreach ($criteria as $crit) { + $criteriacount[$crit['key']]++; + } + + if (count($criteriacount) > 1) { + foreach ($criteriacount as $crit) { + if ($crit > 1) { + throw new moodle_exception('invalidkey'); + } + } + $result = true; + } + + return $result; + } + + /** + * Returns description of method result value + * + * @return external_description + * @since Moodle 2.3 + */ + public static function get_users_returns() { + return new external_multiple_structure( + new external_single_structure( + array( + 'id' => new external_value(PARAM_NUMBER, 'ID of the user'), + 'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL), + 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL), + 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL), + 'fullname' => new external_value(PARAM_NOTAGS, 'The fullname of the user'), + 'email' => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL), + 'address' => new external_value(PARAM_MULTILANG, 'Postal address', VALUE_OPTIONAL), + 'phone1' => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL), + 'phone2' => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL), + 'icq' => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL), + 'skype' => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL), + 'yahoo' => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL), + 'aim' => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL), + 'msn' => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL), + 'department' => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL), + 'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL), + 'interests' => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL), + 'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL), + 'lastaccess' => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL), + 'auth' => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL), + 'confirmed' => new external_value(PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL), + 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL), + 'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL), + 'theme' => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL), + 'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL), + 'mailformat' => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL), + 'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL), + 'descriptionformat' => new external_value(PARAM_INT, 'User profile description format', VALUE_OPTIONAL), + 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL), + 'url' => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL), + 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL), + 'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'), + 'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'), + 'customfields' => new external_multiple_structure( + new external_single_structure( + array( + 'type' => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'), + 'value' => new external_value(PARAM_RAW, 'The value of the custom field'), + 'name' => new external_value(PARAM_RAW, 'The name of the custom field'), + 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'), + ) + ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL), + 'preferences' => new external_multiple_structure( + new external_single_structure( + array( + 'name' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'), + 'value' => new external_value(PARAM_RAW, 'The value of the custom field'), + ) + ), 'User preferences', VALUE_OPTIONAL) + ) + ) + ); + } + /** * Returns description of method parameters * diff --git a/user/lib.php b/user/lib.php index beb8d900c20..9f06d4688b9 100644 --- a/user/lib.php +++ b/user/lib.php @@ -244,7 +244,7 @@ function user_get_user_details($user, $course = null, array $userfields = array( } else { $canviewhiddenuserfields = has_capability('moodle/user:viewhiddendetails', $context); } - $canviewfullnames = has_capability('moodle/site:viewfullnames', $context); + $canviewfullnames = has_capability('moodle/site:viewfullnames', $context); if (!empty($course)) { $canviewuseremail = has_capability('moodle/course:useremail', $context); } else { @@ -484,6 +484,66 @@ function user_get_user_details($user, $course = null, array $userfields = array( return $userdetails; } +/** + * Tries to obtain user details, either recurring directly to the user's system profile + * or trough one of the user's course enrollments (course profile). + * + * @param $user The user. + * @param $courses The courses that the user is enrolled in. + * @param array $userfields The userfields that are to be returned. + * @return null if unsuccessful or the allowed user details. + */ +function user_get_user_details_courses($user) { + global $USER; + $userdetails = null; + + // Get the courses that the user is enrolled in (only active). + $courses = enrol_get_users_courses($user->id, true); + + $systemprofile = can_view_user_details_cap($user); + $systemprofile |= ($user->id == $USER->id); + $systemprofile |= has_coursecontact_role($user->id); + + // Try using system profile + if ($systemprofile) { + $userdetails = user_get_user_details($user, null); + } else { + // Try through course profile + foreach ($courses as $course) { + $courseprofile = can_view_user_details_cap($user, $course); + $courseprofile |= ($user->id == $USER->id); + $courseprofile |= has_coursecontact_role($user->id); + + if ($courseprofile) { + $userdetails = user_get_user_details($user, $course); + } + } + } + + return $userdetails; +} + +/** + * Does $USER have the necessary capabilities to obtain user details + * using a mdl_user record? + * @param $user The mdl_user record + * @param null $course Null only to consider system profile or course to also consider that course's profile. + * @return bool T if he does, false otherwise + */ +function can_view_user_details_cap($user, $course = null) { + if (!empty($course)) { + $context = get_context_instance(CONTEXT_COURSE, $course->id); + $usercontext = get_context_instance(CONTEXT_USER, $user->id); + $result = (has_capability('moodle/user:viewdetails', $context) || has_capability('moodle/user:viewdetails', $usercontext)); + } + else { + $context = get_context_instance(CONTEXT_USER, $user->id); + $usercontext = $context; + $result = has_capability('moodle/user:viewdetails', $usercontext); + } + return $result; +} + /** * Return a list of page types * @param string $pagetype current page type From c70b9853da9393c51d661aefcb638199f608ce6e Mon Sep 17 00:00:00 2001 From: Jerome Mouneyrac Date: Tue, 30 Oct 2012 11:36:29 +0800 Subject: [PATCH 2/2] MDL-35543 modify get_users to get_users_by_field (more complex search function named get_users will be implemented later - focussing yet on retrieving user info for a specified field) --- lib/db/services.php | 8 +- user/externallib.php | 282 +++++++------------------------- user/lib.php | 51 +++--- user/tests/externallib_test.php | 158 ++++++++++++++++++ 4 files changed, 247 insertions(+), 252 deletions(-) diff --git a/lib/db/services.php b/lib/db/services.php index 333f3b9cc9c..1b33a942e62 100644 --- a/lib/db/services.php +++ b/lib/db/services.php @@ -282,11 +282,11 @@ $functions = array( 'capabilities'=> 'moodle/user:viewdetails, moodle/user:viewhiddendetails, moodle/course:useremail, moodle/user:update', ), - 'core_user_get_users' => array( + 'core_user_get_users_by_field' => array( 'classname' => 'core_user_external', - 'methodname' => 'get_users', + 'methodname' => 'get_users_by_field', 'classpath' => 'user/externallib.php', - 'description' => 'Get users by key/value', + 'description' => 'Retrieve users information for a specified unique field - If you want to do a user search, use core_user_get_users()', 'type' => 'read', 'capabilities'=> 'moodle/user:viewdetails, moodle/user:viewhiddendetails, moodle/course:useremail, moodle/user:update', ), @@ -638,4 +638,4 @@ $services = array( 'shortname' => MOODLE_OFFICIAL_MOBILE_SERVICE, 'downloadfiles' => 1 ), -); +); \ No newline at end of file diff --git a/user/externallib.php b/user/externallib.php index 683291eba44..3ffcdb06830 100644 --- a/user/externallib.php +++ b/user/externallib.php @@ -372,258 +372,102 @@ class core_user_external extends external_api { * Returns description of method parameters * * @return external_function_parameters - * @since Moodle 2.3 + * @since Moodle 2.4 */ - public static function get_users_parameters() { + public static function get_users_by_field_parameters() { return new external_function_parameters( array( - 'criteria' => new external_multiple_structure( - new external_single_structure( - array( - 'key' => new external_value(PARAM_ALPHA, 'the user column to search, expected keys (value format) are: - "id" (int) the user id, - "fullname" (string) the user full name (ATTENTION: searching by fullname can be extremely slow!), - "idnumber" (string) the user idnumber, - "username" (string) the user username, - "email" (string) the user email (ATTENTION: searching by email can be extremely slow!), - "auth" (plugin) the user auth plugin'), - 'value' => new external_value(PARAM_RAW, 'the value to match') - ) - ), VALUE_DEFAULT, array() - , 'the key/value pairs to be considered in user search. If several are specified, they will be AND\'ed together'), - 'limitfrom' => new external_value(PARAM_INT, 'return a subset of users, starting at this point', VALUE_DEFAULT, 0), - 'limitnum' => new external_value(PARAM_INT, 'return a subset comprising this many records in total', VALUE_DEFAULT, 30), + 'field' => new external_value(PARAM_ALPHA, 'the search field can be + \'id\' or \'idnumber\' or \'username\' or \'email\''), + 'values' => new external_multiple_structure( + new external_value(PARAM_RAW, 'the value to match')) ) ); } /** - * Get user information, filtered by key/value pairs. - * This function can work in three different ways. - * 1. Specify several times a key (fullname => 'user1', fullname => 'user2', ...) ... - * This will most likely return a user per key, which is useful for getting several different users at the same time. - * 2. Specifiy different keys only once (fullname => 'user1', auth => 'manual', ...) ... - * This is useful for restricting search results - * 3. Without criteria, which is useful for returning all the users to which you have access to details. + * Get user information for a unique field. * - * @param array $criteria key/value pairs to consider in user search, AND'ed together. - * @return array An array of arrays containg user profiles that match the given criteria. - * @since Moodle 2.3 + * @param string $field + * @param array $values + * @return array An array of arrays containg user profiles. + * @since Moodle 2.4 */ - public static function get_users($criteria = array(), $limitfrom = 0, $limitnum = 30) { + public static function get_users_by_field($field, $values) { global $CFG, $USER, $DB; require_once($CFG->dirroot . "/user/lib.php"); - $params = self::validate_parameters(self::get_users_parameters(), - array('criteria' => $criteria, 'limitfrom' => $limitfrom, 'limitnum' => $limitnum)); + $params = self::validate_parameters(self::get_users_by_field_parameters(), + array('field' => $field, 'values' => $values)); - // This array will keep all the users that are allowed to be searched, according to the current user's privileges. - $allowedusers = array(); + // This array will keep all the users that are allowed to be searched, + // according to the current user's privileges. + $cleanedvalues = array(); - // This array will keep the results to be returned. - $result = array(); - if (!empty($params['criteria'])) { + switch ($field) { + case 'id': + $paramtype = PARAM_INT; + break; + case 'idnumber': + $paramtype = PARAM_RAW; + break; + case 'username': + $paramtype = PARAM_USERNAME; + break; + case 'email': + $paramtype = PARAM_EMAIL; + break; + default: + throw new coding_exception('invalid field parameter', + 'The search field \'' . $field . '\' is not supported, look at the web service documentation'); + } - // Check if the specified criteria is a legal case. - // There are two legal situations. - // 1. Multiple times the same criteria key. (diverse = false). - // 2. Different criteria keys but only one occurance for each key (diverse = true). - // For any other case we throw an exception. - $diversecriteria = self::is_diverse_criteria($params['criteria']); - - if ($diversecriteria) { - $allowedusers = self::filter_users_to_criteria($params['criteria']); - } else { - foreach ($params['criteria'] as $crit) { - $allowedusers = $allowedusers + self::filter_users_to_criteria(array('criteria' => $crit)); - } + // Clean the values + foreach ($values as $value) { + $cleanedvalue = clean_param($value, $paramtype); + if ( $value != $cleanedvalue) { + throw new invalid_parameter_exception('The field \'' . $field . + '\' value is invalid: ' . $value . '(cleaned value: '.$cleanedvalue.')'); } + $cleanedvalues[] = $cleanedvalue; } - // In this situation, since there are no users that can be searched, there is no point to proceed further. - if (empty($allowedusers) and !empty($params['criteria'])) { - return $result; - } - - // Paginate the allowed users to save on the JOIN below. - $alloweduserschunks = array_chunk($allowedusers, $params['limitnum'], true); - $allowedusers = $alloweduserschunks[$params['limitfrom']]; - - // The following query is performed to save multiple get_context_instance SQL requests. - list($uselect, $ujoin) = context_instance_preload_sql('u.id', CONTEXT_USER, 'ctx'); - $conditions = array(); - if (!empty($params['criteria'])) { - list($uin, $conditions) = $DB->get_in_or_equal(array_keys($allowedusers), SQL_PARAMS_NAMED); - $usersql = "SELECT u.* $uselect - FROM {user} u $ujoin - WHERE u.id $uin"; - $usersql .= " ORDER BY u.id ASC"; - $users = $DB->get_recordset_sql($usersql, $conditions); - } else { - $usersql = "SELECT u.* $uselect - FROM {user} u $ujoin - ORDER BY u.id ASC"; - $users = $DB->get_recordset_sql($usersql, $conditions, $params['limitfrom'], $params['limitnum']); - } + // Retrieve the users + $users = $DB->get_records_list('user', $field, $cleanedvalues, 'id'); + // Finally retrieve each users information + $returnedusers = array(); foreach ($users as $user) { - context_helper::preload_from_record($user); - $usercontext = context_user::instance($user->id); - self::validate_context($usercontext); $userdetails = user_get_user_details_courses($user); - if ($userdetails != null) { - // Fields matching permissions from /user/editadvanced.php. - $hasuserupdatecap = has_capability('moodle/user:update', context_system::instance()); - $currentuser = ($user->id == $USER->id); - - if ($currentuser or $hasuserupdatecap) { - $userarray['auth'] = $user->auth; - $userarray['confirmed'] = $user->confirmed; - $userarray['idnumber'] = $user->idnumber; - $userarray['lang'] = $user->lang; - $userarray['theme'] = $user->theme; - $userarray['timezone'] = $user->timezone; - $userarray['mailformat'] = $user->mailformat; - } - - $result[] = $userdetails; + // Return the user only if the searched field is returned + // Otherwise it means that the $USER was not allowed to search the returned user + if (!empty($userdetails) and !empty($userdetails[$field])) { + $returnedusers[] = $userdetails; } } - return $result; - } - /** - * Auxiliary for webservice get_users. - * Allows to do a first filtering of users, according to some criteria. - * - * @static - * @param $params The specified webservice parameters. - * @return array An array containing the user identifiers. - * @throws moodle_exception - */ - private static function filter_users_to_criteria($params) { - global $DB, $USER; - $result = array(); - $firstcriteria = true; - foreach ($params as $crit) { - $key = trim($crit['key']); - $siteadmin = is_siteadmin($USER); - $value = null; - switch ($key) { - case 'id': - $value = clean_param($crit['value'], PARAM_INT); - if (!empty($result) || $firstcriteria) { - // We add the users since later the function that gets user details will perform complex capability checks. - $returnedusers = $DB->get_records('user', array('id' => $value), 'id ASC', 'id'); - $result = $firstcriteria ? $returnedusers : array_intersect_key($result, $returnedusers); - } - break; - case 'idnumber': - if (has_capability('moodle/user:update', context_system::instance())) { - $value = clean_param($crit['value'], PARAM_RAW); - if (!empty($result) || $firstcriteria) { - $returnedusers = $DB->get_records('user', array('idnumber' => $value), 'id ASC', 'id'); - $result = $firstcriteria ? $returnedusers : array_intersect_key($result, $returnedusers); - } - } else { - throw new moodle_exception('nocapabilitytouseparameter', 'webservice', '', $key); - } - break; - case 'username': - if ($siteadmin || ($USER->username == $value)) { - $value = clean_param($crit['value'], PARAM_USERNAME); - if (!empty($result) || $firstcriteria) { - $returnedusers = $DB->get_records('user', array('username' => $value), 'id ASC', 'id'); - $result = $firstcriteria ? $returnedusers : array_intersect_key($result, $returnedusers); - } - } else { - throw new moodle_exception('nocapabilitytouseparameter', 'webservice', '', $key); - } - break; - case 'fullname': - $value = clean_param($crit['value'], PARAM_NOTAGS); - $fullname = $DB->sql_fullname(); - if (!empty($result) || $firstcriteria) { - $returnedusers = $DB->get_records_select('user', $DB->sql_like($fullname, ':searchfullname', false), array('searchfullname' => "$value"), 'id ASC', 'id'); - $result = $firstcriteria ? $returnedusers : array_intersect_key($result, $returnedusers); - } - break; - case 'email': - $value = clean_param($crit['value'], PARAM_EMAIL); - // We add the users since later the function that gets user details will perform complex capability checks. - if (!empty($result) || $firstcriteria) { - $returnedusers = $DB->get_records_select('user', $DB->sql_like('email', ':searchemail', false), array('searchemail' => "$value"), 'id ASC', 'id'); - $result = $firstcriteria ? $returnedusers : array_intersect_key($result, $returnedusers); - } - break; - case 'auth': - if (has_capability('moodle/user:update', context_system::instance())) { - $value = clean_param($crit['value'], PARAM_PLUGIN); - if (!empty($result) || $firstcriteria) { - $returnedusers = $DB->get_records('user', array('auth' => $value), 'id ASC', 'id'); - $result = $firstcriteria ? $returnedusers : array_intersect_key($result, $returnedusers); - } - } else { - throw new moodle_exception('nocapabilitytouseparameter', 'webservice', '', $key); - } - break; - default: - throw new moodle_exception('invalidextparam', 'webservice', '', $key); - } - $firstcriteria = false; - } - return $result; - } - - /** - * Auxiliary function for webservice get_users. - * Returns the type of criteria specified, which can be one of two types. - * 1. Multiple times the same criteria key. - * 2. Different criteria keys but only one occurance for each key. - * - * @param $criteria The criteria - * @return bool T if the criteria is diverse (case 2.) F otherwise (case 1.) - * @throws moodle_exceptioninvalidkey If the criteria keys are incorrectly specified. - */ - private static function is_diverse_criteria($criteria) { - $result = false; - $criteriacount = array(); - - foreach ($criteria as $crit) { - $criteriacount[$crit['key']]++; - } - - if (count($criteriacount) > 1) { - foreach ($criteriacount as $crit) { - if ($crit > 1) { - throw new moodle_exception('invalidkey'); - } - } - $result = true; - } - - return $result; + return $returnedusers; } /** * Returns description of method result value * - * @return external_description - * @since Moodle 2.3 + * @return external_multiple_structure + * @since Moodle 2.4 */ - public static function get_users_returns() { + public static function get_users_by_field_returns() { return new external_multiple_structure( new external_single_structure( array( - 'id' => new external_value(PARAM_NUMBER, 'ID of the user'), - 'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL), + 'id' => new external_value(PARAM_INT, 'ID of the user'), + 'username' => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL), 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL), 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL), 'fullname' => new external_value(PARAM_NOTAGS, 'The fullname of the user'), - 'email' => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL), - 'address' => new external_value(PARAM_MULTILANG, 'Postal address', VALUE_OPTIONAL), + 'email' => new external_value(PARAM_EMAIL, 'An email address', VALUE_OPTIONAL), + 'address' => new external_value(PARAM_TEXT, 'Postal address', VALUE_OPTIONAL), 'phone1' => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL), 'phone2' => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL), 'icq' => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL), @@ -633,18 +477,18 @@ class core_user_external extends external_api { 'msn' => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL), 'department' => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL), 'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL), + 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL), 'interests' => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL), 'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL), 'lastaccess' => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL), 'auth' => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL), - 'confirmed' => new external_value(PARAM_NUMBER, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL), - 'idnumber' => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL), + 'confirmed' => new external_value(PARAM_INT, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL), 'lang' => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL), 'theme' => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL), 'timezone' => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL), - 'mailformat' => new external_value(PARAM_INTEGER, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL), + 'mailformat' => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL), 'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL), - 'descriptionformat' => new external_value(PARAM_INT, 'User profile description format', VALUE_OPTIONAL), + 'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL), 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL), 'url' => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL), 'country' => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL), @@ -665,7 +509,7 @@ class core_user_external extends external_api { 'name' => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'), 'value' => new external_value(PARAM_RAW, 'The value of the custom field'), ) - ), 'User preferences', VALUE_OPTIONAL) + ), 'User preferences', VALUE_OPTIONAL) ) ) ); @@ -1241,4 +1085,4 @@ class moodle_user_external extends external_api { require_once($CFG->dirroot . '/enrol/externallib.php'); return core_enrol_external::get_enrolled_users_returns(); } -} +} \ No newline at end of file diff --git a/user/lib.php b/user/lib.php index 9f06d4688b9..2a6d5ed1c0e 100644 --- a/user/lib.php +++ b/user/lib.php @@ -486,12 +486,10 @@ function user_get_user_details($user, $course = null, array $userfields = array( /** * Tries to obtain user details, either recurring directly to the user's system profile - * or trough one of the user's course enrollments (course profile). + * or through one of the user's course enrollments (course profile). * - * @param $user The user. - * @param $courses The courses that the user is enrolled in. - * @param array $userfields The userfields that are to be returned. - * @return null if unsuccessful or the allowed user details. + * @param object $user The user. + * @return array if unsuccessful or the allowed user details. */ function user_get_user_details_courses($user) { global $USER; @@ -500,21 +498,18 @@ function user_get_user_details_courses($user) { // Get the courses that the user is enrolled in (only active). $courses = enrol_get_users_courses($user->id, true); - $systemprofile = can_view_user_details_cap($user); - $systemprofile |= ($user->id == $USER->id); - $systemprofile |= has_coursecontact_role($user->id); + $systemprofile = false; + if (can_view_user_details_cap($user) || ($user->id == $USER->id) || has_coursecontact_role($user->id)) { + $systemprofile = true; + } - // Try using system profile + // Try using system profile. if ($systemprofile) { $userdetails = user_get_user_details($user, null); } else { - // Try through course profile + // Try through course profile. foreach ($courses as $course) { - $courseprofile = can_view_user_details_cap($user, $course); - $courseprofile |= ($user->id == $USER->id); - $courseprofile |= has_coursecontact_role($user->id); - - if ($courseprofile) { + if ($can_view_user_details_cap($user, $course) || ($user->id == $USER->id) || has_coursecontact_role($user->id)) { $userdetails = user_get_user_details($user, $course); } } @@ -524,22 +519,20 @@ function user_get_user_details_courses($user) { } /** - * Does $USER have the necessary capabilities to obtain user details - * using a mdl_user record? - * @param $user The mdl_user record - * @param null $course Null only to consider system profile or course to also consider that course's profile. - * @return bool T if he does, false otherwise + * Check if $USER have the necessary capabilities to obtain user details. + * + * @param object $user + * @param object $course if null then only consider system profile otherwise also consider the course's profile. + * @return bool true if $USER can view user details. */ function can_view_user_details_cap($user, $course = null) { - if (!empty($course)) { + // Check $USER has the capability to view the user details at user context. + $usercontext = get_context_instance(CONTEXT_USER, $user->id); + $result = has_capability('moodle/user:viewdetails', $usercontext); + // Otherwise can $USER see them at course context. + if (!$result && !empty($course)) { $context = get_context_instance(CONTEXT_COURSE, $course->id); - $usercontext = get_context_instance(CONTEXT_USER, $user->id); - $result = (has_capability('moodle/user:viewdetails', $context) || has_capability('moodle/user:viewdetails', $usercontext)); - } - else { - $context = get_context_instance(CONTEXT_USER, $user->id); - $usercontext = $context; - $result = has_capability('moodle/user:viewdetails', $usercontext); + $result = has_capability('moodle/user:viewdetails', $context); } return $result; } @@ -552,4 +545,4 @@ function can_view_user_details_cap($user, $course = null) { */ function user_page_type_list($pagetype, $parentcontext, $currentcontext) { return array('user-profile'=>get_string('page-user-profile', 'pagetype')); -} +} \ No newline at end of file diff --git a/user/tests/externallib_test.php b/user/tests/externallib_test.php index 53670e9810f..e7f19f2e2d2 100644 --- a/user/tests/externallib_test.php +++ b/user/tests/externallib_test.php @@ -33,6 +33,164 @@ require_once($CFG->dirroot . '/user/externallib.php'); class core_user_external_testcase extends externallib_advanced_testcase { + /** + * Test get_users_by_field + */ + public function test_get_users_by_field() { + global $USER, $CFG; + + $this->resetAfterTest(true); + + $course = self::getDataGenerator()->create_course(); + $user1 = array( + 'username' => 'usernametest1', + 'idnumber' => 'idnumbertest1', + 'firstname' => 'First Name User Test 1', + 'lastname' => 'Last Name User Test 1', + 'email' => 'usertest1@email.com', + 'address' => '2 Test Street Perth 6000 WA', + 'phone1' => '01010101010', + 'phone2' => '02020203', + 'icq' => 'testuser1', + 'skype' => 'testuser1', + 'yahoo' => 'testuser1', + 'aim' => 'testuser1', + 'msn' => 'testuser1', + 'department' => 'Department of user 1', + 'institution' => 'Institution of user 1', + 'description' => 'This is a description for user 1', + 'descriptionformat' => FORMAT_MOODLE, + 'city' => 'Perth', + 'url' => 'http://moodle.org', + 'country' => 'au' + ); + $user1 = self::getDataGenerator()->create_user($user1); + if (!empty($CFG->usetags)) { + require_once($CFG->dirroot . '/user/editlib.php'); + require_once($CFG->dirroot . '/tag/lib.php'); + $user1->interests = array('Cinema', 'Tennis', 'Dance', 'Guitar', 'Cooking'); + useredit_update_interests($user1, $user1->interests); + } + $user2 = self::getDataGenerator()->create_user( + array('username' => 'usernametest2', 'idnumber' => 'idnumbertest2')); + + $generatedusers = array(); + $generatedusers[$user1->id] = $user1; + $generatedusers[$user2->id] = $user2; + + $context = context_course::instance($course->id); + $roleid = $this->assignUserCapability('moodle/user:viewdetails', $context->id); + + // Enrol the users in the course. + // We use the manual plugin. + $enrol = enrol_get_plugin('manual'); + $enrolinstances = enrol_get_instances($course->id, true); + foreach ($enrolinstances as $courseenrolinstance) { + if ($courseenrolinstance->enrol == "manual") { + $instance = $courseenrolinstance; + break; + } + } + $enrol->enrol_user($instance, $user1->id, $roleid); + $enrol->enrol_user($instance, $user2->id, $roleid); + $enrol->enrol_user($instance, $USER->id, $roleid); + + // call as admin and receive all possible fields. + $this->setAdminUser(); + + $fieldstosearch = array('id', 'idnumber', 'username', 'email'); + + foreach ($fieldstosearch as $fieldtosearch) { + + // Call the external function. + $returnedusers = core_user_external::get_users_by_field($fieldtosearch, + array($USER->{$fieldtosearch}, $user1->{$fieldtosearch}, $user2->{$fieldtosearch})); + + // Expected result differ following the searched field + // Admin user in the PHPunit framework doesn't have email or idnumber. + if ($fieldtosearch == 'email' or $fieldtosearch == 'idnumber') { + $expectedreturnedusers = 2; + } else { + $expectedreturnedusers = 3; + } + + // Check we retrieve the good total number of enrolled users + no error on capability. + $this->assertEquals($expectedreturnedusers, count($returnedusers)); + + foreach($returnedusers as $returneduser) { + $generateduser = ($returneduser['id'] == $USER->id) ? + $USER : $generatedusers[$returneduser['id']]; + $this->assertEquals($generateduser->username, $returneduser['username']); + if (!empty($generateduser->idnumber)) { + $this->assertEquals($generateduser->idnumber, $returneduser['idnumber']); + } + $this->assertEquals($generateduser->firstname, $returneduser['firstname']); + $this->assertEquals($generateduser->lastname, $returneduser['lastname']); + if ($generateduser->email != $USER->email) { //don't check the tmp modified $USER email + $this->assertEquals($generateduser->email, $returneduser['email']); + } + if (!empty($generateduser->address)) { + $this->assertEquals($generateduser->address, $returneduser['address']); + } + if (!empty($generateduser->phone1)) { + $this->assertEquals($generateduser->phone1, $returneduser['phone1']); + } + if (!empty($generateduser->phone2)) { + $this->assertEquals($generateduser->phone2, $returneduser['phone2']); + } + if (!empty($generateduser->icq)) { + $this->assertEquals($generateduser->icq, $returneduser['icq']); + } + if (!empty($generateduser->skype)) { + $this->assertEquals($generateduser->skype, $returneduser['skype']); + } + if (!empty($generateduser->yahoo)) { + $this->assertEquals($generateduser->yahoo, $returneduser['yahoo']); + } + if (!empty($generateduser->aim)) { + $this->assertEquals($generateduser->aim, $returneduser['aim']); + } + if (!empty($generateduser->msn)) { + $this->assertEquals($generateduser->msn, $returneduser['msn']); + } + if (!empty($generateduser->department)) { + $this->assertEquals($generateduser->department, $returneduser['department']); + } + if (!empty($generateduser->institution)) { + $this->assertEquals($generateduser->institution, $returneduser['institution']); + } + if (!empty($generateduser->description)) { + $this->assertEquals($generateduser->description, $returneduser['description']); + } + if (!empty($generateduser->descriptionformat)) { + $this->assertEquals(FORMAT_HTML, $returneduser['descriptionformat']); + } + if (!empty($generateduser->city)) { + $this->assertEquals($generateduser->city, $returneduser['city']); + } + if (!empty($generateduser->country)) { + $this->assertEquals($generateduser->country, $returneduser['country']); + } + if (!empty($generateduser->url)) { + $this->assertEquals($generateduser->url, $returneduser['url']); + } + if (!empty($CFG->usetags) and !empty($generateduser->interests)) { + $this->assertEquals(implode(', ', $generateduser->interests), $returneduser['interests']); + } + } + } + + // Test that no result are returned for search by username if we are not admin + $this->setGuestUser(); + + // Call the external function. + $returnedusers = core_user_external::get_users_by_field('username', + array($USER->username, $user1->username, $user2->username)); + + // Only the own $USER username should be returned + $this->assertEquals(1, count($returnedusers)); + } + /** * Test get_course_user_profiles */