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/>.
  16
  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  */
  26
  27 defined('MOODLE_INTERNAL') || die;
  28
  29 require_once("$CFG->libdir/externallib.php");
  30
  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 {
  41
  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     }
  58
  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;
  69
  70         $params = self::validate_parameters(self::get_databases_by_courses_parameters(), array('courseids' => $courseids));
  71         $warnings = array();
  72
  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         }
  80
  81         // Array to store the databases to return.
  82         $arrdatabases = array();
  83
  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();
  88
  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);
  95
  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];
 101
 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             }
 111
 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);
 115
 116             foreach ($databases as $database) {
 117
 118                 $datacontext = context_module::instance($database->coursemodule);
 119
 120                 // Entry to return.
 121                 $newdb = array();
 122
 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);
 132
 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');
 137
 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                 }
 148
 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)) {
 152
 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');
 157
 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                 }
 165
 166                 $arrdatabases[] = $newdb;
 167             }
 168         }
 169
 170         $result = array();
 171         $result['databases'] = $arrdatabases;
 172         $result['warnings'] = $warnings;
 173         return $result;
 174     }
 175
 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() {
 183
 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     }
 231
 232 }