Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 4.2.x will end 22 April 2024 (12 months).
  • Bug fixes for security issues in 4.2.x will end 7 October 2024 (18 months).
  • PHP version: minimum PHP 8.0.0 Note: minimum PHP version has increased since Moodle 4.1. PHP 8.1.x is supported too.
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Rating external functions utility class.
 *
 * @package    core_rating
 * @copyright  2017 Juan Leyva
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */

namespace core_rating\external;

defined('MOODLE_INTERNAL') || die();

require_once($CFG->dirroot . '/rating/lib.php');
< require_once($CFG->libdir . '/externallib.php');
< use external_multiple_structure; < use external_single_structure; < use external_value;
> use core_external\external_multiple_structure; > use core_external\external_single_structure; > use core_external\external_value;
use rating_manager; use stdClass; /** * Rating external functions utility class. * * @package core_rating * @copyright 2017 Juan Leyva * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later * @since Moodle 3.4 */ class util { /** * Returns the ratings definition for external functions. */ public static function external_ratings_structure() { return new external_single_structure ( [ 'contextid' => new external_value(PARAM_INT, 'Context id.'), 'component' => new external_value(PARAM_COMPONENT, 'Context name.'), 'ratingarea' => new external_value(PARAM_AREA, 'Rating area name.'), 'canviewall' => new external_value(PARAM_BOOL, 'Whether the user can view all the individual ratings.', VALUE_OPTIONAL), 'canviewany' => new external_value(PARAM_BOOL, 'Whether the user can view aggregate of ratings of others.', VALUE_OPTIONAL), 'scales' => new external_multiple_structure( new external_single_structure ( [ 'id' => new external_value(PARAM_INT, 'Scale id.'), 'courseid' => new external_value(PARAM_INT, 'Course id.', VALUE_OPTIONAL), 'name' => new external_value(PARAM_TEXT, 'Scale name (when a real scale is used).', VALUE_OPTIONAL), 'max' => new external_value(PARAM_INT, 'Max value for the scale.'), 'isnumeric' => new external_value(PARAM_BOOL, 'Whether is a numeric scale.'), 'items' => new external_multiple_structure( new external_single_structure ( [ 'value' => new external_value(PARAM_INT, 'Scale value/option id.'), 'name' => new external_value(PARAM_NOTAGS, 'Scale name.'), ] ), 'Scale items. Only returned for not numerical scales.', VALUE_OPTIONAL ) ], 'Scale information' ), 'Different scales used information', VALUE_OPTIONAL ), 'ratings' => new external_multiple_structure( new external_single_structure ( [ 'itemid' => new external_value(PARAM_INT, 'Item id.'), 'scaleid' => new external_value(PARAM_INT, 'Scale id.', VALUE_OPTIONAL), 'userid' => new external_value(PARAM_INT, 'User who rated id.', VALUE_OPTIONAL), 'aggregate' => new external_value(PARAM_FLOAT, 'Aggregated ratings grade.', VALUE_OPTIONAL), 'aggregatestr' => new external_value(PARAM_NOTAGS, 'Aggregated ratings as string.', VALUE_OPTIONAL), 'aggregatelabel' => new external_value(PARAM_NOTAGS, 'The aggregation label.', VALUE_OPTIONAL), 'count' => new external_value(PARAM_INT, 'Ratings count (used when aggregating).', VALUE_OPTIONAL), 'rating' => new external_value(PARAM_INT, 'The rating the user gave.', VALUE_OPTIONAL), 'canrate' => new external_value(PARAM_BOOL, 'Whether the user can rate the item.', VALUE_OPTIONAL), 'canviewaggregate' => new external_value(PARAM_BOOL, 'Whether the user can view the aggregated grade.', VALUE_OPTIONAL), ] ), 'The ratings', VALUE_OPTIONAL ), ], 'Rating information', VALUE_OPTIONAL ); } /** * Returns rating information inside a data structure like the one defined by external_ratings_structure. * * @param stdClass $mod course module object * @param stdClass $context context object * @param str $component component name * @param str $ratingarea rating area * @param array $items items to add ratings * @return array ratings ready to be returned by external functions. */ public static function get_rating_info($mod, $context, $component, $ratingarea, $items) { global $USER; $ratinginfo = [ 'contextid' => $context->id, 'component' => $component, 'ratingarea' => $ratingarea, 'canviewall' => null, 'canviewany' => null, 'scales' => [], 'ratings' => [], ]; if ($mod->assessed != RATING_AGGREGATE_NONE) { $ratingoptions = new stdClass; $ratingoptions->context = $context; $ratingoptions->component = $component; $ratingoptions->ratingarea = $ratingarea; $ratingoptions->items = $items; $ratingoptions->aggregate = $mod->assessed; $ratingoptions->scaleid = $mod->scale; $ratingoptions->userid = $USER->id; $ratingoptions->assesstimestart = $mod->assesstimestart; $ratingoptions->assesstimefinish = $mod->assesstimefinish; $rm = new rating_manager(); $allitems = $rm->get_ratings($ratingoptions); foreach ($allitems as $item) { if (empty($item->rating)) { continue; } $rating = [ 'itemid' => $item->rating->itemid, 'scaleid' => $item->rating->scaleid, 'userid' => $item->rating->userid, 'rating' => $item->rating->rating, 'canrate' => $item->rating->user_can_rate(), 'canviewaggregate' => $item->rating->user_can_view_aggregate(), ]; // Fill the capabilities fields the first time (the rest are the same values because they are not item dependent). if ($ratinginfo['canviewall'] === null) { $ratinginfo['canviewall'] = $item->rating->settings->permissions->viewall && $item->rating->settings->pluginpermissions->viewall; $ratinginfo['canviewany'] = $item->rating->settings->permissions->viewany && $item->rating->settings->pluginpermissions->viewany; } // Return only the information the user can see. if ($rating['canviewaggregate']) { $rating['aggregate'] = $item->rating->aggregate; $rating['aggregatestr'] = $item->rating->get_aggregate_string(); $rating['aggregatelabel'] = $rm->get_aggregate_label($item->rating->settings->aggregationmethod); $rating['count'] = $item->rating->count; } // If the user can rate, return the scale information only one time. if ($rating['canrate'] && !empty($item->rating->settings->scale->id) && !isset($ratinginfo['scales'][$item->rating->settings->scale->id])) { $scale = $item->rating->settings->scale; // Return only non numeric scales (to avoid return lots of data just including items from 0 to $scale->max). if (!$scale->isnumeric) { $scaleitems = []; foreach ($scale->scaleitems as $value => $name) { $scaleitems[] = [ 'name' => $name, 'value' => $value, ]; } $scale->items = $scaleitems; } $ratinginfo['scales'][$item->rating->settings->scale->id] = (array) $scale; } $ratinginfo['ratings'][] = $rating; } } return $ratinginfo; } }