[Summary view]

Differences Between: [Versions 402 and 403]

   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 core_user;
  28  
  29  defined('MOODLE_INTERNAL') || die;
  30  
  31  require_once($CFG->dirroot.'/grade/lib.php');
  32  
  33  /**
  34   * Get the enrolled users within and map some fields to the returned array of user objects.
  35   *
  36   * @package    core_grades
  37   * @copyright  2022 Mihail Geshoski <mihail@moodle.com>
  38   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  39   * @since      Moodle 4.2
  40   */
  41  class get_enrolled_users_for_selector extends external_api {
  42  
  43      /**
  44       * Returns description of method parameters.
  45       *
  46       * @return external_function_parameters
  47       */
  48      public static function execute_parameters(): external_function_parameters {
  49          return new external_function_parameters (
  50              [
  51                  'courseid' => new external_value(PARAM_INT, 'Course Id', VALUE_REQUIRED),
  52                  'groupid' => new external_value(PARAM_INT, 'Group Id', VALUE_DEFAULT, 0)
  53              ]
  54          );
  55      }
  56  
  57      /**
  58       * Given a course ID find the enrolled users within and map some fields to the returned array of user objects.
  59       *
  60       * @param int $courseid
  61       * @param int|null $groupid
  62       * @return array Users and warnings to pass back to the calling widget.
  63       * @throws coding_exception
  64       * @throws invalid_parameter_exception
  65       * @throws moodle_exception
  66       * @throws restricted_context_exception
  67       */
  68      public static function execute(int $courseid, ?int $groupid = 0): array {
  69          global $DB, $PAGE;
  70  
  71          $params = self::validate_parameters(
  72              self::execute_parameters(),
  73              [
  74                  'courseid' => $courseid,
  75                  'groupid' => $groupid
  76              ]
  77          );
  78  
  79          $warnings = [];
  80          $coursecontext = \context_course::instance($params['courseid']);
  81          parent::validate_context($coursecontext);
  82  
  83          require_capability('moodle/course:viewparticipants', $coursecontext);
  84  
  85          $course = $DB->get_record('course', ['id' => $params['courseid']]);
  86          // Create a graded_users_iterator because it will properly check the groups etc.
  87          $defaultgradeshowactiveenrol = !empty($CFG->grade_report_showonlyactiveenrol);
  88          $showonlyactiveenrol = get_user_preferences('grade_report_showonlyactiveenrol', $defaultgradeshowactiveenrol);
  89          $showonlyactiveenrol = $showonlyactiveenrol || !has_capability('moodle/course:viewsuspendedusers', $coursecontext);
  90  
  91          $gui = new \graded_users_iterator($course, null, $params['groupid']);
  92          $gui->require_active_enrolment($showonlyactiveenrol);
  93          $gui->init();
  94  
  95          $users = [];
  96  
  97          while ($userdata = $gui->next_user()) {
  98              $guiuser = $userdata->user;
  99              $user = new \stdClass();
 100              $user->fullname = fullname($guiuser);
 101              $user->id = $guiuser->id;
 102              $userpicture = new \user_picture($guiuser);
 103              $userpicture->size = 1;
 104              $user->profileimage = $userpicture->get_url($PAGE)->out(false);
 105              $user->email = $guiuser->email;
 106  
 107              $users[] = $user;
 108          }
 109          $gui->close();
 110  
 111          return [
 112              'users' => $users,
 113              'warnings' => $warnings,
 114          ];
 115      }
 116  
 117      /**
 118       * Returns description of method result value.
 119       *
 120       * @return external_single_structure
 121       */
 122      public static function execute_returns(): external_single_structure {
 123          return new external_single_structure([
 124              'users' => new external_multiple_structure(self::user_description()),
 125              'warnings' => new external_warnings(),
 126          ]);
 127      }
 128  
 129      /**
 130       * Create user return value description.
 131       *
 132       * @return external_description
 133       */
 134      public static function user_description(): external_description {
 135          $userfields = [
 136              'id'    => new external_value(core_user::get_property_type('id'), 'ID of the user'),
 137              'profileimage' => new external_value(
 138                  PARAM_URL,
 139                  'The location of the users larger image',
 140                  VALUE_OPTIONAL
 141              ),
 142              'fullname' => new external_value(PARAM_TEXT, 'The full name of the user', VALUE_OPTIONAL),
 143              'email' => new external_value(
 144                  core_user::get_property_type('email'),
 145                  'An email address - allow email as root@localhost',
 146                  VALUE_OPTIONAL)
 147          ];
 148          return new external_single_structure($userfields);
 149      }
 150  }