/rating/classes/external/util.php

<?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 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;
    }
}