6db749232402be22bc5442242282b5fbb89d097e
[moodle.git] / mod / data / 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  * Database module external API
19  *
20  * @package    mod_data
21  * @category   external
22  * @copyright  2015 Juan Leyva <juan@moodle.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  * @since      Moodle 2.9
25  */
27 defined('MOODLE_INTERNAL') || die;
29 require_once("$CFG->libdir/externallib.php");
31 /**
32  * Database module external functions
33  *
34  * @package    mod_data
35  * @category   external
36  * @copyright  2015 Juan Leyva <juan@moodle.com>
37  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38  * @since      Moodle 2.9
39  */
40 class mod_data_external extends external_api {
42     /**
43      * Describes the parameters for get_databases_by_courses.
44      *
45      * @return external_external_function_parameters
46      * @since Moodle 2.9
47      */
48     public static function get_databases_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', VALUE_REQUIRED),
53                     'Array of course ids', VALUE_DEFAULT, array()
54                 ),
55             )
56         );
57     }
59     /**
60      * Returns a list of databases in a provided list of courses,
61      * if no list is provided all databases that the user can view will be returned.
62      *
63      * @param array $courseids the course ids
64      * @return array the database details
65      * @since Moodle 2.9
66      */
67     public static function get_databases_by_courses($courseids = array()) {
68         global $CFG;
70         $params = self::validate_parameters(self::get_databases_by_courses_parameters(), array('courseids' => $courseids));
71         $warnings = array();
73         if (!empty($params['courseids'])) {
74             $courses = array();
75             $courseids = $params['courseids'];
76         } else {
77             $courses = enrol_get_my_courses();
78             $courseids = array_keys($courses);
79         }
81         // Array to store the databases to return.
82         $arrdatabases = array();
84         // Ensure there are courseids to loop through.
85         if (!empty($courseids)) {
86             // Array of the courses we are going to retrieve the databases from.
87             $dbcourses = array();
89             // Go through the courseids.
90             foreach ($courseids as $cid) {
91                 // Check the user can function in this context.
92                 try {
93                     $context = context_course::instance($cid);
94                     self::validate_context($context);
96                     // Check if this course was already loaded (by enrol_get_my_courses).
97                     if (!isset($courses[$cid])) {
98                         $courses[$cid] = get_course($cid);
99                     }
100                     $dbcourses[$cid] = $courses[$cid];
102                 } catch (Exception $e) {
103                     $warnings[] = array(
104                         'item' => 'course',
105                         'itemid' => $cid,
106                         'warningcode' => '1',
107                         'message' => 'No access rights in course context '.$e->getMessage()
108                     );
109                 }
110             }
112             // Get the databases in this course, this function checks users visibility permissions.
113             // We can avoid then additional validate_context calls.
114             $databases = get_all_instances_in_courses("data", $dbcourses);
116             foreach ($databases as $database) {
118                 $datacontext = context_module::instance($database->coursemodule);
120                 // Entry to return.
121                 $newdb = array();
123                 // First, we return information that any user can see in the web interface.
124                 $newdb['id'] = $database->id;
125                 $newdb['coursemodule'] = $database->coursemodule;
126                 $newdb['course'] = $database->course;
127                 $newdb['name']  = external_format_string($database->name, $datacontext->id);
128                 // Format intro.
129                 list($newdb['intro'], $newdb['introformat']) =
130                     external_format_text($database->intro, $database->introformat,
131                                             $datacontext->id, 'mod_data', 'intro', null);
133                 // This information should be only available if the user can see the database entries.
134                 if (has_capability('mod/data:viewentry', $datacontext)) {
135                     $viewablefields = array('comments', 'timeavailablefrom', 'timeavailableto', 'timeviewfrom',
136                                             'timeviewto', 'requiredentries', 'requiredentriestoview');
138                     // This is for avoid a long repetitive list and for
139                     // checking that we are retrieving all the required fields.
140                     foreach ($viewablefields as $field) {
141                         // We do not use isset because it won't work for existing null values.
142                         if (!property_exists($database, $field)) {
143                             throw new invalid_response_exception('Missing database module required field: ' . $field);
144                         }
145                         $newdb[$field] = $database->{$field};
146                     }
147                 }
149                 // Check additional permissions for returning optional private settings.
150                 // I avoid intentionally to use can_[add|update]_moduleinfo.
151                 if (has_capability('moodle/course:manageactivities', $context)) {
153                     $additionalfields = array('maxentries', 'rssarticles', 'singletemplate', 'listtemplate',
154                         'listtemplateheader', 'listtemplatefooter', 'addtemplate', 'rsstemplate', 'rsstitletemplate',
155                         'csstemplate', 'jstemplate', 'asearchtemplate', 'approval', 'manageapproved', 'scale', 'assessed', 'assesstimestart',
156                         'assesstimefinish', 'defaultsort', 'defaultsortdir', 'editany', 'notification');
158                     // This is for avoid a long repetitive list.
159                     foreach ($additionalfields as $field) {
160                         if (property_exists($database, $field)) {
161                             $newdb[$field] = $database->{$field};
162                         }
163                     }
164                 }
166                 $arrdatabases[] = $newdb;
167             }
168         }
170         $result = array();
171         $result['databases'] = $arrdatabases;
172         $result['warnings'] = $warnings;
173         return $result;
174     }
176     /**
177      * Describes the get_databases_by_courses return value.
178      *
179      * @return external_single_structure
180      * @since Moodle 2.9
181      */
182     public static function get_databases_by_courses_returns() {
184         return new external_single_structure(
185             array(
186                 'databases' => new external_multiple_structure(
187                     new external_single_structure(
188                         array(
189                             'id' => new external_value(PARAM_INT, 'Database id'),
190                             'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
191                             'course' => new external_value(PARAM_INT, 'Course id'),
192                             'name' => new external_value(PARAM_RAW, 'Database name'),
193                             'intro' => new external_value(PARAM_RAW, 'The Database intro'),
194                             'introformat' => new external_format_value('intro'),
195                             'comments' => new external_value(PARAM_BOOL, 'comments enabled', VALUE_OPTIONAL),
196                             'timeavailablefrom' => new external_value(PARAM_INT, 'timeavailablefrom field', VALUE_OPTIONAL),
197                             'timeavailableto' => new external_value(PARAM_INT, 'timeavailableto field', VALUE_OPTIONAL),
198                             'timeviewfrom' => new external_value(PARAM_INT, 'timeviewfrom field', VALUE_OPTIONAL),
199                             'timeviewto' => new external_value(PARAM_INT, 'timeviewto field', VALUE_OPTIONAL),
200                             'requiredentries' => new external_value(PARAM_INT, 'requiredentries field', VALUE_OPTIONAL),
201                             'requiredentriestoview' => new external_value(PARAM_INT, 'requiredentriestoview field', VALUE_OPTIONAL),
202                             'maxentries' => new external_value(PARAM_INT, 'maxentries field', VALUE_OPTIONAL),
203                             'rssarticles' => new external_value(PARAM_INT, 'rssarticles field', VALUE_OPTIONAL),
204                             'singletemplate' => new external_value(PARAM_RAW, 'singletemplate field', VALUE_OPTIONAL),
205                             'listtemplate' => new external_value(PARAM_RAW, 'listtemplate field', VALUE_OPTIONAL),
206                             'listtemplateheader' => new external_value(PARAM_RAW, 'listtemplateheader field', VALUE_OPTIONAL),
207                             'listtemplatefooter' => new external_value(PARAM_RAW, 'listtemplatefooter field', VALUE_OPTIONAL),
208                             'addtemplate' => new external_value(PARAM_RAW, 'addtemplate field', VALUE_OPTIONAL),
209                             'rsstemplate' => new external_value(PARAM_RAW, 'rsstemplate field', VALUE_OPTIONAL),
210                             'rsstitletemplate' => new external_value(PARAM_RAW, 'rsstitletemplate field', VALUE_OPTIONAL),
211                             'csstemplate' => new external_value(PARAM_RAW, 'csstemplate field', VALUE_OPTIONAL),
212                             'jstemplate' => new external_value(PARAM_RAW, 'jstemplate field', VALUE_OPTIONAL),
213                             'asearchtemplate' => new external_value(PARAM_RAW, 'asearchtemplate field', VALUE_OPTIONAL),
214                             'approval' => new external_value(PARAM_BOOL, 'approval field', VALUE_OPTIONAL),
215                             'manageapproved' => new external_value(PARAM_BOOL, 'manageapproved field', VALUE_OPTIONAL),
216                             'scale' => new external_value(PARAM_INT, 'scale field', VALUE_OPTIONAL),
217                             'assessed' => new external_value(PARAM_INT, 'assessed field', VALUE_OPTIONAL),
218                             'assesstimestart' => new external_value(PARAM_INT, 'assesstimestart field', VALUE_OPTIONAL),
219                             'assesstimefinish' => new external_value(PARAM_INT, 'assesstimefinish field', VALUE_OPTIONAL),
220                             'defaultsort' => new external_value(PARAM_INT, 'defaultsort field', VALUE_OPTIONAL),
221                             'defaultsortdir' => new external_value(PARAM_INT, 'defaultsortdir field', VALUE_OPTIONAL),
222                             'editany' => new external_value(PARAM_BOOL, 'editany field', VALUE_OPTIONAL),
223                             'notification' => new external_value(PARAM_INT, 'notification field', VALUE_OPTIONAL)
224                         ), 'Database'
225                     )
226                 ),
227                 'warnings' => new external_warnings(),
228             )
229         );
230     }