grade/report/overview/classes/external.php

   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 }