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 * Label external API
19 *
20 * @package    mod_label
21 * @category   external
22 * @copyright  2017 Juan Leyva <juan@moodle.com>
23 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 * @since      Moodle 3.3
25 */
26
27defined('MOODLE_INTERNAL') || die;
28
29require_once("$CFG->libdir/externallib.php");
30
31/**
32 * Label external functions
33 *
34 * @package    mod_label
35 * @category   external
36 * @copyright  2017 Juan Leyva <juan@moodle.com>
37 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38 * @since      Moodle 3.3
39 */
40class mod_label_external extends external_api {
41
42    /**
43     * Describes the parameters for get_labels_by_courses.
44     *
45     * @return external_function_parameters
46     * @since Moodle 3.3
47     */
48    public static function get_labels_by_courses_parameters() {
49        return new external_function_parameters (
50            array(
51                'courseids' => new external_multiple_structure(
52                    new external_value(PARAM_INT, 'Course id'), 'Array of course ids', VALUE_DEFAULT, array()
53                ),
54            )
55        );
56    }
57
58    /**
59     * Returns a list of labels in a provided list of courses.
60     * If no list is provided all labels that the user can view will be returned.
61     *
62     * @param array $courseids course ids
63     * @return array of warnings and labels
64     * @since Moodle 3.3
65     */
66    public static function get_labels_by_courses($courseids = array()) {
67
68        $warnings = array();
69        $returnedlabels = array();
70
71        $params = array(
72            'courseids' => $courseids,
73        );
74        $params = self::validate_parameters(self::get_labels_by_courses_parameters(), $params);
75
76        $mycourses = array();
77        if (empty($params['courseids'])) {
78            $mycourses = enrol_get_my_courses();
79            $params['courseids'] = array_keys($mycourses);
80        }
81
82        // Ensure there are courseids to loop through.
83        if (!empty($params['courseids'])) {
84
85            list($courses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses);
86
87            // Get the labels in this course, this function checks users visibility permissions.
88            // We can avoid then additional validate_context calls.
89            $labels = get_all_instances_in_courses("label", $courses);
90            foreach ($labels as $label) {
91                $context = context_module::instance($label->coursemodule);
92                // Entry to return.
93                $label->name = external_format_string($label->name, $context->id);
94                $options = array('noclean' => true);
95                list($label->intro, $label->introformat) =
96                    external_format_text($label->intro, $label->introformat, $context->id, 'mod_label', 'intro', null, $options);
97                $label->introfiles = external_util::get_area_files($context->id, 'mod_label', 'intro', false, false);
98
99                $returnedlabels[] = $label;
100            }
101        }
102
103        $result = array(
104            'labels' => $returnedlabels,
105            'warnings' => $warnings
106        );
107        return $result;
108    }
109
110    /**
111     * Describes the get_labels_by_courses return value.
112     *
113     * @return external_single_structure
114     * @since Moodle 3.3
115     */
116    public static function get_labels_by_courses_returns() {
117        return new external_single_structure(
118            array(
119                'labels' => new external_multiple_structure(
120                    new external_single_structure(
121                        array(
122                            'id' => new external_value(PARAM_INT, 'Module id'),
123                            'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
124                            'course' => new external_value(PARAM_INT, 'Course id'),
125                            'name' => new external_value(PARAM_RAW, 'Label name'),
126                            'intro' => new external_value(PARAM_RAW, 'Label contents'),
127                            'introformat' => new external_format_value('intro', 'Content format'),
128                            'introfiles' => new external_files('Files in the introduction text'),
129                            'timemodified' => new external_value(PARAM_INT, 'Last time the label was modified'),
130                            'section' => new external_value(PARAM_INT, 'Course section id'),
131                            'visible' => new external_value(PARAM_INT, 'Module visibility'),
132                            'groupmode' => new external_value(PARAM_INT, 'Group mode'),
133                            'groupingid' => new external_value(PARAM_INT, 'Grouping id'),
134                        )
135                    )
136                ),
137                'warnings' => new external_warnings(),
138            )
139        );
140    }
141}
142