weekly release 4.1dev
[moodle.git] / grade / report / overview / classes / external.php
CommitLineData
7cd19312
JL
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
25defined('MOODLE_INTERNAL') || die;
26
27require_once($CFG->libdir . '/externallib.php');
28require_once($CFG->libdir . '/gradelib.php');
29require_once($CFG->dirroot . '/grade/lib.php');
30require_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 */
40class gradereport_overview_external extends external_api {
41
42 /**
43 * Describes the parameters for get_course_grades.
44 *
9db43c73 45 * @return external_function_parameters
7cd19312
JL
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 }
78310c30
JL
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 }
7cd19312 224}