Search moodle.org's
Developer Documentation

   1  <?php
   2  
   3  // This file is part of Moodle - http://moodle.org/
   4  //
   5  // Moodle is free software: you can redistribute it and/or modify
   6  // it under the terms of the GNU General Public License as published by
   7  // the Free Software Foundation, either version 3 of the License, or
   8  // (at your option) any later version.
   9  //
  10  // Moodle is distributed in the hope that it will be useful,
  11  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  // GNU General Public License for more details.
  14  //
  15  // You should have received a copy of the GNU General Public License
  16  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  17  
  18  /**
  19   * External forum API
  20   *
  21   * @package    mod_forum
  22   * @copyright  2012 Mark Nelson <markn@moodle.com>
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  defined('MOODLE_INTERNAL') || die;
  27  
  28  require_once("$CFG->libdir/externallib.php");
  29  
  30  class mod_forum_external extends external_api {
  31  
  32      /**
  33       * Describes the parameters for get_forum.
  34       *
  35       * @return external_external_function_parameters
  36       * @since Moodle 2.5
  37       */
  38      public static function get_forums_by_courses_parameters() {
  39          return new external_function_parameters (
  40              array(
  41                  'courseids' => new external_multiple_structure(new external_value(PARAM_INT, 'course ID',
  42                          '', VALUE_REQUIRED, '', NULL_NOT_ALLOWED), 'Array of Course IDs', VALUE_DEFAULT, array()),
  43              )
  44          );
  45      }
  46  
  47      /**
  48       * Returns a list of forums in a provided list of courses,
  49       * if no list is provided all forums that the user can view
  50       * will be returned.
  51       *
  52       * @param array $courseids the course ids
  53       * @return array the forum details
  54       * @since Moodle 2.5
  55       */
  56      public static function get_forums_by_courses($courseids = array()) {
  57          global $CFG;
  58  
  59          require_once($CFG->dirroot . "/mod/forum/lib.php");
  60  
  61          $params = self::validate_parameters(self::get_forums_by_courses_parameters(), array('courseids' => $courseids));
  62  
  63          if (empty($params['courseids'])) {
  64              // Get all the courses the user can view.
  65              $courseids = array_keys(enrol_get_my_courses());
  66          } else {
  67              $courseids = $params['courseids'];
  68          }
  69  
  70          // Array to store the forums to return.
  71          $arrforums = array();
  72  
  73          // Ensure there are courseids to loop through.
  74          if (!empty($courseids)) {
  75              // Array of the courses we are going to retrieve the forums from.
  76              $dbcourses = array();
  77              // Mod info for courses.
  78              $modinfocourses = array();
  79  
  80              // Go through the courseids and return the forums.
  81              foreach ($courseids as $courseid) {
  82                  // Check the user can function in this context.
  83                  try {
  84                      $context = context_course::instance($courseid);
  85                      self::validate_context($context);
  86                      // Get the modinfo for the course.
  87                      $modinfocourses[$courseid] = get_fast_modinfo($courseid);
  88                      $dbcourses[$courseid] = $modinfocourses[$courseid]->get_course();
  89  
  90                  } catch (Exception $e) {
  91                      continue;
  92                  }
  93              }
  94  
  95              // Get the forums in this course. This function checks users visibility permissions.
  96              if ($forums = get_all_instances_in_courses("forum", $dbcourses)) {
  97                  foreach ($forums as $forum) {
  98  
  99                      $course = $dbcourses[$forum->course];
 100                      $cm = $modinfocourses[$course->id]->get_cm($forum->coursemodule);
 101                      $context = context_module::instance($cm->id);
 102  
 103                      // Skip forums we are not allowed to see discussions.
 104                      if (!has_capability('mod/forum:viewdiscussion', $context)) {
 105                          continue;
 106                      }
 107  
 108                      // Format the intro before being returning using the format setting.
 109                      list($forum->intro, $forum->introformat) = external_format_text($forum->intro, $forum->introformat,
 110                                                                                      $context->id, 'mod_forum', 'intro', 0);
 111                      // Discussions count. This function does static request cache.
 112                      $forum->numdiscussions = forum_count_discussions($forum, $cm, $course);
 113                      $forum->cmid = $forum->coursemodule;
 114  
 115                      // Add the forum to the array to return.
 116                      $arrforums[$forum->id] = $forum;
 117                  }
 118              }
 119          }
 120  
 121          return $arrforums;
 122      }
 123  
 124      /**
 125       * Describes the get_forum return value.
 126       *
 127       * @return external_single_structure
 128       * @since Moodle 2.5
 129       */
 130       public static function get_forums_by_courses_returns() {
 131          return new external_multiple_structure(
 132              new external_single_structure(
 133                  array(
 134                      'id' => new external_value(PARAM_INT, 'Forum id'),
 135                      'course' => new external_value(PARAM_INT, 'Course id'),
 136                      'type' => new external_value(PARAM_TEXT, 'The forum type'),
 137                      'name' => new external_value(PARAM_TEXT, 'Forum name'),
 138                      'intro' => new external_value(PARAM_RAW, 'The forum intro'),
 139                      'introformat' => new external_format_value('intro'),
 140                      'assessed' => new external_value(PARAM_INT, 'Aggregate type'),
 141                      'assesstimestart' => new external_value(PARAM_INT, 'Assess start time'),
 142                      'assesstimefinish' => new external_value(PARAM_INT, 'Assess finish time'),
 143                      'scale' => new external_value(PARAM_INT, 'Scale'),
 144                      'maxbytes' => new external_value(PARAM_INT, 'Maximum attachment size'),
 145                      'maxattachments' => new external_value(PARAM_INT, 'Maximum number of attachments'),
 146                      'forcesubscribe' => new external_value(PARAM_INT, 'Force users to subscribe'),
 147                      'trackingtype' => new external_value(PARAM_INT, 'Subscription mode'),
 148                      'rsstype' => new external_value(PARAM_INT, 'RSS feed for this activity'),
 149                      'rssarticles' => new external_value(PARAM_INT, 'Number of RSS recent articles'),
 150                      'timemodified' => new external_value(PARAM_INT, 'Time modified'),
 151                      'warnafter' => new external_value(PARAM_INT, 'Post threshold for warning'),
 152                      'blockafter' => new external_value(PARAM_INT, 'Post threshold for blocking'),
 153                      'blockperiod' => new external_value(PARAM_INT, 'Time period for blocking'),
 154                      'completiondiscussions' => new external_value(PARAM_INT, 'Student must create discussions'),
 155                      'completionreplies' => new external_value(PARAM_INT, 'Student must post replies'),
 156                      'completionposts' => new external_value(PARAM_INT, 'Student must post discussions or replies'),
 157                      'cmid' => new external_value(PARAM_INT, 'Course module id'),
 158                      'numdiscussions' => new external_value(PARAM_INT, 'Number of discussions in the forum', VALUE_OPTIONAL)
 159                  ), 'forum'
 160              )
 161          );
 162      }
 163  
 164      /**
 165       * Describes the parameters for get_forum_discussions.
 166       *
 167       * @return external_external_function_parameters
 168       * @since Moodle 2.5
 169       * @deprecated Moodle 2.8 MDL-46458 - Please do not call this function any more.
 170       * @see get_forum_discussions_paginated
 171       */
 172      public static function get_forum_discussions_parameters() {
 173          return new external_function_parameters (
 174              array(
 175                  'forumids' => new external_multiple_structure(new external_value(PARAM_INT, 'forum ID',
 176                          '', VALUE_REQUIRED, '', NULL_NOT_ALLOWED), 'Array of Forum IDs', VALUE_REQUIRED),
 177                  'limitfrom' => new external_value(PARAM_INT, 'limit from', VALUE_DEFAULT, 0),
 178                  'limitnum' => new external_value(PARAM_INT, 'limit number', VALUE_DEFAULT, 0)
 179              )
 180          );
 181      }
 182  
 183      /**
 184       * Returns a list of forum discussions as well as a summary of the discussion
 185       * in a provided list of forums.
 186       *
 187       * @param array $forumids the forum ids
 188       * @param int $limitfrom limit from SQL data
 189       * @param int $limitnum limit number SQL data
 190       *
 191       * @return array the forum discussion details
 192       * @since Moodle 2.5
 193       * @deprecated Moodle 2.8 MDL-46458 - Please do not call this function any more.
 194       * @see get_forum_discussions_paginated
 195       */
 196      public static function get_forum_discussions($forumids, $limitfrom = 0, $limitnum = 0) {
 197          global $CFG, $DB, $USER;
 198  
 199          require_once($CFG->dirroot . "/mod/forum/lib.php");
 200  
 201          // Validate the parameter.
 202          $params = self::validate_parameters(self::get_forum_discussions_parameters(),
 203              array(
 204                  'forumids'  => $forumids,
 205                  'limitfrom' => $limitfrom,
 206                  'limitnum'  => $limitnum,
 207              ));
 208          $forumids  = $params['forumids'];
 209          $limitfrom = $params['limitfrom'];
 210          $limitnum  = $params['limitnum'];
 211  
 212          // Array to store the forum discussions to return.
 213          $arrdiscussions = array();
 214          // Keep track of the users we have looked up in the DB.
 215          $arrusers = array();
 216  
 217          // Loop through them.
 218          foreach ($forumids as $id) {
 219              // Get the forum object.
 220              $forum = $DB->get_record('forum', array('id' => $id), '*', MUST_EXIST);
 221              $course = get_course($forum->course);
 222  
 223              $modinfo = get_fast_modinfo($course);
 224              $forums  = $modinfo->get_instances_of('forum');
 225              $cm = $forums[$forum->id];
 226  
 227              // Get the module context.
 228              $modcontext = context_module::instance($cm->id);
 229  
 230              // Validate the context.
 231              self::validate_context($modcontext);
 232  
 233              require_capability('mod/forum:viewdiscussion', $modcontext);
 234  
 235              // Get the discussions for this forum.
 236              $params = array();
 237  
 238              $groupselect = "";
 239              $groupmode = groups_get_activity_groupmode($cm, $course);
 240  
 241              if ($groupmode and $groupmode != VISIBLEGROUPS and !has_capability('moodle/site:accessallgroups', $modcontext)) {
 242                  // Get all the discussions from all the groups this user belongs to.
 243                  $usergroups = groups_get_user_groups($course->id);
 244                  if (!empty($usergroups['0'])) {
 245                      list($sql, $params) = $DB->get_in_or_equal($usergroups['0']);
 246                      $groupselect = "AND (groupid $sql OR groupid = -1)";
 247                  }
 248              }
 249              array_unshift($params, $id);
 250              $select = "forum = ? $groupselect";
 251  
 252              if ($discussions = $DB->get_records_select('forum_discussions', $select, $params, 'timemodified DESC', '*',
 253                                                              $limitfrom, $limitnum)) {
 254  
 255                  // Check if they can view full names.
 256                  $canviewfullname = has_capability('moodle/site:viewfullnames', $modcontext);
 257                  // Get the unreads array, this takes a forum id and returns data for all discussions.
 258                  $unreads = array();
 259                  if ($cantrack = forum_tp_can_track_forums($forum)) {
 260                      if ($forumtracked = forum_tp_is_tracked($forum)) {
 261                          $unreads = forum_get_discussions_unread($cm);
 262                      }
 263                  }
 264                  // The forum function returns the replies for all the discussions in a given forum.
 265                  $replies = forum_count_discussion_replies($id);
 266  
 267                  foreach ($discussions as $discussion) {
 268                      // This function checks capabilities, timed discussions, groups and qanda forums posting.
 269                      if (!forum_user_can_see_discussion($forum, $discussion, $modcontext)) {
 270                          continue;
 271                      }
 272  
 273                      $usernamefields = user_picture::fields();
 274                      // If we don't have the users details then perform DB call.
 275                      if (empty($arrusers[$discussion->userid])) {
 276                          $arrusers[$discussion->userid] = $DB->get_record('user', array('id' => $discussion->userid),
 277                                  $usernamefields, MUST_EXIST);
 278                      }
 279                      // Get the subject.
 280                      $subject = $DB->get_field('forum_posts', 'subject', array('id' => $discussion->firstpost), MUST_EXIST);
 281                      // Create object to return.
 282                      $return = new stdClass();
 283                      $return->id = (int) $discussion->id;
 284                      $return->course = $discussion->course;
 285                      $return->forum = $discussion->forum;
 286                      $return->name = $discussion->name;
 287                      $return->userid = $discussion->userid;
 288                      $return->groupid = $discussion->groupid;
 289                      $return->assessed = $discussion->assessed;
 290                      $return->timemodified = (int) $discussion->timemodified;
 291                      $return->usermodified = $discussion->usermodified;
 292                      $return->timestart = $discussion->timestart;
 293                      $return->timeend = $discussion->timeend;
 294                      $return->firstpost = (int) $discussion->firstpost;
 295                      $return->firstuserfullname = fullname($arrusers[$discussion->userid], $canviewfullname);
 296                      $return->firstuserimagealt = $arrusers[$discussion->userid]->imagealt;
 297                      $return->firstuserpicture = $arrusers[$discussion->userid]->picture;
 298                      $return->firstuseremail = $arrusers[$discussion->userid]->email;
 299                      $return->subject = $subject;
 300                      $return->numunread = '';
 301                      if ($cantrack && $forumtracked) {
 302                          if (isset($unreads[$discussion->id])) {
 303                              $return->numunread = (int) $unreads[$discussion->id];
 304                          }
 305                      }
 306                      // Check if there are any replies to this discussion.
 307                      if (!empty($replies[$discussion->id])) {
 308                           $return->numreplies = (int) $replies[$discussion->id]->replies;
 309                           $return->lastpost = (int) $replies[$discussion->id]->lastpostid;
 310                      } else { // No replies, so the last post will be the first post.
 311                          $return->numreplies = 0;
 312                          $return->lastpost = (int) $discussion->firstpost;
 313                      }
 314                      // Get the last post as well as the user who made it.
 315                      $lastpost = $DB->get_record('forum_posts', array('id' => $return->lastpost), '*', MUST_EXIST);
 316                      if (empty($arrusers[$lastpost->userid])) {
 317                          $arrusers[$lastpost->userid] = $DB->get_record('user', array('id' => $lastpost->userid),
 318                                  $usernamefields, MUST_EXIST);
 319                      }
 320                      $return->lastuserid = $lastpost->userid;
 321                      $return->lastuserfullname = fullname($arrusers[$lastpost->userid], $canviewfullname);
 322                      $return->lastuserimagealt = $arrusers[$lastpost->userid]->imagealt;
 323                      $return->lastuserpicture = $arrusers[$lastpost->userid]->picture;
 324                      $return->lastuseremail = $arrusers[$lastpost->userid]->email;
 325                      // Add the discussion statistics to the array to return.
 326                      $arrdiscussions[$return->id] = (array) $return;
 327                  }
 328              }
 329          }
 330  
 331          return $arrdiscussions;
 332      }
 333  
 334      /**
 335       * Describes the get_forum_discussions return value.
 336       *
 337       * @return external_single_structure
 338       * @since Moodle 2.5
 339       * @deprecated Moodle 2.8 MDL-46458 - Please do not call this function any more.
 340       * @see get_forum_discussions_paginated
 341       */
 342       public static function get_forum_discussions_returns() {
 343          return new external_multiple_structure(
 344              new external_single_structure(
 345                  array(
 346                      'id' => new external_value(PARAM_INT, 'Forum id'),
 347                      'course' => new external_value(PARAM_INT, 'Course id'),
 348                      'forum' => new external_value(PARAM_INT, 'The forum id'),
 349                      'name' => new external_value(PARAM_TEXT, 'Discussion name'),
 350                      'userid' => new external_value(PARAM_INT, 'User id'),
 351                      'groupid' => new external_value(PARAM_INT, 'Group id'),
 352                      'assessed' => new external_value(PARAM_INT, 'Is this assessed?'),
 353                      'timemodified' => new external_value(PARAM_INT, 'Time modified'),
 354                      'usermodified' => new external_value(PARAM_INT, 'The id of the user who last modified'),
 355                      'timestart' => new external_value(PARAM_INT, 'Time discussion can start'),
 356                      'timeend' => new external_value(PARAM_INT, 'Time discussion ends'),
 357                      'firstpost' => new external_value(PARAM_INT, 'The first post in the discussion'),
 358                      'firstuserfullname' => new external_value(PARAM_TEXT, 'The discussion creators fullname'),
 359                      'firstuserimagealt' => new external_value(PARAM_TEXT, 'The discussion creators image alt'),
 360                      'firstuserpicture' => new external_value(PARAM_INT, 'The discussion creators profile picture'),
 361                      'firstuseremail' => new external_value(PARAM_TEXT, 'The discussion creators email'),
 362                      'subject' => new external_value(PARAM_TEXT, 'The discussion subject'),
 363                      'numreplies' => new external_value(PARAM_TEXT, 'The number of replies in the discussion'),
 364                      'numunread' => new external_value(PARAM_TEXT, 'The number of unread posts, blank if this value is
 365                          not available due to forum settings.'),
 366                      'lastpost' => new external_value(PARAM_INT, 'The id of the last post in the discussion'),
 367                      'lastuserid' => new external_value(PARAM_INT, 'The id of the user who made the last post'),
 368                      'lastuserfullname' => new external_value(PARAM_TEXT, 'The last person to posts fullname'),
 369                      'lastuserimagealt' => new external_value(PARAM_TEXT, 'The last person to posts image alt'),
 370                      'lastuserpicture' => new external_value(PARAM_INT, 'The last person to posts profile picture'),
 371                      'lastuseremail' => new external_value(PARAM_TEXT, 'The last person to posts email'),
 372                  ), 'discussion'
 373              )
 374          );
 375      }
 376  
 377      /**
 378       * Describes the parameters for get_forum_discussion_posts.
 379       *
 380       * @return external_external_function_parameters
 381       * @since Moodle 2.7
 382       */
 383      public static function get_forum_discussion_posts_parameters() {
 384          return new external_function_parameters (
 385              array(
 386                  'discussionid' => new external_value(PARAM_INT, 'discussion ID', VALUE_REQUIRED),
 387                  'sortby' => new external_value(PARAM_ALPHA,
 388                      'sort by this element: id, created or modified', VALUE_DEFAULT, 'created'),
 389                  'sortdirection' => new external_value(PARAM_ALPHA, 'sort direction: ASC or DESC', VALUE_DEFAULT, 'DESC')
 390              )
 391          );
 392      }
 393  
 394      /**
 395       * Returns a list of forum posts for a discussion
 396       *
 397       * @param int $discussionid the post ids
 398       * @param string $sortby sort by this element (id, created or modified)
 399       * @param string $sortdirection sort direction: ASC or DESC
 400       *
 401       * @return array the forum post details
 402       * @since Moodle 2.7
 403       */
 404      public static function get_forum_discussion_posts($discussionid, $sortby = "created", $sortdirection = "DESC") {
 405          global $CFG, $DB, $USER;
 406  
 407          $posts = array();
 408          $warnings = array();
 409  
 410          // Validate the parameter.
 411          $params = self::validate_parameters(self::get_forum_discussion_posts_parameters(),
 412              array(
 413                  'discussionid' => $discussionid,
 414                  'sortby' => $sortby,
 415                  'sortdirection' => $sortdirection));
 416  
 417          // Compact/extract functions are not recommended.
 418          $discussionid   = $params['discussionid'];
 419          $sortby         = $params['sortby'];
 420          $sortdirection  = $params['sortdirection'];
 421  
 422          $sortallowedvalues = array('id', 'created', 'modified');
 423          if (!in_array($sortby, $sortallowedvalues)) {
 424              throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $sortby . '),' .
 425                  'allowed values are: ' . implode(',', $sortallowedvalues));
 426          }
 427  
 428          $sortdirection = strtoupper($sortdirection);
 429          $directionallowedvalues = array('ASC', 'DESC');
 430          if (!in_array($sortdirection, $directionallowedvalues)) {
 431              throw new invalid_parameter_exception('Invalid value for sortdirection parameter (value: ' . $sortdirection . '),' .
 432                  'allowed values are: ' . implode(',', $directionallowedvalues));
 433          }
 434  
 435          $discussion = $DB->get_record('forum_discussions', array('id' => $discussionid), '*', MUST_EXIST);
 436          $forum = $DB->get_record('forum', array('id' => $discussion->forum), '*', MUST_EXIST);
 437          $course = $DB->get_record('course', array('id' => $forum->course), '*', MUST_EXIST);
 438          $cm = get_coursemodule_from_instance('forum', $forum->id, $course->id, false, MUST_EXIST);
 439  
 440          // Validate the module context. It checks everything that affects the module visibility (including groupings, etc..).
 441          $modcontext = context_module::instance($cm->id);
 442          self::validate_context($modcontext);
 443  
 444          // This require must be here, see mod/forum/discuss.php.
 445          require_once($CFG->dirroot . "/mod/forum/lib.php");
 446  
 447          // Check they have the view forum capability.
 448          require_capability('mod/forum:viewdiscussion', $modcontext, null, true, 'noviewdiscussionspermission', 'forum');
 449  
 450          if (! $post = forum_get_post_full($discussion->firstpost)) {
 451              throw new moodle_exception('notexists', 'forum');
 452          }
 453  
 454          // This function check groups, qanda, timed discussions, etc.
 455          if (!forum_user_can_see_post($forum, $discussion, $post, null, $cm)) {
 456              throw new moodle_exception('noviewdiscussionspermission', 'forum');
 457          }
 458  
 459          $canviewfullname = has_capability('moodle/site:viewfullnames', $modcontext);
 460  
 461          // We will add this field in the response.
 462          $canreply = forum_user_can_post($forum, $discussion, $USER, $cm, $course, $modcontext);
 463  
 464          $forumtracked = forum_tp_is_tracked($forum);
 465  
 466          $sort = 'p.' . $sortby . ' ' . $sortdirection;
 467          $allposts = forum_get_all_discussion_posts($discussion->id, $sort, $forumtracked);
 468  
 469          foreach ($allposts as $post) {
 470  
 471              if (!forum_user_can_see_post($forum, $discussion, $post, null, $cm)) {
 472                  $warning = array();
 473                  $warning['item'] = 'post';
 474                  $warning['itemid'] = $post->id;
 475                  $warning['warningcode'] = '1';
 476                  $warning['message'] = 'You can\'t see this post';
 477                  $warnings[] = $warning;
 478                  continue;
 479              }
 480  
 481              // Function forum_get_all_discussion_posts adds postread field.
 482              // Note that the value returned can be a boolean or an integer. The WS expects a boolean.
 483              if (empty($post->postread)) {
 484                  $post->postread = false;
 485              } else {
 486                  $post->postread = true;
 487              }
 488  
 489              $post->canreply = $canreply;
 490              if (!empty($post->children)) {
 491                  $post->children = array_keys($post->children);
 492              } else {
 493                  $post->children = array();
 494              }
 495  
 496              $user = new stdclass();
 497              $user->id = $post->userid;
 498              $user = username_load_fields_from_object($user, $post);
 499              $post->userfullname = fullname($user, $canviewfullname);
 500  
 501              // We can have post written by users that are deleted. In this case, those users don't have a valid context.
 502              $usercontext = context_user::instance($user->id, IGNORE_MISSING);
 503              if ($usercontext) {
 504                  $post->userpictureurl = moodle_url::make_webservice_pluginfile_url(
 505                          $usercontext->id, 'user', 'icon', null, '/', 'f1')->out(false);
 506              } else {
 507                  $post->userpictureurl = '';
 508              }
 509  
 510              // Rewrite embedded images URLs.
 511              list($post->message, $post->messageformat) =
 512                  external_format_text($post->message, $post->messageformat, $modcontext->id, 'mod_forum', 'post', $post->id);
 513  
 514              // List attachments.
 515              if (!empty($post->attachment)) {
 516                  $post->attachments = array();
 517  
 518                  $fs = get_file_storage();
 519                  if ($files = $fs->get_area_files($modcontext->id, 'mod_forum', 'attachment', $post->id, "filename", false)) {
 520                      foreach ($files as $file) {
 521                          $filename = $file->get_filename();
 522                          $fileurl = moodle_url::make_webservice_pluginfile_url(
 523                                          $modcontext->id, 'mod_forum', 'attachment', $post->id, '/', $filename);
 524  
 525                          $post->attachments[] = array(
 526                              'filename' => $filename,
 527                              'mimetype' => $file->get_mimetype(),
 528                              'fileurl'  => $fileurl->out(false)
 529                          );
 530                      }
 531                  }
 532              }
 533  
 534              $posts[] = $post;
 535          }
 536  
 537          $result = array();
 538          $result['posts'] = $posts;
 539          $result['warnings'] = $warnings;
 540          return $result;
 541      }
 542  
 543      /**
 544       * Describes the get_forum_discussion_posts return value.
 545       *
 546       * @return external_single_structure
 547       * @since Moodle 2.7
 548       */
 549      public static function get_forum_discussion_posts_returns() {
 550          return new external_single_structure(
 551              array(
 552                  'posts' => new external_multiple_structure(
 553                          new external_single_structure(
 554                              array(
 555                                  'id' => new external_value(PARAM_INT, 'Post id'),
 556                                  'discussion' => new external_value(PARAM_INT, 'Discussion id'),
 557                                  'parent' => new external_value(PARAM_INT, 'Parent id'),
 558                                  'userid' => new external_value(PARAM_INT, 'User id'),
 559                                  'created' => new external_value(PARAM_INT, 'Creation time'),
 560                                  'modified' => new external_value(PARAM_INT, 'Time modified'),
 561                                  'mailed' => new external_value(PARAM_INT, 'Mailed?'),
 562                                  'subject' => new external_value(PARAM_TEXT, 'The post subject'),
 563                                  'message' => new external_value(PARAM_RAW, 'The post message'),
 564                                  'messageformat' => new external_format_value('message'),
 565                                  'messagetrust' => new external_value(PARAM_INT, 'Can we trust?'),
 566                                  'attachment' => new external_value(PARAM_RAW, 'Has attachments?'),
 567                                  'attachments' => new external_multiple_structure(
 568                                      new external_single_structure(
 569                                          array (
 570                                              'filename' => new external_value(PARAM_FILE, 'file name'),
 571                                              'mimetype' => new external_value(PARAM_RAW, 'mime type'),
 572                                              'fileurl'  => new external_value(PARAM_URL, 'file download url')
 573                                          )
 574                                      ), 'attachments', VALUE_OPTIONAL
 575                                  ),
 576                                  'totalscore' => new external_value(PARAM_INT, 'The post message total score'),
 577                                  'mailnow' => new external_value(PARAM_INT, 'Mail now?'),
 578                                  'children' => new external_multiple_structure(new external_value(PARAM_INT, 'children post id')),
 579                                  'canreply' => new external_value(PARAM_BOOL, 'The user can reply to posts?'),
 580                                  'postread' => new external_value(PARAM_BOOL, 'The post was read'),
 581                                  'userfullname' => new external_value(PARAM_TEXT, 'Post author full name'),
 582                                  'userpictureurl' => new external_value(PARAM_URL, 'Post author picture.', VALUE_OPTIONAL)
 583                              ), 'post'
 584                          )
 585                      ),
 586                  'warnings' => new external_warnings()
 587              )
 588          );
 589      }
 590  
 591      /**
 592       * Describes the parameters for get_forum_discussions_paginated.
 593       *
 594       * @return external_external_function_parameters
 595       * @since Moodle 2.8
 596       */
 597      public static function get_forum_discussions_paginated_parameters() {
 598          return new external_function_parameters (
 599              array(
 600                  'forumid' => new external_value(PARAM_INT, 'forum instance id', VALUE_REQUIRED),
 601                  'sortby' => new external_value(PARAM_ALPHA,
 602                      'sort by this element: id, timemodified, timestart or timeend', VALUE_DEFAULT, 'timemodified'),
 603                  'sortdirection' => new external_value(PARAM_ALPHA, 'sort direction: ASC or DESC', VALUE_DEFAULT, 'DESC'),
 604                  'page' => new external_value(PARAM_INT, 'current page', VALUE_DEFAULT, -1),
 605                  'perpage' => new external_value(PARAM_INT, 'items per page', VALUE_DEFAULT, 0),
 606              )
 607          );
 608      }
 609  
 610      /**
 611       * Returns a list of forum discussions optionally sorted and paginated.
 612       *
 613       * @param int $forumid the forum instance id
 614       * @param string $sortby sort by this element (id, timemodified, timestart or timeend)
 615       * @param string $sortdirection sort direction: ASC or DESC
 616       * @param int $page page number
 617       * @param int $perpage items per page
 618       *
 619       * @return array the forum discussion details including warnings
 620       * @since Moodle 2.8
 621       */
 622      public static function get_forum_discussions_paginated($forumid, $sortby = 'timemodified', $sortdirection = 'DESC',
 623                                                      $page = -1, $perpage = 0) {
 624          global $CFG, $DB, $USER;
 625  
 626          require_once($CFG->dirroot . "/mod/forum/lib.php");
 627  
 628          $warnings = array();
 629          $discussions = array();
 630  
 631          $params = self::validate_parameters(self::get_forum_discussions_paginated_parameters(),
 632              array(
 633                  'forumid' => $forumid,
 634                  'sortby' => $sortby,
 635                  'sortdirection' => $sortdirection,
 636                  'page' => $page,
 637                  'perpage' => $perpage
 638              )
 639          );
 640  
 641          // Compact/extract functions are not recommended.
 642          $forumid        = $params['forumid'];
 643          $sortby         = $params['sortby'];
 644          $sortdirection  = $params['sortdirection'];
 645          $page           = $params['page'];
 646          $perpage        = $params['perpage'];
 647  
 648          $sortallowedvalues = array('id', 'timemodified', 'timestart', 'timeend');
 649          if (!in_array($sortby, $sortallowedvalues)) {
 650              throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $sortby . '),' .
 651                  'allowed values are: ' . implode(',', $sortallowedvalues));
 652          }
 653  
 654          $sortdirection = strtoupper($sortdirection);
 655          $directionallowedvalues = array('ASC', 'DESC');
 656          if (!in_array($sortdirection, $directionallowedvalues)) {
 657              throw new invalid_parameter_exception('Invalid value for sortdirection parameter (value: ' . $sortdirection . '),' .
 658                  'allowed values are: ' . implode(',', $directionallowedvalues));
 659          }
 660  
 661          $forum = $DB->get_record('forum', array('id' => $forumid), '*', MUST_EXIST);
 662          $course = $DB->get_record('course', array('id' => $forum->course), '*', MUST_EXIST);
 663          $cm = get_coursemodule_from_instance('forum', $forum->id, $course->id, false, MUST_EXIST);
 664  
 665          // Validate the module context. It checks everything that affects the module visibility (including groupings, etc..).
 666          $modcontext = context_module::instance($cm->id);
 667          self::validate_context($modcontext);
 668  
 669          // Check they have the view forum capability.
 670          require_capability('mod/forum:viewdiscussion', $modcontext, null, true, 'noviewdiscussionspermission', 'forum');
 671  
 672          $sort = 'd.' . $sortby . ' ' . $sortdirection;
 673          $alldiscussions = forum_get_discussions($cm, $sort, true, -1, -1, true, $page, $perpage);
 674  
 675          if ($alldiscussions) {
 676              $canviewfullname = has_capability('moodle/site:viewfullnames', $modcontext);
 677  
 678              // Get the unreads array, this takes a forum id and returns data for all discussions.
 679              $unreads = array();
 680              if ($cantrack = forum_tp_can_track_forums($forum)) {
 681                  if ($forumtracked = forum_tp_is_tracked($forum)) {
 682                      $unreads = forum_get_discussions_unread($cm);
 683                  }
 684              }
 685              // The forum function returns the replies for all the discussions in a given forum.
 686              $replies = forum_count_discussion_replies($forumid, $sort, -1, $page, $perpage);
 687  
 688              foreach ($alldiscussions as $discussion) {
 689  
 690                  // This function checks for qanda forums.
 691                  // Note that the forum_get_discussions returns as id the post id, not the discussion id so we need to do this.
 692                  $discussionrec = clone $discussion;
 693                  $discussionrec->id = $discussion->discussion;
 694                  if (!forum_user_can_see_discussion($forum, $discussionrec, $modcontext)) {
 695                      $warning = array();
 696                      // Function forum_get_discussions returns forum_posts ids not forum_discussions ones.
 697                      $warning['item'] = 'post';
 698                      $warning['itemid'] = $discussion->id;
 699                      $warning['warningcode'] = '1';
 700                      $warning['message'] = 'You can\'t see this discussion';
 701                      $warnings[] = $warning;
 702                      continue;
 703                  }
 704  
 705                  $discussion->numunread = 0;
 706                  if ($cantrack && $forumtracked) {
 707                      if (isset($unreads[$discussion->discussion])) {
 708                          $discussion->numunread = (int) $unreads[$discussion->discussion];
 709                      }
 710                  }
 711  
 712                  $discussion->numreplies = 0;
 713                  if (!empty($replies[$discussion->discussion])) {
 714                      $discussion->numreplies = (int) $replies[$discussion->discussion]->replies;
 715                  }
 716  
 717                  // Load user objects from the results of the query.
 718                  $user = new stdclass();
 719                  $user->id = $discussion->userid;
 720                  $user = username_load_fields_from_object($user, $discussion);
 721                  $discussion->userfullname = fullname($user, $canviewfullname);
 722  
 723                  // We can have post written by users that are deleted. In this case, those users don't have a valid context.
 724                  $usercontext = context_user::instance($user->id, IGNORE_MISSING);
 725                  if ($usercontext) {
 726                      $discussion->userpictureurl = moodle_url::make_webservice_pluginfile_url(
 727                          $usercontext->id, 'user', 'icon', null, '/', 'f1')->out(false);
 728                  } else {
 729                      $discussion->userpictureurl = '';
 730                  }
 731  
 732                  $usermodified = new stdclass();
 733                  $usermodified->id = $discussion->usermodified;
 734                  $usermodified = username_load_fields_from_object($usermodified, $discussion, 'um');
 735                  $discussion->usermodifiedfullname = fullname($usermodified, $canviewfullname);
 736  
 737                  // We can have post written by users that are deleted. In this case, those users don't have a valid context.
 738                  $usercontext = context_user::instance($usermodified->id, IGNORE_MISSING);
 739                  if ($usercontext) {
 740                      $discussion->usermodifiedpictureurl = moodle_url::make_webservice_pluginfile_url(
 741                          $usercontext->id, 'user', 'icon', null, '/', 'f1')->out(false);
 742                  } else {
 743                      $discussion->usermodifiedpictureurl = '';
 744                  }
 745  
 746                  // Rewrite embedded images URLs.
 747                  list($discussion->message, $discussion->messageformat) =
 748                      external_format_text($discussion->message, $discussion->messageformat,
 749                                              $modcontext->id, 'mod_forum', 'post', $discussion->id);
 750  
 751                  // List attachments.
 752                  if (!empty($discussion->attachment)) {
 753                      $discussion->attachments = array();
 754  
 755                      $fs = get_file_storage();
 756                      if ($files = $fs->get_area_files($modcontext->id, 'mod_forum', 'attachment',
 757                                                          $discussion->id, "filename", false)) {
 758                          foreach ($files as $file) {
 759                              $filename = $file->get_filename();
 760  
 761                              $discussion->attachments[] = array(
 762                                  'filename' => $filename,
 763                                  'mimetype' => $file->get_mimetype(),
 764                                  'fileurl'  => file_encode_url($CFG->wwwroot.'/webservice/pluginfile.php',
 765                                                  '/'.$modcontext->id.'/mod_forum/attachment/'.$discussion->id.'/'.$filename)
 766                              );
 767                          }
 768                      }
 769                  }
 770  
 771                  $discussions[] = $discussion;
 772              }
 773          }
 774  
 775          $result = array();
 776          $result['discussions'] = $discussions;
 777          $result['warnings'] = $warnings;
 778          return $result;
 779  
 780      }
 781  
 782      /**
 783       * Describes the get_forum_discussions_paginated return value.
 784       *
 785       * @return external_single_structure
 786       * @since Moodle 2.8
 787       */
 788      public static function get_forum_discussions_paginated_returns() {
 789          return new external_single_structure(
 790              array(
 791                  'discussions' => new external_multiple_structure(
 792                          new external_single_structure(
 793                              array(
 794                                  'id' => new external_value(PARAM_INT, 'Post id'),
 795                                  'name' => new external_value(PARAM_TEXT, 'Discussion name'),
 796                                  'groupid' => new external_value(PARAM_INT, 'Group id'),
 797                                  'timemodified' => new external_value(PARAM_INT, 'Time modified'),
 798                                  'usermodified' => new external_value(PARAM_INT, 'The id of the user who last modified'),
 799                                  'timestart' => new external_value(PARAM_INT, 'Time discussion can start'),
 800                                  'timeend' => new external_value(PARAM_INT, 'Time discussion ends'),
 801                                  'discussion' => new external_value(PARAM_INT, 'Discussion id'),
 802                                  'parent' => new external_value(PARAM_INT, 'Parent id'),
 803                                  'userid' => new external_value(PARAM_INT, 'User who started the discussion id'),
 804                                  'created' => new external_value(PARAM_INT, 'Creation time'),
 805                                  'modified' => new external_value(PARAM_INT, 'Time modified'),
 806                                  'mailed' => new external_value(PARAM_INT, 'Mailed?'),
 807                                  'subject' => new external_value(PARAM_TEXT, 'The post subject'),
 808                                  'message' => new external_value(PARAM_RAW, 'The post message'),
 809                                  'messageformat' => new external_format_value('message'),
 810                                  'messagetrust' => new external_value(PARAM_INT, 'Can we trust?'),
 811                                  'attachment' => new external_value(PARAM_RAW, 'Has attachments?'),
 812                                  'attachments' => new external_multiple_structure(
 813                                      new external_single_structure(
 814                                          array (
 815                                              'filename' => new external_value(PARAM_FILE, 'file name'),
 816                                              'mimetype' => new external_value(PARAM_RAW, 'mime type'),
 817                                              'fileurl'  => new external_value(PARAM_URL, 'file download url')
 818                                          )
 819                                      ), 'attachments', VALUE_OPTIONAL
 820                                  ),
 821                                  'totalscore' => new external_value(PARAM_INT, 'The post message total score'),
 822                                  'mailnow' => new external_value(PARAM_INT, 'Mail now?'),
 823                                  'userfullname' => new external_value(PARAM_TEXT, 'Post author full name'),
 824                                  'usermodifiedfullname' => new external_value(PARAM_TEXT, 'Post modifier full name'),
 825                                  'userpictureurl' => new external_value(PARAM_URL, 'Post author picture.'),
 826                                  'usermodifiedpictureurl' => new external_value(PARAM_URL, 'Post modifier picture.'),
 827                                  'numreplies' => new external_value(PARAM_TEXT, 'The number of replies in the discussion'),
 828                                  'numunread' => new external_value(PARAM_INT, 'The number of unread discussions.')
 829                              ), 'post'
 830                          )
 831                      ),
 832                  'warnings' => new external_warnings()
 833              )
 834          );
 835      }
 836  
 837  }

Search This Site: