rating/lib.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/>.
  16
  17 /**
  18  * A class representing a single rating and containing some static methods for manipulating ratings
  19  *
  20  * @package    core_rating
  21  * @subpackage rating
  22  * @copyright  2010 Andrew Davis
  23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24  */
  25
  26 define('RATING_UNSET_RATING', -999);
  27
  28 define ('RATING_AGGREGATE_NONE', 0); //no ratings
  29 define ('RATING_AGGREGATE_AVERAGE', 1);
  30 define ('RATING_AGGREGATE_COUNT', 2);
  31 define ('RATING_AGGREGATE_MAXIMUM', 3);
  32 define ('RATING_AGGREGATE_MINIMUM', 4);
  33 define ('RATING_AGGREGATE_SUM', 5);
  34
  35 define ('RATING_DEFAULT_SCALE', 5);
  36
  37 /**
  38  * The rating class represents a single rating by a single user
  39  *
  40  * @package   core_rating
  41  * @category  rating
  42  * @copyright 2010 Andrew Davis
  43  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  44  * @since     Moodle 2.0
  45  */
  46 class rating implements renderable {
  47
  48     /**
  49      * @var stdClass The context in which this rating exists
  50      */
  51     public $context;
  52
  53     /**
  54      * @var string The component using ratings. For example "mod_forum"
  55      */
  56     public $component;
  57
  58     /**
  59      * @var string The rating area to associate this rating with
  60      *             This allows a plugin to rate more than one thing by specifying different rating areas
  61      */
  62     public $ratingarea = null;
  63
  64     /**
  65      * @var int The id of the item (forum post, glossary item etc) being rated
  66      */
  67     public $itemid;
  68
  69     /**
  70      * @var int The id scale (1-5, 0-100) that was in use when the rating was submitted
  71      */
  72     public $scaleid;
  73
  74     /**
  75      * @var int The id of the user who submitted the rating
  76      */
  77     public $userid;
  78
  79     /**
  80      * @var stdclass settings for this rating. Necessary to render the rating.
  81      */
  82     public $settings;
  83
  84     /**
  85      * @var int The Id of this rating within the rating table. This is only set if the rating already exists
  86      */
  87     public $id = null;
  88
  89     /**
  90      * @var int The aggregate of the combined ratings for the associated item. This is only set if the rating already exists
  91      */
  92     public $aggregate = null;
  93
  94     /**
  95      * @var int The total number of ratings for the associated item. This is only set if the rating already exists
  96      */
  97     public $count = 0;
  98
  99     /**
 100      * @var int The rating the associated user gave the associated item. This is only set if the rating already exists
 101      */
 102     public $rating = null;
 103
 104     /**
 105      * @var int The time the associated item was created
 106      */
 107     public $itemtimecreated = null;
 108
 109     /**
 110      * @var int The id of the user who submitted the rating
 111      */
 112     public $itemuserid = null;
 113
 114     /**
 115      * Constructor.
 116      *
 117      * @param stdClass $options {
 118      *            context => context context to use for the rating [required]
 119      *            component => component using ratings ie mod_forum [required]
 120      *            ratingarea => ratingarea to associate this rating with [required]
 121      *            itemid  => int the id of the associated item (forum post, glossary item etc) [required]
 122      *            scaleid => int The scale in use when the rating was submitted [required]
 123      *            userid  => int The id of the user who submitted the rating [required]
 124      *            settings => Settings for the rating object [optional]
 125      *            id => The id of this rating (if the rating is from the db) [optional]
 126      *            aggregate => The aggregate for the rating [optional]
 127      *            count => The number of ratings [optional]
 128      *            rating => The rating given by the user [optional]
 129      * }
 130      */
 131     public function __construct($options) {
 132         $this->context =    $options->context;
 133         $this->component =  $options->component;
 134         $this->ratingarea = $options->ratingarea;
 135         $this->itemid =     $options->itemid;
 136         $this->scaleid =    $options->scaleid;
 137         $this->userid =     $options->userid;
 138
 139         if (isset($options->settings)) {
 140             $this->settings = $options->settings;
 141         }
 142         if (isset($options->id)) {
 143             $this->id = $options->id;
 144         }
 145         if (isset($options->aggregate)) {
 146             $this->aggregate = $options->aggregate;
 147         }
 148         if (isset($options->count)) {
 149             $this->count = $options->count;
 150         }
 151         if (isset($options->rating)) {
 152             $this->rating = $options->rating;
 153         }
 154     }
 155
 156     /**
 157      * Update this rating in the database
 158      *
 159      * @param int $rating the integer value of this rating
 160      */
 161     public function update_rating($rating) {
 162         global $DB;
 163
 164         $time = time();
 165
 166         $data = new stdClass;
 167         $data->rating       = $rating;
 168         $data->timemodified = $time;
 169
 170         $item = new stdclass();
 171         $item->id = $this->itemid;
 172         $items = array($item);
 173
 174         $ratingoptions = new stdClass;
 175         $ratingoptions->context = $this->context;
 176         $ratingoptions->component = $this->component;
 177         $ratingoptions->ratingarea = $this->ratingarea;
 178         $ratingoptions->items = $items;
 179         $ratingoptions->aggregate = RATING_AGGREGATE_AVERAGE;//we dont actually care what aggregation method is applied
 180         $ratingoptions->scaleid = $this->scaleid;
 181         $ratingoptions->userid = $this->userid;
 182
 183         $rm = new rating_manager();
 184         $items = $rm->get_ratings($ratingoptions);
 185         $firstitem = $items[0]->rating;
 186
 187         if (empty($firstitem->id)) {
 188             // Insert a new rating
 189             $data->contextid    = $this->context->id;
 190             $data->component    = $this->component;
 191             $data->ratingarea   = $this->ratingarea;
 192             $data->rating       = $rating;
 193             $data->scaleid      = $this->scaleid;
 194             $data->userid       = $this->userid;
 195             $data->itemid       = $this->itemid;
 196             $data->timecreated  = $time;
 197             $data->timemodified = $time;
 198             $DB->insert_record('rating', $data);
 199         } else {
 200             // Update the rating
 201             $data->id           = $firstitem->id;
 202             $DB->update_record('rating', $data);
 203         }
 204     }
 205
 206     /**
 207      * Retreive the integer value of this rating
 208      *
 209      * @return int the integer value of this rating object
 210      */
 211     public function get_rating() {
 212         return $this->rating;
 213     }
 214
 215     /**
 216      * Returns this ratings aggregate value as a string.
 217      *
 218      * @return string ratings aggregate value
 219      */
 220     public function get_aggregate_string() {
 221
 222         $aggregate = $this->aggregate;
 223         $method = $this->settings->aggregationmethod;
 224
 225         // only display aggregate if aggregation method isn't COUNT
 226         $aggregatestr = '';
 227         if ($aggregate && $method != RATING_AGGREGATE_COUNT) {
 228             if ($method != RATING_AGGREGATE_SUM && !$this->settings->scale->isnumeric) {
 229                 $aggregatestr .= $this->settings->scale->scaleitems[round($aggregate)]; //round aggregate as we're using it as an index
 230             } else { // aggregation is SUM or the scale is numeric
 231                 $aggregatestr .= round($aggregate, 1);
 232             }
 233         }
 234
 235         return $aggregatestr;
 236     }
 237
 238     /**
 239      * Returns true if the user is able to rate this rating object
 240      *
 241      * @param int $userid Current user assumed if left empty
 242      * @return bool true if the user is able to rate this rating object
 243      */
 244     public function user_can_rate($userid = null) {
 245         if (empty($userid)) {
 246             global $USER;
 247             $userid = $USER->id;
 248         }
 249         // You can't rate your item
 250         if ($this->itemuserid == $userid) {
 251             return false;
 252         }
 253         // You can't rate if you don't have the system cap
 254         if (!$this->settings->permissions->rate) {
 255             return false;
 256         }
 257         // You can't rate if you don't have the plugin cap
 258         if (!$this->settings->pluginpermissions->rate) {
 259             return false;
 260         }
 261
 262         // You can't rate if the item was outside of the assessment times
 263         $timestart = $this->settings->assesstimestart;
 264         $timefinish = $this->settings->assesstimefinish;
 265         $timecreated = $this->itemtimecreated;
 266         if (!empty($timestart) && !empty($timefinish) && ($timecreated < $timestart || $timecreated > $timefinish)) {
 267             return false;
 268         }
 269         return true;
 270     }
 271
 272     /**
 273      * Returns true if the user is able to view the aggregate for this rating object.
 274      *
 275      * @param int|null $userid If left empty the current user is assumed.
 276      * @return bool true if the user is able to view the aggregate for this rating object
 277      */
 278     public function user_can_view_aggregate($userid = null) {
 279         if (empty($userid)) {
 280             global $USER;
 281             $userid = $USER->id;
 282         }
 283
 284         // if the item doesnt belong to anyone or its another user's items and they can see the aggregate on items they don't own
 285         // Note that viewany doesnt mean you can see the aggregate or ratings of your own items
 286         if ((empty($this->itemuserid) or $this->itemuserid != $userid) && $this->settings->permissions->viewany && $this->settings->pluginpermissions->viewany ) {
 287             return true;
 288         }
 289
 290         // if its the current user's item and they have permission to view the aggregate on their own items
 291         if ($this->itemuserid == $userid && $this->settings->permissions->view && $this->settings->pluginpermissions->view) {
 292             return true;
 293         }
 294
 295         return false;
 296     }
 297
 298     /**
 299      * Returns a URL to view all of the ratings for the item this rating is for.
 300      *
 301      * If this is a rating of a post then this URL will take the user to a page that shows all of the ratings for the post
 302      * (this one included).
 303      *
 304      * @param bool $popup whether of not the URL should be loaded in a popup
 305      * @return moodle_url URL to view all of the ratings for the item this rating is for.
 306      */
 307     public function get_view_ratings_url($popup = false) {
 308         $attributes = array(
 309             'contextid'  => $this->context->id,
 310             'component'  => $this->component,
 311             'ratingarea' => $this->ratingarea,
 312             'itemid'     => $this->itemid,
 313             'scaleid'    => $this->settings->scale->id
 314         );
 315         if ($popup) {
 316             $attributes['popup'] = 1;
 317         }
 318         return new moodle_url('/rating/index.php', $attributes);
 319     }
 320
 321     /**
 322      * Returns a URL that can be used to rate the associated item.
 323      *
 324      * @param int|null          $rating    The rating to give the item, if null then no rating param is added.
 325      * @param moodle_url|string $returnurl The URL to return to.
 326      * @return moodle_url can be used to rate the associated item.
 327      */
 328     public function get_rate_url($rating = null, $returnurl = null) {
 329         if (empty($returnurl)) {
 330             if (!empty($this->settings->returnurl)) {
 331                 $returnurl = $this->settings->returnurl;
 332             } else {
 333                 global $PAGE;
 334                 $returnurl = $PAGE->url;
 335             }
 336         }
 337         $args = array(
 338             'contextid'   => $this->context->id,
 339             'component'   => $this->component,
 340             'ratingarea'  => $this->ratingarea,
 341             'itemid'      => $this->itemid,
 342             'scaleid'     => $this->settings->scale->id,
 343             'returnurl'   => $returnurl,
 344             'rateduserid' => $this->itemuserid,
 345             'aggregation' => $this->settings->aggregationmethod,
 346             'sesskey'     => sesskey()
 347         );
 348         if (!empty($rating)) {
 349             $args['rating'] = $rating;
 350         }
 351         $url = new moodle_url('/rating/rate.php', $args);
 352         return $url;
 353     }
 354
 355     /**
 356     * Remove this rating from the database
 357     * @return void
 358     */
 359     //public function delete_rating() {
 360         //todo implement this if its actually needed
 361     //}
 362 } //end rating class definition
 363
 364 /**
 365  * The rating_manager class provides the ability to retrieve sets of ratings from the database
 366  *
 367  * @package   core_rating
 368  * @category  rating
 369  * @copyright 2010 Andrew Davis
 370  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 371  * @since     Moodle 2.0
 372  */
 373 class rating_manager {
 374
 375     /**
 376      * @var array An array of calculated scale options to save us generating them for each request.
 377      */
 378     protected $scales = array();
 379
 380     /**
 381      * Delete one or more ratings. Specify either a rating id, an item id or just the context id.
 382      *
 383      * @global moodle_database $DB
 384      * @param stdClass $options {
 385      *            contextid => int the context in which the ratings exist [required]
 386      *            ratingid => int the id of an individual rating to delete [optional]
 387      *            userid => int delete the ratings submitted by this user. May be used in conjuction with itemid [optional]
 388      *            itemid => int delete all ratings attached to this item [optional]
 389      *            component => string The component to delete ratings from [optional]
 390      *            ratingarea => string The ratingarea to delete ratings from [optional]
 391      * }
 392      */
 393     public function delete_ratings($options) {
 394         global $DB;
 395
 396         if (empty($options->contextid)) {
 397             throw new coding_exception('The context option is a required option when deleting ratings.');
 398         }
 399
 400         $conditions = array('contextid' => $options->contextid);
 401         $possibleconditions = array(
 402             'ratingid'   => 'id',
 403             'userid'     => 'userid',
 404             'itemid'     => 'itemid',
 405             'component'  => 'component',
 406             'ratingarea' => 'ratingarea'
 407         );
 408         foreach ($possibleconditions as $option => $field) {
 409             if (isset($options->{$option})) {
 410                 $conditions[$field] = $options->{$option};
 411             }
 412         }
 413         $DB->delete_records('rating', $conditions);
 414     }
 415
 416     /**
 417      * Returns an array of ratings for a given item (forum post, glossary entry etc). This returns all users ratings for a single item
 418      *
 419      * @param stdClass $options {
 420      *            context => context the context in which the ratings exists [required]
 421      *            component => component using ratings ie mod_forum [required]
 422      *            ratingarea => ratingarea to associate this rating with [required]
 423      *            itemid  =>  int the id of the associated item (forum post, glossary item etc) [required]
 424      *            sort    => string SQL sort by clause [optional]
 425      * }
 426      * @return array an array of ratings
 427      */
 428     public function get_all_ratings_for_item($options) {
 429         global $DB;
 430
 431         if (!isset($options->context)) {
 432             throw new coding_exception('The context option is a required option when getting ratings for an item.');
 433         }
 434         if (!isset($options->itemid)) {
 435             throw new coding_exception('The itemid option is a required option when getting ratings for an item.');
 436         }
 437         if (!isset($options->component)) {
 438             throw new coding_exception('The component option is now a required option when getting ratings for an item.');
 439         }
 440         if (!isset($options->ratingarea)) {
 441             throw new coding_exception('The ratingarea option is now a required option when getting ratings for an item.');
 442         }
 443
 444         $sortclause = '';
 445         if( !empty($options->sort) ) {
 446             $sortclause = "ORDER BY $options->sort";
 447         }
 448
 449         $params = array(
 450             'contextid'  => $options->context->id,
 451             'itemid'     => $options->itemid,
 452             'component'  => $options->component,
 453             'ratingarea' => $options->ratingarea,
 454         );
 455         $userfields = user_picture::fields('u', null, 'userid');
 456         $sql = "SELECT r.id, r.rating, r.itemid, r.userid, r.timemodified, r.component, r.ratingarea, $userfields
 457                   FROM {rating} r
 458              LEFT JOIN {user} u ON r.userid = u.id
 459                  WHERE r.contextid = :contextid AND
 460                        r.itemid  = :itemid AND
 461                        r.component = :component AND
 462                        r.ratingarea = :ratingarea
 463                        {$sortclause}";
 464
 465         return $DB->get_records_sql($sql, $params);
 466     }
 467
 468     /**
 469      * Adds rating objects to an array of items (forum posts, glossary entries etc). Rating objects are available at $item->rating
 470      *
 471      * @param stdClass $options {
 472      *            context          => context the context in which the ratings exists [required]
 473      *            component        => the component name ie mod_forum [required]
 474      *            ratingarea       => the ratingarea we are interested in [required]
 475      *            items            => array an array of items such as forum posts or glossary items. They must have an 'id' member ie $items[0]->id[required]
 476      *            aggregate        => int what aggregation method should be applied. RATING_AGGREGATE_AVERAGE, RATING_AGGREGATE_MAXIMUM etc [required]
 477      *            scaleid          => int the scale from which the user can select a rating [required]
 478      *            userid           => int the id of the current user [optional]
 479      *            returnurl        => string the url to return the user to after submitting a rating. Can be left null for ajax requests [optional]
 480      *            assesstimestart  => int only allow rating of items created after this timestamp [optional]
 481      *            assesstimefinish => int only allow rating of items created before this timestamp [optional]
 482      * @return array the array of items with their ratings attached at $items[0]->rating
 483      */
 484     public function get_ratings($options) {
 485         global $DB, $USER;
 486
 487         if (!isset($options->context)) {
 488             throw new coding_exception('The context option is a required option when getting ratings.');
 489         }
 490
 491         if (!isset($options->component)) {
 492             throw new coding_exception('The component option is a required option when getting ratings.');
 493         }
 494
 495         if (!isset($options->ratingarea)) {
 496             throw new coding_exception('The ratingarea option is a required option when getting ratings.');
 497         }
 498
 499         if (!isset($options->scaleid)) {
 500             throw new coding_exception('The scaleid option is a required option when getting ratings.');
 501         }
 502
 503         if (!isset($options->items)) {
 504             throw new coding_exception('The items option is a required option when getting ratings.');
 505         } else if (empty($options->items)) {
 506             return array();
 507         }
 508
 509         if (!isset($options->aggregate)) {
 510             throw new coding_exception('The aggregate option is a required option when getting ratings.');
 511         } else if ($options->aggregate == RATING_AGGREGATE_NONE) {
 512             // Ratings arn't enabled.
 513             return $options->items;
 514         }
 515         $aggregatestr = $this->get_aggregation_method($options->aggregate);
 516
 517         // Default the userid to the current user if it is not set
 518         if (empty($options->userid)) {
 519             $userid = $USER->id;
 520         } else {
 521             $userid = $options->userid;
 522         }
 523
 524         // Get the item table name, the item id field, and the item user field for the given rating item
 525         // from the related component.
 526         list($type, $name) = core_component::normalize_component($options->component);
 527         $default = array(null, 'id', 'userid');
 528         list($itemtablename, $itemidcol, $itemuseridcol) = plugin_callback($type, $name, 'rating', 'get_item_fields', array($options), $default);
 529
 530         // Create an array of item ids
 531         $itemids = array();
 532         foreach ($options->items as $item) {
 533             $itemids[] = $item->{$itemidcol};
 534         }
 535
 536         // get the items from the database
 537         list($itemidtest, $params) = $DB->get_in_or_equal($itemids, SQL_PARAMS_NAMED);
 538         $params['contextid'] = $options->context->id;
 539         $params['userid']    = $userid;
 540         $params['component']    = $options->component;
 541         $params['ratingarea'] = $options->ratingarea;
 542
 543         $sql = "SELECT r.id, r.itemid, r.userid, r.scaleid, r.rating AS usersrating
 544                   FROM {rating} r
 545                  WHERE r.userid = :userid AND
 546                        r.contextid = :contextid AND
 547                        r.itemid {$itemidtest} AND
 548                        r.component = :component AND
 549                        r.ratingarea = :ratingarea
 550               ORDER BY r.itemid";
 551         $userratings = $DB->get_records_sql($sql, $params);
 552
 553         $sql = "SELECT r.itemid, $aggregatestr(r.rating) AS aggrrating, COUNT(r.rating) AS numratings
 554                   FROM {rating} r
 555                  WHERE r.contextid = :contextid AND
 556                        r.itemid {$itemidtest} AND
 557                        r.component = :component AND
 558                        r.ratingarea = :ratingarea
 559               GROUP BY r.itemid, r.component, r.ratingarea, r.contextid
 560               ORDER BY r.itemid";
 561         $aggregateratings = $DB->get_records_sql($sql, $params);
 562
 563         $ratingoptions = new stdClass;
 564         $ratingoptions->context = $options->context;
 565         $ratingoptions->component = $options->component;
 566         $ratingoptions->ratingarea = $options->ratingarea;
 567         $ratingoptions->settings = $this->generate_rating_settings_object($options);
 568         foreach ($options->items as $item) {
 569             $founduserrating = false;
 570             foreach($userratings as $userrating) {
 571                 //look for an existing rating from this user of this item
 572                 if ($item->{$itemidcol} == $userrating->itemid) {
 573                     // Note: rec->scaleid = the id of scale at the time the rating was submitted
 574                     // may be different from the current scale id
 575                     $ratingoptions->scaleid = $userrating->scaleid;
 576                     $ratingoptions->userid = $userrating->userid;
 577                     $ratingoptions->id = $userrating->id;
 578                     $ratingoptions->rating = min($userrating->usersrating, $ratingoptions->settings->scale->max);
 579
 580                     $founduserrating = true;
 581                     break;
 582                 }
 583             }
 584             if (!$founduserrating) {
 585                 $ratingoptions->scaleid = null;
 586                 $ratingoptions->userid = null;
 587                 $ratingoptions->id = null;
 588                 $ratingoptions->rating =  null;
 589             }
 590
 591             if (array_key_exists($item->{$itemidcol}, $aggregateratings)) {
 592                 $rec = $aggregateratings[$item->{$itemidcol}];
 593                 $ratingoptions->itemid = $item->{$itemidcol};
 594                 $ratingoptions->aggregate = min($rec->aggrrating, $ratingoptions->settings->scale->max);
 595                 $ratingoptions->count = $rec->numratings;
 596             } else {
 597                 $ratingoptions->itemid = $item->{$itemidcol};
 598                 $ratingoptions->aggregate = null;
 599                 $ratingoptions->count = 0;
 600             }
 601
 602             $rating = new rating($ratingoptions);
 603             $rating->itemtimecreated = $this->get_item_time_created($item);
 604             if (!empty($item->{$itemuseridcol})) {
 605                 $rating->itemuserid = $item->{$itemuseridcol};
 606             }
 607             $item->rating = $rating;
 608         }
 609
 610         return $options->items;
 611     }
 612
 613     /**
 614      * Generates a rating settings object based upon the options it is provided.
 615      *
 616      * @param stdClass $options {
 617      *      context           => context the context in which the ratings exists [required]
 618      *      component         => string The component the items belong to [required]
 619      *      ratingarea        => string The ratingarea the items belong to [required]
 620      *      aggregate         => int what aggregation method should be applied. RATING_AGGREGATE_AVERAGE, RATING_AGGREGATE_MAXIMUM etc [required]
 621      *      scaleid           => int the scale from which the user can select a rating [required]
 622      *      returnurl         => string the url to return the user to after submitting a rating. Can be left null for ajax requests [optional]
 623      *      assesstimestart   => int only allow rating of items created after this timestamp [optional]
 624      *      assesstimefinish  => int only allow rating of items created before this timestamp [optional]
 625      *      plugintype        => string plugin type ie 'mod' Used to find the permissions callback [optional]
 626      *      pluginname        => string plugin name ie 'forum' Used to find the permissions callback [optional]
 627      * }
 628      * @return stdClass rating settings object
 629      */
 630     protected function generate_rating_settings_object($options) {
 631
 632         if (!isset($options->context)) {
 633             throw new coding_exception('The context option is a required option when generating a rating settings object.');
 634         }
 635         if (!isset($options->component)) {
 636             throw new coding_exception('The component option is now a required option when generating a rating settings object.');
 637         }
 638         if (!isset($options->ratingarea)) {
 639             throw new coding_exception('The ratingarea option is now a required option when generating a rating settings object.');
 640         }
 641         if (!isset($options->aggregate)) {
 642             throw new coding_exception('The aggregate option is now a required option when generating a rating settings object.');
 643         }
 644         if (!isset($options->scaleid)) {
 645             throw new coding_exception('The scaleid option is now a required option when generating a rating settings object.');
 646         }
 647
 648         // settings that are common to all ratings objects in this context
 649         $settings = new stdClass;
 650         $settings->scale             = $this->generate_rating_scale_object($options->scaleid); // the scale to use now
 651         $settings->aggregationmethod = $options->aggregate;
 652         $settings->assesstimestart   = null;
 653         $settings->assesstimefinish  = null;
 654
 655         // Collect options into the settings object
 656         if (!empty($options->assesstimestart)) {
 657             $settings->assesstimestart = $options->assesstimestart;
 658         }
 659         if (!empty($options->assesstimefinish)) {
 660             $settings->assesstimefinish = $options->assesstimefinish;
 661         }
 662         if (!empty($options->returnurl)) {
 663             $settings->returnurl = $options->returnurl;
 664         }
 665
 666         // check site capabilities
 667         $settings->permissions = new stdClass;
 668         $settings->permissions->view    = has_capability('moodle/rating:view', $options->context); // can view the aggregate of ratings of their own items
 669         $settings->permissions->viewany = has_capability('moodle/rating:viewany', $options->context); // can view the aggregate of ratings of other people's items
 670         $settings->permissions->viewall = has_capability('moodle/rating:viewall', $options->context); // can view individual ratings
 671         $settings->permissions->rate    = has_capability('moodle/rating:rate', $options->context); // can submit ratings
 672
 673         // check module capabilities (mostly for backwards compatability with old modules that previously implemented their own ratings)
 674         $pluginpermissionsarray = $this->get_plugin_permissions_array($options->context->id, $options->component, $options->ratingarea);
 675         $settings->pluginpermissions = new stdClass;
 676         $settings->pluginpermissions->view    = $pluginpermissionsarray['view'];
 677         $settings->pluginpermissions->viewany = $pluginpermissionsarray['viewany'];
 678         $settings->pluginpermissions->viewall = $pluginpermissionsarray['viewall'];
 679         $settings->pluginpermissions->rate    = $pluginpermissionsarray['rate'];
 680
 681         return $settings;
 682     }
 683
 684     /**
 685      * Generates a scale object that can be returned
 686      *
 687      * @global moodle_database $DB moodle database object
 688      * @param int $scaleid scale-type identifier
 689      * @return stdClass scale for ratings
 690      */
 691     protected function generate_rating_scale_object($scaleid) {
 692         global $DB;
 693         if (!array_key_exists('s'.$scaleid, $this->scales)) {
 694             $scale = new stdClass;
 695             $scale->id = $scaleid;
 696             $scale->name = null;
 697             $scale->courseid = null;
 698             $scale->scaleitems = array();
 699             $scale->isnumeric = true;
 700             $scale->max = $scaleid;
 701
 702             if ($scaleid < 0) {
 703                 // It is a proper scale (not numeric)
 704                 $scalerecord = $DB->get_record('scale', array('id' => abs($scaleid)));
 705                 if ($scalerecord) {
 706                     // We need to generate an array with string keys starting at 1
 707                     $scalearray = explode(',', $scalerecord->scale);
 708                     $c = count($scalearray);
 709                     for ($i = 0; $i < $c; $i++) {
 710                         // treat index as a string to allow sorting without changing the value
 711                         $scale->scaleitems[(string)($i + 1)] = $scalearray[$i];
 712                     }
 713                     krsort($scale->scaleitems); // have the highest grade scale item appear first
 714                     $scale->isnumeric = false;
 715                     $scale->name = $scalerecord->name;
 716                     $scale->courseid = $scalerecord->courseid;
 717                     $scale->max = count($scale->scaleitems);
 718                 }
 719             } else {
 720                 //generate an array of values for numeric scales
 721                 for($i = 0; $i <= (int)$scaleid; $i++) {
 722                     $scale->scaleitems[(string)$i] = $i;
 723                 }
 724             }
 725             $this->scales['s'.$scaleid] = $scale;
 726         }
 727         return $this->scales['s'.$scaleid];
 728     }
 729
 730     /**
 731      * Gets the time the given item was created
 732      *
 733      * TODO: MDL-31511 - Find a better solution for this, its not ideal to test for fields really we should be
 734      * asking the component the item belongs to what field to look for or even the value we
 735      * are looking for.
 736      *
 737      * @param stdClass $item
 738      * @return int|null return null if the created time is unavailable, otherwise return a timestamp
 739      */
 740     protected function get_item_time_created($item) {
 741         if( !empty($item->created) ) {
 742             return $item->created;//the forum_posts table has created instead of timecreated
 743         }
 744         else if(!empty($item->timecreated)) {
 745             return $item->timecreated;
 746         }
 747         else {
 748             return null;
 749         }
 750     }
 751
 752     /**
 753      * Returns an array of grades calculated by aggregating item ratings.
 754      *
 755      * @param stdClass $options {
 756      *            userid => int the id of the user whose items have been rated. NOT the user who submitted the ratings. 0 to update all. [required]
 757      *            aggregationmethod => int the aggregation method to apply when calculating grades ie RATING_AGGREGATE_AVERAGE [required]
 758      *            scaleid => int the scale from which the user can select a rating. Used for bounds checking. [required]
 759      *            itemtable => int the table containing the items [required]
 760      *            itemtableusercolum => int the column of the user table containing the item owner's user id [required]
 761      *            component => The component for the ratings [required]
 762      *            ratingarea => The ratingarea for the ratings [required]
 763      *            contextid => int the context in which the rated items exist [optional]
 764      *            modulename => string the name of the module [optional]
 765      *            moduleid => int the id of the module instance [optional]
 766      * }
 767      * @return array the array of the user's grades
 768      */
 769     public function get_user_grades($options) {
 770         global $DB;
 771
 772         $contextid = null;
 773
 774         if (!isset($options->component)) {
 775             throw new coding_exception('The component option is now a required option when getting user grades from ratings.');
 776         }
 777         if (!isset($options->ratingarea)) {
 778             throw new coding_exception('The ratingarea option is now a required option when getting user grades from ratings.');
 779         }
 780
 781         //if the calling code doesn't supply a context id we'll have to figure it out
 782         if( !empty($options->contextid) ) {
 783             $contextid = $options->contextid;
 784         }
 785         else if( !empty($options->cmid) ) {
 786             //not implemented as not currently used although cmid is potentially available (the forum supplies it)
 787             //Is there a convenient way to get a context id from a cm id?
 788             //$cmidnumber = $options->cmidnumber;
 789         }
 790         else if ( !empty($options->modulename) && !empty($options->moduleid) ) {
 791             $modulename = $options->modulename;
 792             $moduleid   = intval($options->moduleid);
 793
 794             // Going direct to the db for the context id seems wrong.
 795             $ctxselect = ', ' . context_helper::get_preload_record_columns_sql('ctx');
 796             $ctxjoin = "LEFT JOIN {context} ctx ON (ctx.instanceid = cm.id AND ctx.contextlevel = :contextlevel)";
 797             $sql = "SELECT cm.* $ctxselect
 798                       FROM {course_modules} cm
 799                  LEFT JOIN {modules} mo ON mo.id = cm.module
 800                  LEFT JOIN {{$modulename}} m ON m.id = cm.instance $ctxjoin
 801                      WHERE mo.name=:modulename AND
 802                            m.id=:moduleid";
 803             $params = array('modulename' => $modulename, 'moduleid' => $moduleid, 'contextlevel' => CONTEXT_MODULE);
 804             $contextrecord = $DB->get_record_sql($sql, $params, '*', MUST_EXIST);
 805             $contextid = $contextrecord->ctxid;
 806         }
 807
 808         $params = array();
 809         $params['contextid']  = $contextid;
 810         $params['component']  = $options->component;
 811         $params['ratingarea'] = $options->ratingarea;
 812         $itemtable            = $options->itemtable;
 813         $itemtableusercolumn  = $options->itemtableusercolumn;
 814         $scaleid              = $options->scaleid;
 815         $aggregationstring    = $this->get_aggregation_method($options->aggregationmethod);
 816
 817         //if userid is not 0 we only want the grade for a single user
 818         $singleuserwhere = '';
 819         if ($options->userid != 0) {
 820             $params['userid1'] = intval($options->userid);
 821             $singleuserwhere = "AND i.{$itemtableusercolumn} = :userid1";
 822         }
 823
 824         //MDL-24648 The where line used to be "WHERE (r.contextid is null or r.contextid=:contextid)"
 825         //r.contextid will be null for users who haven't been rated yet
 826         //no longer including users who haven't been rated to reduce memory requirements
 827         $sql = "SELECT u.id as id, u.id AS userid, $aggregationstring(r.rating) AS rawgrade
 828                   FROM {user} u
 829              LEFT JOIN {{$itemtable}} i ON u.id=i.{$itemtableusercolumn}
 830              LEFT JOIN {rating} r ON r.itemid=i.id
 831                  WHERE r.contextid = :contextid AND
 832                        r.component = :component AND
 833                        r.ratingarea = :ratingarea
 834                        $singleuserwhere
 835               GROUP BY u.id";
 836         $results = $DB->get_records_sql($sql, $params);
 837
 838         if ($results) {
 839
 840             $scale = null;
 841             $max = 0;
 842             if ($options->scaleid >= 0) {
 843                 //numeric
 844                 $max = $options->scaleid;
 845             } else {
 846                 //custom scales
 847                 $scale = $DB->get_record('scale', array('id' => -$options->scaleid));
 848                 if ($scale) {
 849                     $scale = explode(',', $scale->scale);
 850                     $max = count($scale);
 851                 } else {
 852                     debugging('rating_manager::get_user_grades() received a scale ID that doesnt exist');
 853                 }
 854             }
 855
 856             // it could throw off the grading if count and sum returned a rawgrade higher than scale
 857             // so to prevent it we review the results and ensure that rawgrade does not exceed the scale, if it does we set rawgrade = scale (i.e. full credit)
 858             foreach ($results as $rid=>$result) {
 859                 if ($options->scaleid >= 0) {
 860                     //numeric
 861                     if ($result->rawgrade > $options->scaleid) {
 862                         $results[$rid]->rawgrade = $options->scaleid;
 863                     }
 864                 } else {
 865                     //scales
 866                     if (!empty($scale) && $result->rawgrade > $max) {
 867                         $results[$rid]->rawgrade = $max;
 868                     }
 869                 }
 870             }
 871         }
 872
 873         return $results;
 874     }
 875
 876     /**
 877      * Returns array of aggregate types. Used by ratings.
 878      *
 879      * @return array aggregate types
 880      */
 881     public function get_aggregate_types() {
 882         return array (RATING_AGGREGATE_NONE     => get_string('aggregatenone', 'rating'),
 883                       RATING_AGGREGATE_AVERAGE  => get_string('aggregateavg', 'rating'),
 884                       RATING_AGGREGATE_COUNT    => get_string('aggregatecount', 'rating'),
 885                       RATING_AGGREGATE_MAXIMUM  => get_string('aggregatemax', 'rating'),
 886                       RATING_AGGREGATE_MINIMUM  => get_string('aggregatemin', 'rating'),
 887                       RATING_AGGREGATE_SUM      => get_string('aggregatesum', 'rating'));
 888     }
 889
 890     /**
 891      * Converts an aggregation method constant into something that can be included in SQL
 892      *
 893      * @param int $aggregate An aggregation constant. For example, RATING_AGGREGATE_AVERAGE.
 894      * @return string an SQL aggregation method
 895      */
 896     public function get_aggregation_method($aggregate) {
 897         $aggregatestr = null;
 898         switch($aggregate){
 899             case RATING_AGGREGATE_AVERAGE:
 900                 $aggregatestr = 'AVG';
 901                 break;
 902             case RATING_AGGREGATE_COUNT:
 903                 $aggregatestr = 'COUNT';
 904                 break;
 905             case RATING_AGGREGATE_MAXIMUM:
 906                 $aggregatestr = 'MAX';
 907                 break;
 908             case RATING_AGGREGATE_MINIMUM:
 909                 $aggregatestr = 'MIN';
 910                 break;
 911             case RATING_AGGREGATE_SUM:
 912                 $aggregatestr = 'SUM';
 913                 break;
 914             default:
 915                 $aggregatestr = 'AVG'; // Default to this to avoid real breakage - MDL-22270
 916                 debugging('Incorrect call to get_aggregation_method(), was called with incorrect aggregate method ' . $aggregate, DEBUG_DEVELOPER);
 917         }
 918         return $aggregatestr;
 919     }
 920
 921     /**
 922      * Looks for a callback like forum_rating_permissions() to retrieve permissions from the plugin whose items are being rated
 923      *
 924      * @param int $contextid The current context id
 925      * @param string $component the name of the component that is using ratings ie 'mod_forum'
 926      * @param string $ratingarea The area the rating is associated with
 927      * @return array rating related permissions
 928      */
 929     public function get_plugin_permissions_array($contextid, $component, $ratingarea) {
 930         $pluginpermissionsarray = null;
 931         $defaultpluginpermissions = array('rate'=>false,'view'=>false,'viewany'=>false,'viewall'=>false);//deny by default
 932         if (!empty($component)) {
 933             list($type, $name) = core_component::normalize_component($component);
 934             $pluginpermissionsarray = plugin_callback($type, $name, 'rating', 'permissions', array($contextid, $component, $ratingarea), $defaultpluginpermissions);
 935         } else {
 936             $pluginpermissionsarray = $defaultpluginpermissions;
 937         }
 938         return $pluginpermissionsarray;
 939     }
 940
 941     /**
 942      * Validates a submitted rating
 943      *
 944      * @param array $params submitted data
 945      *            context => object the context in which the rated items exists [required]
 946      *            component => The component the rating belongs to [required]
 947      *            ratingarea => The ratingarea the rating is associated with [required]
 948      *            itemid => int the ID of the object being rated [required]
 949      *            scaleid => int the scale from which the user can select a rating. Used for bounds checking. [required]
 950      *            rating => int the submitted rating
 951      *            rateduserid => int the id of the user whose items have been rated. NOT the user who submitted the ratings. 0 to update all. [required]
 952      *            aggregation => int the aggregation method to apply when calculating grades ie RATING_AGGREGATE_AVERAGE [optional]
 953      * @return boolean true if the rating is valid. False if callback wasnt found and will throw rating_exception if rating is invalid
 954      */
 955     public function check_rating_is_valid($params) {
 956
 957         if (!isset($params['context'])) {
 958             throw new coding_exception('The context option is a required option when checking rating validity.');
 959         }
 960         if (!isset($params['component'])) {
 961             throw new coding_exception('The component option is now a required option when checking rating validity');
 962         }
 963         if (!isset($params['ratingarea'])) {
 964             throw new coding_exception('The ratingarea option is now a required option when checking rating validity');
 965         }
 966         if (!isset($params['itemid'])) {
 967             throw new coding_exception('The itemid option is now a required option when checking rating validity');
 968         }
 969         if (!isset($params['scaleid'])) {
 970             throw new coding_exception('The scaleid option is now a required option when checking rating validity');
 971         }
 972         if (!isset($params['rateduserid'])) {
 973             throw new coding_exception('The rateduserid option is now a required option when checking rating validity');
 974         }
 975
 976         list($plugintype, $pluginname) = core_component::normalize_component($params['component']);
 977
 978         //this looks for a function like forum_rating_validate() in mod_forum lib.php
 979         //wrapping the params array in another array as call_user_func_array() expands arrays into multiple arguments
 980         $isvalid = plugin_callback($plugintype, $pluginname, 'rating', 'validate', array($params), null);
 981
 982         //if null then the callback doesn't exist
 983         if ($isvalid === null) {
 984             $isvalid = false;
 985             debugging('rating validation callback not found for component '.  clean_param($component, PARAM_ALPHANUMEXT));
 986         }
 987         return $isvalid;
 988     }
 989
 990     /**
 991      * Initialises JavaScript to enable AJAX ratings on the provided page
 992      *
 993      * @param moodle_page $page
 994      * @return true always returns true
 995      */
 996     public function initialise_rating_javascript(moodle_page $page) {
 997         global $CFG;
 998
 999         //only needs to be initialized once
1000         static $done = false;
1001         if ($done) {
1002             return true;
1003         }
1004
1005         if (!empty($CFG->enableajax)) {
1006             $page->requires->js_init_call('M.core_rating.init');
1007         }
1008         $done = true;
1009
1010         return true;
1011     }
1012
1013     /**
1014      * Returns a string that describes the aggregation method that was provided.
1015      *
1016      * @param string $aggregationmethod
1017      * @return string describes the aggregation method that was provided
1018      */
1019     public function get_aggregate_label($aggregationmethod) {
1020         $aggregatelabel = '';
1021         switch ($aggregationmethod) {
1022             case RATING_AGGREGATE_AVERAGE :
1023                 $aggregatelabel .= get_string("aggregateavg", "rating");
1024                 break;
1025             case RATING_AGGREGATE_COUNT :
1026                 $aggregatelabel .= get_string("aggregatecount", "rating");
1027                 break;
1028             case RATING_AGGREGATE_MAXIMUM :
1029                 $aggregatelabel .= get_string("aggregatemax", "rating");
1030                 break;
1031             case RATING_AGGREGATE_MINIMUM :
1032                 $aggregatelabel .= get_string("aggregatemin", "rating");
1033                 break;
1034             case RATING_AGGREGATE_SUM :
1035                 $aggregatelabel .= get_string("aggregatesum", "rating");
1036                 break;
1037         }
1038         $aggregatelabel .= get_string('labelsep', 'langconfig');
1039         return $aggregatelabel;
1040     }
1041
1042 }//end rating_manager class definition
1043
1044 /**
1045  * The rating_exception class provides the ability to generate exceptions that can be easily identified as coming from the ratings system
1046  *
1047  * @package   core_rating
1048  * @category  rating
1049  * @copyright 2010 Andrew Davis
1050  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
1051  * @since     Moodle 2.0
1052  */
1053 class rating_exception extends moodle_exception {
1054     /**
1055      * @var string The message to accompany the thrown exception
1056      */
1057     public $message;
1058     /**
1059      * Generate exceptions that can be easily identified as coming from the ratings system
1060      *
1061      * @param string $errorcode the error code to generate
1062      */
1063     function __construct($errorcode) {
1064         $this->errorcode = $errorcode;
1065         $this->message = get_string($errorcode, 'error');
1066     }
1067 }