Proyectos de Subversion Moodle

<?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');

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;

    }

}