[Summary view]

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]

   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  use core_course\external\helper_for_get_mods_by_courses;
  18  use core_external\external_api;
  19  use core_external\external_function_parameters;
  20  use core_external\external_multiple_structure;
  21  use core_external\external_single_structure;
  22  use core_external\external_value;
  23  use core_external\external_warnings;
  24  use core_external\util;
  25  
  26  /**
  27   * URL external functions
  28   *
  29   * @package    mod_url
  30   * @category   external
  31   * @copyright  2015 Juan Leyva <juan@moodle.com>
  32   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  33   * @since      Moodle 3.0
  34   */
  35  class mod_url_external extends external_api {
  36  
  37      /**
  38       * Returns description of method parameters
  39       *
  40       * @return external_function_parameters
  41       * @since Moodle 3.0
  42       */
  43      public static function view_url_parameters() {
  44          return new external_function_parameters(
  45              array(
  46                  'urlid' => new external_value(PARAM_INT, 'url instance id')
  47              )
  48          );
  49      }
  50  
  51      /**
  52       * Trigger the course module viewed event and update the module completion status.
  53       *
  54       * @param int $urlid the url instance id
  55       * @return array of warnings and status result
  56       * @since Moodle 3.0
  57       * @throws moodle_exception
  58       */
  59      public static function view_url($urlid) {
  60          global $DB, $CFG;
  61          require_once($CFG->dirroot . "/mod/url/lib.php");
  62  
  63          $params = self::validate_parameters(self::view_url_parameters(),
  64                                              array(
  65                                                  'urlid' => $urlid
  66                                              ));
  67          $warnings = array();
  68  
  69          // Request and permission validation.
  70          $url = $DB->get_record('url', array('id' => $params['urlid']), '*', MUST_EXIST);
  71          list($course, $cm) = get_course_and_cm_from_instance($url, 'url');
  72  
  73          $context = context_module::instance($cm->id);
  74          self::validate_context($context);
  75  
  76          require_capability('mod/url:view', $context);
  77  
  78          // Call the url/lib API.
  79          url_view($url, $course, $cm, $context);
  80  
  81          $result = array();
  82          $result['status'] = true;
  83          $result['warnings'] = $warnings;
  84          return $result;
  85      }
  86  
  87      /**
  88       * Returns description of method result value
  89       *
  90       * @return \core_external\external_description
  91       * @since Moodle 3.0
  92       */
  93      public static function view_url_returns() {
  94          return new external_single_structure(
  95              array(
  96                  'status' => new external_value(PARAM_BOOL, 'status: true if success'),
  97                  'warnings' => new external_warnings()
  98              )
  99          );
 100      }
 101  
 102      /**
 103       * Describes the parameters for get_urls_by_courses.
 104       *
 105       * @return external_function_parameters
 106       * @since Moodle 3.3
 107       */
 108      public static function get_urls_by_courses_parameters() {
 109          return new external_function_parameters (
 110              array(
 111                  'courseids' => new external_multiple_structure(
 112                      new external_value(PARAM_INT, 'Course id'), 'Array of course ids', VALUE_DEFAULT, array()
 113                  ),
 114              )
 115          );
 116      }
 117  
 118      /**
 119       * Returns a list of urls in a provided list of courses.
 120       * If no list is provided all urls that the user can view will be returned.
 121       *
 122       * @param array $courseids course ids
 123       * @return array of warnings and urls
 124       * @since Moodle 3.3
 125       */
 126      public static function get_urls_by_courses($courseids = array()) {
 127  
 128          $warnings = array();
 129          $returnedurls = array();
 130  
 131          $params = array(
 132              'courseids' => $courseids,
 133          );
 134          $params = self::validate_parameters(self::get_urls_by_courses_parameters(), $params);
 135  
 136          $mycourses = array();
 137          if (empty($params['courseids'])) {
 138              $mycourses = enrol_get_my_courses();
 139              $params['courseids'] = array_keys($mycourses);
 140          }
 141  
 142          // Ensure there are courseids to loop through.
 143          if (!empty($params['courseids'])) {
 144  
 145              list($courses, $warnings) = util::validate_courses($params['courseids'], $mycourses);
 146  
 147              // Get the urls in this course, this function checks users visibility permissions.
 148              // We can avoid then additional validate_context calls.
 149              $urls = get_all_instances_in_courses("url", $courses);
 150              foreach ($urls as $url) {
 151                  helper_for_get_mods_by_courses::format_name_and_intro($url, 'mod_url');
 152                  $returnedurls[] = $url;
 153              }
 154          }
 155  
 156          $result = array(
 157              'urls' => $returnedurls,
 158              'warnings' => $warnings
 159          );
 160          return $result;
 161      }
 162  
 163      /**
 164       * Describes the get_urls_by_courses return value.
 165       *
 166       * @return external_single_structure
 167       * @since Moodle 3.3
 168       */
 169      public static function get_urls_by_courses_returns() {
 170          return new external_single_structure(
 171              array(
 172                  'urls' => new external_multiple_structure(
 173                      new external_single_structure(array_merge(
 174                          helper_for_get_mods_by_courses::standard_coursemodule_elements_returns(),
 175                          [
 176                              'externalurl' => new external_value(PARAM_RAW_TRIMMED, 'External URL'),
 177                              'display' => new external_value(PARAM_INT, 'How to display the url'),
 178                              'displayoptions' => new external_value(PARAM_RAW, 'Display options (width, height)'),
 179                              'parameters' => new external_value(PARAM_RAW, 'Parameters to append to the URL'),
 180                              'timemodified' => new external_value(PARAM_INT, 'Last time the url was modified'),
 181                          ]
 182                      ))
 183                  ),
 184                  'warnings' => new external_warnings(),
 185              )
 186          );
 187      }
 188  }