MDL-49347 rating: New external function core_rating_get_item_ratings
[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  * Completion 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 require_once("$CFG->libdir/externallib.php");
28 require_once("$CFG->dirroot/rating/lib.php");
30 /**
31  * Completion external functions
32  *
33  * @package    core_rating
34  * @category   external
35  * @copyright  2015 Costantino Cito <ccito@cvaconsulting.com>
36  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
37  * @since      Moodle 2.9
38  */
39 class core_rating_external extends external_api {
41     /**
42      * Returns description of get_item_ratings parameters.
43      *
44      * @return external_function_parameters
45      * @since Moodle 2.9
46      */
47     public static function get_item_ratings_parameters() {
48         return new external_function_parameters (
49             array(
50                 'contextlevel' => new external_value(PARAM_ALPHA, 'contextlevel'),
51                 'instanceid'  => new external_value(PARAM_INT, 'The Instance id of item associated with the context level'),
52                 'component'   => new external_value(PARAM_COMPONENT, 'component'),
53                 'ratingarea'  => new external_value(PARAM_AREA, 'Rating area', VALUE_DEFAULT, ''),
54                 'itemid'      => new external_value(PARAM_INT, 'Associated id'),
55                 'scaleid'     => new external_value(PARAM_INT, 'Scale id'),
56                 'sort'        => new external_value(PARAM_TEXT, 'Sort order', VALUE_DEFAULT, ''),
57             )
58         );
59     }
61     /**
62      * Getting list of ratings for a given item (forum post etc)
63      * @param string $contextlevel ('context_course', etc..)
64      * @param int $instanceid (eg. the 'id' in the 'book' table)
65      * @param string $component the name of the component
66      * @param string|null $ratingarea
67      * @param int $itemid the item id
68      * @param int $scaleid the scale id
69      * @param string $sort sql order
70      * @return array Result and possible warnings
71      * @throws moodle_exception
72      * @since Moodle 2.9
73      */
74     public static function get_item_ratings($contextlevel, $instanceid, $component, $ratingarea, $itemid, $scaleid, $sort) {
75         global $USER;
77         $arrayparams = array(
78                  'contextlevel' => $contextlevel,
79                  'instanceid'   => $instanceid,
80                  'component'    => $component,
81                  'ratingarea'   => $ratingarea,
82                  'itemid'       => $itemid,
83                  'scaleid'      => $scaleid,
84                  'sort'         => $sort);
86         // Validate and normalize parameters.
87         $params = self::validate_parameters(self::get_item_ratings_parameters(), $arrayparams);
89         $context = self::get_context_from_params($params);
90         self::validate_context($context);
91         list($context, $course, $cm) = get_context_info_array($context->id);
93         // Minimal capability required.
94         if (!has_capability('moodle/rating:view', $context)) {
95             throw new moodle_exception('noviewrate', 'rating');
96         }
98         // Can we see all ratings?
99         $canviewallratings = has_capability('moodle/rating:viewall', $context);
101         // Create the Sql sort order string.
102         switch ($params['sort']) {
103             case 'firstname':
104                 $sqlsort = "u.firstname ASC";
105                 break;
106             case 'rating':
107                 $sqlsort = "r.rating ASC";
108                 break;
109             default:
110                 $sqlsort = "r.timemodified ASC";
111         }
113         $ratingoptions = new stdClass;
114         $ratingoptions->context = $context;
115         $ratingoptions->component = $params['component'];
116         $ratingoptions->ratingarea = $params['ratingarea'];
117         $ratingoptions->itemid = $params['itemid'];
118         $ratingoptions->sort = $sqlsort;
120         $rm = new rating_manager();
121         $ratings = $rm->get_all_ratings_for_item($ratingoptions);
122         $scalemenu = make_grades_menu($params['scaleid']);
124         // If the scale was changed after ratings were submitted some ratings may have a value above the current maximum.
125         // We can't just do count($scalemenu) - 1 as custom scales start at index 1, not 0.
126         $maxrating = max(array_keys($scalemenu));
128         $results = array();
130         foreach ($ratings as $rating) {
131             if ($canviewallratings || $USER->id == $rating->userid) {
132                 $result = array();
133                 $usercontext = context_user::instance($rating->userid);
134                 $profileimageurl = moodle_url::make_pluginfile_url($usercontext->id, 'user', 'icon', null, '/', 'f1');
135                 $result['userid'] = $rating->userid;
136                 $result['userpictureurl'] = $profileimageurl->out(false);
137                 $result['fullname'] = fullname($rating);
138                 $result['rating'] = $scalemenu[$rating->rating];
139                 $result['timemodified'] = $rating->timemodified;
140                 $results[] = $result;
141             }
142         }
144         $warnings = array();
145         return array('ratings' => $results, 'warning' => $warnings);
146     }
148     /**
149      * Returns description of get_item_ratings result values.
150      *
151      * @return external_single_structure
152      * @since Moodle 2.9
153      */
154     public static function get_item_ratings_returns() {
156         return new external_single_structure(
157             array(
158                 'ratings'    => new external_multiple_structure(
159                     new external_single_structure(
160                         array(
161                             'userid'          => new external_value(PARAM_INT,  'User id'),
162                             'userpictureurl'  => new external_value(PARAM_URL,  'URL user picture'),
163                             'fullname'        => new external_value(PARAM_TEXT, 'fullname'),
164                             'rating'          => new external_value(PARAM_TEXT, 'Rating on scale'),
165                             'timemodified'    => new external_value(PARAM_INT,  'Time modified (timestamp)')
166                         ), 'Ratings'
167                     ), 'List of ratings'
168                 ),
169                 'warnings'  => new external_warnings(),
170             )
171         );
172     }