[Summary view]

   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_function_parameters;
  21  use core_external\external_value;
  22  
  23  defined('MOODLE_INTERNAL') || die;
  24  
  25  require_once($CFG->dirroot.'/grade/lib.php');
  26  
  27  /**
  28   * Web service to return the grade tree structure for a given course.
  29   *
  30   * @package    core_grades
  31   * @copyright  2023 Mihail Geshoski <mihail@moodle.com>
  32   * @category   external
  33   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  34   */
  35  class get_grade_tree extends external_api {
  36  
  37      /**
  38       * Returns description of method parameters.
  39       *
  40       * @return external_function_parameters
  41       */
  42      public static function execute_parameters(): external_function_parameters {
  43          return new external_function_parameters (
  44              [
  45                  'courseid' => new external_value(PARAM_INT, 'Course ID', VALUE_REQUIRED)
  46              ]
  47          );
  48      }
  49  
  50      /**
  51       * Given a course ID, return the grade tree structure for that course.
  52       *
  53       * @param int $courseid The course ID.
  54       * @return string JSON encoded data representing the course grade tree structure.
  55       */
  56      public static function execute(int $courseid): string {
  57  
  58          $params = self::validate_parameters(
  59              self::execute_parameters(),
  60              [
  61                  'courseid' => $courseid
  62              ]
  63          );
  64  
  65          $context = \context_course::instance($params['courseid']);
  66          parent::validate_context($context);
  67          // Make sure that the user has the capability to view the full grade tree in the course.
  68          require_capability('moodle/grade:viewall', $context);
  69          // Get the course grade category.
  70          $coursegradecategory = \grade_category::fetch_course_category($params['courseid']);
  71          $coursegradetree = self::generate_course_grade_tree($coursegradecategory);
  72  
  73          return json_encode($coursegradetree);
  74      }
  75  
  76      /**
  77       * Describes the return structure.
  78       *
  79       * @return external_value
  80       */
  81      public static function execute_returns(): external_value {
  82          return new external_value(PARAM_RAW, 'JSON encoded data representing the course grade tree structure.');
  83      }
  84  
  85      /**
  86       * Recursively generates the course grade tree structure.
  87       *
  88       * @param \grade_category $gradecategory The course grade category.
  89       * @return array The course grade tree structure.
  90       */
  91      private static function generate_course_grade_tree(\grade_category $gradecategory): array {
  92          $gradecategorydata = [
  93              'id' => $gradecategory->id,
  94              'name' => $gradecategory->get_name(),
  95              'iscategory' => true,
  96              'haschildcategories' => false
  97          ];
  98  
  99          // Get the children of the grade category.
 100          if ($gradecategorychildren = $gradecategory->get_children()) {
 101              foreach ($gradecategorychildren as $child) {
 102                  // If the child is a grade category, recursively generate the grade tree structure for that category.
 103                  if ($child['object'] instanceof \grade_category) {
 104                      $gradecategorydata['haschildcategories'] = true;
 105                      $gradecategorydata['children'][] = self::generate_course_grade_tree($child['object']);
 106                  } else { // Otherwise, add the grade item to the grade tree structure.
 107                      $gradecategorydata['children'][] = [
 108                          'id' => $child['object']->id,
 109                          'name' => $child['object']->get_name(),
 110                          'iscategory' => false,
 111                          'children' => null
 112                      ];
 113                  }
 114              }
 115          } else { // If the grade category has no children, set the children property to null.
 116              $gradecategorydata['children'] = null;
 117          }
 118  
 119          return $gradecategorydata;
 120      }
 121  }