Search moodle.org's
Developer Documentation


  • Bug fixes for general core bugs in 2.8.x ended 9 November 2015 (12 months).
  • Bug fixes for security issues in 2.8.x ended 9 May 2016 (18 months).
  • minimum PHP 5.4.4 (always use latest PHP 5.4.x or 5.5.x on Windows - http://windows.php.net/download/), PHP 7 is NOT supported
  • Differences Between: [Versions 28 and 29] [Versions 28 and 30] [Versions 28 and 31] [Versions 28 and 32] [Versions 28 and 33] [Versions 28 and 34] [Versions 28 and 35] [Versions 28 and 36] [Versions 28 and 37]

       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: