Merge branch 'wip-MDL-34938-master' of git://github.com/marinaglancy/moodle
[moodle.git] / rating / classes / external.php
CommitLineData
db5b6971
CC
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/**
46e41e63 18 * Rating external API
db5b6971
CC
19 *
20 * @package core_rating
21 * @category external
22 * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 * @since Moodle 2.9
25 */
26
46e41e63
JL
27defined('MOODLE_INTERNAL') || die;
28
db5b6971
CC
29require_once("$CFG->libdir/externallib.php");
30require_once("$CFG->dirroot/rating/lib.php");
31
32/**
46e41e63 33 * Rating external functions
db5b6971
CC
34 *
35 * @package core_rating
36 * @category external
37 * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com>
38 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39 * @since Moodle 2.9
40 */
41class core_rating_external extends external_api {
42
43 /**
44 * Returns description of get_item_ratings parameters.
45 *
46 * @return external_function_parameters
47 * @since Moodle 2.9
48 */
49 public static function get_item_ratings_parameters() {
50 return new external_function_parameters (
51 array(
46e41e63
JL
52 'contextlevel' => new external_value(PARAM_ALPHA, 'context level: course, module, user, etc...'),
53 'instanceid' => new external_value(PARAM_INT, 'the instance id of item associated with the context level'),
54 'component' => new external_value(PARAM_COMPONENT, 'component'),
55 'ratingarea' => new external_value(PARAM_AREA, 'rating area'),
56 'itemid' => new external_value(PARAM_INT, 'associated id'),
57 'scaleid' => new external_value(PARAM_INT, 'scale id'),
58 'sort' => new external_value(PARAM_ALPHA, 'sort order (firstname, rating or timemodified)')
db5b6971
CC
59 )
60 );
61 }
62
63 /**
46e41e63
JL
64 * Retrieve a list of ratings for a given item (forum post etc)
65 *
66 * @param string $contextlevel course, module, user...
67 * @param int $instanceid the instance if for the context element
db5b6971 68 * @param string $component the name of the component
46e41e63 69 * @param string $ratingarea rating area
db5b6971
CC
70 * @param int $itemid the item id
71 * @param int $scaleid the scale id
46e41e63 72 * @param string $sort sql order (firstname, rating or timemodified)
db5b6971
CC
73 * @return array Result and possible warnings
74 * @throws moodle_exception
75 * @since Moodle 2.9
76 */
77 public static function get_item_ratings($contextlevel, $instanceid, $component, $ratingarea, $itemid, $scaleid, $sort) {
78 global $USER;
79
46e41e63
JL
80 $warnings = array();
81
db5b6971 82 $arrayparams = array(
46e41e63
JL
83 'contextlevel' => $contextlevel,
84 'instanceid' => $instanceid,
85 'component' => $component,
86 'ratingarea' => $ratingarea,
87 'itemid' => $itemid,
88 'scaleid' => $scaleid,
89 'sort' => $sort
90 );
db5b6971
CC
91
92 // Validate and normalize parameters.
93 $params = self::validate_parameters(self::get_item_ratings_parameters(), $arrayparams);
94
95 $context = self::get_context_from_params($params);
96 self::validate_context($context);
db5b6971
CC
97
98 // Minimal capability required.
99 if (!has_capability('moodle/rating:view', $context)) {
100 throw new moodle_exception('noviewrate', 'rating');
101 }
102
46e41e63
JL
103 list($context, $course, $cm) = get_context_info_array($context->id);
104
db5b6971
CC
105 // Can we see all ratings?
106 $canviewallratings = has_capability('moodle/rating:viewall', $context);
107
108 // Create the Sql sort order string.
109 switch ($params['sort']) {
110 case 'firstname':
111 $sqlsort = "u.firstname ASC";
112 break;
113 case 'rating':
114 $sqlsort = "r.rating ASC";
115 break;
116 default:
117 $sqlsort = "r.timemodified ASC";
118 }
119
120 $ratingoptions = new stdClass;
121 $ratingoptions->context = $context;
122 $ratingoptions->component = $params['component'];
123 $ratingoptions->ratingarea = $params['ratingarea'];
124 $ratingoptions->itemid = $params['itemid'];
125 $ratingoptions->sort = $sqlsort;
126
127 $rm = new rating_manager();
128 $ratings = $rm->get_all_ratings_for_item($ratingoptions);
129 $scalemenu = make_grades_menu($params['scaleid']);
130
131 // If the scale was changed after ratings were submitted some ratings may have a value above the current maximum.
132 // We can't just do count($scalemenu) - 1 as custom scales start at index 1, not 0.
133 $maxrating = max(array_keys($scalemenu));
134
135 $results = array();
136
137 foreach ($ratings as $rating) {
138 if ($canviewallratings || $USER->id == $rating->userid) {
46e41e63
JL
139 if ($rating->rating > $maxrating) {
140 $rating->rating = $maxrating;
141 }
d982713a
JL
142
143 $profileimageurl = '';
144 // We can have ratings from deleted users. In this case, those users don't have a valid context.
145 $usercontext = context_user::instance($rating->userid, IGNORE_MISSING);
146 if ($usercontext) {
147 $profileimageurl = moodle_url::make_webservice_pluginfile_url($usercontext->id, 'user', 'icon', null,
148 '/', 'f1')->out(false);
149 }
46e41e63
JL
150
151 $result = array();
152 $result['id'] = $rating->id;
db5b6971 153 $result['userid'] = $rating->userid;
d982713a 154 $result['userpictureurl'] = $profileimageurl;
46e41e63 155 $result['userfullname'] = fullname($rating);
db5b6971
CC
156 $result['rating'] = $scalemenu[$rating->rating];
157 $result['timemodified'] = $rating->timemodified;
158 $results[] = $result;
159 }
160 }
161
46e41e63
JL
162 return array(
163 'ratings' => $results,
164 'warnings' => $warnings
165 );
db5b6971
CC
166 }
167
168 /**
169 * Returns description of get_item_ratings result values.
170 *
171 * @return external_single_structure
172 * @since Moodle 2.9
173 */
174 public static function get_item_ratings_returns() {
175
176 return new external_single_structure(
177 array(
178 'ratings' => new external_multiple_structure(
179 new external_single_structure(
180 array(
46e41e63
JL
181 'id' => new external_value(PARAM_INT, 'rating id'),
182 'userid' => new external_value(PARAM_INT, 'user id'),
db5b6971 183 'userpictureurl' => new external_value(PARAM_URL, 'URL user picture'),
46e41e63
JL
184 'userfullname' => new external_value(PARAM_NOTAGS, 'user fullname'),
185 'rating' => new external_value(PARAM_NOTAGS, 'rating on scale'),
186 'timemodified' => new external_value(PARAM_INT, 'time modified (timestamp)')
187 ), 'Rating'
188 ), 'list of ratings'
db5b6971
CC
189 ),
190 'warnings' => new external_warnings(),
191 )
192 );
193 }
194
195}