a23b4edecdf54cf9ab1439f18d83397310bbe415
[moodle.git] / rating / 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/>.
17 /**
18  * Rating external API
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  */
27 defined('MOODLE_INTERNAL') || die;
29 require_once("$CFG->libdir/externallib.php");
30 require_once("$CFG->dirroot/rating/lib.php");
32 /**
33  * Rating external functions
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  */
41 class core_rating_external extends external_api {
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(
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)')
59             )
60         );
61     }
63     /**
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
68      * @param string $component the name of the component
69      * @param string $ratingarea rating area
70      * @param int $itemid the item id
71      * @param int $scaleid the scale id
72      * @param string $sort sql order (firstname, rating or timemodified)
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;
80         $warnings = array();
82         $arrayparams = array(
83             'contextlevel' => $contextlevel,
84             'instanceid'   => $instanceid,
85             'component'    => $component,
86             'ratingarea'   => $ratingarea,
87             'itemid'       => $itemid,
88             'scaleid'      => $scaleid,
89             'sort'         => $sort
90         );
92         // Validate and normalize parameters.
93         $params = self::validate_parameters(self::get_item_ratings_parameters(), $arrayparams);
95         $context = self::get_context_from_params($params);
96         self::validate_context($context);
98         // Minimal capability required.
99         if (!has_capability('moodle/rating:view', $context)) {
100             throw new moodle_exception('noviewrate', 'rating');
101         }
103         list($context, $course, $cm) = get_context_info_array($context->id);
105         // Can we see all ratings?
106         $canviewallratings = has_capability('moodle/rating:viewall', $context);
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         }
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;
127         $rm = new rating_manager();
128         $ratings = $rm->get_all_ratings_for_item($ratingoptions);
129         $scalemenu = make_grades_menu($params['scaleid']);
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));
135         $results = array();
137         foreach ($ratings as $rating) {
138             if ($canviewallratings || $USER->id == $rating->userid) {
139                 if ($rating->rating > $maxrating) {
140                     $rating->rating = $maxrating;
141                 }
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                 }
151                 $result = array();
152                 $result['id'] = $rating->id;
153                 $result['userid'] = $rating->userid;
154                 $result['userpictureurl'] = $profileimageurl;
155                 $result['userfullname'] = fullname($rating);
156                 $result['rating'] = $scalemenu[$rating->rating];
157                 $result['timemodified'] = $rating->timemodified;
158                 $results[] = $result;
159             }
160         }
162         return array(
163             'ratings' => $results,
164             'warnings' => $warnings
165         );
166     }
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() {
176         return new external_single_structure(
177             array(
178                 'ratings'    => new external_multiple_structure(
179                     new external_single_structure(
180                         array(
181                             'id'              => new external_value(PARAM_INT,  'rating id'),
182                             'userid'          => new external_value(PARAM_INT,  'user id'),
183                             'userpictureurl'  => new external_value(PARAM_URL,  'URL user picture'),
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'
189                 ),
190                 'warnings'  => new external_warnings(),
191             )
192         );
193     }