[Summary view]

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  /**
  18   * External grade report overview API
  19   *
  20   * @package    gradereport_overview
  21   * @copyright  2016 Juan Leyva <juan@moodle.com>
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  defined('MOODLE_INTERNAL') || die;
  26  
  27  require_once($CFG->libdir . '/externallib.php');
  28  require_once($CFG->libdir . '/gradelib.php');
  29  require_once($CFG->dirroot . '/grade/lib.php');
  30  require_once($CFG->dirroot . '/grade/report/overview/lib.php');
  31  
  32  /**
  33   * External grade overview report API implementation
  34   *
  35   * @package    gradereport_overview
  36   * @copyright  2016 Juan Leyva <juan@moodle.com>
  37   * @category   external
  38   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  39   */
  40  class gradereport_overview_external extends external_api {
  41  
  42      /**
  43       * Describes the parameters for get_course_grades.
  44       *
  45       * @return external_function_parameters
  46       * @since Moodle 3.2
  47       */
  48      public static function get_course_grades_parameters() {
  49          return new external_function_parameters (
  50              array(
  51                  'userid' => new external_value(PARAM_INT, 'Get grades for this user (optional, default current)', VALUE_DEFAULT, 0)
  52              )
  53          );
  54      }
  55  
  56      /**
  57       * Get the given user courses final grades
  58       *
  59       * @param int $userid get grades for this user (optional, default current)
  60       *
  61       * @return array the grades tables
  62       * @since Moodle 3.2
  63       */
  64      public static function get_course_grades($userid = 0) {
  65          global $USER;
  66  
  67          $warnings = array();
  68  
  69          // Validate the parameter.
  70          $params = self::validate_parameters(self::get_course_grades_parameters(),
  71              array(
  72                  'userid' => $userid
  73              )
  74          );
  75  
  76          $userid = $params['userid'];
  77          if (empty($userid)) {
  78              $userid = $USER->id;
  79          }
  80  
  81          $systemcontext = context_system::instance();
  82          self::validate_context($systemcontext);
  83  
  84          if ($USER->id != $userid) {
  85              // We must check if the current user can view other users grades.
  86              $user = core_user::get_user($userid, '*', MUST_EXIST);
  87              core_user::require_active_user($user);
  88              require_capability('moodle/grade:viewall', $systemcontext);
  89          }
  90  
  91          // We need the site course, and course context.
  92          $course = get_course(SITEID);
  93          $context = context_course::instance($course->id);
  94  
  95          // Force a regrade if required.
  96          grade_regrade_final_grades_if_required($course);
  97          // Get the course final grades now.
  98          $gpr = new grade_plugin_return(array('type' => 'report', 'plugin' => 'overview', 'courseid' => $course->id,
  99                                          'userid' => $userid));
 100          $report = new grade_report_overview($userid, $gpr, $context);
 101          $coursesgrades = $report->setup_courses_data(true);
 102  
 103          $grades = array();
 104          foreach ($coursesgrades as $coursegrade) {
 105              $gradeinfo = array(
 106                  'courseid' => $coursegrade['course']->id,
 107                  'grade' => grade_format_gradevalue($coursegrade['finalgrade'], $coursegrade['courseitem'], true),
 108                  'rawgrade' => $coursegrade['finalgrade'],
 109              );
 110              if (isset($coursegrade['rank'])) {
 111                  $gradeinfo['rank'] = $coursegrade['rank'];
 112              }
 113              $grades[] = $gradeinfo;
 114          }
 115  
 116          $result = array();
 117          $result['grades'] = $grades;
 118          $result['warnings'] = $warnings;
 119          return $result;
 120      }
 121  
 122      /**
 123       * Describes the get_course_grades return value.
 124       *
 125       * @return external_single_structure
 126       * @since Moodle 3.2
 127       */
 128      public static function get_course_grades_returns() {
 129          return new external_single_structure(
 130              array(
 131                  'grades' => new external_multiple_structure(
 132                      new external_single_structure(
 133                          array(
 134                              'courseid' => new external_value(PARAM_INT, 'Course id'),
 135                              'grade' => new external_value(PARAM_RAW, 'Grade formatted'),
 136                              'rawgrade' => new external_value(PARAM_RAW, 'Raw grade, not formatted'),
 137                              'rank' => new external_value(PARAM_INT, 'Your rank in the course', VALUE_OPTIONAL),
 138                          )
 139                      )
 140                  ),
 141                  'warnings' => new external_warnings()
 142              )
 143          );
 144      }
 145  
 146      /**
 147       * Returns description of method parameters
 148       *
 149       * @return external_function_parameters
 150       * @since Moodle 3.2
 151       */
 152      public static function view_grade_report_parameters() {
 153          return new external_function_parameters(
 154              array(
 155                  'courseid' => new external_value(PARAM_INT, 'id of the course'),
 156                  'userid' => new external_value(PARAM_INT, 'id of the user, 0 means current user', VALUE_DEFAULT, 0)
 157              )
 158          );
 159      }
 160  
 161      /**
 162       * Trigger the user report events, do the same that the web interface view of the report
 163       *
 164       * @param int $courseid id of course
 165       * @param int $userid id of the user the report belongs to
 166       * @return array of warnings and status result
 167       * @since Moodle 3.2
 168       * @throws moodle_exception
 169       */
 170      public static function view_grade_report($courseid, $userid = 0) {
 171          global $USER;
 172  
 173          $params = self::validate_parameters(self::view_grade_report_parameters(),
 174              array(
 175                  'courseid' => $courseid,
 176                  'userid' => $userid
 177              )
 178          );
 179  
 180          $warnings = array();
 181          $course = get_course($params['courseid']);
 182  
 183          $context = context_course::instance($course->id);
 184          self::validate_context($context);
 185  
 186          $userid = $params['userid'];
 187          if (empty($userid)) {
 188              $userid = $USER->id;
 189          } else {
 190              $user = core_user::get_user($userid, '*', MUST_EXIST);
 191              core_user::require_active_user($user);
 192          }
 193          $systemcontext = context_system::instance();
 194          $personalcontext = context_user::instance($userid);
 195  
 196          $access = grade_report_overview::check_access($systemcontext, $context, $personalcontext, $course, $userid);
 197  
 198          if (!$access) {
 199              throw new moodle_exception('nopermissiontoviewgrades', 'error');
 200          }
 201  
 202          grade_report_overview::viewed($context, $course->id, $userid);
 203  
 204          $result = array();
 205          $result['status'] = true;
 206          $result['warnings'] = $warnings;
 207          return $result;
 208      }
 209  
 210      /**
 211       * Returns description of method result value
 212       *
 213       * @return external_description
 214       * @since Moodle 3.2
 215       */
 216      public static function view_grade_report_returns() {
 217          return new external_single_structure(
 218              array(
 219                  'status' => new external_value(PARAM_BOOL, 'status: true if success'),
 220                  'warnings' => new external_warnings()
 221              )
 222          );
 223      }
 224  }