[Summary view]

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]

   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   * 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   */
  26  
  27  defined('MOODLE_INTERNAL') || die;
  28  
  29  require_once("$CFG->dirroot/rating/lib.php");
  30  
  31  use core_external\external_api;
  32  use core_external\external_value;
  33  use core_external\external_single_structure;
  34  use core_external\external_multiple_structure;
  35  use core_external\external_function_parameters;
  36  use core_external\external_warnings;
  37  
  38  /**
  39   * Rating external functions
  40   *
  41   * @package    core_rating
  42   * @category   external
  43   * @copyright  2015 Costantino Cito <ccito@cvaconsulting.com>
  44   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  45   * @since      Moodle 2.9
  46   */
  47  class core_rating_external extends external_api {
  48  
  49      /**
  50       * Returns description of get_item_ratings parameters.
  51       *
  52       * @return external_function_parameters
  53       * @since Moodle 2.9
  54       */
  55      public static function get_item_ratings_parameters() {
  56          return new external_function_parameters (
  57              array(
  58                  'contextlevel'  => new external_value(PARAM_ALPHA, 'context level: course, module, user, etc...'),
  59                  'instanceid'    => new external_value(PARAM_INT, 'the instance id of item associated with the context level'),
  60                  'component'     => new external_value(PARAM_COMPONENT, 'component'),
  61                  'ratingarea'    => new external_value(PARAM_AREA, 'rating area'),
  62                  'itemid'        => new external_value(PARAM_INT, 'associated id'),
  63                  'scaleid'       => new external_value(PARAM_INT, 'scale id'),
  64                  'sort'          => new external_value(PARAM_ALPHA, 'sort order (firstname, rating or timemodified)')
  65              )
  66          );
  67      }
  68  
  69      /**
  70       * Retrieve a list of ratings for a given item (forum post etc)
  71       *
  72       * @param string $contextlevel course, module, user...
  73       * @param int $instanceid the instance if for the context element
  74       * @param string $component the name of the component
  75       * @param string $ratingarea rating area
  76       * @param int $itemid the item id
  77       * @param int $scaleid the scale id
  78       * @param string $sort sql order (firstname, rating or timemodified)
  79       * @return array Result and possible warnings
  80       * @throws moodle_exception
  81       * @since Moodle 2.9
  82       */
  83      public static function get_item_ratings($contextlevel, $instanceid, $component, $ratingarea, $itemid, $scaleid, $sort) {
  84          global $USER, $PAGE;
  85  
  86          $warnings = array();
  87  
  88          $arrayparams = array(
  89              'contextlevel' => $contextlevel,
  90              'instanceid'   => $instanceid,
  91              'component'    => $component,
  92              'ratingarea'   => $ratingarea,
  93              'itemid'       => $itemid,
  94              'scaleid'      => $scaleid,
  95              'sort'         => $sort
  96          );
  97  
  98          // Validate and normalize parameters.
  99          $params = self::validate_parameters(self::get_item_ratings_parameters(), $arrayparams);
 100  
 101          $context = self::get_context_from_params($params);
 102          self::validate_context($context);
 103  
 104          // Minimal capability required.
 105          $callbackparams = array('contextid' => $context->id,
 106                          'component' => $component,
 107                          'ratingarea' => $ratingarea,
 108                          'itemid' => $itemid,
 109                          'scaleid' => $scaleid);
 110          if (!has_capability('moodle/rating:view', $context) ||
 111                  !component_callback($component, 'rating_can_see_item_ratings', array($callbackparams), true)) {
 112              throw new moodle_exception('noviewrate', 'rating');
 113          }
 114  
 115          list($context, $course, $cm) = get_context_info_array($context->id);
 116  
 117          // Can we see all ratings?
 118          $canviewallratings = has_capability('moodle/rating:viewall', $context);
 119  
 120          // Create the Sql sort order string.
 121          switch ($params['sort']) {
 122              case 'firstname':
 123                  $sqlsort = "u.firstname ASC";
 124                  break;
 125              case 'rating':
 126                  $sqlsort = "r.rating ASC";
 127                  break;
 128              default:
 129                  $sqlsort = "r.timemodified ASC";
 130          }
 131  
 132          $ratingoptions = new stdClass;
 133          $ratingoptions->context = $context;
 134          $ratingoptions->component = $params['component'];
 135          $ratingoptions->ratingarea = $params['ratingarea'];
 136          $ratingoptions->itemid = $params['itemid'];
 137          $ratingoptions->sort = $sqlsort;
 138  
 139          $rm = new rating_manager();
 140          $ratings = $rm->get_all_ratings_for_item($ratingoptions);
 141          $scalemenu = make_grades_menu($params['scaleid']);
 142  
 143          // If the scale was changed after ratings were submitted some ratings may have a value above the current maximum.
 144          // We can't just do count($scalemenu) - 1 as custom scales start at index 1, not 0.
 145          $maxrating = max(array_keys($scalemenu));
 146  
 147          $results = array();
 148  
 149          foreach ($ratings as $rating) {
 150              if ($canviewallratings || $USER->id == $rating->userid) {
 151                  if ($rating->rating > $maxrating) {
 152                      $rating->rating = $maxrating;
 153                  }
 154  
 155                  $result = array();
 156                  $result['id'] = $rating->id;
 157                  $result['userid'] = $rating->userid;
 158                  $result['userfullname'] = fullname($rating);
 159                  $result['rating'] = $scalemenu[$rating->rating];
 160                  $result['timemodified'] = $rating->timemodified;
 161  
 162                  // The rating object has all the required fields for generating the picture url.
 163                  // Undo the aliasing of the user id column from fields::get_sql.
 164                  $rating->id = $rating->userid;
 165                  $userpicture = new user_picture($rating);
 166                  $userpicture->size = 1; // Size f1.
 167                  $result['userpictureurl'] = $userpicture->get_url($PAGE)->out(false);
 168  
 169                  $results[] = $result;
 170              }
 171          }
 172  
 173          return array(
 174              'ratings' => $results,
 175              'warnings' => $warnings
 176          );
 177      }
 178  
 179      /**
 180       * Returns description of get_item_ratings result values.
 181       *
 182       * @return external_single_structure
 183       * @since Moodle 2.9
 184       */
 185      public static function get_item_ratings_returns() {
 186  
 187          return new external_single_structure(
 188              array(
 189                  'ratings'    => new external_multiple_structure(
 190                      new external_single_structure(
 191                          array(
 192                              'id'              => new external_value(PARAM_INT,  'rating id'),
 193                              'userid'          => new external_value(PARAM_INT,  'user id'),
 194                              'userpictureurl'  => new external_value(PARAM_URL,  'URL user picture'),
 195                              'userfullname'    => new external_value(PARAM_NOTAGS, 'user fullname'),
 196                              'rating'          => new external_value(PARAM_NOTAGS, 'rating on scale'),
 197                              'timemodified'    => new external_value(PARAM_INT,  'time modified (timestamp)')
 198                          ), 'Rating'
 199                      ), 'list of ratings'
 200                  ),
 201                  'warnings'  => new external_warnings(),
 202              )
 203          );
 204      }
 205  
 206      /**
 207       * Returns description of add_rating parameters.
 208       *
 209       * @return external_function_parameters
 210       * @since Moodle 3.2
 211       */
 212      public static function add_rating_parameters() {
 213          return new external_function_parameters (
 214              array(
 215                  'contextlevel'  => new external_value(PARAM_ALPHA, 'context level: course, module, user, etc...'),
 216                  'instanceid'    => new external_value(PARAM_INT, 'the instance id of item associated with the context level'),
 217                  'component'     => new external_value(PARAM_COMPONENT, 'component'),
 218                  'ratingarea'    => new external_value(PARAM_AREA, 'rating area'),
 219                  'itemid'        => new external_value(PARAM_INT, 'associated id'),
 220                  'scaleid'       => new external_value(PARAM_INT, 'scale id'),
 221                  'rating'        => new external_value(PARAM_INT, 'user rating'),
 222                  'rateduserid'   => new external_value(PARAM_INT, 'rated user id'),
 223                  'aggregation'   => new external_value(PARAM_INT, 'agreggation method', VALUE_DEFAULT, RATING_AGGREGATE_NONE)
 224              )
 225          );
 226      }
 227  
 228      /**
 229       * Adds a rating to an item
 230       *
 231       * @param string $contextlevel course, module, user...
 232       * @param int $instanceid the instance if for the context element
 233       * @param string $component the name of the component
 234       * @param string $ratingarea rating area
 235       * @param int $itemid the item id
 236       * @param int $scaleid the scale id
 237       * @param int $rating the user rating
 238       * @param int $rateduserid the rated user id
 239       * @param int $aggregation the aggregation method
 240       * @return array result and possible warnings
 241       * @throws moodle_exception
 242       * @since Moodle 3.2
 243       */
 244      public static function add_rating($contextlevel, $instanceid, $component, $ratingarea, $itemid, $scaleid, $rating, $rateduserid,
 245                                          $aggregation = RATING_AGGREGATE_NONE) {
 246          $warnings = array();
 247  
 248          $params = array(
 249              'contextlevel' => $contextlevel,
 250              'instanceid'   => $instanceid,
 251              'component'    => $component,
 252              'ratingarea'   => $ratingarea,
 253              'itemid'       => $itemid,
 254              'scaleid'      => $scaleid,
 255              'rating'       => $rating,
 256              'rateduserid'  => $rateduserid,
 257              'aggregation'  => $aggregation,
 258          );
 259  
 260          // Validate and normalize parameters.
 261          $params = self::validate_parameters(self::add_rating_parameters(), $params);
 262  
 263          $context = self::get_context_from_params($params);
 264          self::validate_context($context);
 265          $cm = get_coursemodule_from_id(false, $context->instanceid, 0, false, MUST_EXIST);
 266  
 267          require_capability('moodle/rating:rate', $context);
 268  
 269          $rm = new rating_manager();
 270          $result = $rm->add_rating($cm, $context, $params['component'], $params['ratingarea'], $params['itemid'], $params['scaleid'],
 271                                      $params['rating'], $params['rateduserid'], $params['aggregation']);
 272  
 273          if (!empty($result->error)) {
 274              throw new moodle_exception($result->error, 'rating');
 275          }
 276  
 277          $returndata = array(
 278              'success' => $result->success,
 279              'warnings' => $warnings
 280          );
 281  
 282          if (isset($result->aggregate)) {
 283              $returndata['aggregate'] = $result->aggregate;
 284              $returndata['count'] = $result->count;
 285              $returndata['itemid'] = $result->itemid;
 286          }
 287  
 288          return $returndata;
 289      }
 290  
 291      /**
 292       * Returns description of add_rating result values.
 293       *
 294       * @return external_single_structure
 295       * @since Moodle 3.2
 296       */
 297      public static function add_rating_returns() {
 298  
 299          return new external_single_structure(
 300              array(
 301                  'success' => new external_value(PARAM_BOOL, 'Whether the rate was successfully created'),
 302                  'aggregate' => new external_value(PARAM_TEXT, 'New aggregate', VALUE_OPTIONAL),
 303                  'count' => new external_value(PARAM_INT, 'Ratings count', VALUE_OPTIONAL),
 304                  'itemid' => new external_value(PARAM_INT, 'Rating item id', VALUE_OPTIONAL),
 305                  'warnings'  => new external_warnings(),
 306              )
 307          );
 308      }
 309  }