MDL-53149 mod_data: update backup and webservices for timemodified
[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         $mycourses = array();
74         if (empty($params['courseids'])) {
75             $mycourses = enrol_get_my_courses();
76             $params['courseids'] = array_keys($mycourses);
77         }
79         // Array to store the databases to return.
80         $arrdatabases = array();
82         // Ensure there are courseids to loop through.
83         if (!empty($params['courseids'])) {
85             list($dbcourses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses);
87             // Get the databases in this course, this function checks users visibility permissions.
88             // We can avoid then additional validate_context calls.
89             $databases = get_all_instances_in_courses("data", $dbcourses);
91             foreach ($databases as $database) {
93                 $datacontext = context_module::instance($database->coursemodule);
95                 // Entry to return.
96                 $newdb = array();
98                 // First, we return information that any user can see in the web interface.
99                 $newdb['id'] = $database->id;
100                 $newdb['coursemodule'] = $database->coursemodule;
101                 $newdb['course'] = $database->course;
102                 $newdb['name']  = external_format_string($database->name, $datacontext->id);
103                 // Format intro.
104                 list($newdb['intro'], $newdb['introformat']) =
105                     external_format_text($database->intro, $database->introformat,
106                                             $datacontext->id, 'mod_data', 'intro', null);
108                 // This information should be only available if the user can see the database entries.
109                 if (has_capability('mod/data:viewentry', $datacontext)) {
110                     $viewablefields = array('comments', 'timeavailablefrom', 'timeavailableto', 'timeviewfrom',
111                                             'timeviewto', 'requiredentries', 'requiredentriestoview');
113                     // This is for avoid a long repetitive list and for
114                     // checking that we are retrieving all the required fields.
115                     foreach ($viewablefields as $field) {
116                         // We do not use isset because it won't work for existing null values.
117                         if (!property_exists($database, $field)) {
118                             throw new invalid_response_exception('Missing database module required field: ' . $field);
119                         }
120                         $newdb[$field] = $database->{$field};
121                     }
122                 }
124                 // Check additional permissions for returning optional private settings.
125                 // I avoid intentionally to use can_[add|update]_moduleinfo.
126                 if (has_capability('moodle/course:manageactivities', $datacontext)) {
128                     $additionalfields = array('maxentries', 'rssarticles', 'singletemplate', 'listtemplate',
129                         'listtemplateheader', 'listtemplatefooter', 'addtemplate', 'rsstemplate', 'rsstitletemplate',
130                         'csstemplate', 'jstemplate', 'asearchtemplate', 'approval', 'manageapproved', 'scale', 'assessed', 'assesstimestart',
131                         'assesstimefinish', 'defaultsort', 'defaultsortdir', 'editany', 'notification', 'timemodified');
133                     // This is for avoid a long repetitive list.
134                     foreach ($additionalfields as $field) {
135                         if (property_exists($database, $field)) {
136                             $newdb[$field] = $database->{$field};
137                         }
138                     }
139                 }
141                 $arrdatabases[] = $newdb;
142             }
143         }
145         $result = array();
146         $result['databases'] = $arrdatabases;
147         $result['warnings'] = $warnings;
148         return $result;
149     }
151     /**
152      * Describes the get_databases_by_courses return value.
153      *
154      * @return external_single_structure
155      * @since Moodle 2.9
156      */
157     public static function get_databases_by_courses_returns() {
159         return new external_single_structure(
160             array(
161                 'databases' => new external_multiple_structure(
162                     new external_single_structure(
163                         array(
164                             'id' => new external_value(PARAM_INT, 'Database id'),
165                             'coursemodule' => new external_value(PARAM_INT, 'Course module id'),
166                             'course' => new external_value(PARAM_INT, 'Course id'),
167                             'name' => new external_value(PARAM_RAW, 'Database name'),
168                             'intro' => new external_value(PARAM_RAW, 'The Database intro'),
169                             'introformat' => new external_format_value('intro'),
170                             'comments' => new external_value(PARAM_BOOL, 'comments enabled', VALUE_OPTIONAL),
171                             'timeavailablefrom' => new external_value(PARAM_INT, 'timeavailablefrom field', VALUE_OPTIONAL),
172                             'timeavailableto' => new external_value(PARAM_INT, 'timeavailableto field', VALUE_OPTIONAL),
173                             'timeviewfrom' => new external_value(PARAM_INT, 'timeviewfrom field', VALUE_OPTIONAL),
174                             'timeviewto' => new external_value(PARAM_INT, 'timeviewto field', VALUE_OPTIONAL),
175                             'requiredentries' => new external_value(PARAM_INT, 'requiredentries field', VALUE_OPTIONAL),
176                             'requiredentriestoview' => new external_value(PARAM_INT, 'requiredentriestoview field', VALUE_OPTIONAL),
177                             'maxentries' => new external_value(PARAM_INT, 'maxentries field', VALUE_OPTIONAL),
178                             'rssarticles' => new external_value(PARAM_INT, 'rssarticles field', VALUE_OPTIONAL),
179                             'singletemplate' => new external_value(PARAM_RAW, 'singletemplate field', VALUE_OPTIONAL),
180                             'listtemplate' => new external_value(PARAM_RAW, 'listtemplate field', VALUE_OPTIONAL),
181                             'listtemplateheader' => new external_value(PARAM_RAW, 'listtemplateheader field', VALUE_OPTIONAL),
182                             'listtemplatefooter' => new external_value(PARAM_RAW, 'listtemplatefooter field', VALUE_OPTIONAL),
183                             'addtemplate' => new external_value(PARAM_RAW, 'addtemplate field', VALUE_OPTIONAL),
184                             'rsstemplate' => new external_value(PARAM_RAW, 'rsstemplate field', VALUE_OPTIONAL),
185                             'rsstitletemplate' => new external_value(PARAM_RAW, 'rsstitletemplate field', VALUE_OPTIONAL),
186                             'csstemplate' => new external_value(PARAM_RAW, 'csstemplate field', VALUE_OPTIONAL),
187                             'jstemplate' => new external_value(PARAM_RAW, 'jstemplate field', VALUE_OPTIONAL),
188                             'asearchtemplate' => new external_value(PARAM_RAW, 'asearchtemplate field', VALUE_OPTIONAL),
189                             'approval' => new external_value(PARAM_BOOL, 'approval field', VALUE_OPTIONAL),
190                             'manageapproved' => new external_value(PARAM_BOOL, 'manageapproved field', VALUE_OPTIONAL),
191                             'scale' => new external_value(PARAM_INT, 'scale field', VALUE_OPTIONAL),
192                             'assessed' => new external_value(PARAM_INT, 'assessed field', VALUE_OPTIONAL),
193                             'assesstimestart' => new external_value(PARAM_INT, 'assesstimestart field', VALUE_OPTIONAL),
194                             'assesstimefinish' => new external_value(PARAM_INT, 'assesstimefinish field', VALUE_OPTIONAL),
195                             'defaultsort' => new external_value(PARAM_INT, 'defaultsort field', VALUE_OPTIONAL),
196                             'defaultsortdir' => new external_value(PARAM_INT, 'defaultsortdir field', VALUE_OPTIONAL),
197                             'editany' => new external_value(PARAM_BOOL, 'editany field', VALUE_OPTIONAL),
198                             'notification' => new external_value(PARAM_INT, 'notification field', VALUE_OPTIONAL),
199                             'timemodified' => new external_value(PARAM_INT, 'Time modified', VALUE_OPTIONAL)
200                         ), 'Database'
201                     )
202                 ),
203                 'warnings' => new external_warnings(),
204             )
205         );
206     }