"Fossies" - the Fresh Open Source Software Archive

Member "moodle/rating/classes/external.php" (6 Sep 2019, 12228 Bytes) of package /linux/www/moodle-3.6.6.tgz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) PHP source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "external.php" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 3.6.5_vs_3.6.6.

    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->libdir/externallib.php");
   30 require_once("$CFG->dirroot/rating/lib.php");
   31 
   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 {
   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(
   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     }
   62 
   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, $PAGE;
   79 
   80         $warnings = array();
   81 
   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         );
   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);
   97 
   98         // Minimal capability required.
   99         $callbackparams = array('contextid' => $context->id,
  100                         'component' => $component,
  101                         'ratingarea' => $ratingarea,
  102                         'itemid' => $itemid,
  103                         'scaleid' => $scaleid);
  104         if (!has_capability('moodle/rating:view', $context) ||
  105                 !component_callback($component, 'rating_can_see_item_ratings', array($callbackparams), true)) {
  106             throw new moodle_exception('noviewrate', 'rating');
  107         }
  108 
  109         list($context, $course, $cm) = get_context_info_array($context->id);
  110 
  111         // Can we see all ratings?
  112         $canviewallratings = has_capability('moodle/rating:viewall', $context);
  113 
  114         // Create the Sql sort order string.
  115         switch ($params['sort']) {
  116             case 'firstname':
  117                 $sqlsort = "u.firstname ASC";
  118                 break;
  119             case 'rating':
  120                 $sqlsort = "r.rating ASC";
  121                 break;
  122             default:
  123                 $sqlsort = "r.timemodified ASC";
  124         }
  125 
  126         $ratingoptions = new stdClass;
  127         $ratingoptions->context = $context;
  128         $ratingoptions->component = $params['component'];
  129         $ratingoptions->ratingarea = $params['ratingarea'];
  130         $ratingoptions->itemid = $params['itemid'];
  131         $ratingoptions->sort = $sqlsort;
  132 
  133         $rm = new rating_manager();
  134         $ratings = $rm->get_all_ratings_for_item($ratingoptions);
  135         $scalemenu = make_grades_menu($params['scaleid']);
  136 
  137         // If the scale was changed after ratings were submitted some ratings may have a value above the current maximum.
  138         // We can't just do count($scalemenu) - 1 as custom scales start at index 1, not 0.
  139         $maxrating = max(array_keys($scalemenu));
  140 
  141         $results = array();
  142 
  143         foreach ($ratings as $rating) {
  144             if ($canviewallratings || $USER->id == $rating->userid) {
  145                 if ($rating->rating > $maxrating) {
  146                     $rating->rating = $maxrating;
  147                 }
  148 
  149                 $result = array();
  150                 $result['id'] = $rating->id;
  151                 $result['userid'] = $rating->userid;
  152                 $result['userfullname'] = fullname($rating);
  153                 $result['rating'] = $scalemenu[$rating->rating];
  154                 $result['timemodified'] = $rating->timemodified;
  155 
  156                 // The rating object has all the required fields for generating the picture url.
  157                 // Undo the aliasing of the user id column from user_picture::fields().
  158                 $rating->id = $rating->userid;
  159                 $userpicture = new user_picture($rating);
  160                 $userpicture->size = 1; // Size f1.
  161                 $result['userpictureurl'] = $userpicture->get_url($PAGE)->out(false);
  162 
  163                 $results[] = $result;
  164             }
  165         }
  166 
  167         return array(
  168             'ratings' => $results,
  169             'warnings' => $warnings
  170         );
  171     }
  172 
  173     /**
  174      * Returns description of get_item_ratings result values.
  175      *
  176      * @return external_single_structure
  177      * @since Moodle 2.9
  178      */
  179     public static function get_item_ratings_returns() {
  180 
  181         return new external_single_structure(
  182             array(
  183                 'ratings'    => new external_multiple_structure(
  184                     new external_single_structure(
  185                         array(
  186                             'id'              => new external_value(PARAM_INT,  'rating id'),
  187                             'userid'          => new external_value(PARAM_INT,  'user id'),
  188                             'userpictureurl'  => new external_value(PARAM_URL,  'URL user picture'),
  189                             'userfullname'    => new external_value(PARAM_NOTAGS, 'user fullname'),
  190                             'rating'          => new external_value(PARAM_NOTAGS, 'rating on scale'),
  191                             'timemodified'    => new external_value(PARAM_INT,  'time modified (timestamp)')
  192                         ), 'Rating'
  193                     ), 'list of ratings'
  194                 ),
  195                 'warnings'  => new external_warnings(),
  196             )
  197         );
  198     }
  199 
  200     /**
  201      * Returns description of add_rating parameters.
  202      *
  203      * @return external_function_parameters
  204      * @since Moodle 3.2
  205      */
  206     public static function add_rating_parameters() {
  207         return new external_function_parameters (
  208             array(
  209                 'contextlevel'  => new external_value(PARAM_ALPHA, 'context level: course, module, user, etc...'),
  210                 'instanceid'    => new external_value(PARAM_INT, 'the instance id of item associated with the context level'),
  211                 'component'     => new external_value(PARAM_COMPONENT, 'component'),
  212                 'ratingarea'    => new external_value(PARAM_AREA, 'rating area'),
  213                 'itemid'        => new external_value(PARAM_INT, 'associated id'),
  214                 'scaleid'       => new external_value(PARAM_INT, 'scale id'),
  215                 'rating'        => new external_value(PARAM_INT, 'user rating'),
  216                 'rateduserid'   => new external_value(PARAM_INT, 'rated user id'),
  217                 'aggregation'   => new external_value(PARAM_INT, 'agreggation method', VALUE_DEFAULT, RATING_AGGREGATE_NONE)
  218             )
  219         );
  220     }
  221 
  222     /**
  223      * Adds a rating to an item
  224      *
  225      * @param string $contextlevel course, module, user...
  226      * @param int $instanceid the instance if for the context element
  227      * @param string $component the name of the component
  228      * @param string $ratingarea rating area
  229      * @param int $itemid the item id
  230      * @param int $scaleid the scale id
  231      * @param int $rating the user rating
  232      * @param int $rateduserid the rated user id
  233      * @param int $aggregation the aggregation method
  234      * @return array result and possible warnings
  235      * @throws moodle_exception
  236      * @since Moodle 3.2
  237      */
  238     public static function add_rating($contextlevel, $instanceid, $component, $ratingarea, $itemid, $scaleid, $rating, $rateduserid,
  239                                         $aggregation = RATING_AGGREGATE_NONE) {
  240         $warnings = array();
  241 
  242         $params = array(
  243             'contextlevel' => $contextlevel,
  244             'instanceid'   => $instanceid,
  245             'component'    => $component,
  246             'ratingarea'   => $ratingarea,
  247             'itemid'       => $itemid,
  248             'scaleid'      => $scaleid,
  249             'rating'       => $rating,
  250             'rateduserid'  => $rateduserid,
  251             'aggregation'  => $aggregation,
  252         );
  253 
  254         // Validate and normalize parameters.
  255         $params = self::validate_parameters(self::add_rating_parameters(), $params);
  256 
  257         $context = self::get_context_from_params($params);
  258         self::validate_context($context);
  259         $cm = get_coursemodule_from_id(false, $context->instanceid, 0, false, MUST_EXIST);
  260 
  261         require_capability('moodle/rating:rate', $context);
  262 
  263         $rm = new rating_manager();
  264         $result = $rm->add_rating($cm, $context, $params['component'], $params['ratingarea'], $params['itemid'], $params['scaleid'],
  265                                     $params['rating'], $params['rateduserid'], $params['aggregation']);
  266 
  267         if (!empty($result->error)) {
  268             throw new moodle_exception($result->error, 'rating');
  269         }
  270 
  271         $returndata = array(
  272             'success' => $result->success,
  273             'warnings' => $warnings
  274         );
  275 
  276         if (isset($result->aggregate)) {
  277             $returndata['aggregate'] = $result->aggregate;
  278             $returndata['count'] = $result->count;
  279             $returndata['itemid'] = $result->itemid;
  280         }
  281 
  282         return $returndata;
  283     }
  284 
  285     /**
  286      * Returns description of add_rating result values.
  287      *
  288      * @return external_single_structure
  289      * @since Moodle 3.2
  290      */
  291     public static function add_rating_returns() {
  292 
  293         return new external_single_structure(
  294             array(
  295                 'success' => new external_value(PARAM_BOOL, 'Whether the rate was successfully created'),
  296                 'aggregate' => new external_value(PARAM_TEXT, 'New aggregate', VALUE_OPTIONAL),
  297                 'count' => new external_value(PARAM_INT, 'Ratings count', VALUE_OPTIONAL),
  298                 'itemid' => new external_value(PARAM_INT, 'Rating item id', VALUE_OPTIONAL),
  299                 'warnings'  => new external_warnings(),
  300             )
  301         );
  302     }
  303 }