[Summary view]

Differences Between: [Versions 401 and 402] [Versions 401 and 403]

   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   * This is the external API for blogs.
  19   *
  20   * @package    core_blog
  21   * @copyright  2018 Juan Leyva
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  namespace core_blog;
  26  defined('MOODLE_INTERNAL') || die();
  27  
  28  require_once($CFG->libdir .'/externallib.php');
  29  require_once($CFG->dirroot .'/blog/lib.php');
  30  require_once($CFG->dirroot .'/blog/locallib.php');
  31  
  32  use external_api;
  33  use external_function_parameters;
  34  use external_value;
  35  use external_single_structure;
  36  use external_multiple_structure;
  37  use external_warnings;
  38  use context_system;
  39  use context_course;
  40  use moodle_exception;
  41  use core_blog\external\post_exporter;
  42  
  43  /**
  44   * This is the external API for blogs.
  45   *
  46   * @copyright  2018 Juan Leyva
  47   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  48   */
  49  class external extends external_api {
  50  
  51      /**
  52       * Validate access to the blog and the filters to apply when listing entries.
  53       *
  54       * @param  array  $rawwsfilters array containing the filters in WS format
  55       * @return array  context, filters to apply and the calculated courseid and user
  56       * @since  Moodle 3.6
  57       */
  58      protected static function validate_access_and_filters($rawwsfilters) {
  59          global $CFG;
  60  
  61          if (empty($CFG->enableblogs)) {
  62              throw new moodle_exception('blogdisable', 'blog');
  63          }
  64  
  65          // Init filters.
  66          $filterstype = array(
  67              'courseid' => PARAM_INT,
  68              'groupid' => PARAM_INT,
  69              'userid' => PARAM_INT,
  70              'tagid' => PARAM_INT,
  71              'tag' => PARAM_NOTAGS,
  72              'cmid' => PARAM_INT,
  73              'entryid' => PARAM_INT,
  74              'search' => PARAM_RAW
  75          );
  76          $filters = array(
  77              'courseid' => null,
  78              'groupid' => null,
  79              'userid' => null,
  80              'tagid' => null,
  81              'tag' => null,
  82              'cmid' => null,
  83              'entryid' => null,
  84              'search' => null
  85          );
  86  
  87          foreach ($rawwsfilters as $filter) {
  88              $name = trim($filter['name']);
  89              if (!isset($filterstype[$name])) {
  90                  throw new moodle_exception('errorinvalidparam', 'webservice', '', $name);
  91              }
  92              $filters[$name] = clean_param($filter['value'], $filterstype[$name]);
  93          }
  94  
  95          // Do not overwrite here the filters, blog_get_headers and blog_listing will take care of that.
  96          list($courseid, $userid) = blog_validate_access($filters['courseid'], $filters['cmid'], $filters['groupid'],
  97              $filters['entryid'], $filters['userid']);
  98  
  99          if ($courseid && $courseid != SITEID) {
 100              $context = context_course::instance($courseid);
 101              self::validate_context($context);
 102          } else {
 103              $context = context_system::instance();
 104              if ($CFG->bloglevel == BLOG_GLOBAL_LEVEL) {
 105                  // Everybody can see anything - no login required unless site is locked down using forcelogin.
 106                  if ($CFG->forcelogin) {
 107                      self::validate_context($context);
 108                  }
 109              } else {
 110                  self::validate_context($context);
 111              }
 112          }
 113          // Courseid and userid may not be the same that the ones in $filters.
 114          return array($context, $filters, $courseid, $userid);
 115      }
 116  
 117      /**
 118       * Returns description of get_entries() parameters.
 119       *
 120       * @return external_function_parameters
 121       * @since  Moodle 3.6
 122       */
 123      public static function get_entries_parameters() {
 124          return new external_function_parameters(
 125              array(
 126                  'filters' => new external_multiple_structure (
 127                      new external_single_structure(
 128                          array(
 129                              'name' => new external_value(PARAM_ALPHA,
 130                                  'The expected keys (value format) are:
 131                                  tag      PARAM_NOTAGS blog tag
 132                                  tagid    PARAM_INT    blog tag id
 133                                  userid   PARAM_INT    blog author (userid)
 134                                  cmid    PARAM_INT    course module id
 135                                  entryid  PARAM_INT    entry id
 136                                  groupid  PARAM_INT    group id
 137                                  courseid PARAM_INT    course id
 138                                  search   PARAM_RAW    search term
 139                                  '
 140                              ),
 141                              'value' => new external_value(PARAM_RAW, 'The value of the filter.')
 142                          )
 143                      ), 'Parameters to filter blog listings.', VALUE_DEFAULT, array()
 144                  ),
 145                  'page' => new external_value(PARAM_INT, 'The blog page to return.', VALUE_DEFAULT, 0),
 146                  'perpage' => new external_value(PARAM_INT, 'The number of posts to return per page.', VALUE_DEFAULT, 10),
 147              )
 148          );
 149      }
 150  
 151      /**
 152       * Return blog entries.
 153       *
 154       * @param array $filters the parameters to filter the blog listing
 155       * @param int $page the blog page to return
 156       * @param int $perpage the number of posts to return per page
 157       * @return array with the blog entries and warnings
 158       * @since  Moodle 3.6
 159       */
 160      public static function get_entries($filters = array(), $page = 0, $perpage = 10) {
 161          global $PAGE;
 162  
 163          $warnings = array();
 164          $params = self::validate_parameters(self::get_entries_parameters(),
 165              array('filters' => $filters, 'page' => $page, 'perpage' => $perpage));
 166  
 167          list($context, $filters, $courseid, $userid) = self::validate_access_and_filters($params['filters']);
 168  
 169          $PAGE->set_context($context); // Needed by internal APIs.
 170          $output = $PAGE->get_renderer('core');
 171  
 172          // Get filters.
 173          $blogheaders = blog_get_headers($filters['courseid'], $filters['groupid'], $filters['userid'], $filters['tagid'],
 174              $filters['tag'], $filters['cmid'], $filters['entryid'], $filters['search']);
 175          $bloglisting = new \blog_listing($blogheaders['filters']);
 176  
 177          $page  = $params['page'];
 178          $limit = empty($params['perpage']) ? get_user_preferences('blogpagesize', 10) : $params['perpage'];
 179          $start = $page * $limit;
 180          $entries = $bloglisting->get_entries($start, $limit);
 181          $totalentries = $bloglisting->count_entries();
 182  
 183          $exportedentries = array();
 184          foreach ($entries as $entry) {
 185              $exporter = new post_exporter($entry, array('context' => $context));
 186              $exportedentries[] = $exporter->export($output);
 187          }
 188          return array(
 189              'warnings' => $warnings,
 190              'entries' => $exportedentries,
 191              'totalentries' => $totalentries,
 192          );
 193      }
 194  
 195      /**
 196       * Returns description of get_entries() result value.
 197       *
 198       * @return external_description
 199       * @since  Moodle 3.6
 200       */
 201      public static function get_entries_returns() {
 202          return new external_single_structure(
 203              array(
 204                  'entries' => new external_multiple_structure(
 205                      post_exporter::get_read_structure()
 206                  ),
 207                  'totalentries' => new external_value(PARAM_INT, 'The total number of entries found.'),
 208                  'warnings' => new external_warnings(),
 209              )
 210          );
 211      }
 212  
 213      /**
 214       * Returns description of view_entries() parameters.
 215       *
 216       * @return external_function_parameters
 217       * @since  Moodle 3.6
 218       */
 219      public static function view_entries_parameters() {
 220          return new external_function_parameters(
 221              array(
 222                  'filters' => new external_multiple_structure (
 223                      new external_single_structure(
 224                          array(
 225                              'name' => new external_value(PARAM_ALPHA,
 226                                  'The expected keys (value format) are:
 227                                  tag      PARAM_NOTAGS blog tag
 228                                  tagid    PARAM_INT    blog tag id
 229                                  userid   PARAM_INT    blog author (userid)
 230                                  cmid     PARAM_INT    course module id
 231                                  entryid  PARAM_INT    entry id
 232                                  groupid  PARAM_INT    group id
 233                                  courseid PARAM_INT    course id
 234                                  search   PARAM_RAW    search term
 235                                  '
 236                              ),
 237                              'value' => new external_value(PARAM_RAW, 'The value of the filter.')
 238                          )
 239                      ), 'Parameters used in the filter of view_entries.', VALUE_DEFAULT, array()
 240                  ),
 241              )
 242          );
 243      }
 244  
 245      /**
 246       * Trigger the blog_entries_viewed event.
 247       *
 248       * @param array $filters the parameters used in the filter of get_entries
 249       * @return array with status result and warnings
 250       * @since  Moodle 3.6
 251       */
 252      public static function view_entries($filters = array()) {
 253  
 254          $warnings = array();
 255          $params = self::validate_parameters(self::view_entries_parameters(), array('filters' => $filters));
 256  
 257          list($context, $filters, $courseid, $userid) = self::validate_access_and_filters($params['filters']);
 258  
 259          $eventparams = array(
 260              'other' => array('entryid' => $filters['entryid'], 'tagid' => $filters['tagid'], 'userid' => $userid,
 261                  'modid' => $filters['cmid'], 'groupid' => $filters['groupid'], 'search' => $filters['search']
 262              )
 263          );
 264          if (!empty($userid)) {
 265              $eventparams['relateduserid'] = $userid;
 266          }
 267          $eventparams['other']['courseid'] = ($courseid === SITEID) ? 0 : $courseid;
 268          $event = \core\event\blog_entries_viewed::create($eventparams);
 269          $event->trigger();
 270  
 271          return array(
 272              'warnings' => $warnings,
 273              'status' => true,
 274          );
 275      }
 276  
 277      /**
 278       * Returns description of view_entries() result value.
 279       *
 280       * @return external_description
 281       * @since  Moodle 3.6
 282       */
 283      public static function view_entries_returns() {
 284          return new external_single_structure(
 285              array(
 286                  'status' => new external_value(PARAM_BOOL, 'status: true if success'),
 287                  'warnings' => new external_warnings(),
 288              )
 289          );
 290      }
 291  }