Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 401 and 402] [Versions 401 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 coding_exception;
  20  use context_course;
  21  use external_api;
  22  use external_description;
  23  use external_function_parameters;
  24  use external_multiple_structure;
  25  use external_single_structure;
  26  use external_value;
  27  use external_warnings;
  28  use invalid_parameter_exception;
  29  use moodle_exception;
  30  use restricted_context_exception;
  31  
  32  defined('MOODLE_INTERNAL') || die;
  33  
  34  require_once($CFG->libdir.'/externallib.php');
  35  
  36  /**
  37   * External group report API implementation
  38   *
  39   * @package    core_grades
  40   * @copyright  2022 Mathew May <mathew.solutions>
  41   * @category   external
  42   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  43   */
  44  class get_groups_for_search_widget extends external_api {
  45  
  46      /**
  47       * Returns description of method parameters.
  48       *
  49       * @return external_function_parameters
  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 group action', VALUE_REQUIRED)
  56              ]
  57          );
  58      }
  59  
  60      /**
  61       * Given a course ID find the existing user groups and map some fields to the returned array of group objects.
  62       *
  63       * @param int $courseid
  64       * @param string $actionbaseurl The base URL for the group action.
  65       * @return array Groups and warnings to pass back to the calling widget.
  66       */
  67      public static function execute(int $courseid, string $actionbaseurl): array {
  68          global $DB, $USER, $COURSE;
  69  
  70          $params = self::validate_parameters(
  71              self::execute_parameters(),
  72              [
  73                  'courseid' => $courseid,
  74                  'actionbaseurl' => $actionbaseurl
  75              ]
  76          );
  77  
  78          $warnings = [];
  79          $context = context_course::instance($params['courseid']);
  80          parent::validate_context($context);
  81  
  82          $mappedgroups = [];
  83          $course = $DB->get_record('course', ['id' => $params['courseid']]);
  84          // Initialise the grade tracking object.
  85          if ($groupmode = $course->groupmode) {
  86              $aag = has_capability('moodle/site:accessallgroups', $context);
  87  
  88              $usergroups = [];
  89              $groupuserid = 0;
  90              if ($groupmode == VISIBLEGROUPS || $aag) {
  91                  // Get user's own groups and put to the top.
  92                  $usergroups = groups_get_all_groups($course->id, $USER->id, $course->defaultgroupingid);
  93              } else {
  94                  $groupuserid = $USER->id;
  95              }
  96              $allowedgroups = groups_get_all_groups($course->id, $groupuserid, $course->defaultgroupingid);
  97  
  98              $allgroups = array_merge($allowedgroups, $usergroups);
  99              // Filter out any duplicate groups.
 100              $groupsmenu = array_intersect_key($allgroups, array_unique(array_column($allgroups, 'name')));
 101  
 102              if (!$allowedgroups || $groupmode == VISIBLEGROUPS || $aag) {
 103                  array_unshift($groupsmenu, (object) [
 104                      'id' => 0,
 105                      'name' => get_string('allparticipants'),
 106                  ]);
 107              }
 108  
 109              $mappedgroups = array_map(function($group) use ($COURSE, $actionbaseurl, $context) {
 110                  $url = new \moodle_url($actionbaseurl, [
 111                      'id' => $COURSE->id,
 112                      'group' => $group->id
 113                  ]);
 114                  return (object) [
 115                      'id' => $group->id,
 116                      'name' => format_string($group->name, true, ['context' => $context]),
 117                      'url' => $url->out(false),
 118                      'active' => false // @TODO MDL-76246
 119                  ];
 120              }, $groupsmenu);
 121          }
 122  
 123          return [
 124              'groups' => $mappedgroups,
 125              'warnings' => $warnings,
 126          ];
 127      }
 128  
 129      /**
 130       * Returns description of what the group search for the widget should return.
 131       *
 132       * @return external_single_structure
 133       */
 134      public static function execute_returns(): external_single_structure {
 135          return new external_single_structure([
 136              'groups' => new external_multiple_structure(self::group_description()),
 137              'warnings' => new external_warnings(),
 138          ]);
 139      }
 140  
 141      /**
 142       * Create group return value description.
 143       *
 144       * @return external_description
 145       */
 146      public static function group_description(): external_description {
 147          $groupfields = [
 148              'id' => new external_value(PARAM_ALPHANUM, 'An ID for the group', VALUE_REQUIRED),
 149              'url' => new external_value(PARAM_URL, 'The link that applies the group action', VALUE_REQUIRED),
 150              'name' => new external_value(PARAM_TEXT, 'The full name of the group', VALUE_REQUIRED),
 151              'active' => new external_value(PARAM_BOOL, 'Are we currently on this item?', VALUE_REQUIRED)
 152          ];
 153          return new external_single_structure($groupfields);
 154      }
 155  }