MDL-59237 mod_workshop: New WS get_workshops_by_courses
[moodle.git] / mod / workshop / classes / external.php
CommitLineData
9f1ab2db
JL
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 * Workshop external API
19 *
20 * @package mod_workshop
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.4
25 */
26
27defined('MOODLE_INTERNAL') || die;
28
29require_once("$CFG->libdir/externallib.php");
30
31use mod_workshop\external\workshop_summary_exporter;
32
33/**
34 * Workshop external functions
35 *
36 * @package mod_workshop
37 * @category external
38 * @copyright 2017 Juan Leyva <juan@moodle.com>
39 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
40 * @since Moodle 3.4
41 */
42class mod_workshop_external extends external_api {
43
44 /**
45 * Describes the parameters for get_workshops_by_courses.
46 *
47 * @return external_function_parameters
48 * @since Moodle 3.4
49 */
50 public static function get_workshops_by_courses_parameters() {
51 return new external_function_parameters (
52 array(
53 'courseids' => new external_multiple_structure(
54 new external_value(PARAM_INT, 'Course id'), 'Array of course ids', VALUE_DEFAULT, array()
55 ),
56 )
57 );
58 }
59
60 /**
61 * Returns a list of workshops in a provided list of courses.
62 * If no list is provided all workshops that the user can view will be returned.
63 *
64 * @param array $courseids course ids
65 * @return array of warnings and workshops
66 * @since Moodle 3.4
67 */
68 public static function get_workshops_by_courses($courseids = array()) {
69 global $PAGE;
70
71 $warnings = array();
72 $returnedworkshops = array();
73
74 $params = array(
75 'courseids' => $courseids,
76 );
77 $params = self::validate_parameters(self::get_workshops_by_courses_parameters(), $params);
78
79 $mycourses = array();
80 if (empty($params['courseids'])) {
81 $mycourses = enrol_get_my_courses();
82 $params['courseids'] = array_keys($mycourses);
83 }
84
85 // Ensure there are courseids to loop through.
86 if (!empty($params['courseids'])) {
87
88 list($courses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses);
89 $output = $PAGE->get_renderer('core');
90
91 // Get the workshops in this course, this function checks users visibility permissions.
92 // We can avoid then additional validate_context calls.
93 $workshops = get_all_instances_in_courses("workshop", $courses);
94 foreach ($workshops as $workshop) {
95
96 $context = context_module::instance($workshop->coursemodule);
97 // Remove fields that are not from the workshop (added by get_all_instances_in_courses).
98 unset($workshop->coursemodule, $workshop->context, $workshop->visible, $workshop->section, $workshop->groupmode,
99 $workshop->groupingid);
100
101 $exporter = new workshop_summary_exporter($workshop, array('context' => $context));
102 $returnedworkshops[] = $exporter->export($output);
103 }
104 }
105
106 $result = array(
107 'workshops' => $returnedworkshops,
108 'warnings' => $warnings
109 );
110 return $result;
111 }
112
113 /**
114 * Describes the get_workshops_by_courses return value.
115 *
116 * @return external_single_structure
117 * @since Moodle 3.4
118 */
119 public static function get_workshops_by_courses_returns() {
120 return new external_single_structure(
121 array(
122 'workshops' => new external_multiple_structure(
123 workshop_summary_exporter::get_read_structure()
124 ),
125 'warnings' => new external_warnings(),
126 )
127 );
128 }
129}