[Summary view]

Differences Between: [Versions 401 and 402]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  namespace core_grades\external;
  18  
  19  use core_external\external_api;
  20  use core_external\external_description;
  21  use core_external\external_function_parameters;
  22  use core_external\external_multiple_structure;
  23  use core_external\external_single_structure;
  24  use core_external\external_value;
  25  use core_external\external_warnings;
  26  use core_external\restricted_context_exception;
  27  use moodle_url;
  28  use core_user;
  29  
  30  defined('MOODLE_INTERNAL') || die;
  31  
  32  require_once($CFG->dirroot.'/grade/lib.php');
  33  
  34  /**
  35   * Get the enrolled users within and map some fields to the returned array of user objects.
  36   *
  37   * @package    core_grades
  38   * @copyright  2022 Mihail Geshoski <mihail@moodle.com>
  39   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  40   * @since      Moodle 4.1
  41   * @deprecated
  42   */
  43  class get_enrolled_users_for_search_widget extends external_api {
  44  
  45      /**
  46       * Returns description of method parameters.
  47       *
  48       * @return external_function_parameters
  49       * @deprecated since 4.2
  50       */
  51      public static function execute_parameters(): external_function_parameters {
  52          return new external_function_parameters (
  53              [
  54                  'courseid' => new external_value(PARAM_INT, 'Course Id', VALUE_REQUIRED),
  55                  'actionbaseurl' => new external_value(PARAM_URL, 'The base URL for the user option', VALUE_REQUIRED),
  56                  'groupid' => new external_value(PARAM_INT, 'Group Id', VALUE_DEFAULT, 0)
  57              ]
  58          );
  59      }
  60  
  61      /**
  62       * Given a course ID find the enrolled users within and map some fields to the returned array of user objects.
  63       *
  64       * @param int $courseid
  65       * @param string $actionbaseurl The base URL for the user option.
  66       * @param int|null $groupid
  67       * @return array Users and warnings to pass back to the calling widget.
  68       * @throws coding_exception
  69       * @throws invalid_parameter_exception
  70       * @throws moodle_exception
  71       * @throws restricted_context_exception
  72       * @deprecated since 4.2
  73       */
  74      public static function execute(int $courseid, string $actionbaseurl, ?int $groupid = 0): array {
  75          global $DB, $PAGE;
  76  
  77          $params = self::validate_parameters(
  78              self::execute_parameters(),
  79              [
  80                  'courseid' => $courseid,
  81                  'actionbaseurl' => $actionbaseurl,
  82                  'groupid' => $groupid
  83              ]
  84          );
  85  
  86          $warnings = [];
  87          $coursecontext = \context_course::instance($params['courseid']);
  88          parent::validate_context($coursecontext);
  89  
  90          require_capability('moodle/course:viewparticipants', $coursecontext);
  91  
  92          $course = $DB->get_record('course', ['id' => $params['courseid']]);
  93          // Create a graded_users_iterator because it will properly check the groups etc.
  94          $defaultgradeshowactiveenrol = !empty($CFG->grade_report_showonlyactiveenrol);
  95          $showonlyactiveenrol = get_user_preferences('grade_report_showonlyactiveenrol', $defaultgradeshowactiveenrol);
  96          $showonlyactiveenrol = $showonlyactiveenrol || !has_capability('moodle/course:viewsuspendedusers', $coursecontext);
  97  
  98          $gui = new \graded_users_iterator($course, null, $params['groupid']);
  99          $gui->require_active_enrolment($showonlyactiveenrol);
 100          $gui->init();
 101  
 102          $users = [];
 103  
 104          while ($userdata = $gui->next_user()) {
 105              $guiuser = $userdata->user;
 106              $user = new \stdClass();
 107              $user->fullname = fullname($guiuser);
 108              $user->id = $guiuser->id;
 109              $user->url = (new moodle_url($actionbaseurl, ['id' => $courseid, 'userid' => $guiuser->id]))->out(false);
 110              $userpicture = new \user_picture($guiuser);
 111              $userpicture->size = 1;
 112              $user->profileimage = $userpicture->get_url($PAGE)->out(false);
 113              $user->email = $guiuser->email;
 114              $user->active = false;
 115  
 116              $users[] = $user;
 117          }
 118          $gui->close();
 119  
 120          return [
 121              'users' => $users,
 122              'warnings' => $warnings,
 123          ];
 124      }
 125  
 126      /**
 127       * Returns description of method result value.
 128       *
 129       * @return external_single_structure
 130       * @deprecated since 4.2
 131       */
 132      public static function execute_returns(): external_single_structure {
 133          return new external_single_structure([
 134              'users' => new external_multiple_structure(self::user_description()),
 135              'warnings' => new external_warnings(),
 136          ]);
 137      }
 138  
 139      /**
 140       * Create user return value description.
 141       *
 142       * @return external_description
 143       */
 144      public static function user_description(): external_description {
 145          $userfields = [
 146              'id'    => new external_value(core_user::get_property_type('id'), 'ID of the user'),
 147              'profileimage' => new external_value(
 148                  PARAM_URL,
 149                  'The location of the users larger image',
 150                  VALUE_OPTIONAL
 151              ),
 152              'url' => new external_value(
 153                  PARAM_URL,
 154                  'The link to the user report',
 155                  VALUE_OPTIONAL
 156              ),
 157              'fullname' => new external_value(PARAM_TEXT, 'The full name of the user', VALUE_OPTIONAL),
 158              'email' => new external_value(
 159                  core_user::get_property_type('email'),
 160                  'An email address - allow email as root@localhost',
 161                  VALUE_OPTIONAL),
 162              'active' => new external_value(PARAM_BOOL, 'Are we currently on this item?', VALUE_REQUIRED)
 163          ];
 164          return new external_single_structure($userfields);
 165      }
 166  
 167      /**
 168       * Mark the function as deprecated.
 169       * @return bool
 170       */
 171      public static function execute_is_deprecated() {
 172          return true;
 173      }
 174  }