Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

MDL-29938 get_users - search users external function

  • Loading branch information...
commit b0365ea5d1ac08aa22e65cba935b192ea3411eeb 1 parent 6319737
Jérôme Mouneyrac authored January 23, 2013
9  lib/db/services.php
@@ -273,6 +273,15 @@
273 273
         'capabilities'=> 'moodle/user:create',
274 274
     ),
275 275
 
  276
+    'core_user_get_users' => array(
  277
+        'classname'   => 'core_user_external',
  278
+        'methodname'  => 'get_users',
  279
+        'classpath'   => 'user/externallib.php',
  280
+        'description' => 'search for users matching the parameters',
  281
+        'type'        => 'read',
  282
+        'capabilities'=> 'moodle/user:viewdetails, moodle/user:viewhiddendetails, moodle/course:useremail, moodle/user:update',
  283
+    ),
  284
+
276 285
     'moodle_user_get_users_by_id' => array(
277 286
         'classname'   => 'core_user_external',
278 287
         'methodname'  => 'get_users_by_id',
379  user/externallib.php
@@ -458,64 +458,174 @@ public static function get_users_by_field($field, $values) {
458 458
      * @since Moodle 2.4
459 459
      */
460 460
     public static function get_users_by_field_returns() {
461  
-        return new external_multiple_structure(
462  
-            new external_single_structure(
463  
-                array(
464  
-                    'id'    => new external_value(PARAM_INT, 'ID of the user'),
465  
-                    'username'    => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
466  
-                    'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
467  
-                    'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
468  
-                    'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
469  
-                    'email'       => new external_value(PARAM_EMAIL, 'An email address', VALUE_OPTIONAL),
470  
-                    'address'     => new external_value(PARAM_TEXT, 'Postal address', VALUE_OPTIONAL),
471  
-                    'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
472  
-                    'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
473  
-                    'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
474  
-                    'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
475  
-                    'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
476  
-                    'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
477  
-                    'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
478  
-                    'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
479  
-                    'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
480  
-                    'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
481  
-                    'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
482  
-                    'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
483  
-                    'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
484  
-                    'auth'        => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL),
485  
-                    'confirmed'   => new external_value(PARAM_INT, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL),
486  
-                    'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL),
487  
-                    'theme'       => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
488  
-                    'timezone'    => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
489  
-                    'mailformat'  => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
490  
-                    'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
491  
-                    'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
492  
-                    'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
493  
-                    'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
494  
-                    'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
495  
-                    'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
496  
-                    'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
497  
-                    'customfields' => new external_multiple_structure(
498  
-                        new external_single_structure(
499  
-                            array(
500  
-                                'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
501  
-                                'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
502  
-                                'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
503  
-                                'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
504  
-                            )
505  
-                        ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
506  
-                    'preferences' => new external_multiple_structure(
507  
-                        new external_single_structure(
508  
-                            array(
509  
-                                'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
510  
-                                'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
511  
-                            )
512  
-                    ), 'User preferences', VALUE_OPTIONAL)
  461
+        return new external_multiple_structure(core_user_external::user_description());
  462
+    }
  463
+
  464
+
  465
+    /**
  466
+     * Returns description of get_users() parameters
  467
+     *
  468
+     * @return external_function_parameters
  469
+     * @since Moodle 2.4
  470
+     */
  471
+    public static function get_users_parameters() {
  472
+        return new external_function_parameters(
  473
+            array(
  474
+                'criteria' => new external_multiple_structure(
  475
+                    new external_single_structure(
  476
+                        array(
  477
+                            'key'        => new external_value(PARAM_ALPHA, 'the user column to search, expected keys (value format) are:
  478
+                                                    "id" (int) matching user id,
  479
+                                                    "lastname" (string) user last name (Note: you can use % for searching but it can be slow!),
  480
+                                                    "firstname" (string) user first name (Note: you can use % for searching but it can be slow!),
  481
+                                                    "idnumber" (string) matching user idnumber,
  482
+                                                    "username" (string) matching user username,
  483
+                                                    "email" (string) user email (Note: you can use % for searching but it can be slow!),
  484
+                                                    "auth" (plugin) matching user auth plugin'),
  485
+                            'value'      => new external_value(PARAM_RAW, 'the value to search')
  486
+                        )
  487
+                    ), 'the key/value pairs to be considered in user search. Values can not be empty.
  488
+                        Specifiy different keys only once (fullname => \'user1\', auth => \'manual\', ...) -
  489
+                        key occurences are ignored, only the last occurence is considered.
  490
+                        The search is executed with AND operator on the criterias.'
513 491
                 )
514 492
             )
515 493
         );
516 494
     }
517 495
 
518 496
     /**
  497
+     * Retrieve matching user
  498
+     *
  499
+     * @param string $field
  500
+     * @param array $values
  501
+     * @return array An array of arrays containg user profiles.
  502
+     * @since Moodle 2.4
  503
+     */
  504
+    public static function get_users($criteria = array()) {
  505
+        global $CFG, $USER, $DB;
  506
+
  507
+        require_once($CFG->dirroot . "/user/lib.php");
  508
+
  509
+        $params = self::validate_parameters(self::get_users_parameters(),
  510
+                array('criteria' => $criteria));
  511
+
  512
+        // Validate the criteria and retrieve the users
  513
+        $cleanedvalues = array();
  514
+        $firstcriteria = true;
  515
+        $users = array();
  516
+        $warnings = array();
  517
+        $sql = '';
  518
+        $sqlparams = array();
  519
+
  520
+        foreach ($params['criteria'] as $criteria) {
  521
+
  522
+            // Clean the parameters
  523
+            $paramtype = PARAM_RAW;
  524
+            switch ($criteria['key']) {
  525
+                case 'id':
  526
+                    $paramtype = PARAM_INT;
  527
+                    break;
  528
+                case 'idnumber':
  529
+                    $paramtype = PARAM_RAW;
  530
+                    break;
  531
+                case 'username':
  532
+                    $paramtype = PARAM_USERNAME;
  533
+                    break;
  534
+                case 'email':
  535
+                    // we use PARAM_RAW to allow searches with %
  536
+                    $paramtype = PARAM_RAW;
  537
+                    break;
  538
+                case 'auth':
  539
+                    $paramtype = PARAM_AUTH;
  540
+                    break;
  541
+                case 'lastname':
  542
+                case 'firstname':
  543
+                    $paramtype = PARAM_TEXT;
  544
+                    break;
  545
+                default:
  546
+                    // Send back a warning that this search key is not supported in this version
  547
+                    // This warning will make the function extandable without breaking clients
  548
+                    $warnings[] = array(
  549
+                        'item' => 'key',
  550
+                        'itemid' => $criteria['key'],
  551
+                        'warningcode' => 'invalidfieldparameter',
  552
+                        'message' => 'The search key \'' . $$criteria['key'] . '\' is not supported, look at the web service documentation'
  553
+                    );
  554
+            }
  555
+            $cleanedvalue = clean_param($criteria['value'], $paramtype);
  556
+
  557
+            // If first criteria do not add AND to the query
  558
+            if ($firstcriteria) {
  559
+                $firstcriteria = false;
  560
+            } else {
  561
+                $sql .= ' AND ';
  562
+            }
  563
+
  564
+            // Create the SQL
  565
+            switch ($criteria['key']) {
  566
+                case 'id':
  567
+                case 'idnumber':
  568
+                case 'username':
  569
+                case 'auth':
  570
+                    $sql .= $criteria['key'] . ' = :' . $criteria['key'];
  571
+                    $sqlparams[$criteria['key']] = $cleanedvalue;
  572
+                    break;
  573
+                case 'email':
  574
+                case 'lastname':
  575
+                case 'firstname':
  576
+                    $sql .= $DB->sql_like($criteria['key'], ':'.$criteria['key'], false);
  577
+                    $sqlparams[$criteria['key']] = $cleanedvalue;
  578
+                    break;
  579
+                default:
  580
+                    break;
  581
+            }
  582
+        }
  583
+
  584
+        $users = $DB->get_records_select('user', $sql, $sqlparams, 'id ASC');
  585
+
  586
+        // Finally retrieve each users information
  587
+        $returnedusers = array();
  588
+        foreach ($users as $user) {
  589
+
  590
+            $userdetails = user_get_user_details_courses($user);
  591
+
  592
+            // Return the user only if all the searched fields are returned.
  593
+            // Otherwise it means that the $USER was not allowed to search the returned user.
  594
+            if (!empty($userdetails)) {
  595
+                $validuser = true;
  596
+
  597
+                foreach($params['criteria'] as $criteria) {
  598
+                    if (empty($userdetails[$criteria['key']])) {
  599
+                        $validuser = false;
  600
+                    }
  601
+                }
  602
+
  603
+                if ($validuser) {
  604
+                    $returnedusers[] = $userdetails;
  605
+                }
  606
+            }
  607
+        }
  608
+
  609
+        return array('users' => $returnedusers, 'warnings' => $warnings);
  610
+    }
  611
+
  612
+    /**
  613
+     * Returns description of get_users result value
  614
+     *
  615
+     * @return external_description
  616
+     * @since Moodle 2.3
  617
+     */
  618
+    public static function get_users_returns() {
  619
+        return new external_single_structure(
  620
+            array('users' => new external_multiple_structure(
  621
+                                core_user_external::user_description()
  622
+                             ),
  623
+                  'warnings' => new external_warnings()
  624
+            )
  625
+        );
  626
+    }
  627
+
  628
+    /**
519 629
      * Returns description of method parameters
520 630
      *
521 631
      * @return external_function_parameters
@@ -583,6 +693,8 @@ public static function get_users_by_id($userids) {
583 693
         return $result;
584 694
     }
585 695
 
  696
+
  697
+
586 698
     /**
587 699
      * Returns description of method result value
588 700
      *
@@ -591,67 +703,7 @@ public static function get_users_by_id($userids) {
591 703
      */
592 704
     public static function get_users_by_id_returns() {
593 705
         return new external_multiple_structure(
594  
-            new external_single_structure(
595  
-                array(
596  
-                    'id'    => new external_value(PARAM_INT, 'ID of the user'),
597  
-                    'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
598  
-                    'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
599  
-                    'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
600  
-                    'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
601  
-                    'email'       => new external_value(PARAM_TEXT, 'An email address - allow email as root@localhost', VALUE_OPTIONAL),
602  
-                    'address'     => new external_value(PARAM_TEXT, 'Postal address', VALUE_OPTIONAL),
603  
-                    'phone1'      => new external_value(PARAM_NOTAGS, 'Phone 1', VALUE_OPTIONAL),
604  
-                    'phone2'      => new external_value(PARAM_NOTAGS, 'Phone 2', VALUE_OPTIONAL),
605  
-                    'icq'         => new external_value(PARAM_NOTAGS, 'icq number', VALUE_OPTIONAL),
606  
-                    'skype'       => new external_value(PARAM_NOTAGS, 'skype id', VALUE_OPTIONAL),
607  
-                    'yahoo'       => new external_value(PARAM_NOTAGS, 'yahoo id', VALUE_OPTIONAL),
608  
-                    'aim'         => new external_value(PARAM_NOTAGS, 'aim id', VALUE_OPTIONAL),
609  
-                    'msn'         => new external_value(PARAM_NOTAGS, 'msn number', VALUE_OPTIONAL),
610  
-                    'department'  => new external_value(PARAM_TEXT, 'department', VALUE_OPTIONAL),
611  
-                    'institution' => new external_value(PARAM_TEXT, 'institution', VALUE_OPTIONAL),
612  
-                    'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
613  
-                    'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
614  
-                    'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
615  
-                    'auth'        => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL),
616  
-                    'confirmed'   => new external_value(PARAM_INT, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL),
617  
-                    'idnumber'    => new external_value(PARAM_RAW, 'An arbitrary ID code number perhaps from the institution', VALUE_OPTIONAL),
618  
-                    'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL),
619  
-                    'theme'       => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
620  
-                    'timezone'    => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
621  
-                    'mailformat'  => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
622  
-                    'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
623  
-                    'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
624  
-                    'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
625  
-                    'url'         => new external_value(PARAM_URL, 'URL of the user', VALUE_OPTIONAL),
626  
-                    'country'     => new external_value(PARAM_ALPHA, 'Home country code of the user, such as AU or CZ', VALUE_OPTIONAL),
627  
-                    'profileimageurlsmall' => new external_value(PARAM_URL, 'User image profile URL - small version'),
628  
-                    'profileimageurl' => new external_value(PARAM_URL, 'User image profile URL - big version'),
629  
-                    'customfields' => new external_multiple_structure(
630  
-                        new external_single_structure(
631  
-                            array(
632  
-                                'type'  => new external_value(PARAM_ALPHANUMEXT, 'The type of the custom field - text field, checkbox...'),
633  
-                                'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
634  
-                                'name' => new external_value(PARAM_RAW, 'The name of the custom field'),
635  
-                                'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
636  
-                            )
637  
-                    ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
638  
-                    'preferences' => new external_multiple_structure(
639  
-                        new external_single_structure(
640  
-                            array(
641  
-                                'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
642  
-                                'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
643  
-                            )
644  
-                    ), 'User preferences', VALUE_OPTIONAL),
645  
-                    'enrolledcourses' => new external_multiple_structure(
646  
-                        new external_single_structure(
647  
-                            array(
648  
-                                'id'  => new external_value(PARAM_INT, 'Id of the course'),
649  
-                                'fullname'  => new external_value(PARAM_RAW, 'Fullname of the course'),
650  
-                                'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
651  
-                            )
652  
-                    ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
653  
-                )
654  
-            )
  706
+            core_user_external::user_description()
655 707
         );
656 708
     }
657 709
     /**
@@ -742,11 +794,48 @@ public static function get_course_user_profiles($userlist) {
742 794
      * @since Moodle 2.2
743 795
      */
744 796
     public static function get_course_user_profiles_returns() {
745  
-        return new external_multiple_structure(
746  
-            new external_single_structure(
747  
-                array(
  797
+        $additionalfields = array(
  798
+                    'groups' => new external_multiple_structure(
  799
+                        new external_single_structure(
  800
+                            array(
  801
+                                'id'  => new external_value(PARAM_INT, 'group id'),
  802
+                                'name' => new external_value(PARAM_RAW, 'group name'),
  803
+                                'description' => new external_value(PARAM_RAW, 'group description'),
  804
+                                'descriptionformat' => new external_format_value('description'),
  805
+                            )
  806
+                        ), 'user groups', VALUE_OPTIONAL),
  807
+                    'roles' => new external_multiple_structure(
  808
+                        new external_single_structure(
  809
+                            array(
  810
+                                'roleid'       => new external_value(PARAM_INT, 'role id'),
  811
+                                'name'         => new external_value(PARAM_RAW, 'role name'),
  812
+                                'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
  813
+                                'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
  814
+                            )
  815
+                        ), 'user roles', VALUE_OPTIONAL),
  816
+                    'enrolledcourses' => new external_multiple_structure(
  817
+	                    new external_single_structure(
  818
+		                    array(
  819
+			                    'id'  => new external_value(PARAM_INT, 'Id of the course'),
  820
+			                    'fullname'  => new external_value(PARAM_RAW, 'Fullname of the course'),
  821
+			                    'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
  822
+		                    )
  823
+	                    ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
  824
+                    );
  825
+
  826
+        return new external_multiple_structure(core_user_external::user_description($additionalfields));
  827
+    }
  828
+
  829
+    /**
  830
+     * Create user return value description.
  831
+     *
  832
+     * @param array $additionalfiels some additional field
  833
+     * @return single_structure_description
  834
+     */
  835
+    public static function user_description($additionalfiels = array()) {
  836
+        $userfields = array(
748 837
                     'id'    => new external_value(PARAM_INT, 'ID of the user'),
749  
-                    'username'    => new external_value(PARAM_RAW, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
  838
+                    'username'    => new external_value(PARAM_USERNAME, 'Username policy is defined in Moodle security config', VALUE_OPTIONAL),
750 839
                     'firstname'   => new external_value(PARAM_NOTAGS, 'The first name(s) of the user', VALUE_OPTIONAL),
751 840
                     'lastname'    => new external_value(PARAM_NOTAGS, 'The family name of the user', VALUE_OPTIONAL),
752 841
                     'fullname'    => new external_value(PARAM_NOTAGS, 'The fullname of the user'),
@@ -765,6 +854,12 @@ public static function get_course_user_profiles_returns() {
765 854
                     'interests'   => new external_value(PARAM_TEXT, 'user interests (separated by commas)', VALUE_OPTIONAL),
766 855
                     'firstaccess' => new external_value(PARAM_INT, 'first access to the site (0 if never)', VALUE_OPTIONAL),
767 856
                     'lastaccess'  => new external_value(PARAM_INT, 'last access to the site (0 if never)', VALUE_OPTIONAL),
  857
+                    'auth'        => new external_value(PARAM_PLUGIN, 'Auth plugins include manual, ldap, imap, etc', VALUE_OPTIONAL),
  858
+                    'confirmed'   => new external_value(PARAM_INT, 'Active user: 1 if confirmed, 0 otherwise', VALUE_OPTIONAL),
  859
+                    'lang'        => new external_value(PARAM_SAFEDIR, 'Language code such as "en", must exist on server', VALUE_OPTIONAL),
  860
+                    'theme'       => new external_value(PARAM_PLUGIN, 'Theme name such as "standard", must exist on server', VALUE_OPTIONAL),
  861
+                    'timezone'    => new external_value(PARAM_TIMEZONE, 'Timezone code such as Australia/Perth, or 99 for default', VALUE_OPTIONAL),
  862
+                    'mailformat'  => new external_value(PARAM_INT, 'Mail format code is 0 for plain text, 1 for HTML etc', VALUE_OPTIONAL),
768 863
                     'description' => new external_value(PARAM_RAW, 'User profile description', VALUE_OPTIONAL),
769 864
                     'descriptionformat' => new external_format_value('description', VALUE_OPTIONAL),
770 865
                     'city'        => new external_value(PARAM_NOTAGS, 'Home city of the user', VALUE_OPTIONAL),
@@ -781,43 +876,20 @@ public static function get_course_user_profiles_returns() {
781 876
                                 'shortname' => new external_value(PARAM_RAW, 'The shortname of the custom field - to be able to build the field class in the code'),
782 877
                             )
783 878
                         ), 'User custom fields (also known as user profil fields)', VALUE_OPTIONAL),
784  
-                    'groups' => new external_multiple_structure(
785  
-                        new external_single_structure(
786  
-                            array(
787  
-                                'id'  => new external_value(PARAM_INT, 'group id'),
788  
-                                'name' => new external_value(PARAM_RAW, 'group name'),
789  
-                                'description' => new external_value(PARAM_RAW, 'group description'),
790  
-                                'descriptionformat' => new external_format_value('description'),
791  
-                            )
792  
-                        ), 'user groups', VALUE_OPTIONAL),
793  
-                    'roles' => new external_multiple_structure(
794  
-                        new external_single_structure(
795  
-                            array(
796  
-                                'roleid'       => new external_value(PARAM_INT, 'role id'),
797  
-                                'name'         => new external_value(PARAM_RAW, 'role name'),
798  
-                                'shortname'    => new external_value(PARAM_ALPHANUMEXT, 'role shortname'),
799  
-                                'sortorder'    => new external_value(PARAM_INT, 'role sortorder')
800  
-                            )
801  
-                        ), 'user roles', VALUE_OPTIONAL),
802 879
                     'preferences' => new external_multiple_structure(
803 880
                         new external_single_structure(
804 881
                             array(
805 882
                                 'name'  => new external_value(PARAM_ALPHANUMEXT, 'The name of the preferences'),
806 883
                                 'value' => new external_value(PARAM_RAW, 'The value of the custom field'),
807 884
                             )
808  
-                    ), 'User preferences', VALUE_OPTIONAL),
809  
-                    'enrolledcourses' => new external_multiple_structure(
810  
-                        new external_single_structure(
811  
-                            array(
812  
-                                'id'  => new external_value(PARAM_INT, 'Id of the course'),
813  
-                                'fullname' => new external_value(PARAM_RAW, 'Fullname of the course'),
814  
-                                'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
815  
-                            )
816  
-                    ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL)
817  
-                )
818  
-            )
819  
-        );
  885
+                    ), 'Users preferences', VALUE_OPTIONAL)
  886
+                );
  887
+        if (!empty($additionalfields)) {
  888
+            $userfields = array_merge($userfields, $additionalfields);
  889
+        }
  890
+        return new external_single_structure($userfields);
820 891
     }
  892
+
821 893
 }
822 894
 
823 895
  /**
@@ -995,7 +1067,16 @@ public static function get_users_by_id($userids) {
995 1067
      * @see core_user_external::get_users_by_id_returns()
996 1068
      */
997 1069
     public static function get_users_by_id_returns() {
998  
-        return core_user_external::get_users_by_id_returns();
  1070
+        $additionalfields = array (
  1071
+            'enrolledcourses' => new external_multiple_structure(
  1072
+	        new external_single_structure(
  1073
+		        array(
  1074
+			        'id'  => new external_value(PARAM_INT, 'Id of the course'),
  1075
+			        'fullname'  => new external_value(PARAM_RAW, 'Fullname of the course'),
  1076
+			        'shortname' => new external_value(PARAM_RAW, 'Shortname of the course')
  1077
+		        )
  1078
+	        ), 'Courses where the user is enrolled - limited by which courses the user is able to see', VALUE_OPTIONAL));
  1079
+        return core_user_external::get_users_by_id_returns($additionalfields);
999 1080
     }
1000 1081
     /**
1001 1082
      * Returns description of method parameters
@@ -1085,4 +1166,4 @@ public static function get_users_by_courseid_returns() {
1085 1166
         require_once($CFG->dirroot . '/enrol/externallib.php');
1086 1167
         return core_enrol_external::get_enrolled_users_returns();
1087 1168
     }
1088  
-}
  1169
+}
150  user/tests/externallib_test.php
@@ -34,6 +34,156 @@
34 34
 class core_user_external_testcase extends externallib_advanced_testcase {
35 35
 
36 36
     /**
  37
+     * Test get_users
  38
+     */
  39
+    public function test_get_users() {
  40
+        global $USER, $CFG;
  41
+
  42
+        $this->resetAfterTest(true);
  43
+
  44
+        $course = self::getDataGenerator()->create_course();
  45
+        $user1 = array(
  46
+            'username' => 'usernametest1',
  47
+            'idnumber' => 'idnumbertest1',
  48
+            'firstname' => 'First Name User Test 1',
  49
+            'lastname' => 'Last Name User Test 1',
  50
+            'email' => 'usertest1@email.com',
  51
+            'address' => '2 Test Street Perth 6000 WA',
  52
+            'phone1' => '01010101010',
  53
+            'phone2' => '02020203',
  54
+            'icq' => 'testuser1',
  55
+            'skype' => 'testuser1',
  56
+            'yahoo' => 'testuser1',
  57
+            'aim' => 'testuser1',
  58
+            'msn' => 'testuser1',
  59
+            'department' => 'Department of user 1',
  60
+            'institution' => 'Institution of user 1',
  61
+            'description' => 'This is a description for user 1',
  62
+            'descriptionformat' => FORMAT_MOODLE,
  63
+            'city' => 'Perth',
  64
+            'url' => 'http://moodle.org',
  65
+            'country' => 'au'
  66
+            );
  67
+        $user1 = self::getDataGenerator()->create_user($user1);
  68
+        if (!empty($CFG->usetags)) {
  69
+            require_once($CFG->dirroot . '/user/editlib.php');
  70
+            require_once($CFG->dirroot . '/tag/lib.php');
  71
+            $user1->interests = array('Cinema', 'Tennis', 'Dance', 'Guitar', 'Cooking');
  72
+            useredit_update_interests($user1, $user1->interests);
  73
+        }
  74
+        $user2 = self::getDataGenerator()->create_user(
  75
+                array('username' => 'usernametest2', 'idnumber' => 'idnumbertest2'));
  76
+
  77
+        $generatedusers = array();
  78
+        $generatedusers[$user1->id] = $user1;
  79
+        $generatedusers[$user2->id] = $user2;
  80
+
  81
+        $context = context_course::instance($course->id);
  82
+        $roleid = $this->assignUserCapability('moodle/user:viewdetails', $context->id);
  83
+
  84
+        // Enrol the users in the course.
  85
+        // We use the manual plugin.
  86
+        $enrol = enrol_get_plugin('manual');
  87
+        $enrolinstances = enrol_get_instances($course->id, true);
  88
+        foreach ($enrolinstances as $courseenrolinstance) {
  89
+            if ($courseenrolinstance->enrol == "manual") {
  90
+                $instance = $courseenrolinstance;
  91
+                break;
  92
+            }
  93
+        }
  94
+        $enrol->enrol_user($instance, $user1->id, $roleid);
  95
+        $enrol->enrol_user($instance, $user2->id, $roleid);
  96
+        $enrol->enrol_user($instance, $USER->id, $roleid);
  97
+
  98
+        // call as admin and receive all possible fields.
  99
+        $this->setAdminUser();
  100
+
  101
+        $searchparams = array(
  102
+            array('key' => 'email', 'value' => $user1->email),
  103
+            array('key' => 'firstname', 'value' => $user1->firstname));
  104
+
  105
+        // Call the external function.
  106
+        $result = core_user_external::get_users($searchparams);
  107
+
  108
+        // Check we retrieve the good total number of enrolled users + no error on capability.
  109
+        $expectedreturnedusers = 1;
  110
+        $returnedusers = $result['users'];
  111
+        $this->assertEquals($expectedreturnedusers, count($returnedusers));
  112
+
  113
+        foreach($returnedusers as $returneduser) {
  114
+            $generateduser = ($returneduser['id'] == $USER->id) ?
  115
+                                $USER : $generatedusers[$returneduser['id']];
  116
+            $this->assertEquals($generateduser->username, $returneduser['username']);
  117
+            if (!empty($generateduser->idnumber)) {
  118
+                $this->assertEquals($generateduser->idnumber, $returneduser['idnumber']);
  119
+            }
  120
+            $this->assertEquals($generateduser->firstname, $returneduser['firstname']);
  121
+            $this->assertEquals($generateduser->lastname, $returneduser['lastname']);
  122
+            if ($generateduser->email != $USER->email) { //don't check the tmp modified $USER email
  123
+                $this->assertEquals($generateduser->email, $returneduser['email']);
  124
+            }
  125
+            if (!empty($generateduser->address)) {
  126
+                $this->assertEquals($generateduser->address, $returneduser['address']);
  127
+            }
  128
+            if (!empty($generateduser->phone1)) {
  129
+                $this->assertEquals($generateduser->phone1, $returneduser['phone1']);
  130
+            }
  131
+            if (!empty($generateduser->phone2)) {
  132
+                $this->assertEquals($generateduser->phone2, $returneduser['phone2']);
  133
+            }
  134
+            if (!empty($generateduser->icq)) {
  135
+                $this->assertEquals($generateduser->icq, $returneduser['icq']);
  136
+            }
  137
+            if (!empty($generateduser->skype)) {
  138
+                $this->assertEquals($generateduser->skype, $returneduser['skype']);
  139
+            }
  140
+            if (!empty($generateduser->yahoo)) {
  141
+                $this->assertEquals($generateduser->yahoo, $returneduser['yahoo']);
  142
+            }
  143
+            if (!empty($generateduser->aim)) {
  144
+                $this->assertEquals($generateduser->aim, $returneduser['aim']);
  145
+            }
  146
+            if (!empty($generateduser->msn)) {
  147
+                $this->assertEquals($generateduser->msn, $returneduser['msn']);
  148
+            }
  149
+            if (!empty($generateduser->department)) {
  150
+                $this->assertEquals($generateduser->department, $returneduser['department']);
  151
+            }
  152
+            if (!empty($generateduser->institution)) {
  153
+                $this->assertEquals($generateduser->institution, $returneduser['institution']);
  154
+            }
  155
+            if (!empty($generateduser->description)) {
  156
+                $this->assertEquals($generateduser->description, $returneduser['description']);
  157
+            }
  158
+            if (!empty($generateduser->descriptionformat)) {
  159
+                $this->assertEquals(FORMAT_HTML, $returneduser['descriptionformat']);
  160
+            }
  161
+            if (!empty($generateduser->city)) {
  162
+                $this->assertEquals($generateduser->city, $returneduser['city']);
  163
+            }
  164
+            if (!empty($generateduser->country)) {
  165
+                $this->assertEquals($generateduser->country, $returneduser['country']);
  166
+            }
  167
+            if (!empty($generateduser->url)) {
  168
+                $this->assertEquals($generateduser->url, $returneduser['url']);
  169
+            }
  170
+            if (!empty($CFG->usetags) and !empty($generateduser->interests)) {
  171
+                $this->assertEquals(implode(', ', $generateduser->interests), $returneduser['interests']);
  172
+            }
  173
+        }
  174
+
  175
+        // Test that no result are returned for search by username if we are not admin
  176
+        $this->setGuestUser();
  177
+
  178
+        // Call the external function.
  179
+        $returnedusers = core_user_external::get_users_by_field('username',
  180
+                    array($USER->username, $user1->username, $user2->username));
  181
+
  182
+        // Only the own $USER username should be returned
  183
+        $this->assertEquals(1, count($returnedusers));
  184
+    }
  185
+
  186
+    /**
37 187
      * Test get_users_by_field
38 188
      */
39 189
     public function test_get_users_by_field() {

0 notes on commit b0365ea

Please sign in to comment.
Something went wrong with that request. Please try again.