[Summary view] [Print] [Text view]

   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   * Wiki module external API.
  19   *
  20   * @package    mod_wiki
  21   * @category   external
  22   * @copyright  2015 Dani Palou <dani@moodle.com>
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   * @since      Moodle 3.1
  25   */
  26  
  27  defined('MOODLE_INTERNAL') || die;
  28  
  29  require_once($CFG->libdir . '/externallib.php');
  30  require_once($CFG->dirroot . '/mod/wiki/lib.php');
  31  require_once($CFG->dirroot . '/mod/wiki/locallib.php');
  32  
  33  /**
  34   * Wiki module external functions.
  35   *
  36   * @package    mod_wiki
  37   * @category   external
  38   * @copyright  2015 Dani Palou <dani@moodle.com>
  39   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  40   * @since      Moodle 3.1
  41   */
  42  class mod_wiki_external extends external_api {
  43  
  44      /**
  45       * Describes the parameters for get_wikis_by_courses.
  46       *
  47       * @return external_function_parameters
  48       * @since Moodle 3.1
  49       */
  50      public static function get_wikis_by_courses_parameters() {
  51          return new external_function_parameters (
  52              array(
  53                  'courseids' => new external_multiple_structure(
  54                      new external_value(PARAM_INT, 'Course ID'), 'Array of course ids.', VALUE_DEFAULT, array()
  55                  ),
  56              )
  57          );
  58      }
  59  
  60      /**
  61       * Returns a list of wikis in a provided list of courses,
  62       * if no list is provided all wikis that the user can view will be returned.
  63       *
  64       * @param array $courseids The courses IDs.
  65       * @return array Containing a list of warnings and a list of wikis.
  66       * @since Moodle 3.1
  67       */
  68      public static function get_wikis_by_courses($courseids = array()) {
  69  
  70          $returnedwikis = array();
  71          $warnings = array();
  72  
  73          $params = self::validate_parameters(self::get_wikis_by_courses_parameters(), array('courseids' => $courseids));
  74  
  75          $mycourses = array();
  76          if (empty($params['courseids'])) {
  77              $mycourses = enrol_get_my_courses();
  78              $params['courseids'] = array_keys($mycourses);
  79          }
  80  
  81          // Ensure there are courseids to loop through.
  82          if (!empty($params['courseids'])) {
  83  
  84              list($courses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses);
  85  
  86              // Get the wikis in this course, this function checks users visibility permissions.
  87              // We can avoid then additional validate_context calls.
  88              $wikis = get_all_instances_in_courses('wiki', $courses);
  89  
  90              foreach ($wikis as $wiki) {
  91  
  92                  $context = context_module::instance($wiki->coursemodule);
  93  
  94                  // Entry to return.
  95                  $module = array();
  96  
  97                  // First, we return information that any user can see in (or can deduce from) the web interface.
  98                  $module['id'] = $wiki->id;
  99                  $module['coursemodule'] = $wiki->coursemodule;
 100                  $module['course'] = $wiki->course;
 101                  $module['name']  = external_format_string($wiki->name, $context->id);
 102  
 103                  $viewablefields = [];
 104                  if (has_capability('mod/wiki:viewpage', $context)) {
 105                      list($module['intro'], $module['introformat']) =
 106                          external_format_text($wiki->intro, $wiki->introformat, $context->id, 'mod_wiki', 'intro', $wiki->id);
 107                      $module['introfiles'] = external_util::get_area_files($context->id, 'mod_wiki', 'intro', false, false);
 108  
 109                      $viewablefields = array('firstpagetitle', 'wikimode', 'defaultformat', 'forceformat', 'editbegin', 'editend',
 110                                              'section', 'visible', 'groupmode', 'groupingid');
 111                  }
 112  
 113                  // Check additional permissions for returning optional private settings.
 114                  if (has_capability('moodle/course:manageactivities', $context)) {
 115                      $additionalfields = array('timecreated', 'timemodified');
 116                      $viewablefields = array_merge($viewablefields, $additionalfields);
 117                  }
 118  
 119                  foreach ($viewablefields as $field) {
 120                      $module[$field] = $wiki->{$field};
 121                  }
 122  
 123                  // Check if user can add new pages.
 124                  $module['cancreatepages'] = wiki_can_create_pages($context);
 125  
 126                  $returnedwikis[] = $module;
 127              }
 128          }
 129  
 130          $result = array();
 131          $result['wikis'] = $returnedwikis;
 132          $result['warnings'] = $warnings;
 133          return $result;
 134      }
 135  
 136      /**
 137       * Describes the get_wikis_by_courses return value.
 138       *
 139       * @return external_single_structure
 140       * @since Moodle 3.1
 141       */
 142      public static function get_wikis_by_courses_returns() {
 143  
 144          return new external_single_structure(
 145              array(
 146                  'wikis' => new external_multiple_structure(
 147                      new external_single_structure(
 148                          array(
 149                              'id' => new external_value(PARAM_INT, 'Wiki ID.'),
 150                              'coursemodule' => new external_value(PARAM_INT, 'Course module ID.'),
 151                              'course' => new external_value(PARAM_INT, 'Course ID.'),
 152                              'name' => new external_value(PARAM_RAW, 'Wiki name.'),
 153                              'intro' => new external_value(PARAM_RAW, 'Wiki intro.', VALUE_OPTIONAL),
 154                              'introformat' => new external_format_value('Wiki intro format.', VALUE_OPTIONAL),
 155                              'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL),
 156                              'timecreated' => new external_value(PARAM_INT, 'Time of creation.', VALUE_OPTIONAL),
 157                              'timemodified' => new external_value(PARAM_INT, 'Time of last modification.', VALUE_OPTIONAL),
 158                              'firstpagetitle' => new external_value(PARAM_RAW, 'First page title.', VALUE_OPTIONAL),
 159                              'wikimode' => new external_value(PARAM_TEXT, 'Wiki mode (individual, collaborative).', VALUE_OPTIONAL),
 160                              'defaultformat' => new external_value(PARAM_TEXT, 'Wiki\'s default format (html, creole, nwiki).',
 161                                                                              VALUE_OPTIONAL),
 162                              'forceformat' => new external_value(PARAM_INT, '1 if format is forced, 0 otherwise.',
 163                                                                              VALUE_OPTIONAL),
 164                              'editbegin' => new external_value(PARAM_INT, 'Edit begin.', VALUE_OPTIONAL),
 165                              'editend' => new external_value(PARAM_INT, 'Edit end.', VALUE_OPTIONAL),
 166                              'section' => new external_value(PARAM_INT, 'Course section ID.', VALUE_OPTIONAL),
 167                              'visible' => new external_value(PARAM_INT, '1 if visible, 0 otherwise.', VALUE_OPTIONAL),
 168                              'groupmode' => new external_value(PARAM_INT, 'Group mode.', VALUE_OPTIONAL),
 169                              'groupingid' => new external_value(PARAM_INT, 'Group ID.', VALUE_OPTIONAL),
 170                              'cancreatepages' => new external_value(PARAM_BOOL, 'True if user can create pages.'),
 171                          ), 'Wikis'
 172                      )
 173                  ),
 174                  'warnings' => new external_warnings(),
 175              )
 176          );
 177      }
 178  
 179      /**
 180       * Describes the parameters for view_wiki.
 181       *
 182       * @return external_function_parameters
 183       * @since Moodle 3.1
 184       */
 185      public static function view_wiki_parameters() {
 186          return new external_function_parameters (
 187              array(
 188                  'wikiid' => new external_value(PARAM_INT, 'Wiki instance ID.')
 189              )
 190          );
 191      }
 192  
 193      /**
 194       * Trigger the course module viewed event and update the module completion status.
 195       *
 196       * @param int $wikiid The wiki instance ID.
 197       * @return array of warnings and status result.
 198       * @since Moodle 3.1
 199       */
 200      public static function view_wiki($wikiid) {
 201  
 202          $params = self::validate_parameters(self::view_wiki_parameters(),
 203                                              array(
 204                                                  'wikiid' => $wikiid
 205                                              ));
 206          $warnings = array();
 207  
 208          // Get wiki instance.
 209          if (!$wiki = wiki_get_wiki($params['wikiid'])) {
 210              throw new moodle_exception('incorrectwikiid', 'wiki');
 211          }
 212  
 213          // Permission validation.
 214          list($course, $cm) = get_course_and_cm_from_instance($wiki, 'wiki');
 215          $context = context_module::instance($cm->id);
 216          self::validate_context($context);
 217  
 218          // Check if user can view this wiki.
 219          // We don't use wiki_user_can_view because it requires to have a valid subwiki for the user.
 220          if (!has_capability('mod/wiki:viewpage', $context)) {
 221              throw new moodle_exception('cannotviewpage', 'wiki');
 222          }
 223  
 224          // Trigger course_module_viewed event and completion.
 225          wiki_view($wiki, $course, $cm, $context);
 226  
 227          $result = array();
 228          $result['status'] = true;
 229          $result['warnings'] = $warnings;
 230          return $result;
 231      }
 232  
 233      /**
 234       * Describes the view_wiki return value.
 235       *
 236       * @return external_single_structure
 237       * @since Moodle 3.1
 238       */
 239      public static function view_wiki_returns() {
 240          return new external_single_structure(
 241              array(
 242                  'status' => new external_value(PARAM_BOOL, 'Status: true if success.'),
 243                  'warnings' => new external_warnings()
 244              )
 245          );
 246      }
 247  
 248      /**
 249       * Describes the parameters for view_page.
 250       *
 251       * @return external_function_parameters
 252       * @since Moodle 3.1
 253       */
 254      public static function view_page_parameters() {
 255          return new external_function_parameters (
 256              array(
 257                  'pageid' => new external_value(PARAM_INT, 'Wiki page ID.'),
 258              )
 259          );
 260      }
 261  
 262      /**
 263       * Trigger the page viewed event and update the module completion status.
 264       *
 265       * @param int $pageid The page ID.
 266       * @return array of warnings and status result.
 267       * @since Moodle 3.1
 268       * @throws moodle_exception if page is not valid.
 269       */
 270      public static function view_page($pageid) {
 271  
 272          $params = self::validate_parameters(self::view_page_parameters(),
 273                                              array(
 274                                                  'pageid' => $pageid
 275                                              ));
 276          $warnings = array();
 277  
 278          // Get wiki page.
 279          if (!$page = wiki_get_page($params['pageid'])) {
 280              throw new moodle_exception('incorrectpageid', 'wiki');
 281          }
 282  
 283          // Get wiki instance.
 284          if (!$wiki = wiki_get_wiki_from_pageid($params['pageid'])) {
 285              throw new moodle_exception('incorrectwikiid', 'wiki');
 286          }
 287  
 288          // Permission validation.
 289          list($course, $cm) = get_course_and_cm_from_instance($wiki, 'wiki');
 290          $context = context_module::instance($cm->id);
 291          self::validate_context($context);
 292  
 293          // Check if user can view this wiki.
 294          if (!$subwiki = wiki_get_subwiki($page->subwikiid)) {
 295              throw new moodle_exception('incorrectsubwikiid', 'wiki');
 296          }
 297          if (!wiki_user_can_view($subwiki, $wiki)) {
 298              throw new moodle_exception('cannotviewpage', 'wiki');
 299          }
 300  
 301          // Trigger page_viewed event and completion.
 302          wiki_page_view($wiki, $page, $course, $cm, $context);
 303  
 304          $result = array();
 305          $result['status'] = true;
 306          $result['warnings'] = $warnings;
 307          return $result;
 308      }
 309  
 310      /**
 311       * Describes the view_page return value.
 312       *
 313       * @return external_single_structure
 314       * @since Moodle 3.1
 315       */
 316      public static function view_page_returns() {
 317          return new external_single_structure(
 318              array(
 319                  'status' => new external_value(PARAM_BOOL, 'Status: true if success.'),
 320                  'warnings' => new external_warnings()
 321              )
 322          );
 323      }
 324  
 325      /**
 326       * Describes the parameters for get_subwikis.
 327       *
 328       * @return external_function_parameters
 329       * @since Moodle 3.1
 330       */
 331      public static function get_subwikis_parameters() {
 332          return new external_function_parameters (
 333              array(
 334                  'wikiid' => new external_value(PARAM_INT, 'Wiki instance ID.')
 335              )
 336          );
 337      }
 338  
 339      /**
 340       * Returns the list of subwikis the user can see in a specific wiki.
 341       *
 342       * @param int $wikiid The wiki instance ID.
 343       * @return array Containing a list of warnings and a list of subwikis.
 344       * @since Moodle 3.1
 345       */
 346      public static function get_subwikis($wikiid) {
 347          global $USER;
 348  
 349          $warnings = array();
 350  
 351          $params = self::validate_parameters(self::get_subwikis_parameters(), array('wikiid' => $wikiid));
 352  
 353          // Get wiki instance.
 354          if (!$wiki = wiki_get_wiki($params['wikiid'])) {
 355              throw new moodle_exception('incorrectwikiid', 'wiki');
 356          }
 357  
 358          // Validate context and capabilities.
 359          list($course, $cm) = get_course_and_cm_from_instance($wiki, 'wiki');
 360          $context = context_module::instance($cm->id);
 361          self::validate_context($context);
 362          require_capability('mod/wiki:viewpage', $context);
 363  
 364          $returnedsubwikis = wiki_get_visible_subwikis($wiki, $cm, $context);
 365          foreach ($returnedsubwikis as $subwiki) {
 366              $subwiki->canedit = wiki_user_can_edit($subwiki);
 367          }
 368  
 369          $result = array();
 370          $result['subwikis'] = $returnedsubwikis;
 371          $result['warnings'] = $warnings;
 372          return $result;
 373      }
 374  
 375      /**
 376       * Describes the get_subwikis return value.
 377       *
 378       * @return external_single_structure
 379       * @since Moodle 3.1
 380       */
 381      public static function get_subwikis_returns() {
 382          return new external_single_structure(
 383              array(
 384                  'subwikis' => new external_multiple_structure(
 385                      new external_single_structure(
 386                          array(
 387                              'id' => new external_value(PARAM_INT, 'Subwiki ID.'),
 388                              'wikiid' => new external_value(PARAM_INT, 'Wiki ID.'),
 389                              'groupid' => new external_value(PARAM_RAW, 'Group ID.'),
 390                              'userid' => new external_value(PARAM_INT, 'User ID.'),
 391                              'canedit' => new external_value(PARAM_BOOL, 'True if user can edit the subwiki.'),
 392                          ), 'Subwikis'
 393                      )
 394                  ),
 395                  'warnings' => new external_warnings(),
 396              )
 397          );
 398      }
 399  
 400      /**
 401       * Describes the parameters for get_subwiki_pages.
 402       *
 403       * @return external_function_parameters
 404       * @since Moodle 3.1
 405       */
 406      public static function get_subwiki_pages_parameters() {
 407          return new external_function_parameters (
 408              array(
 409                  'wikiid' => new external_value(PARAM_INT, 'Wiki instance ID.'),
 410                  'groupid' => new external_value(PARAM_INT, 'Subwiki\'s group ID, -1 means current group. It will be ignored'
 411                                          . ' if the wiki doesn\'t use groups.', VALUE_DEFAULT, -1),
 412                  'userid' => new external_value(PARAM_INT, 'Subwiki\'s user ID, 0 means current user. It will be ignored'
 413                                          .' in collaborative wikis.', VALUE_DEFAULT, 0),
 414                  'options' => new external_single_structure(
 415                              array(
 416                                      'sortby' => new external_value(PARAM_ALPHA,
 417                                              'Field to sort by (id, title, ...).', VALUE_DEFAULT, 'title'),
 418                                      'sortdirection' => new external_value(PARAM_ALPHA,
 419                                              'Sort direction: ASC or DESC.', VALUE_DEFAULT, 'ASC'),
 420                                      'includecontent' => new external_value(PARAM_INT,
 421                                              'Include each page contents or just the contents size.', VALUE_DEFAULT, 1),
 422                              ), 'Options', VALUE_DEFAULT, array()),
 423              )
 424          );
 425      }
 426  
 427      /**
 428       * Returns the list of pages from a specific subwiki.
 429       *
 430       * @param int $wikiid The wiki instance ID.
 431       * @param int $groupid The group ID. If not defined, use current group.
 432       * @param int $userid The user ID. If not defined, use current user.
 433       * @param array $options Several options like sort by, sort direction, ...
 434       * @return array Containing a list of warnings and a list of pages.
 435       * @since Moodle 3.1
 436       */
 437      public static function get_subwiki_pages($wikiid, $groupid = -1, $userid = 0, $options = array()) {
 438  
 439          $returnedpages = array();
 440          $warnings = array();
 441  
 442          $params = self::validate_parameters(self::get_subwiki_pages_parameters(),
 443                                              array(
 444                                                  'wikiid' => $wikiid,
 445                                                  'groupid' => $groupid,
 446                                                  'userid' => $userid,
 447                                                  'options' => $options
 448                                                  )
 449              );
 450  
 451          // Get wiki instance.
 452          if (!$wiki = wiki_get_wiki($params['wikiid'])) {
 453              throw new moodle_exception('incorrectwikiid', 'wiki');
 454          }
 455          list($course, $cm) = get_course_and_cm_from_instance($wiki, 'wiki');
 456          $context = context_module::instance($cm->id);
 457          self::validate_context($context);
 458  
 459          // Determine groupid and userid to use.
 460          list($groupid, $userid) = self::determine_group_and_user($cm, $wiki, $params['groupid'], $params['userid']);
 461  
 462          // Get subwiki and validate it.
 463          $subwiki = wiki_get_subwiki_by_group_and_user_with_validation($wiki, $groupid, $userid);
 464  
 465          if ($subwiki === false) {
 466              throw new moodle_exception('cannotviewpage', 'wiki');
 467          } else if ($subwiki->id != -1) {
 468  
 469              // Set sort param.
 470              $options = $params['options'];
 471              if (!empty($options['sortby'])) {
 472                  if ($options['sortdirection'] != 'ASC' && $options['sortdirection'] != 'DESC') {
 473                      // Invalid sort direction. Use default.
 474                      $options['sortdirection'] = 'ASC';
 475                  }
 476                  $sort = $options['sortby'] . ' ' . $options['sortdirection'];
 477              }
 478  
 479              $pages = wiki_get_page_list($subwiki->id, $sort);
 480              $caneditpages = wiki_user_can_edit($subwiki);
 481              $firstpage = wiki_get_first_page($subwiki->id);
 482  
 483              foreach ($pages as $page) {
 484                  $retpage = array(
 485                          'id' => $page->id,
 486                          'subwikiid' => $page->subwikiid,
 487                          'title' => external_format_string($page->title, $context->id),
 488                          'timecreated' => $page->timecreated,
 489                          'timemodified' => $page->timemodified,
 490                          'timerendered' => $page->timerendered,
 491                          'userid' => $page->userid,
 492                          'pageviews' => $page->pageviews,
 493                          'readonly' => $page->readonly,
 494                          'caneditpage' => $caneditpages,
 495                          'firstpage' => $page->id == $firstpage->id
 496                      );
 497  
 498                  // Refresh page cached content if needed.
 499                  if ($page->timerendered + WIKI_REFRESH_CACHE_TIME < time()) {
 500                      if ($content = wiki_refresh_cachedcontent($page)) {
 501                          $page = $content['page'];
 502                      }
 503                  }
 504                  list($cachedcontent, $contentformat) = external_format_text(
 505                              $page->cachedcontent, FORMAT_HTML, $context->id, 'mod_wiki', 'attachments', $subwiki->id);
 506  
 507                  if ($options['includecontent']) {
 508                      // Return the page content.
 509                      $retpage['cachedcontent'] = $cachedcontent;
 510                      $retpage['contentformat'] = $contentformat;
 511                  } else {
 512                      // Return the size of the content.
 513                      if (function_exists('mb_strlen') && ((int)ini_get('mbstring.func_overload') & 2)) {
 514                          $retpage['contentsize'] = mb_strlen($cachedcontent, '8bit');
 515                      } else {
 516                          $retpage['contentsize'] = strlen($cachedcontent);
 517                      }
 518                  }
 519  
 520                  $returnedpages[] = $retpage;
 521              }
 522          }
 523  
 524          $result = array();
 525          $result['pages'] = $returnedpages;
 526          $result['warnings'] = $warnings;
 527          return $result;
 528      }
 529  
 530      /**
 531       * Describes the get_subwiki_pages return value.
 532       *
 533       * @return external_single_structure
 534       * @since Moodle 3.1
 535       */
 536      public static function get_subwiki_pages_returns() {
 537  
 538          return new external_single_structure(
 539              array(
 540                  'pages' => new external_multiple_structure(
 541                      new external_single_structure(
 542                          array(
 543                              'id' => new external_value(PARAM_INT, 'Page ID.'),
 544                              'subwikiid' => new external_value(PARAM_INT, 'Page\'s subwiki ID.'),
 545                              'title' => new external_value(PARAM_RAW, 'Page title.'),
 546                              'timecreated' => new external_value(PARAM_INT, 'Time of creation.'),
 547                              'timemodified' => new external_value(PARAM_INT, 'Time of last modification.'),
 548                              'timerendered' => new external_value(PARAM_INT, 'Time of last renderization.'),
 549                              'userid' => new external_value(PARAM_INT, 'ID of the user that last modified the page.'),
 550                              'pageviews' => new external_value(PARAM_INT, 'Number of times the page has been viewed.'),
 551                              'readonly' => new external_value(PARAM_INT, '1 if readonly, 0 otherwise.'),
 552                              'caneditpage' => new external_value(PARAM_BOOL, 'True if user can edit the page.'),
 553                              'firstpage' => new external_value(PARAM_BOOL, 'True if it\'s the first page.'),
 554                              'cachedcontent' => new external_value(PARAM_RAW, 'Page contents.', VALUE_OPTIONAL),
 555                              'contentformat' => new external_format_value('cachedcontent', VALUE_OPTIONAL),
 556                              'contentsize' => new external_value(PARAM_INT, 'Size of page contents in bytes (doesn\'t include'.
 557                                                                              ' size of attached files).', VALUE_OPTIONAL),
 558                          ), 'Pages'
 559                      )
 560                  ),
 561                  'warnings' => new external_warnings(),
 562              )
 563          );
 564      }
 565  
 566      /**
 567       * Describes the parameters for get_page_contents.
 568       *
 569       * @return external_function_parameters
 570       * @since Moodle 3.1
 571       */
 572      public static function get_page_contents_parameters() {
 573          return new external_function_parameters (
 574              array(
 575                  'pageid' => new external_value(PARAM_INT, 'Page ID.')
 576              )
 577          );
 578      }
 579  
 580      /**
 581       * Get a page contents.
 582       *
 583       * @param int $pageid The page ID.
 584       * @return array of warnings and page data.
 585       * @since Moodle 3.1
 586       */
 587      public static function get_page_contents($pageid) {
 588  
 589          $params = self::validate_parameters(self::get_page_contents_parameters(),
 590                                              array(
 591                                                  'pageid' => $pageid
 592                                              )
 593              );
 594          $warnings = array();
 595  
 596          // Get wiki page.
 597          if (!$page = wiki_get_page($params['pageid'])) {
 598              throw new moodle_exception('incorrectpageid', 'wiki');
 599          }
 600  
 601          // Get wiki instance.
 602          if (!$wiki = wiki_get_wiki_from_pageid($params['pageid'])) {
 603              throw new moodle_exception('incorrectwikiid', 'wiki');
 604          }
 605  
 606          // Permission validation.
 607          $cm = get_coursemodule_from_instance('wiki', $wiki->id, $wiki->course);
 608          $context = context_module::instance($cm->id);
 609          self::validate_context($context);
 610  
 611          // Check if user can view this wiki.
 612          if (!$subwiki = wiki_get_subwiki($page->subwikiid)) {
 613              throw new moodle_exception('incorrectsubwikiid', 'wiki');
 614          }
 615          if (!wiki_user_can_view($subwiki, $wiki)) {
 616              throw new moodle_exception('cannotviewpage', 'wiki');
 617          }
 618  
 619          $returnedpage = array();
 620          $returnedpage['id'] = $page->id;
 621          $returnedpage['wikiid'] = $wiki->id;
 622          $returnedpage['subwikiid'] = $page->subwikiid;
 623          $returnedpage['groupid'] = $subwiki->groupid;
 624          $returnedpage['userid'] = $subwiki->userid;
 625          $returnedpage['title'] = $page->title;
 626  
 627          // Refresh page cached content if needed.
 628          if ($page->timerendered + WIKI_REFRESH_CACHE_TIME < time()) {
 629              if ($content = wiki_refresh_cachedcontent($page)) {
 630                  $page = $content['page'];
 631              }
 632          }
 633  
 634          list($returnedpage['cachedcontent'], $returnedpage['contentformat']) = external_format_text(
 635                              $page->cachedcontent, FORMAT_HTML, $context->id, 'mod_wiki', 'attachments', $subwiki->id);
 636          $returnedpage['caneditpage'] = wiki_user_can_edit($subwiki);
 637  
 638          $result = array();
 639          $result['page'] = $returnedpage;
 640          $result['warnings'] = $warnings;
 641          return $result;
 642      }
 643  
 644      /**
 645       * Describes the get_page_contents return value.
 646       *
 647       * @return external_single_structure
 648       * @since Moodle 3.1
 649       */
 650      public static function get_page_contents_returns() {
 651          return new external_single_structure(
 652              array(
 653                  'page' => new external_single_structure(
 654                      array(
 655                          'id' => new external_value(PARAM_INT, 'Page ID.'),
 656                          'wikiid' => new external_value(PARAM_INT, 'Page\'s wiki ID.'),
 657                          'subwikiid' => new external_value(PARAM_INT, 'Page\'s subwiki ID.'),
 658                          'groupid' => new external_value(PARAM_INT, 'Page\'s group ID.'),
 659                          'userid' => new external_value(PARAM_INT, 'Page\'s user ID.'),
 660                          'title' => new external_value(PARAM_RAW, 'Page title.'),
 661                          'cachedcontent' => new external_value(PARAM_RAW, 'Page contents.'),
 662                          'contentformat' => new external_format_value('cachedcontent', VALUE_OPTIONAL),
 663                          'caneditpage' => new external_value(PARAM_BOOL, 'True if user can edit the page.')
 664                      ), 'Page'
 665                  ),
 666                  'warnings' => new external_warnings()
 667              )
 668          );
 669      }
 670  
 671      /**
 672       * Describes the parameters for get_subwiki_files.
 673       *
 674       * @return external_function_parameters
 675       * @since Moodle 3.1
 676       */
 677      public static function get_subwiki_files_parameters() {
 678          return new external_function_parameters (
 679              array(
 680                  'wikiid' => new external_value(PARAM_INT, 'Wiki instance ID.'),
 681                  'groupid' => new external_value(PARAM_INT, 'Subwiki\'s group ID, -1 means current group. It will be ignored'
 682                                          . ' if the wiki doesn\'t use groups.', VALUE_DEFAULT, -1),
 683                  'userid' => new external_value(PARAM_INT, 'Subwiki\'s user ID, 0 means current user. It will be ignored'
 684                                          .' in collaborative wikis.', VALUE_DEFAULT, 0)
 685              )
 686          );
 687      }
 688  
 689      /**
 690       * Returns the list of files from a specific subwiki.
 691       *
 692       * @param int $wikiid The wiki instance ID.
 693       * @param int $groupid The group ID. If not defined, use current group.
 694       * @param int $userid The user ID. If not defined, use current user.
 695       * @return array Containing a list of warnings and a list of files.
 696       * @since Moodle 3.1
 697       * @throws moodle_exception
 698       */
 699      public static function get_subwiki_files($wikiid, $groupid = -1, $userid = 0) {
 700  
 701          $returnedfiles = array();
 702          $warnings = array();
 703  
 704          $params = self::validate_parameters(self::get_subwiki_files_parameters(),
 705                                              array(
 706                                                  'wikiid' => $wikiid,
 707                                                  'groupid' => $groupid,
 708                                                  'userid' => $userid
 709                                                  )
 710              );
 711  
 712          // Get wiki instance.
 713          if (!$wiki = wiki_get_wiki($params['wikiid'])) {
 714              throw new moodle_exception('incorrectwikiid', 'wiki');
 715          }
 716          list($course, $cm) = get_course_and_cm_from_instance($wiki, 'wiki');
 717          $context = context_module::instance($cm->id);
 718          self::validate_context($context);
 719  
 720          // Determine groupid and userid to use.
 721          list($groupid, $userid) = self::determine_group_and_user($cm, $wiki, $params['groupid'], $params['userid']);
 722  
 723          // Get subwiki and validate it.
 724          $subwiki = wiki_get_subwiki_by_group_and_user_with_validation($wiki, $groupid, $userid);
 725  
 726          // Get subwiki based on group and user.
 727          if ($subwiki === false) {
 728              throw new moodle_exception('cannotviewfiles', 'wiki');
 729          } else if ($subwiki->id != -1) {
 730              // The subwiki exists, let's get the files.
 731              $returnedfiles = external_util::get_area_files($context->id, 'mod_wiki', 'attachments', $subwiki->id);
 732          }
 733  
 734          $result = array();
 735          $result['files'] = $returnedfiles;
 736          $result['warnings'] = $warnings;
 737          return $result;
 738      }
 739  
 740      /**
 741       * Describes the get_subwiki_pages return value.
 742       *
 743       * @return external_single_structure
 744       * @since Moodle 3.1
 745       */
 746      public static function get_subwiki_files_returns() {
 747  
 748          return new external_single_structure(
 749              array(
 750                  'files' => new external_files('Files'),
 751                  'warnings' => new external_warnings(),
 752              )
 753          );
 754      }
 755  
 756      /**
 757       * Utility function for determining the groupid and userid to use.
 758       *
 759       * @param stdClass $cm The course module.
 760       * @param stdClass $wiki The wiki.
 761       * @param int $groupid Group ID. If not defined, use current group.
 762       * @param int $userid User ID. If not defined, use current user.
 763       * @return array Array containing the courseid and userid.
 764       * @since  Moodle 3.1
 765       */
 766      protected static function determine_group_and_user($cm, $wiki, $groupid = -1, $userid = 0) {
 767          global $USER;
 768  
 769          $currentgroup = groups_get_activity_group($cm);
 770          if ($currentgroup === false) {
 771              // Activity doesn't use groups.
 772              $groupid = 0;
 773          } else if ($groupid == -1) {
 774              // Use current group.
 775              $groupid = !empty($currentgroup) ? $currentgroup : 0;
 776          }
 777  
 778          // Determine user.
 779          if ($wiki->wikimode == 'collaborative') {
 780              // Collaborative wikis don't use userid in subwikis.
 781              $userid = 0;
 782          } else if (empty($userid)) {
 783              // Use current user.
 784              $userid = $USER->id;
 785          }
 786  
 787          return array($groupid, $userid);
 788      }
 789  
 790      /**
 791       * Describes the parameters for get_page_for_editing.
 792       *
 793       * @return external_function_parameters
 794       * @since Moodle 3.1
 795       */
 796      public static function get_page_for_editing_parameters() {
 797          return new external_function_parameters (
 798              array(
 799                  'pageid' => new external_value(PARAM_INT, 'Page ID to edit.'),
 800                  'section' => new external_value(PARAM_RAW, 'Section page title.', VALUE_DEFAULT, null)
 801              )
 802          );
 803      }
 804  
 805      /**
 806       * Locks and retrieves info of page-section to be edited.
 807       *
 808       * @param int $pageid The page ID.
 809       * @param string $section Section page title.
 810       * @return array of warnings and page data.
 811       * @since Moodle 3.1
 812       */
 813      public static function get_page_for_editing($pageid, $section = null) {
 814          global $USER;
 815  
 816          $params = self::validate_parameters(self::get_page_for_editing_parameters(),
 817                                              array(
 818                                                  'pageid' => $pageid,
 819                                                  'section' => $section
 820                                              )
 821              );
 822  
 823          $warnings = array();
 824  
 825          // Get wiki page.
 826          if (!$page = wiki_get_page($params['pageid'])) {
 827              throw new moodle_exception('incorrectpageid', 'wiki');
 828          }
 829  
 830          // Get wiki instance.
 831          if (!$wiki = wiki_get_wiki_from_pageid($params['pageid'])) {
 832              throw new moodle_exception('incorrectwikiid', 'wiki');
 833          }
 834  
 835          // Get subwiki instance.
 836          if (!$subwiki = wiki_get_subwiki($page->subwikiid)) {
 837              throw new moodle_exception('incorrectsubwikiid', 'wiki');
 838          }
 839  
 840          // Permission validation.
 841          $cm = get_coursemodule_from_instance('wiki', $wiki->id, $wiki->course);
 842          $context = context_module::instance($cm->id);
 843          self::validate_context($context);
 844  
 845          if (!wiki_user_can_edit($subwiki)) {
 846              throw new moodle_exception('cannoteditpage', 'wiki');
 847          }
 848  
 849          if (!wiki_set_lock($params['pageid'], $USER->id, $params['section'], true)) {
 850              throw new moodle_exception('pageislocked', 'wiki');
 851          }
 852  
 853          $version = wiki_get_current_version($page->id);
 854          if (empty($version)) {
 855              throw new moodle_exception('versionerror', 'wiki');
 856          }
 857  
 858          if (!is_null($params['section'])) {
 859              $content = wiki_parser_proxy::get_section($version->content, $version->contentformat, $params['section']);
 860          } else {
 861              $content = $version->content;
 862          }
 863  
 864          $pagesection = array();
 865          $pagesection['content'] = $content;
 866          $pagesection['contentformat'] = $version->contentformat;
 867          $pagesection['version'] = $version->version;
 868  
 869          $result = array();
 870          $result['pagesection'] = $pagesection;
 871          $result['warnings'] = $warnings;
 872          return $result;
 873  
 874      }
 875  
 876      /**
 877       * Describes the get_page_for_editing return value.
 878       *
 879       * @return external_single_structure
 880       * @since Moodle 3.1
 881       */
 882      public static function get_page_for_editing_returns() {
 883          return new external_single_structure(
 884              array(
 885                  'pagesection' => new external_single_structure(
 886                      array(
 887                          'content' => new external_value(PARAM_RAW, 'The contents of the page-section to be edited.'),
 888                          'contentformat' => new external_value(PARAM_TEXT, 'Format of the original content of the page.'),
 889                          'version' => new external_value(PARAM_INT, 'Latest version of the page.'),
 890                          'warnings' => new external_warnings()
 891                      )
 892                  )
 893              )
 894          );
 895      }
 896  
 897      /**
 898       * Describes the parameters for new_page.
 899       *
 900       * @return external_function_parameters
 901       * @since Moodle 3.1
 902       */
 903      public static function new_page_parameters() {
 904          return new external_function_parameters (
 905              array(
 906                  'title' => new external_value(PARAM_TEXT, 'New page title.'),
 907                  'content' => new external_value(PARAM_RAW, 'Page contents.'),
 908                  'contentformat' => new external_value(PARAM_TEXT, 'Page contents format. If an invalid format is provided, default
 909                      wiki format is used.', VALUE_DEFAULT, null),
 910                  'subwikiid' => new external_value(PARAM_INT, 'Page\'s subwiki ID.', VALUE_DEFAULT, null),
 911                  'wikiid' => new external_value(PARAM_INT, 'Page\'s wiki ID. Used if subwiki does not exists.', VALUE_DEFAULT,
 912                      null),
 913                  'userid' => new external_value(PARAM_INT, 'Subwiki\'s user ID. Used if subwiki does not exists.', VALUE_DEFAULT,
 914                      null),
 915                  'groupid' => new external_value(PARAM_INT, 'Subwiki\'s group ID. Used if subwiki does not exists.', VALUE_DEFAULT,
 916                      null)
 917              )
 918          );
 919      }
 920  
 921      /**
 922       * Creates a new page.
 923       *
 924       * @param string $title New page title.
 925       * @param string $content Page contents.
 926       * @param int $contentformat Page contents format. If an invalid format is provided, default wiki format is used.
 927       * @param int $subwikiid The Subwiki ID where to store the page.
 928       * @param int $wikiid Page\'s wiki ID. Used if subwiki does not exists.
 929       * @param int $userid Subwiki\'s user ID. Used if subwiki does not exists.
 930       * @param int $groupid Subwiki\'s group ID. Used if subwiki does not exists.
 931       * @return array of warnings and page data.
 932       * @since Moodle 3.1
 933       */
 934      public static function new_page($title, $content, $contentformat = null, $subwikiid = null, $wikiid = null, $userid = null,
 935          $groupid = null) {
 936          global $USER;
 937  
 938          $params = self::validate_parameters(self::new_page_parameters(),
 939                                              array(
 940                                                  'title' => $title,
 941                                                  'content' => $content,
 942                                                  'contentformat' => $contentformat,
 943                                                  'subwikiid' => $subwikiid,
 944                                                  'wikiid' => $wikiid,
 945                                                  'userid' => $userid,
 946                                                  'groupid' => $groupid
 947                                              )
 948              );
 949  
 950          $warnings = array();
 951  
 952          // Get wiki and subwiki instances.
 953          if (!empty($params['subwikiid'])) {
 954              if (!$subwiki = wiki_get_subwiki($params['subwikiid'])) {
 955                  throw new moodle_exception('incorrectsubwikiid', 'wiki');
 956              }
 957  
 958              if (!$wiki = wiki_get_wiki($subwiki->wikiid)) {
 959                  throw new moodle_exception('incorrectwikiid', 'wiki');
 960              }
 961  
 962              // Permission validation.
 963              $cm = get_coursemodule_from_instance('wiki', $wiki->id, $wiki->course);
 964              $context = context_module::instance($cm->id);
 965              self::validate_context($context);
 966  
 967          } else {
 968              if (!$wiki = wiki_get_wiki($params['wikiid'])) {
 969                  throw new moodle_exception('incorrectwikiid', 'wiki');
 970              }
 971  
 972              // Permission validation.
 973              $cm = get_coursemodule_from_instance('wiki', $wiki->id, $wiki->course);
 974              $context = context_module::instance($cm->id);
 975              self::validate_context($context);
 976  
 977              // Determine groupid and userid to use.
 978              list($groupid, $userid) = self::determine_group_and_user($cm, $wiki, $params['groupid'], $params['userid']);
 979  
 980              // Get subwiki and validate it.
 981              $subwiki = wiki_get_subwiki_by_group_and_user_with_validation($wiki, $groupid, $userid);
 982  
 983              if ($subwiki === false) {
 984                  // User cannot view page.
 985                  throw new moodle_exception('cannoteditpage', 'wiki');
 986              } else if ($subwiki->id < 0) {
 987                  // Subwiki needed to check edit permissions.
 988                  if (!wiki_user_can_edit($subwiki)) {
 989                      throw new moodle_exception('cannoteditpage', 'wiki');
 990                  }
 991  
 992                  // Subwiki does not exists and it can be created.
 993                  $swid = wiki_add_subwiki($wiki->id, $groupid, $userid);
 994                  if (!$subwiki = wiki_get_subwiki($swid)) {
 995                      throw new moodle_exception('incorrectsubwikiid', 'wiki');
 996                  }
 997              }
 998          }
 999  
1000          // Subwiki needed to check edit permissions.
1001          if (!wiki_user_can_edit($subwiki)) {
1002              throw new moodle_exception('cannoteditpage', 'wiki');
1003          }
1004  
1005          if ($page = wiki_get_page_by_title($subwiki->id, $params['title'])) {
1006              throw new moodle_exception('pageexists', 'wiki');
1007          }
1008  
1009          // Ignore invalid formats and use default instead.
1010          if (!$params['contentformat'] || $wiki->forceformat) {
1011              $params['contentformat'] = $wiki->defaultformat;
1012          } else {
1013              $formats = wiki_get_formats();
1014              if (!in_array($params['contentformat'], $formats)) {
1015                  $params['contentformat'] = $wiki->defaultformat;
1016              }
1017          }
1018  
1019          $newpageid = wiki_create_page($subwiki->id, $params['title'], $params['contentformat'], $USER->id);
1020  
1021          if (!$page = wiki_get_page($newpageid)) {
1022              throw new moodle_exception('incorrectpageid', 'wiki');
1023          }
1024  
1025          // Save content.
1026          $save = wiki_save_page($page, $params['content'], $USER->id);
1027  
1028          if (!$save) {
1029              throw new moodle_exception('savingerror', 'wiki');
1030          }
1031  
1032          $result = array();
1033          $result['pageid'] = $page->id;
1034          $result['warnings'] = $warnings;
1035          return $result;
1036      }
1037  
1038      /**
1039       * Describes the new_page return value.
1040       *
1041       * @return external_single_structure
1042       * @since Moodle 3.1
1043       */
1044      public static function new_page_returns() {
1045          return new external_single_structure(
1046              array(
1047                  'pageid' => new external_value(PARAM_INT, 'New page id.'),
1048                  'warnings' => new external_warnings()
1049              )
1050          );
1051      }
1052  
1053      /**
1054       * Describes the parameters for edit_page.
1055       *
1056       * @return external_function_parameters
1057       * @since Moodle 3.1
1058       */
1059      public static function edit_page_parameters() {
1060          return new external_function_parameters (
1061              array(
1062                  'pageid' => new external_value(PARAM_INT, 'Page ID.'),
1063                  'content' => new external_value(PARAM_RAW, 'Page contents.'),
1064                  'section' => new external_value(PARAM_RAW, 'Section page title.', VALUE_DEFAULT, null)
1065              )
1066          );
1067      }
1068  
1069      /**
1070       * Edit a page contents.
1071       *
1072       * @param int $pageid The page ID.
1073       * @param string $content Page contents.
1074       * @param int $section Section to be edited.
1075       * @return array of warnings and page data.
1076       * @since Moodle 3.1
1077       */
1078      public static function edit_page($pageid, $content, $section = null) {
1079          global $USER;
1080  
1081          $params = self::validate_parameters(self::edit_page_parameters(),
1082                                              array(
1083                                                  'pageid' => $pageid,
1084                                                  'content' => $content,
1085                                                  'section' => $section
1086                                              )
1087              );
1088          $warnings = array();
1089  
1090          // Get wiki page.
1091          if (!$page = wiki_get_page($params['pageid'])) {
1092              throw new moodle_exception('incorrectpageid', 'wiki');
1093          }
1094  
1095          // Get wiki instance.
1096          if (!$wiki = wiki_get_wiki_from_pageid($params['pageid'])) {
1097              throw new moodle_exception('incorrectwikiid', 'wiki');
1098          }
1099  
1100          // Get subwiki instance.
1101          if (!$subwiki = wiki_get_subwiki($page->subwikiid)) {
1102              throw new moodle_exception('incorrectsubwikiid', 'wiki');
1103          }
1104  
1105          // Permission validation.
1106          $cm = get_coursemodule_from_instance('wiki', $wiki->id, $wiki->course);
1107          $context = context_module::instance($cm->id);
1108          self::validate_context($context);
1109  
1110          if (!wiki_user_can_edit($subwiki)) {
1111              throw new moodle_exception('cannoteditpage', 'wiki');
1112          }
1113  
1114          if (wiki_is_page_section_locked($page->id, $USER->id, $params['section'])) {
1115              throw new moodle_exception('pageislocked', 'wiki');
1116          }
1117  
1118          // Save content.
1119          if (!is_null($params['section'])) {
1120              $version = wiki_get_current_version($page->id);
1121              $content = wiki_parser_proxy::get_section($version->content, $version->contentformat, $params['section'], false);
1122              if (!$content) {
1123                  throw new moodle_exception('invalidsection', 'wiki');
1124              }
1125  
1126              $save = wiki_save_section($page, $params['section'], $params['content'], $USER->id);
1127          } else {
1128              $save = wiki_save_page($page, $params['content'], $USER->id);
1129          }
1130  
1131          wiki_delete_locks($page->id, $USER->id, $params['section']);
1132  
1133          if (!$save) {
1134              throw new moodle_exception('savingerror', 'wiki');
1135          }
1136  
1137          $result = array();
1138          $result['pageid'] = $page->id;
1139          $result['warnings'] = $warnings;
1140          return $result;
1141      }
1142  
1143      /**
1144       * Describes the edit_page return value.
1145       *
1146       * @return external_single_structure
1147       * @since Moodle 3.1
1148       */
1149      public static function edit_page_returns() {
1150          return new external_single_structure(
1151              array(
1152                  'pageid' => new external_value(PARAM_INT, 'Edited page id.'),
1153                  'warnings' => new external_warnings()
1154              )
1155          );
1156      }
1157  
1158  }