MDL-50550 wiki: New WS mod_wiki_get_wikis_by_courses
[moodle.git] / mod / wiki / classes / external.php
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/>.
17 /**
18  * Wiki module external API.
19  *
20  * @package    mod_wiki
21  * @category   external
22  * @copyright  2015 Dani Palou <dani@moodle.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  * @since      Moodle 3.1
25  */
27 defined('MOODLE_INTERNAL') || die;
29 require_once($CFG->libdir . '/externallib.php');
30 require_once($CFG->dirroot . '/mod/wiki/lib.php');
31 require_once($CFG->dirroot . '/mod/wiki/locallib.php');
33 /**
34  * Wiki module external functions.
35  *
36  * @package    mod_wiki
37  * @category   external
38  * @copyright  2015 Dani Palou <dani@moodle.com>
39  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
40  * @since      Moodle 3.1
41  */
42 class mod_wiki_external extends external_api {
44     /**
45      * Describes the parameters for get_wikis_by_courses.
46      *
47      * @return external_function_parameters
48      * @since Moodle 3.1
49      */
50     public static function get_wikis_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     }
60     /**
61      * Returns a list of wikis in a provided list of courses,
62      * if no list is provided all wikis that the user can view will be returned.
63      *
64      * @param array $courseids The courses IDs.
65      * @return array Containing a list of warnings and a list of wikis.
66      * @since Moodle 3.1
67      */
68     public static function get_wikis_by_courses($courseids = array()) {
70         $returnedwikis = array();
71         $warnings = array();
73         $params = self::validate_parameters(self::get_wikis_by_courses_parameters(), array('courseids' => $courseids));
75         $mycourses = array();
76         if (empty($params['courseids'])) {
77             $mycourses = enrol_get_my_courses();
78             $params['courseids'] = array_keys($mycourses);
79         }
81         // Ensure there are courseids to loop through.
82         if (!empty($params['courseids'])) {
84             list($courses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses);
86             // Get the wikis in this course, this function checks users visibility permissions.
87             // We can avoid then additional validate_context calls.
88             $wikis = get_all_instances_in_courses('wiki', $courses);
90             foreach ($wikis as $wiki) {
92                 $context = context_module::instance($wiki->coursemodule);
94                 // Entry to return.
95                 $module = array();
97                 // First, we return information that any user can see in (or can deduce from) the web interface.
98                 $module['id'] = $wiki->id;
99                 $module['coursemodule'] = $wiki->coursemodule;
100                 $module['course'] = $wiki->course;
101                 $module['name']  = external_format_string($wiki->name, $context->id);
103                 $viewablefields = [];
104                 if (has_capability('mod/wiki:viewpage', $context)) {
105                     list($module['intro'], $module['introformat']) =
106                         external_format_text($wiki->intro, $wiki->introformat, $context->id, 'mod_wiki', 'intro', $wiki->id);
108                     $viewablefields = array('firstpagetitle', 'wikimode', 'defaultformat', 'forceformat', 'editbegin', 'editend',
109                                             'section', 'visible', 'groupmode', 'groupingid');
110                 }
112                 // Check additional permissions for returning optional private settings.
113                 if (has_capability('moodle/course:manageactivities', $context)) {
114                     $additionalfields = array('timecreated', 'timemodified');
115                     $viewablefields = array_merge($viewablefields, $additionalfields);
116                 }
118                 foreach ($viewablefields as $field) {
119                     $module[$field] = $wiki->{$field};
120                 }
122                 // Check if user can add new pages.
123                 $module['cancreatepages'] = wiki_can_create_pages($context);
125                 $returnedwikis[] = $module;
126             }
127         }
129         $result = array();
130         $result['wikis'] = $returnedwikis;
131         $result['warnings'] = $warnings;
132         return $result;
133     }
135     /**
136      * Describes the get_wikis_by_courses return value.
137      *
138      * @return external_single_structure
139      * @since Moodle 3.1
140      */
141     public static function get_wikis_by_courses_returns() {
143         return new external_single_structure(
144             array(
145                 'wikis' => new external_multiple_structure(
146                     new external_single_structure(
147                         array(
148                             'id' => new external_value(PARAM_INT, 'Wiki ID.'),
149                             'coursemodule' => new external_value(PARAM_INT, 'Course module ID.'),
150                             'course' => new external_value(PARAM_INT, 'Course ID.'),
151                             'name' => new external_value(PARAM_RAW, 'Wiki name.'),
152                             'intro' => new external_value(PARAM_RAW, 'Wiki intro.', VALUE_OPTIONAL),
153                             'introformat' => new external_format_value('Wiki intro format.', VALUE_OPTIONAL),
154                             'timecreated' => new external_value(PARAM_INT, 'Time of creation.', VALUE_OPTIONAL),
155                             'timemodified' => new external_value(PARAM_INT, 'Time of last modification.', VALUE_OPTIONAL),
156                             'firstpagetitle' => new external_value(PARAM_RAW, 'First page title.', VALUE_OPTIONAL),
157                             'wikimode' => new external_value(PARAM_TEXT, 'Wiki mode (individual, collaborative).', VALUE_OPTIONAL),
158                             'defaultformat' => new external_value(PARAM_TEXT, 'Wiki\'s default format (html, creole, nwiki).',
159                                                                             VALUE_OPTIONAL),
160                             'forceformat' => new external_value(PARAM_INT, '1 if format is forced, 0 otherwise.',
161                                                                             VALUE_OPTIONAL),
162                             'editbegin' => new external_value(PARAM_INT, 'Edit begin.', VALUE_OPTIONAL),
163                             'editend' => new external_value(PARAM_INT, 'Edit end.', VALUE_OPTIONAL),
164                             'section' => new external_value(PARAM_INT, 'Course section ID.', VALUE_OPTIONAL),
165                             'visible' => new external_value(PARAM_INT, '1 if visible, 0 otherwise.', VALUE_OPTIONAL),
166                             'groupmode' => new external_value(PARAM_INT, 'Group mode.', VALUE_OPTIONAL),
167                             'groupingid' => new external_value(PARAM_INT, 'Group ID.', VALUE_OPTIONAL),
168                             'cancreatepages' => new external_value(PARAM_BOOL, 'True if user can create pages.'),
169                         ), 'Wikis'
170                     )
171                 ),
172                 'warnings' => new external_warnings(),
173             )
174         );
175     }