Merge branch 'MDL-49921-master' of git://github.com/jleyva/moodle
[moodle.git] / mod / forum / externallib.php
1 <?php
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/>.
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  */
26 defined('MOODLE_INTERNAL') || die;
28 require_once("$CFG->libdir/externallib.php");
30 class mod_forum_external extends external_api {
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     }
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;
59         require_once($CFG->dirroot . "/mod/forum/lib.php");
61         $params = self::validate_parameters(self::get_forums_by_courses_parameters(), array('courseids' => $courseids));
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         }
70         // Array to store the forums to return.
71         $arrforums = array();
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();
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();
90                 } catch (Exception $e) {
91                     continue;
92                 }
93             }
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) {
99                     $course = $dbcourses[$forum->course];
100                     $cm = $modinfocourses[$course->id]->get_cm($forum->coursemodule);
101                     $context = context_module::instance($cm->id);
103                     // Skip forums we are not allowed to see discussions.
104                     if (!has_capability('mod/forum:viewdiscussion', $context)) {
105                         continue;
106                     }
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;
115                     // Add the forum to the array to return.
116                     $arrforums[$forum->id] = $forum;
117                 }
118             }
119         }
121         return $arrforums;
122     }
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_TEXT, '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     }
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     }
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;
199         require_once($CFG->dirroot . "/mod/forum/lib.php");
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'];
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();
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);
223             $modinfo = get_fast_modinfo($course);
224             $forums  = $modinfo->get_instances_of('forum');
225             $cm = $forums[$forum->id];
227             // Get the module context.
228             $modcontext = context_module::instance($cm->id);
230             // Validate the context.
231             self::validate_context($modcontext);
233             require_capability('mod/forum:viewdiscussion', $modcontext);
235             // Get the discussions for this forum.
236             $params = array();
238             $groupselect = "";
239             $groupmode = groups_get_activity_groupmode($cm, $course);
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";
252             if ($discussions = $DB->get_records_select('forum_discussions', $select, $params, 'timemodified DESC', '*',
253                                                             $limitfrom, $limitnum)) {
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);
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                     }
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         }
331         return $arrdiscussions;
332     }
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     }
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     }
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;
407         $warnings = array();
409         // Validate the parameter.
410         $params = self::validate_parameters(self::get_forum_discussion_posts_parameters(),
411             array(
412                 'discussionid' => $discussionid,
413                 'sortby' => $sortby,
414                 'sortdirection' => $sortdirection));
416         // Compact/extract functions are not recommended.
417         $discussionid   = $params['discussionid'];
418         $sortby         = $params['sortby'];
419         $sortdirection  = $params['sortdirection'];
421         $sortallowedvalues = array('id', 'created', 'modified');
422         if (!in_array($sortby, $sortallowedvalues)) {
423             throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $sortby . '),' .
424                 'allowed values are: ' . implode(',', $sortallowedvalues));
425         }
427         $sortdirection = strtoupper($sortdirection);
428         $directionallowedvalues = array('ASC', 'DESC');
429         if (!in_array($sortdirection, $directionallowedvalues)) {
430             throw new invalid_parameter_exception('Invalid value for sortdirection parameter (value: ' . $sortdirection . '),' .
431                 'allowed values are: ' . implode(',', $directionallowedvalues));
432         }
434         $discussion = $DB->get_record('forum_discussions', array('id' => $discussionid), '*', MUST_EXIST);
435         $forum = $DB->get_record('forum', array('id' => $discussion->forum), '*', MUST_EXIST);
436         $course = $DB->get_record('course', array('id' => $forum->course), '*', MUST_EXIST);
437         $cm = get_coursemodule_from_instance('forum', $forum->id, $course->id, false, MUST_EXIST);
439         // Validate the module context. It checks everything that affects the module visibility (including groupings, etc..).
440         $modcontext = context_module::instance($cm->id);
441         self::validate_context($modcontext);
443         // This require must be here, see mod/forum/discuss.php.
444         require_once($CFG->dirroot . "/mod/forum/lib.php");
446         // Check they have the view forum capability.
447         require_capability('mod/forum:viewdiscussion', $modcontext, null, true, 'noviewdiscussionspermission', 'forum');
449         if (! $post = forum_get_post_full($discussion->firstpost)) {
450             throw new moodle_exception('notexists', 'forum');
451         }
453         // This function check groups, qanda, timed discussions, etc.
454         if (!forum_user_can_see_post($forum, $discussion, $post, null, $cm)) {
455             throw new moodle_exception('noviewdiscussionspermission', 'forum');
456         }
458         $canviewfullname = has_capability('moodle/site:viewfullnames', $modcontext);
460         // We will add this field in the response.
461         $canreply = forum_user_can_post($forum, $discussion, $USER, $cm, $course, $modcontext);
463         $forumtracked = forum_tp_is_tracked($forum);
465         $sort = 'p.' . $sortby . ' ' . $sortdirection;
466         $posts = forum_get_all_discussion_posts($discussion->id, $sort, $forumtracked);
468         foreach ($posts as $pid => $post) {
470             if (!forum_user_can_see_post($forum, $discussion, $post, null, $cm)) {
471                 $warning = array();
472                 $warning['item'] = 'post';
473                 $warning['itemid'] = $post->id;
474                 $warning['warningcode'] = '1';
475                 $warning['message'] = 'You can\'t see this post';
476                 $warnings[] = $warning;
477                 continue;
478             }
480             // Function forum_get_all_discussion_posts adds postread field.
481             // Note that the value returned can be a boolean or an integer. The WS expects a boolean.
482             if (empty($post->postread)) {
483                 $posts[$pid]->postread = false;
484             } else {
485                 $posts[$pid]->postread = true;
486             }
488             $posts[$pid]->canreply = $canreply;
489             if (!empty($posts[$pid]->children)) {
490                 $posts[$pid]->children = array_keys($posts[$pid]->children);
491             } else {
492                 $posts[$pid]->children = array();
493             }
495             $user = new stdclass();
496             $user->id = $post->userid;
497             $user = username_load_fields_from_object($user, $post);
498             $post->userfullname = fullname($user, $canviewfullname);
500             // We can have post written by users that are deleted. In this case, those users don't have a valid context.
501             $usercontext = context_user::instance($user->id, IGNORE_MISSING);
502             if ($usercontext) {
503                 $post->userpictureurl = moodle_url::make_webservice_pluginfile_url(
504                         $usercontext->id, 'user', 'icon', null, '/', 'f1')->out(false);
505             } else {
506                 $post->userpictureurl = '';
507             }
509             // Rewrite embedded images URLs.
510             list($post->message, $post->messageformat) =
511                 external_format_text($post->message, $post->messageformat, $modcontext->id, 'mod_forum', 'post', $post->id);
513             // List attachments.
514             if (!empty($post->attachment)) {
515                 $post->attachments = array();
517                 $fs = get_file_storage();
518                 if ($files = $fs->get_area_files($modcontext->id, 'mod_forum', 'attachment', $post->id, "filename", false)) {
519                     foreach ($files as $file) {
520                         $filename = $file->get_filename();
521                         $fileurl = moodle_url::make_webservice_pluginfile_url(
522                                         $modcontext->id, 'mod_forum', 'attachment', $post->id, '/', $filename);
524                         $post->attachments[] = array(
525                             'filename' => $filename,
526                             'mimetype' => $file->get_mimetype(),
527                             'fileurl'  => $fileurl->out(false)
528                         );
529                     }
530                 }
531             }
533             $posts[$pid] = (array) $post;
534         }
536         $result = array();
537         $result['posts'] = $posts;
538         $result['warnings'] = $warnings;
539         return $result;
540     }
542     /**
543      * Describes the get_forum_discussion_posts return value.
544      *
545      * @return external_single_structure
546      * @since Moodle 2.7
547      */
548     public static function get_forum_discussion_posts_returns() {
549         return new external_single_structure(
550             array(
551                 'posts' => new external_multiple_structure(
552                         new external_single_structure(
553                             array(
554                                 'id' => new external_value(PARAM_INT, 'Post id'),
555                                 'discussion' => new external_value(PARAM_INT, 'Discussion id'),
556                                 'parent' => new external_value(PARAM_INT, 'Parent id'),
557                                 'userid' => new external_value(PARAM_INT, 'User id'),
558                                 'created' => new external_value(PARAM_INT, 'Creation time'),
559                                 'modified' => new external_value(PARAM_INT, 'Time modified'),
560                                 'mailed' => new external_value(PARAM_INT, 'Mailed?'),
561                                 'subject' => new external_value(PARAM_TEXT, 'The post subject'),
562                                 'message' => new external_value(PARAM_RAW, 'The post message'),
563                                 'messageformat' => new external_format_value('message'),
564                                 'messagetrust' => new external_value(PARAM_INT, 'Can we trust?'),
565                                 'attachment' => new external_value(PARAM_RAW, 'Has attachments?'),
566                                 'attachments' => new external_multiple_structure(
567                                     new external_single_structure(
568                                         array (
569                                             'filename' => new external_value(PARAM_FILE, 'file name'),
570                                             'mimetype' => new external_value(PARAM_RAW, 'mime type'),
571                                             'fileurl'  => new external_value(PARAM_URL, 'file download url')
572                                         )
573                                     ), 'attachments', VALUE_OPTIONAL
574                                 ),
575                                 'totalscore' => new external_value(PARAM_INT, 'The post message total score'),
576                                 'mailnow' => new external_value(PARAM_INT, 'Mail now?'),
577                                 'children' => new external_multiple_structure(new external_value(PARAM_INT, 'children post id')),
578                                 'canreply' => new external_value(PARAM_BOOL, 'The user can reply to posts?'),
579                                 'postread' => new external_value(PARAM_BOOL, 'The post was read'),
580                                 'userfullname' => new external_value(PARAM_TEXT, 'Post author full name'),
581                                 'userpictureurl' => new external_value(PARAM_URL, 'Post author picture.', VALUE_OPTIONAL)
582                             ), 'post'
583                         )
584                     ),
585                 'warnings' => new external_warnings()
586             )
587         );
588     }
590     /**
591      * Describes the parameters for get_forum_discussions_paginated.
592      *
593      * @return external_external_function_parameters
594      * @since Moodle 2.8
595      */
596     public static function get_forum_discussions_paginated_parameters() {
597         return new external_function_parameters (
598             array(
599                 'forumid' => new external_value(PARAM_INT, 'forum instance id', VALUE_REQUIRED),
600                 'sortby' => new external_value(PARAM_ALPHA,
601                     'sort by this element: id, timemodified, timestart or timeend', VALUE_DEFAULT, 'timemodified'),
602                 'sortdirection' => new external_value(PARAM_ALPHA, 'sort direction: ASC or DESC', VALUE_DEFAULT, 'DESC'),
603                 'page' => new external_value(PARAM_INT, 'current page', VALUE_DEFAULT, -1),
604                 'perpage' => new external_value(PARAM_INT, 'items per page', VALUE_DEFAULT, 0),
605             )
606         );
607     }
609     /**
610      * Returns a list of forum discussions optionally sorted and paginated.
611      *
612      * @param int $forumid the forum instance id
613      * @param string $sortby sort by this element (id, timemodified, timestart or timeend)
614      * @param string $sortdirection sort direction: ASC or DESC
615      * @param int $page page number
616      * @param int $perpage items per page
617      *
618      * @return array the forum discussion details including warnings
619      * @since Moodle 2.8
620      */
621     public static function get_forum_discussions_paginated($forumid, $sortby = 'timemodified', $sortdirection = 'DESC',
622                                                     $page = -1, $perpage = 0) {
623         global $CFG, $DB, $USER;
625         require_once($CFG->dirroot . "/mod/forum/lib.php");
627         $warnings = array();
629         $params = self::validate_parameters(self::get_forum_discussions_paginated_parameters(),
630             array(
631                 'forumid' => $forumid,
632                 'sortby' => $sortby,
633                 'sortdirection' => $sortdirection,
634                 'page' => $page,
635                 'perpage' => $perpage
636             )
637         );
639         // Compact/extract functions are not recommended.
640         $forumid        = $params['forumid'];
641         $sortby         = $params['sortby'];
642         $sortdirection  = $params['sortdirection'];
643         $page           = $params['page'];
644         $perpage        = $params['perpage'];
646         $sortallowedvalues = array('id', 'timemodified', 'timestart', 'timeend');
647         if (!in_array($sortby, $sortallowedvalues)) {
648             throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $sortby . '),' .
649                 'allowed values are: ' . implode(',', $sortallowedvalues));
650         }
652         $sortdirection = strtoupper($sortdirection);
653         $directionallowedvalues = array('ASC', 'DESC');
654         if (!in_array($sortdirection, $directionallowedvalues)) {
655             throw new invalid_parameter_exception('Invalid value for sortdirection parameter (value: ' . $sortdirection . '),' .
656                 'allowed values are: ' . implode(',', $directionallowedvalues));
657         }
659         $forum = $DB->get_record('forum', array('id' => $forumid), '*', MUST_EXIST);
660         $course = $DB->get_record('course', array('id' => $forum->course), '*', MUST_EXIST);
661         $cm = get_coursemodule_from_instance('forum', $forum->id, $course->id, false, MUST_EXIST);
663         // Validate the module context. It checks everything that affects the module visibility (including groupings, etc..).
664         $modcontext = context_module::instance($cm->id);
665         self::validate_context($modcontext);
667         // Check they have the view forum capability.
668         require_capability('mod/forum:viewdiscussion', $modcontext, null, true, 'noviewdiscussionspermission', 'forum');
670         $sort = 'd.' . $sortby . ' ' . $sortdirection;
671         $discussions = forum_get_discussions($cm, $sort, true, -1, -1, true, $page, $perpage);
673         if ($discussions) {
674             $canviewfullname = has_capability('moodle/site:viewfullnames', $modcontext);
676             // Get the unreads array, this takes a forum id and returns data for all discussions.
677             $unreads = array();
678             if ($cantrack = forum_tp_can_track_forums($forum)) {
679                 if ($forumtracked = forum_tp_is_tracked($forum)) {
680                     $unreads = forum_get_discussions_unread($cm);
681                 }
682             }
683             // The forum function returns the replies for all the discussions in a given forum.
684             $replies = forum_count_discussion_replies($forumid, $sort, -1, $page, $perpage);
686             foreach ($discussions as $did => $discussion) {
687                 // This function checks for qanda forums.
688                 if (!forum_user_can_see_discussion($forum, $discussion, $modcontext)) {
689                     $warning = array();
690                     // Function forum_get_discussions returns forum_posts ids not forum_discussions ones.
691                     $warning['item'] = 'post';
692                     $warning['itemid'] = $discussion->id;
693                     $warning['warningcode'] = '1';
694                     $warning['message'] = 'You can\'t see this discussion';
695                     $warnings[] = $warning;
696                     continue;
697                 }
699                 $discussion->numunread = 0;
700                 if ($cantrack && $forumtracked) {
701                     if (isset($unreads[$discussion->discussion])) {
702                         $discussion->numunread = (int) $unreads[$discussion->discussion];
703                     }
704                 }
706                 $discussion->numreplies = 0;
707                 if (!empty($replies[$discussion->discussion])) {
708                     $discussion->numreplies = (int) $replies[$discussion->discussion]->replies;
709                 }
711                 // Load user objects from the results of the query.
712                 $user = new stdclass();
713                 $user->id = $discussion->userid;
714                 $user = username_load_fields_from_object($user, $discussion);
715                 $discussion->userfullname = fullname($user, $canviewfullname);
717                 // We can have post written by users that are deleted. In this case, those users don't have a valid context.
718                 $usercontext = context_user::instance($user->id, IGNORE_MISSING);
719                 if ($usercontext) {
720                     $discussion->userpictureurl = moodle_url::make_webservice_pluginfile_url(
721                         $usercontext->id, 'user', 'icon', null, '/', 'f1')->out(false);
722                 } else {
723                     $discussion->userpictureurl = '';
724                 }
726                 $usermodified = new stdclass();
727                 $usermodified->id = $discussion->usermodified;
728                 $usermodified = username_load_fields_from_object($usermodified, $discussion, 'um');
729                 $discussion->usermodifiedfullname = fullname($usermodified, $canviewfullname);
731                 // We can have post written by users that are deleted. In this case, those users don't have a valid context.
732                 $usercontext = context_user::instance($usermodified->id, IGNORE_MISSING);
733                 if ($usercontext) {
734                     $discussion->usermodifiedpictureurl = moodle_url::make_webservice_pluginfile_url(
735                         $usercontext->id, 'user', 'icon', null, '/', 'f1')->out(false);
736                 } else {
737                     $discussion->usermodifiedpictureurl = '';
738                 }
740                 // Rewrite embedded images URLs.
741                 list($discussion->message, $discussion->messageformat) =
742                     external_format_text($discussion->message, $discussion->messageformat,
743                                             $modcontext->id, 'mod_forum', 'post', $discussion->id);
745                 // List attachments.
746                 if (!empty($discussion->attachment)) {
747                     $discussion->attachments = array();
749                     $fs = get_file_storage();
750                     if ($files = $fs->get_area_files($modcontext->id, 'mod_forum', 'attachment',
751                                                         $discussion->id, "filename", false)) {
752                         foreach ($files as $file) {
753                             $filename = $file->get_filename();
755                             $discussion->attachments[] = array(
756                                 'filename' => $filename,
757                                 'mimetype' => $file->get_mimetype(),
758                                 'fileurl'  => file_encode_url($CFG->wwwroot.'/webservice/pluginfile.php',
759                                                 '/'.$modcontext->id.'/mod_forum/attachment/'.$discussion->id.'/'.$filename)
760                             );
761                         }
762                     }
763                 }
765                 $discussions[$did] = (array) $discussion;
766             }
767         }
769         $result = array();
770         $result['discussions'] = $discussions;
771         $result['warnings'] = $warnings;
772         return $result;
774     }
776     /**
777      * Describes the get_forum_discussions_paginated return value.
778      *
779      * @return external_single_structure
780      * @since Moodle 2.8
781      */
782     public static function get_forum_discussions_paginated_returns() {
783         return new external_single_structure(
784             array(
785                 'discussions' => new external_multiple_structure(
786                         new external_single_structure(
787                             array(
788                                 'id' => new external_value(PARAM_INT, 'Post id'),
789                                 'name' => new external_value(PARAM_TEXT, 'Discussion name'),
790                                 'groupid' => new external_value(PARAM_INT, 'Group id'),
791                                 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
792                                 'usermodified' => new external_value(PARAM_INT, 'The id of the user who last modified'),
793                                 'timestart' => new external_value(PARAM_INT, 'Time discussion can start'),
794                                 'timeend' => new external_value(PARAM_INT, 'Time discussion ends'),
795                                 'discussion' => new external_value(PARAM_INT, 'Discussion id'),
796                                 'parent' => new external_value(PARAM_INT, 'Parent id'),
797                                 'userid' => new external_value(PARAM_INT, 'User who started the discussion id'),
798                                 'created' => new external_value(PARAM_INT, 'Creation time'),
799                                 'modified' => new external_value(PARAM_INT, 'Time modified'),
800                                 'mailed' => new external_value(PARAM_INT, 'Mailed?'),
801                                 'subject' => new external_value(PARAM_TEXT, 'The post subject'),
802                                 'message' => new external_value(PARAM_RAW, 'The post message'),
803                                 'messageformat' => new external_format_value('message'),
804                                 'messagetrust' => new external_value(PARAM_INT, 'Can we trust?'),
805                                 'attachment' => new external_value(PARAM_RAW, 'Has attachments?'),
806                                 'attachments' => new external_multiple_structure(
807                                     new external_single_structure(
808                                         array (
809                                             'filename' => new external_value(PARAM_FILE, 'file name'),
810                                             'mimetype' => new external_value(PARAM_RAW, 'mime type'),
811                                             'fileurl'  => new external_value(PARAM_URL, 'file download url')
812                                         )
813                                     ), 'attachments', VALUE_OPTIONAL
814                                 ),
815                                 'totalscore' => new external_value(PARAM_INT, 'The post message total score'),
816                                 'mailnow' => new external_value(PARAM_INT, 'Mail now?'),
817                                 'userfullname' => new external_value(PARAM_TEXT, 'Post author full name'),
818                                 'usermodifiedfullname' => new external_value(PARAM_TEXT, 'Post modifier full name'),
819                                 'userpictureurl' => new external_value(PARAM_URL, 'Post author picture.'),
820                                 'usermodifiedpictureurl' => new external_value(PARAM_URL, 'Post modifier picture.'),
821                                 'numreplies' => new external_value(PARAM_TEXT, 'The number of replies in the discussion'),
822                                 'numunread' => new external_value(PARAM_INT, 'The number of unread discussions.')
823                             ), 'post'
824                         )
825                     ),
826                 'warnings' => new external_warnings()
827             )
828         );
829     }
831     /**
832      * Returns description of method parameters
833      *
834      * @return external_function_parameters
835      * @since Moodle 2.9
836      */
837     public static function view_forum_parameters() {
838         return new external_function_parameters(
839             array(
840                 'forumid' => new external_value(PARAM_INT, 'forum instance id')
841             )
842         );
843     }
845     /**
846      * Simulate the forum/view.php web interface page: trigger events, completion, etc...
847      *
848      * @param int $forumid the forum instance id
849      * @return array of warnings and status result
850      * @since Moodle 2.9
851      * @throws moodle_exception
852      */
853     public static function view_forum($forumid) {
854         global $DB, $CFG;
855         require_once($CFG->dirroot . "/mod/forum/lib.php");
857         $params = self::validate_parameters(self::view_forum_parameters(),
858                                             array(
859                                                 'forumid' => $forumid
860                                             ));
861         $warnings = array();
863         // Request and permission validation.
864         $forum = $DB->get_record('forum', array('id' => $params['forumid']), 'id', MUST_EXIST);
865         list($course, $cm) = get_course_and_cm_from_instance($forum, 'forum');
867         $context = context_module::instance($cm->id);
868         self::validate_context($context);
870         require_capability('mod/forum:viewdiscussion', $context, null, true, 'noviewdiscussionspermission', 'forum');
872         // Call the forum/lib API.
873         forum_view($forum, $course, $cm, $context);
875         $result = array();
876         $result['status'] = true;
877         $result['warnings'] = $warnings;
878         return $result;
879     }
881     /**
882      * Returns description of method result value
883      *
884      * @return external_description
885      * @since Moodle 2.9
886      */
887     public static function view_forum_returns() {
888         return new external_single_structure(
889             array(
890                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
891                 'warnings' => new external_warnings()
892             )
893         );
894     }
896     /**
897      * Returns description of method parameters
898      *
899      * @return external_function_parameters
900      * @since Moodle 2.9
901      */
902     public static function view_forum_discussion_parameters() {
903         return new external_function_parameters(
904             array(
905                 'discussionid' => new external_value(PARAM_INT, 'discussion id')
906             )
907         );
908     }
910     /**
911      * Simulate the forum/discuss.php web interface page: trigger events
912      *
913      * @param int $discussionid the discussion id
914      * @return array of warnings and status result
915      * @since Moodle 2.9
916      * @throws moodle_exception
917      */
918     public static function view_forum_discussion($discussionid) {
919         global $DB, $CFG;
920         require_once($CFG->dirroot . "/mod/forum/lib.php");
922         $params = self::validate_parameters(self::view_forum_discussion_parameters(),
923                                             array(
924                                                 'discussionid' => $discussionid
925                                             ));
926         $warnings = array();
928         $discussion = $DB->get_record('forum_discussions', array('id' => $params['discussionid']), '*', MUST_EXIST);
929         $forum = $DB->get_record('forum', array('id' => $discussion->forum), '*', MUST_EXIST);
930         list($course, $cm) = get_course_and_cm_from_instance($forum, 'forum');
932         // Validate the module context. It checks everything that affects the module visibility (including groupings, etc..).
933         $modcontext = context_module::instance($cm->id);
934         self::validate_context($modcontext);
936         require_capability('mod/forum:viewdiscussion', $modcontext, null, true, 'noviewdiscussionspermission', 'forum');
938         // Call the forum/lib API.
939         forum_discussion_view($modcontext, $forum, $discussion);
941         $result = array();
942         $result['status'] = true;
943         $result['warnings'] = $warnings;
944         return $result;
945     }
947     /**
948      * Returns description of method result value
949      *
950      * @return external_description
951      * @since Moodle 2.9
952      */
953     public static function view_forum_discussion_returns() {
954         return new external_single_structure(
955             array(
956                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
957                 'warnings' => new external_warnings()
958             )
959         );
960     }