diff --git a/lib/db/services.php b/lib/db/services.php index a2a8d93bf16a4..ddf6a4f35a5b1 100644 --- a/lib/db/services.php +++ b/lib/db/services.php @@ -273,6 +273,15 @@ 'capabilities'=> 'moodle/user:create', ), + 'core_user_get_users' => array( + 'classname' => 'core_user_external', + 'methodname' => 'get_users', + 'classpath' => 'user/externallib.php', + 'description' => 'search for users matching the parameters', + 'type' => 'read', + 'capabilities'=> 'moodle/user:viewdetails, moodle/user:viewhiddendetails, moodle/course:useremail, moodle/user:update', + ), + 'moodle_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 3ffcdb0683038..ba02d018a3a3f 100644 --- a/user/externallib.php +++ b/user/externallib.php @@ -51,7 +51,7 @@ public static function create_users_parameters() { 'users' => new external_multiple_structure( new external_single_structure( array( - 'username' => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config. Must be lowercase.'), + 'username' => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config.'), 'password' => new external_value(PARAM_RAW, 'Plain text password consisting of any characters'), 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user'), 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user'), @@ -276,7 +276,7 @@ public static function update_users_parameters() { new external_single_structure( array( 'id' => new external_value(PARAM_INT, 'ID of the user'), - 'username' => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config. Must be lowercase.', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED), + 'username' => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config.', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED), 'password' => new external_value(PARAM_RAW, 'Plain text password consisting of any characters', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED), 'firstname' => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL, '',NULL_NOT_ALLOWED), 'lastname' => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL), @@ -412,7 +412,7 @@ public static function get_users_by_field($field, $values) { $paramtype = PARAM_RAW; break; case 'username': - $paramtype = PARAM_USERNAME; + $paramtype = PARAM_RAW; break; case 'email': $paramtype = PARAM_EMAIL; @@ -438,7 +438,6 @@ public static function get_users_by_field($field, $values) { // Finally retrieve each users information $returnedusers = array(); foreach ($users as $user) { - $userdetails = user_get_user_details_courses($user); // Return the user only if the searched field is returned @@ -458,63 +457,184 @@ public static function get_users_by_field($field, $values) { * @since Moodle 2.4 */ public static function get_users_by_field_returns() { - return new external_multiple_structure( - new external_single_structure( - array( - '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_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), - '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), - '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_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_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_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), - '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) + return new external_multiple_structure(self::user_description()); + } + + + /** + * Returns description of get_users() parameters. + * + * @return external_function_parameters + * @since Moodle 2.5 + */ + 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) matching user id, + "lastname" (string) user last name (Note: you can use % for searching but it may be considerably slower!), + "firstname" (string) user first name (Note: you can use % for searching but it may be considerably slower!), + "idnumber" (string) matching user idnumber, + "username" (string) matching user username, + "email" (string) user email (Note: you can use % for searching but it may be considerably slower!), + "auth" (string) matching user auth plugin'), + 'value' => new external_value(PARAM_RAW, 'the value to search') + ) + ), 'the key/value pairs to be considered in user search. Values can not be empty. + Specify different keys only once (fullname => \'user1\', auth => \'manual\', ...) - + key occurences are forbidden. + The search is executed with AND operator on the criterias. Invalid criterias (keys) are ignored, + the search is still executed on the valid criterias. + You can search without criteria, but the function is not designed for it. + It could very slow or timeout. The function is designed to search some specific users.' ) ) ); } + /** + * Retrieve matching user. + * + * @param array $criteria the allowed array keys are id/lastname/firstname/idnumber/username/email/auth. + * @return array An array of arrays containing user profiles. + * @since Moodle 2.5 + */ + public static function get_users($criteria = array()) { + global $CFG, $USER, $DB; + + require_once($CFG->dirroot . "/user/lib.php"); + + $params = self::validate_parameters(self::get_users_parameters(), + array('criteria' => $criteria)); + + // Validate the criteria and retrieve the users. + $users = array(); + $warnings = array(); + $sqlparams = array(); + $usedkeys = array(); + + // Do not retrieve deleted users. + $sql = ' deleted = 0'; + + foreach ($params['criteria'] as $criteriaindex => $criteria) { + + // Check that the criteria has never been used. + if (array_key_exists($criteria['key'], $usedkeys)) { + throw new moodle_exception('keyalreadyset', '', '', null, 'The key ' . $criteria['key'] . ' can only be sent once'); + } else { + $usedkeys[$criteria['key']] = true; + } + + $invalidcriteria = false; + // Clean the parameters. + $paramtype = PARAM_RAW; + switch ($criteria['key']) { + case 'id': + $paramtype = PARAM_INT; + break; + case 'idnumber': + $paramtype = PARAM_RAW; + break; + case 'username': + $paramtype = PARAM_RAW; + break; + case 'email': + // We use PARAM_RAW to allow searches with %. + $paramtype = PARAM_RAW; + break; + case 'auth': + $paramtype = PARAM_AUTH; + break; + case 'lastname': + case 'firstname': + $paramtype = PARAM_TEXT; + break; + default: + // Send back a warning that this search key is not supported in this version. + // This warning will make the function extandable without breaking clients. + $warnings[] = array( + 'item' => $criteria['key'], + 'warningcode' => 'invalidfieldparameter', + 'message' => 'The search key \'' . $criteria['key'] . '\' is not supported, look at the web service documentation' + ); + // Do not add this invalid criteria to the created SQL request. + $invalidcriteria = true; + unset($params['criteria'][$criteriaindex]); + break; + } + + if (!$invalidcriteria) { + $cleanedvalue = clean_param($criteria['value'], $paramtype); + + $sql .= ' AND '; + + // Create the SQL. + switch ($criteria['key']) { + case 'id': + case 'idnumber': + case 'username': + case 'auth': + $sql .= $criteria['key'] . ' = :' . $criteria['key']; + $sqlparams[$criteria['key']] = $cleanedvalue; + break; + case 'email': + case 'lastname': + case 'firstname': + $sql .= $DB->sql_like($criteria['key'], ':' . $criteria['key'], false); + $sqlparams[$criteria['key']] = $cleanedvalue; + break; + default: + break; + } + } + } + + $users = $DB->get_records_select('user', $sql, $sqlparams, 'id ASC'); + + // Finally retrieve each users information. + $returnedusers = array(); + foreach ($users as $user) { + $userdetails = user_get_user_details_courses($user); + + // Return the user only if all the searched fields are returned. + // Otherwise it means that the $USER was not allowed to search the returned user. + if (!empty($userdetails)) { + $validuser = true; + + foreach($params['criteria'] as $criteria) { + if (empty($userdetails[$criteria['key']])) { + $validuser = false; + } + } + + if ($validuser) { + $returnedusers[] = $userdetails; + } + } + } + + return array('users' => $returnedusers, 'warnings' => $warnings); + } + + /** + * Returns description of get_users result value. + * + * @return external_description + * @since Moodle 2.5 + */ + public static function get_users_returns() { + return new external_single_structure( + array('users' => new external_multiple_structure( + self::user_description() + ), + 'warnings' => new external_warnings('always set to \'key\'', 'faulty key name') + ) + ); + } + /** * Returns description of method parameters * @@ -590,70 +710,18 @@ public static function get_users_by_id($userids) { * @since Moodle 2.2 */ public static function get_users_by_id_returns() { - return new external_multiple_structure( - new external_single_structure( - array( - 'id' => new external_value(PARAM_INT, '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_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), - '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_INT, '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_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_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), - '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), - 'enrolledcourses' => new external_multiple_structure( - new external_single_structure( - array( - 'id' => new external_value(PARAM_INT, 'Id of the course'), - 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'), - 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course') - ) - ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL) - ) - ) - ); + $additionalfields = array ( + 'enrolledcourses' => new external_multiple_structure( + new external_single_structure( + array( + 'id' => new external_value(PARAM_INT, 'Id of the course'), + 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'), + 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course') + ) + ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)); + return new external_multiple_structure(self::user_description($additionalfields)); } + /** * Returns description of method parameters * @@ -742,11 +810,48 @@ public static function get_course_user_profiles($userlist) { * @since Moodle 2.2 */ public static function get_course_user_profiles_returns() { - return new external_multiple_structure( - new external_single_structure( - array( + $additionalfields = array( + 'groups' => new external_multiple_structure( + new external_single_structure( + array( + 'id' => new external_value(PARAM_INT, 'group id'), + 'name' => new external_value(PARAM_RAW, 'group name'), + 'description' => new external_value(PARAM_RAW, 'group description'), + 'descriptionformat' => new external_format_value('description'), + ) + ), 'user groups', VALUE_OPTIONAL), + 'roles' => new external_multiple_structure( + new external_single_structure( + array( + 'roleid' => new external_value(PARAM_INT, 'role id'), + 'name' => new external_value(PARAM_RAW, 'role name'), + 'shortname' => new external_value(PARAM_ALPHANUMEXT, 'role shortname'), + 'sortorder' => new external_value(PARAM_INT, 'role sortorder') + ) + ), 'user roles', VALUE_OPTIONAL), + 'enrolledcourses' => new external_multiple_structure( + new external_single_structure( + array( + 'id' => new external_value(PARAM_INT, 'Id of the course'), + 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'), + 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course') + ) + ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL) + ); + + return new external_multiple_structure(self::user_description($additionalfields)); + } + + /** + * Create user return value description. + * + * @param array $additionalfields some additional field + * @return single_structure_description + */ + public static function user_description($additionalfields = array()) { + $userfields = array( 'id' => new external_value(PARAM_INT, 'ID of the user'), - 'username' => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL), + 'username' => new external_value(PARAM_RAW, 'The username', 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'), @@ -765,6 +870,12 @@ public static function get_course_user_profiles_returns() { '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_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_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_format_value('description', VALUE_OPTIONAL), 'city' => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL), @@ -780,44 +891,21 @@ public static function get_course_user_profiles_returns() { '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), - 'groups' => new external_multiple_structure( - new external_single_structure( - array( - 'id' => new external_value(PARAM_INT, 'group id'), - 'name' => new external_value(PARAM_RAW, 'group name'), - 'description' => new external_value(PARAM_RAW, 'group description'), - 'descriptionformat' => new external_format_value('description'), - ) - ), 'user groups', VALUE_OPTIONAL), - 'roles' => new external_multiple_structure( - new external_single_structure( - array( - 'roleid' => new external_value(PARAM_INT, 'role id'), - 'name' => new external_value(PARAM_RAW, 'role name'), - 'shortname' => new external_value(PARAM_ALPHANUMEXT, 'role shortname'), - 'sortorder' => new external_value(PARAM_INT, 'role sortorder') - ) - ), 'user roles', VALUE_OPTIONAL), + ), 'User custom fields (also known as user profile 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), - 'enrolledcourses' => new external_multiple_structure( - new external_single_structure( - array( - 'id' => new external_value(PARAM_INT, 'Id of the course'), - 'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'), - 'shortname' => new external_value(PARAM_RAW, 'Shortname of the course') - ) - ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL) - ) - ) - ); + ), 'Users preferences', VALUE_OPTIONAL) + ); + if (!empty($additionalfields)) { + $userfields = array_merge($userfields, $additionalfields); + } + return new external_single_structure($userfields); } + } /** @@ -1085,4 +1173,4 @@ public static function get_users_by_courseid_returns() { 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/tests/externallib_test.php b/user/tests/externallib_test.php index c582b6d3ea7ed..e761c1437fa62 100644 --- a/user/tests/externallib_test.php +++ b/user/tests/externallib_test.php @@ -33,6 +33,166 @@ class core_user_external_testcase extends externallib_advanced_testcase { + /** + * Test get_users + */ + public function test_get_users() { + 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); + set_config('usetags', 1); + 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. + $this->getDataGenerator()->enrol_user($user1->id, $course->id, $roleid); + $this->getDataGenerator()->enrol_user($user2->id, $course->id, $roleid); + $this->getDataGenerator()->enrol_user($USER->id, $course->id, $roleid); + + // call as admin and receive all possible fields. + $this->setAdminUser(); + + $searchparams = array( + array('key' => 'invalidkey', 'value' => 'invalidkey'), + array('key' => 'email', 'value' => $user1->email), + array('key' => 'firstname', 'value' => $user1->firstname)); + + // Call the external function. + $result = core_user_external::get_users($searchparams); + + // We need to execute the return values cleaning process to simulate the web service server + $result = external_api::clean_returnvalue(core_user_external::get_users_returns(), $result); + + // Check we retrieve the good total number of enrolled users + no error on capability. + $expectedreturnedusers = 1; + $returnedusers = $result['users']; + $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 the invalid key warning. + $warnings = $result['warnings']; + $this->assertEquals(count($warnings), 1); + $warning = array_pop($warnings); + $this->assertEquals($warning['item'], 'invalidkey'); + $this->assertEquals($warning['warningcode'], 'invalidfieldparameter'); + + // Test sending twice the same search field. + try { + $searchparams = array( + array('key' => 'firstname', 'value' => 'Canard'), + array('key' => 'email', 'value' => $user1->email), + array('key' => 'firstname', 'value' => $user1->firstname)); + + // Call the external function. + $result = core_user_external::get_users($searchparams); + $this->fail('Expecting \'keyalreadyset\' moodle_exception to be thrown.'); + } catch (moodle_exception $e) { + $this->assertEquals('keyalreadyset', $e->errorcode); + } catch (Exception $e) { + $this->fail('Expecting \'keyalreadyset\' moodle_exception to be thrown.'); + } + } + /** * Test get_users_by_field */