MDL-57407 mod_forum: Return ratings in external functions
[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_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         $courses = array();
64         if (empty($params['courseids'])) {
65             $courses = enrol_get_my_courses();
66             $params['courseids'] = array_keys($courses);
67         }
69         // Array to store the forums to return.
70         $arrforums = array();
71         $warnings = array();
73         // Ensure there are courseids to loop through.
74         if (!empty($params['courseids'])) {
76             list($courses, $warnings) = external_util::validate_courses($params['courseids'], $courses);
78             // Get the forums in this course. This function checks users visibility permissions.
79             $forums = get_all_instances_in_courses("forum", $courses);
80             foreach ($forums as $forum) {
82                 $course = $courses[$forum->course];
83                 $cm = get_coursemodule_from_instance('forum', $forum->id, $course->id);
84                 $context = context_module::instance($cm->id);
86                 // Skip forums we are not allowed to see discussions.
87                 if (!has_capability('mod/forum:viewdiscussion', $context)) {
88                     continue;
89                 }
91                 $forum->name = external_format_string($forum->name, $context->id);
92                 // Format the intro before being returning using the format setting.
93                 list($forum->intro, $forum->introformat) = external_format_text($forum->intro, $forum->introformat,
94                                                                                 $context->id, 'mod_forum', 'intro', null);
95                 $forum->introfiles = external_util::get_area_files($context->id, 'mod_forum', 'intro', false, false);
96                 // Discussions count. This function does static request cache.
97                 $forum->numdiscussions = forum_count_discussions($forum, $cm, $course);
98                 $forum->cmid = $forum->coursemodule;
99                 $forum->cancreatediscussions = forum_user_can_post_discussion($forum, null, -1, $cm, $context);
100                 $forum->istracked = forum_tp_is_tracked($forum);
101                 if ($forum->istracked) {
102                     $forum->unreadpostscount = forum_tp_count_forum_unread_posts($cm, $course);
103                 }
105                 // Add the forum to the array to return.
106                 $arrforums[$forum->id] = $forum;
107             }
108         }
110         return $arrforums;
111     }
113     /**
114      * Describes the get_forum return value.
115      *
116      * @return external_single_structure
117      * @since Moodle 2.5
118      */
119     public static function get_forums_by_courses_returns() {
120         return new external_multiple_structure(
121             new external_single_structure(
122                 array(
123                     'id' => new external_value(PARAM_INT, 'Forum id'),
124                     'course' => new external_value(PARAM_INT, 'Course id'),
125                     'type' => new external_value(PARAM_TEXT, 'The forum type'),
126                     'name' => new external_value(PARAM_RAW, 'Forum name'),
127                     'intro' => new external_value(PARAM_RAW, 'The forum intro'),
128                     'introformat' => new external_format_value('intro'),
129                     'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL),
130                     'assessed' => new external_value(PARAM_INT, 'Aggregate type'),
131                     'assesstimestart' => new external_value(PARAM_INT, 'Assess start time'),
132                     'assesstimefinish' => new external_value(PARAM_INT, 'Assess finish time'),
133                     'scale' => new external_value(PARAM_INT, 'Scale'),
134                     'maxbytes' => new external_value(PARAM_INT, 'Maximum attachment size'),
135                     'maxattachments' => new external_value(PARAM_INT, 'Maximum number of attachments'),
136                     'forcesubscribe' => new external_value(PARAM_INT, 'Force users to subscribe'),
137                     'trackingtype' => new external_value(PARAM_INT, 'Subscription mode'),
138                     'rsstype' => new external_value(PARAM_INT, 'RSS feed for this activity'),
139                     'rssarticles' => new external_value(PARAM_INT, 'Number of RSS recent articles'),
140                     'timemodified' => new external_value(PARAM_INT, 'Time modified'),
141                     'warnafter' => new external_value(PARAM_INT, 'Post threshold for warning'),
142                     'blockafter' => new external_value(PARAM_INT, 'Post threshold for blocking'),
143                     'blockperiod' => new external_value(PARAM_INT, 'Time period for blocking'),
144                     'completiondiscussions' => new external_value(PARAM_INT, 'Student must create discussions'),
145                     'completionreplies' => new external_value(PARAM_INT, 'Student must post replies'),
146                     'completionposts' => new external_value(PARAM_INT, 'Student must post discussions or replies'),
147                     'cmid' => new external_value(PARAM_INT, 'Course module id'),
148                     'numdiscussions' => new external_value(PARAM_INT, 'Number of discussions in the forum', VALUE_OPTIONAL),
149                     'cancreatediscussions' => new external_value(PARAM_BOOL, 'If the user can create discussions', VALUE_OPTIONAL),
150                     'lockdiscussionafter' => new external_value(PARAM_INT, 'After what period a discussion is locked', VALUE_OPTIONAL),
151                     'istracked' => new external_value(PARAM_BOOL, 'If the user is tracking the forum', VALUE_OPTIONAL),
152                     'unreadpostscount' => new external_value(PARAM_INT, 'The number of unread posts for tracked forums',
153                         VALUE_OPTIONAL),
154                 ), 'forum'
155             )
156         );
157     }
159     /**
160      * Describes the parameters for get_forum_discussion_posts.
161      *
162      * @return external_function_parameters
163      * @since Moodle 2.7
164      */
165     public static function get_forum_discussion_posts_parameters() {
166         return new external_function_parameters (
167             array(
168                 'discussionid' => new external_value(PARAM_INT, 'discussion ID', VALUE_REQUIRED),
169                 'sortby' => new external_value(PARAM_ALPHA,
170                     'sort by this element: id, created or modified', VALUE_DEFAULT, 'created'),
171                 'sortdirection' => new external_value(PARAM_ALPHA, 'sort direction: ASC or DESC', VALUE_DEFAULT, 'DESC')
172             )
173         );
174     }
176     /**
177      * Returns a list of forum posts for a discussion
178      *
179      * @param int $discussionid the post ids
180      * @param string $sortby sort by this element (id, created or modified)
181      * @param string $sortdirection sort direction: ASC or DESC
182      *
183      * @return array the forum post details
184      * @since Moodle 2.7
185      */
186     public static function get_forum_discussion_posts($discussionid, $sortby = "created", $sortdirection = "DESC") {
187         global $CFG, $DB, $USER, $PAGE;
189         $posts = array();
190         $warnings = array();
192         // Validate the parameter.
193         $params = self::validate_parameters(self::get_forum_discussion_posts_parameters(),
194             array(
195                 'discussionid' => $discussionid,
196                 'sortby' => $sortby,
197                 'sortdirection' => $sortdirection));
199         // Compact/extract functions are not recommended.
200         $discussionid   = $params['discussionid'];
201         $sortby         = $params['sortby'];
202         $sortdirection  = $params['sortdirection'];
204         $sortallowedvalues = array('id', 'created', 'modified');
205         if (!in_array($sortby, $sortallowedvalues)) {
206             throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $sortby . '),' .
207                 'allowed values are: ' . implode(',', $sortallowedvalues));
208         }
210         $sortdirection = strtoupper($sortdirection);
211         $directionallowedvalues = array('ASC', 'DESC');
212         if (!in_array($sortdirection, $directionallowedvalues)) {
213             throw new invalid_parameter_exception('Invalid value for sortdirection parameter (value: ' . $sortdirection . '),' .
214                 'allowed values are: ' . implode(',', $directionallowedvalues));
215         }
217         $discussion = $DB->get_record('forum_discussions', array('id' => $discussionid), '*', MUST_EXIST);
218         $forum = $DB->get_record('forum', array('id' => $discussion->forum), '*', MUST_EXIST);
219         $course = $DB->get_record('course', array('id' => $forum->course), '*', MUST_EXIST);
220         $cm = get_coursemodule_from_instance('forum', $forum->id, $course->id, false, MUST_EXIST);
222         // Validate the module context. It checks everything that affects the module visibility (including groupings, etc..).
223         $modcontext = context_module::instance($cm->id);
224         self::validate_context($modcontext);
226         // This require must be here, see mod/forum/discuss.php.
227         require_once($CFG->dirroot . "/mod/forum/lib.php");
229         // Check they have the view forum capability.
230         require_capability('mod/forum:viewdiscussion', $modcontext, null, true, 'noviewdiscussionspermission', 'forum');
232         if (! $post = forum_get_post_full($discussion->firstpost)) {
233             throw new moodle_exception('notexists', 'forum');
234         }
236         // This function check groups, qanda, timed discussions, etc.
237         if (!forum_user_can_see_post($forum, $discussion, $post, null, $cm)) {
238             throw new moodle_exception('noviewdiscussionspermission', 'forum');
239         }
241         $canviewfullname = has_capability('moodle/site:viewfullnames', $modcontext);
243         // We will add this field in the response.
244         $canreply = forum_user_can_post($forum, $discussion, $USER, $cm, $course, $modcontext);
246         $forumtracked = forum_tp_is_tracked($forum);
248         $sort = 'p.' . $sortby . ' ' . $sortdirection;
249         $allposts = forum_get_all_discussion_posts($discussion->id, $sort, $forumtracked);
251         foreach ($allposts as $post) {
253             if (!forum_user_can_see_post($forum, $discussion, $post, null, $cm)) {
254                 $warning = array();
255                 $warning['item'] = 'post';
256                 $warning['itemid'] = $post->id;
257                 $warning['warningcode'] = '1';
258                 $warning['message'] = 'You can\'t see this post';
259                 $warnings[] = $warning;
260                 continue;
261             }
263             // Function forum_get_all_discussion_posts adds postread field.
264             // Note that the value returned can be a boolean or an integer. The WS expects a boolean.
265             if (empty($post->postread)) {
266                 $post->postread = false;
267             } else {
268                 $post->postread = true;
269             }
271             $post->canreply = $canreply;
272             if (!empty($post->children)) {
273                 $post->children = array_keys($post->children);
274             } else {
275                 $post->children = array();
276             }
278             if (forum_is_author_hidden($post, $forum)) {
279                 $post->userid = null;
280                 $post->userfullname = null;
281                 $post->userpictureurl = null;
282             } else {
283                 $user = new stdclass();
284                 $user->id = $post->userid;
285                 $user = username_load_fields_from_object($user, $post, null, array('picture', 'imagealt', 'email'));
286                 $post->userfullname = fullname($user, $canviewfullname);
288                 $userpicture = new user_picture($user);
289                 $userpicture->size = 1; // Size f1.
290                 $post->userpictureurl = $userpicture->get_url($PAGE)->out(false);
291             }
293             $post->subject = external_format_string($post->subject, $modcontext->id);
294             // Rewrite embedded images URLs.
295             list($post->message, $post->messageformat) =
296                 external_format_text($post->message, $post->messageformat, $modcontext->id, 'mod_forum', 'post', $post->id);
298             // List attachments.
299             if (!empty($post->attachment)) {
300                 $post->attachments = external_util::get_area_files($modcontext->id, 'mod_forum', 'attachment', $post->id);
301             }
302             $messageinlinefiles = external_util::get_area_files($modcontext->id, 'mod_forum', 'post', $post->id);
303             if (!empty($messageinlinefiles)) {
304                 $post->messageinlinefiles = $messageinlinefiles;
305             }
307             $posts[] = $post;
308         }
310         $result = array();
311         $result['posts'] = $posts;
312         $result['ratinginfo'] = \core_rating\external\util::get_rating_info($forum, $modcontext, 'mod_forum', 'post', $posts);
313         $result['warnings'] = $warnings;
314         return $result;
315     }
317     /**
318      * Describes the get_forum_discussion_posts return value.
319      *
320      * @return external_single_structure
321      * @since Moodle 2.7
322      */
323     public static function get_forum_discussion_posts_returns() {
324         return new external_single_structure(
325             array(
326                 'posts' => new external_multiple_structure(
327                         new external_single_structure(
328                             array(
329                                 'id' => new external_value(PARAM_INT, 'Post id'),
330                                 'discussion' => new external_value(PARAM_INT, 'Discussion id'),
331                                 'parent' => new external_value(PARAM_INT, 'Parent id'),
332                                 'userid' => new external_value(PARAM_INT, 'User id'),
333                                 'created' => new external_value(PARAM_INT, 'Creation time'),
334                                 'modified' => new external_value(PARAM_INT, 'Time modified'),
335                                 'mailed' => new external_value(PARAM_INT, 'Mailed?'),
336                                 'subject' => new external_value(PARAM_TEXT, 'The post subject'),
337                                 'message' => new external_value(PARAM_RAW, 'The post message'),
338                                 'messageformat' => new external_format_value('message'),
339                                 'messagetrust' => new external_value(PARAM_INT, 'Can we trust?'),
340                                 'messageinlinefiles' => new external_files('post message inline files', VALUE_OPTIONAL),
341                                 'attachment' => new external_value(PARAM_RAW, 'Has attachments?'),
342                                 'attachments' => new external_files('attachments', VALUE_OPTIONAL),
343                                 'totalscore' => new external_value(PARAM_INT, 'The post message total score'),
344                                 'mailnow' => new external_value(PARAM_INT, 'Mail now?'),
345                                 'children' => new external_multiple_structure(new external_value(PARAM_INT, 'children post id')),
346                                 'canreply' => new external_value(PARAM_BOOL, 'The user can reply to posts?'),
347                                 'postread' => new external_value(PARAM_BOOL, 'The post was read'),
348                                 'userfullname' => new external_value(PARAM_TEXT, 'Post author full name'),
349                                 'userpictureurl' => new external_value(PARAM_URL, 'Post author picture.', VALUE_OPTIONAL)
350                             ), 'post'
351                         )
352                     ),
353                 'ratinginfo' => \core_rating\external\util::external_ratings_structure(),
354                 'warnings' => new external_warnings()
355             )
356         );
357     }
359     /**
360      * Describes the parameters for get_forum_discussions_paginated.
361      *
362      * @return external_function_parameters
363      * @since Moodle 2.8
364      */
365     public static function get_forum_discussions_paginated_parameters() {
366         return new external_function_parameters (
367             array(
368                 'forumid' => new external_value(PARAM_INT, 'forum instance id', VALUE_REQUIRED),
369                 'sortby' => new external_value(PARAM_ALPHA,
370                     'sort by this element: id, timemodified, timestart or timeend', VALUE_DEFAULT, 'timemodified'),
371                 'sortdirection' => new external_value(PARAM_ALPHA, 'sort direction: ASC or DESC', VALUE_DEFAULT, 'DESC'),
372                 'page' => new external_value(PARAM_INT, 'current page', VALUE_DEFAULT, -1),
373                 'perpage' => new external_value(PARAM_INT, 'items per page', VALUE_DEFAULT, 0),
374             )
375         );
376     }
378     /**
379      * Returns a list of forum discussions optionally sorted and paginated.
380      *
381      * @param int $forumid the forum instance id
382      * @param string $sortby sort by this element (id, timemodified, timestart or timeend)
383      * @param string $sortdirection sort direction: ASC or DESC
384      * @param int $page page number
385      * @param int $perpage items per page
386      *
387      * @return array the forum discussion details including warnings
388      * @since Moodle 2.8
389      */
390     public static function get_forum_discussions_paginated($forumid, $sortby = 'timemodified', $sortdirection = 'DESC',
391                                                     $page = -1, $perpage = 0) {
392         global $CFG, $DB, $USER, $PAGE;
394         require_once($CFG->dirroot . "/mod/forum/lib.php");
396         $warnings = array();
397         $discussions = array();
399         $params = self::validate_parameters(self::get_forum_discussions_paginated_parameters(),
400             array(
401                 'forumid' => $forumid,
402                 'sortby' => $sortby,
403                 'sortdirection' => $sortdirection,
404                 'page' => $page,
405                 'perpage' => $perpage
406             )
407         );
409         // Compact/extract functions are not recommended.
410         $forumid        = $params['forumid'];
411         $sortby         = $params['sortby'];
412         $sortdirection  = $params['sortdirection'];
413         $page           = $params['page'];
414         $perpage        = $params['perpage'];
416         $sortallowedvalues = array('id', 'timemodified', 'timestart', 'timeend');
417         if (!in_array($sortby, $sortallowedvalues)) {
418             throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $sortby . '),' .
419                 'allowed values are: ' . implode(',', $sortallowedvalues));
420         }
422         $sortdirection = strtoupper($sortdirection);
423         $directionallowedvalues = array('ASC', 'DESC');
424         if (!in_array($sortdirection, $directionallowedvalues)) {
425             throw new invalid_parameter_exception('Invalid value for sortdirection parameter (value: ' . $sortdirection . '),' .
426                 'allowed values are: ' . implode(',', $directionallowedvalues));
427         }
429         $forum = $DB->get_record('forum', array('id' => $forumid), '*', MUST_EXIST);
430         $course = $DB->get_record('course', array('id' => $forum->course), '*', MUST_EXIST);
431         $cm = get_coursemodule_from_instance('forum', $forum->id, $course->id, false, MUST_EXIST);
433         // Validate the module context. It checks everything that affects the module visibility (including groupings, etc..).
434         $modcontext = context_module::instance($cm->id);
435         self::validate_context($modcontext);
437         // Check they have the view forum capability.
438         require_capability('mod/forum:viewdiscussion', $modcontext, null, true, 'noviewdiscussionspermission', 'forum');
440         $sort = 'd.pinned DESC, d.' . $sortby . ' ' . $sortdirection;
441         $alldiscussions = forum_get_discussions($cm, $sort, true, -1, -1, true, $page, $perpage, FORUM_POSTS_ALL_USER_GROUPS);
443         if ($alldiscussions) {
444             $canviewfullname = has_capability('moodle/site:viewfullnames', $modcontext);
446             // Get the unreads array, this takes a forum id and returns data for all discussions.
447             $unreads = array();
448             if ($cantrack = forum_tp_can_track_forums($forum)) {
449                 if ($forumtracked = forum_tp_is_tracked($forum)) {
450                     $unreads = forum_get_discussions_unread($cm);
451                 }
452             }
453             // The forum function returns the replies for all the discussions in a given forum.
454             $replies = forum_count_discussion_replies($forumid, $sort, -1, $page, $perpage);
456             foreach ($alldiscussions as $discussion) {
458                 // This function checks for qanda forums.
459                 // Note that the forum_get_discussions returns as id the post id, not the discussion id so we need to do this.
460                 $discussionrec = clone $discussion;
461                 $discussionrec->id = $discussion->discussion;
462                 if (!forum_user_can_see_discussion($forum, $discussionrec, $modcontext)) {
463                     $warning = array();
464                     // Function forum_get_discussions returns forum_posts ids not forum_discussions ones.
465                     $warning['item'] = 'post';
466                     $warning['itemid'] = $discussion->id;
467                     $warning['warningcode'] = '1';
468                     $warning['message'] = 'You can\'t see this discussion';
469                     $warnings[] = $warning;
470                     continue;
471                 }
473                 $discussion->numunread = 0;
474                 if ($cantrack && $forumtracked) {
475                     if (isset($unreads[$discussion->discussion])) {
476                         $discussion->numunread = (int) $unreads[$discussion->discussion];
477                     }
478                 }
480                 $discussion->numreplies = 0;
481                 if (!empty($replies[$discussion->discussion])) {
482                     $discussion->numreplies = (int) $replies[$discussion->discussion]->replies;
483                 }
485                 $discussion->name = external_format_string($discussion->name, $modcontext->id);
486                 $discussion->subject = external_format_string($discussion->subject, $modcontext->id);
487                 // Rewrite embedded images URLs.
488                 list($discussion->message, $discussion->messageformat) =
489                     external_format_text($discussion->message, $discussion->messageformat,
490                                             $modcontext->id, 'mod_forum', 'post', $discussion->id);
492                 // List attachments.
493                 if (!empty($discussion->attachment)) {
494                     $discussion->attachments = external_util::get_area_files($modcontext->id, 'mod_forum', 'attachment',
495                                                                                 $discussion->id);
496                 }
497                 $messageinlinefiles = external_util::get_area_files($modcontext->id, 'mod_forum', 'post', $discussion->id);
498                 if (!empty($messageinlinefiles)) {
499                     $discussion->messageinlinefiles = $messageinlinefiles;
500                 }
502                 $discussion->locked = forum_discussion_is_locked($forum, $discussion);
503                 $discussion->canreply = forum_user_can_post($forum, $discussion, $USER, $cm, $course, $modcontext);
505                 if (forum_is_author_hidden($discussion, $forum)) {
506                     $discussion->userid = null;
507                     $discussion->userfullname = null;
508                     $discussion->userpictureurl = null;
510                     $discussion->usermodified = null;
511                     $discussion->usermodifiedfullname = null;
512                     $discussion->usermodifiedpictureurl = null;
513                 } else {
514                     $picturefields = explode(',', user_picture::fields());
516                     // Load user objects from the results of the query.
517                     $user = new stdclass();
518                     $user->id = $discussion->userid;
519                     $user = username_load_fields_from_object($user, $discussion, null, $picturefields);
520                     // Preserve the id, it can be modified by username_load_fields_from_object.
521                     $user->id = $discussion->userid;
522                     $discussion->userfullname = fullname($user, $canviewfullname);
524                     $userpicture = new user_picture($user);
525                     $userpicture->size = 1; // Size f1.
526                     $discussion->userpictureurl = $userpicture->get_url($PAGE)->out(false);
528                     $usermodified = new stdclass();
529                     $usermodified->id = $discussion->usermodified;
530                     $usermodified = username_load_fields_from_object($usermodified, $discussion, 'um', $picturefields);
531                     // Preserve the id (it can be overwritten due to the prefixed $picturefields).
532                     $usermodified->id = $discussion->usermodified;
533                     $discussion->usermodifiedfullname = fullname($usermodified, $canviewfullname);
535                     $userpicture = new user_picture($usermodified);
536                     $userpicture->size = 1; // Size f1.
537                     $discussion->usermodifiedpictureurl = $userpicture->get_url($PAGE)->out(false);
538                 }
540                 $discussions[] = $discussion;
541             }
542         }
544         $result = array();
545         $result['discussions'] = $discussions;
546         $result['warnings'] = $warnings;
547         return $result;
549     }
551     /**
552      * Describes the get_forum_discussions_paginated return value.
553      *
554      * @return external_single_structure
555      * @since Moodle 2.8
556      */
557     public static function get_forum_discussions_paginated_returns() {
558         return new external_single_structure(
559             array(
560                 'discussions' => new external_multiple_structure(
561                         new external_single_structure(
562                             array(
563                                 'id' => new external_value(PARAM_INT, 'Post id'),
564                                 'name' => new external_value(PARAM_TEXT, 'Discussion name'),
565                                 'groupid' => new external_value(PARAM_INT, 'Group id'),
566                                 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
567                                 'usermodified' => new external_value(PARAM_INT, 'The id of the user who last modified'),
568                                 'timestart' => new external_value(PARAM_INT, 'Time discussion can start'),
569                                 'timeend' => new external_value(PARAM_INT, 'Time discussion ends'),
570                                 'discussion' => new external_value(PARAM_INT, 'Discussion id'),
571                                 'parent' => new external_value(PARAM_INT, 'Parent id'),
572                                 'userid' => new external_value(PARAM_INT, 'User who started the discussion id'),
573                                 'created' => new external_value(PARAM_INT, 'Creation time'),
574                                 'modified' => new external_value(PARAM_INT, 'Time modified'),
575                                 'mailed' => new external_value(PARAM_INT, 'Mailed?'),
576                                 'subject' => new external_value(PARAM_TEXT, 'The post subject'),
577                                 'message' => new external_value(PARAM_RAW, 'The post message'),
578                                 'messageformat' => new external_format_value('message'),
579                                 'messagetrust' => new external_value(PARAM_INT, 'Can we trust?'),
580                                 'messageinlinefiles' => new external_files('post message inline files', VALUE_OPTIONAL),
581                                 'attachment' => new external_value(PARAM_RAW, 'Has attachments?'),
582                                 'attachments' => new external_files('attachments', VALUE_OPTIONAL),
583                                 'totalscore' => new external_value(PARAM_INT, 'The post message total score'),
584                                 'mailnow' => new external_value(PARAM_INT, 'Mail now?'),
585                                 'userfullname' => new external_value(PARAM_TEXT, 'Post author full name'),
586                                 'usermodifiedfullname' => new external_value(PARAM_TEXT, 'Post modifier full name'),
587                                 'userpictureurl' => new external_value(PARAM_URL, 'Post author picture.'),
588                                 'usermodifiedpictureurl' => new external_value(PARAM_URL, 'Post modifier picture.'),
589                                 'numreplies' => new external_value(PARAM_TEXT, 'The number of replies in the discussion'),
590                                 'numunread' => new external_value(PARAM_INT, 'The number of unread discussions.'),
591                                 'pinned' => new external_value(PARAM_BOOL, 'Is the discussion pinned'),
592                                 'locked' => new external_value(PARAM_BOOL, 'Is the discussion locked'),
593                                 'canreply' => new external_value(PARAM_BOOL, 'Can the user reply to the discussion'),
594                             ), 'post'
595                         )
596                     ),
597                 'warnings' => new external_warnings()
598             )
599         );
600     }
602     /**
603      * Returns description of method parameters
604      *
605      * @return external_function_parameters
606      * @since Moodle 2.9
607      */
608     public static function view_forum_parameters() {
609         return new external_function_parameters(
610             array(
611                 'forumid' => new external_value(PARAM_INT, 'forum instance id')
612             )
613         );
614     }
616     /**
617      * Trigger the course module viewed event and update the module completion status.
618      *
619      * @param int $forumid the forum instance id
620      * @return array of warnings and status result
621      * @since Moodle 2.9
622      * @throws moodle_exception
623      */
624     public static function view_forum($forumid) {
625         global $DB, $CFG;
626         require_once($CFG->dirroot . "/mod/forum/lib.php");
628         $params = self::validate_parameters(self::view_forum_parameters(),
629                                             array(
630                                                 'forumid' => $forumid
631                                             ));
632         $warnings = array();
634         // Request and permission validation.
635         $forum = $DB->get_record('forum', array('id' => $params['forumid']), '*', MUST_EXIST);
636         list($course, $cm) = get_course_and_cm_from_instance($forum, 'forum');
638         $context = context_module::instance($cm->id);
639         self::validate_context($context);
641         require_capability('mod/forum:viewdiscussion', $context, null, true, 'noviewdiscussionspermission', 'forum');
643         // Call the forum/lib API.
644         forum_view($forum, $course, $cm, $context);
646         $result = array();
647         $result['status'] = true;
648         $result['warnings'] = $warnings;
649         return $result;
650     }
652     /**
653      * Returns description of method result value
654      *
655      * @return external_description
656      * @since Moodle 2.9
657      */
658     public static function view_forum_returns() {
659         return new external_single_structure(
660             array(
661                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
662                 'warnings' => new external_warnings()
663             )
664         );
665     }
667     /**
668      * Returns description of method parameters
669      *
670      * @return external_function_parameters
671      * @since Moodle 2.9
672      */
673     public static function view_forum_discussion_parameters() {
674         return new external_function_parameters(
675             array(
676                 'discussionid' => new external_value(PARAM_INT, 'discussion id')
677             )
678         );
679     }
681     /**
682      * Trigger the discussion viewed event.
683      *
684      * @param int $discussionid the discussion id
685      * @return array of warnings and status result
686      * @since Moodle 2.9
687      * @throws moodle_exception
688      */
689     public static function view_forum_discussion($discussionid) {
690         global $DB, $CFG, $USER;
691         require_once($CFG->dirroot . "/mod/forum/lib.php");
693         $params = self::validate_parameters(self::view_forum_discussion_parameters(),
694                                             array(
695                                                 'discussionid' => $discussionid
696                                             ));
697         $warnings = array();
699         $discussion = $DB->get_record('forum_discussions', array('id' => $params['discussionid']), '*', MUST_EXIST);
700         $forum = $DB->get_record('forum', array('id' => $discussion->forum), '*', MUST_EXIST);
701         list($course, $cm) = get_course_and_cm_from_instance($forum, 'forum');
703         // Validate the module context. It checks everything that affects the module visibility (including groupings, etc..).
704         $modcontext = context_module::instance($cm->id);
705         self::validate_context($modcontext);
707         require_capability('mod/forum:viewdiscussion', $modcontext, null, true, 'noviewdiscussionspermission', 'forum');
709         // Call the forum/lib API.
710         forum_discussion_view($modcontext, $forum, $discussion);
712         // Mark as read if required.
713         if (!$CFG->forum_usermarksread && forum_tp_is_tracked($forum)) {
714             forum_tp_mark_discussion_read($USER, $discussion->id);
715         }
717         $result = array();
718         $result['status'] = true;
719         $result['warnings'] = $warnings;
720         return $result;
721     }
723     /**
724      * Returns description of method result value
725      *
726      * @return external_description
727      * @since Moodle 2.9
728      */
729     public static function view_forum_discussion_returns() {
730         return new external_single_structure(
731             array(
732                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
733                 'warnings' => new external_warnings()
734             )
735         );
736     }
738     /**
739      * Returns description of method parameters
740      *
741      * @return external_function_parameters
742      * @since Moodle 3.0
743      */
744     public static function add_discussion_post_parameters() {
745         return new external_function_parameters(
746             array(
747                 'postid' => new external_value(PARAM_INT, 'the post id we are going to reply to
748                                                 (can be the initial discussion post'),
749                 'subject' => new external_value(PARAM_TEXT, 'new post subject'),
750                 'message' => new external_value(PARAM_RAW, 'new post message (only html format allowed)'),
751                 'options' => new external_multiple_structure (
752                     new external_single_structure(
753                         array(
754                             'name' => new external_value(PARAM_ALPHANUM,
755                                         'The allowed keys (value format) are:
756                                         discussionsubscribe (bool); subscribe to the discussion?, default to true
757                                         inlineattachmentsid              (int); the draft file area id for inline attachments
758                                         attachmentsid       (int); the draft file area id for attachments
759                             '),
760                             'value' => new external_value(PARAM_RAW, 'the value of the option,
761                                                             this param is validated in the external function.'
762                         )
763                     )
764                 ), 'Options', VALUE_DEFAULT, array())
765             )
766         );
767     }
769     /**
770      * Create new posts into an existing discussion.
771      *
772      * @param int $postid the post id we are going to reply to
773      * @param string $subject new post subject
774      * @param string $message new post message (only html format allowed)
775      * @param array $options optional settings
776      * @return array of warnings and the new post id
777      * @since Moodle 3.0
778      * @throws moodle_exception
779      */
780     public static function add_discussion_post($postid, $subject, $message, $options = array()) {
781         global $DB, $CFG, $USER;
782         require_once($CFG->dirroot . "/mod/forum/lib.php");
784         $params = self::validate_parameters(self::add_discussion_post_parameters(),
785             array(
786                 'postid' => $postid,
787                 'subject' => $subject,
788                 'message' => $message,
789                 'options' => $options
790             )
791         );
792         $warnings = array();
794         if (!$parent = forum_get_post_full($params['postid'])) {
795             throw new moodle_exception('invalidparentpostid', 'forum');
796         }
798         if (!$discussion = $DB->get_record("forum_discussions", array("id" => $parent->discussion))) {
799             throw new moodle_exception('notpartofdiscussion', 'forum');
800         }
802         // Request and permission validation.
803         $forum = $DB->get_record('forum', array('id' => $discussion->forum), '*', MUST_EXIST);
804         list($course, $cm) = get_course_and_cm_from_instance($forum, 'forum');
806         $context = context_module::instance($cm->id);
807         self::validate_context($context);
809         // Validate options.
810         $options = array(
811             'discussionsubscribe' => true,
812             'inlineattachmentsid' => 0,
813             'attachmentsid' => null
814         );
815         foreach ($params['options'] as $option) {
816             $name = trim($option['name']);
817             switch ($name) {
818                 case 'discussionsubscribe':
819                     $value = clean_param($option['value'], PARAM_BOOL);
820                     break;
821                 case 'inlineattachmentsid':
822                     $value = clean_param($option['value'], PARAM_INT);
823                     break;
824                 case 'attachmentsid':
825                     $value = clean_param($option['value'], PARAM_INT);
826                     // Ensure that the user has permissions to create attachments.
827                     if (!has_capability('mod/forum:createattachment', $context)) {
828                         $value = 0;
829                     }
830                     break;
831                 default:
832                     throw new moodle_exception('errorinvalidparam', 'webservice', '', $name);
833             }
834             $options[$name] = $value;
835         }
837         if (!forum_user_can_post($forum, $discussion, $USER, $cm, $course, $context)) {
838             throw new moodle_exception('nopostforum', 'forum');
839         }
841         $thresholdwarning = forum_check_throttling($forum, $cm);
842         forum_check_blocking_threshold($thresholdwarning);
844         // Create the post.
845         $post = new stdClass();
846         $post->discussion = $discussion->id;
847         $post->parent = $parent->id;
848         $post->subject = $params['subject'];
849         $post->message = $params['message'];
850         $post->messageformat = FORMAT_HTML;   // Force formatting for now.
851         $post->messagetrust = trusttext_trusted($context);
852         $post->itemid = $options['inlineattachmentsid'];
853         $post->attachments   = $options['attachmentsid'];
854         $fakemform = $post->attachments;
855         if ($postid = forum_add_new_post($post, $fakemform)) {
857             $post->id = $postid;
859             // Trigger events and completion.
860             $params = array(
861                 'context' => $context,
862                 'objectid' => $post->id,
863                 'other' => array(
864                     'discussionid' => $discussion->id,
865                     'forumid' => $forum->id,
866                     'forumtype' => $forum->type,
867                 )
868             );
869             $event = \mod_forum\event\post_created::create($params);
870             $event->add_record_snapshot('forum_posts', $post);
871             $event->add_record_snapshot('forum_discussions', $discussion);
872             $event->trigger();
874             // Update completion state.
875             $completion = new completion_info($course);
876             if ($completion->is_enabled($cm) &&
877                     ($forum->completionreplies || $forum->completionposts)) {
878                 $completion->update_state($cm, COMPLETION_COMPLETE);
879             }
881             $settings = new stdClass();
882             $settings->discussionsubscribe = $options['discussionsubscribe'];
883             forum_post_subscription($settings, $forum, $discussion);
884         } else {
885             throw new moodle_exception('couldnotadd', 'forum');
886         }
888         $result = array();
889         $result['postid'] = $postid;
890         $result['warnings'] = $warnings;
891         return $result;
892     }
894     /**
895      * Returns description of method result value
896      *
897      * @return external_description
898      * @since Moodle 3.0
899      */
900     public static function add_discussion_post_returns() {
901         return new external_single_structure(
902             array(
903                 'postid' => new external_value(PARAM_INT, 'new post id'),
904                 'warnings' => new external_warnings()
905             )
906         );
907     }
909     /**
910      * Returns description of method parameters
911      *
912      * @return external_function_parameters
913      * @since Moodle 3.0
914      */
915     public static function add_discussion_parameters() {
916         return new external_function_parameters(
917             array(
918                 'forumid' => new external_value(PARAM_INT, 'Forum instance ID'),
919                 'subject' => new external_value(PARAM_TEXT, 'New Discussion subject'),
920                 'message' => new external_value(PARAM_RAW, 'New Discussion message (only html format allowed)'),
921                 'groupid' => new external_value(PARAM_INT, 'The group, default to 0', VALUE_DEFAULT, 0),
922                 'options' => new external_multiple_structure (
923                     new external_single_structure(
924                         array(
925                             'name' => new external_value(PARAM_ALPHANUM,
926                                         'The allowed keys (value format) are:
927                                         discussionsubscribe (bool); subscribe to the discussion?, default to true
928                                         discussionpinned    (bool); is the discussion pinned, default to false
929                                         inlineattachmentsid              (int); the draft file area id for inline attachments
930                                         attachmentsid       (int); the draft file area id for attachments
931                             '),
932                             'value' => new external_value(PARAM_RAW, 'The value of the option,
933                                                             This param is validated in the external function.'
934                         )
935                     )
936                 ), 'Options', VALUE_DEFAULT, array())
937             )
938         );
939     }
941     /**
942      * Add a new discussion into an existing forum.
943      *
944      * @param int $forumid the forum instance id
945      * @param string $subject new discussion subject
946      * @param string $message new discussion message (only html format allowed)
947      * @param int $groupid the user course group
948      * @param array $options optional settings
949      * @return array of warnings and the new discussion id
950      * @since Moodle 3.0
951      * @throws moodle_exception
952      */
953     public static function add_discussion($forumid, $subject, $message, $groupid = 0, $options = array()) {
954         global $DB, $CFG;
955         require_once($CFG->dirroot . "/mod/forum/lib.php");
957         $params = self::validate_parameters(self::add_discussion_parameters(),
958                                             array(
959                                                 'forumid' => $forumid,
960                                                 'subject' => $subject,
961                                                 'message' => $message,
962                                                 'groupid' => $groupid,
963                                                 'options' => $options
964                                             ));
966         $warnings = array();
968         // Request and permission validation.
969         $forum = $DB->get_record('forum', array('id' => $params['forumid']), '*', MUST_EXIST);
970         list($course, $cm) = get_course_and_cm_from_instance($forum, 'forum');
972         $context = context_module::instance($cm->id);
973         self::validate_context($context);
975         // Validate options.
976         $options = array(
977             'discussionsubscribe' => true,
978             'discussionpinned' => false,
979             'inlineattachmentsid' => 0,
980             'attachmentsid' => null
981         );
982         foreach ($params['options'] as $option) {
983             $name = trim($option['name']);
984             switch ($name) {
985                 case 'discussionsubscribe':
986                     $value = clean_param($option['value'], PARAM_BOOL);
987                     break;
988                 case 'discussionpinned':
989                     $value = clean_param($option['value'], PARAM_BOOL);
990                     break;
991                 case 'inlineattachmentsid':
992                     $value = clean_param($option['value'], PARAM_INT);
993                     break;
994                 case 'attachmentsid':
995                     $value = clean_param($option['value'], PARAM_INT);
996                     // Ensure that the user has permissions to create attachments.
997                     if (!has_capability('mod/forum:createattachment', $context)) {
998                         $value = 0;
999                     }
1000                     break;
1001                 default:
1002                     throw new moodle_exception('errorinvalidparam', 'webservice', '', $name);
1003             }
1004             $options[$name] = $value;
1005         }
1007         // Normalize group.
1008         if (!groups_get_activity_groupmode($cm)) {
1009             // Groups not supported, force to -1.
1010             $groupid = -1;
1011         } else {
1012             // Check if we receive the default or and empty value for groupid,
1013             // in this case, get the group for the user in the activity.
1014             if (empty($params['groupid'])) {
1015                 $groupid = groups_get_activity_group($cm);
1016             } else {
1017                 // Here we rely in the group passed, forum_user_can_post_discussion will validate the group.
1018                 $groupid = $params['groupid'];
1019             }
1020         }
1022         if (!forum_user_can_post_discussion($forum, $groupid, -1, $cm, $context)) {
1023             throw new moodle_exception('cannotcreatediscussion', 'forum');
1024         }
1026         $thresholdwarning = forum_check_throttling($forum, $cm);
1027         forum_check_blocking_threshold($thresholdwarning);
1029         // Create the discussion.
1030         $discussion = new stdClass();
1031         $discussion->course = $course->id;
1032         $discussion->forum = $forum->id;
1033         $discussion->message = $params['message'];
1034         $discussion->messageformat = FORMAT_HTML;   // Force formatting for now.
1035         $discussion->messagetrust = trusttext_trusted($context);
1036         $discussion->itemid = $options['inlineattachmentsid'];
1037         $discussion->groupid = $groupid;
1038         $discussion->mailnow = 0;
1039         $discussion->subject = $params['subject'];
1040         $discussion->name = $discussion->subject;
1041         $discussion->timestart = 0;
1042         $discussion->timeend = 0;
1043         $discussion->attachments = $options['attachmentsid'];
1045         if (has_capability('mod/forum:pindiscussions', $context) && $options['discussionpinned']) {
1046             $discussion->pinned = FORUM_DISCUSSION_PINNED;
1047         } else {
1048             $discussion->pinned = FORUM_DISCUSSION_UNPINNED;
1049         }
1050         $fakemform = $options['attachmentsid'];
1051         if ($discussionid = forum_add_discussion($discussion, $fakemform)) {
1053             $discussion->id = $discussionid;
1055             // Trigger events and completion.
1057             $params = array(
1058                 'context' => $context,
1059                 'objectid' => $discussion->id,
1060                 'other' => array(
1061                     'forumid' => $forum->id,
1062                 )
1063             );
1064             $event = \mod_forum\event\discussion_created::create($params);
1065             $event->add_record_snapshot('forum_discussions', $discussion);
1066             $event->trigger();
1068             $completion = new completion_info($course);
1069             if ($completion->is_enabled($cm) &&
1070                     ($forum->completiondiscussions || $forum->completionposts)) {
1071                 $completion->update_state($cm, COMPLETION_COMPLETE);
1072             }
1074             $settings = new stdClass();
1075             $settings->discussionsubscribe = $options['discussionsubscribe'];
1076             forum_post_subscription($settings, $forum, $discussion);
1077         } else {
1078             throw new moodle_exception('couldnotadd', 'forum');
1079         }
1081         $result = array();
1082         $result['discussionid'] = $discussionid;
1083         $result['warnings'] = $warnings;
1084         return $result;
1085     }
1087     /**
1088      * Returns description of method result value
1089      *
1090      * @return external_description
1091      * @since Moodle 3.0
1092      */
1093     public static function add_discussion_returns() {
1094         return new external_single_structure(
1095             array(
1096                 'discussionid' => new external_value(PARAM_INT, 'New Discussion ID'),
1097                 'warnings' => new external_warnings()
1098             )
1099         );
1100     }
1102     /**
1103      * Returns description of method parameters
1104      *
1105      * @return external_function_parameters
1106      * @since Moodle 3.1
1107      */
1108     public static function can_add_discussion_parameters() {
1109         return new external_function_parameters(
1110             array(
1111                 'forumid' => new external_value(PARAM_INT, 'Forum instance ID'),
1112                 'groupid' => new external_value(PARAM_INT, 'The group to check, default to active group.
1113                                                 Use -1 to check if the user can post in all the groups.', VALUE_DEFAULT, null)
1114             )
1115         );
1116     }
1118     /**
1119      * Check if the current user can add discussions in the given forum (and optionally for the given group).
1120      *
1121      * @param int $forumid the forum instance id
1122      * @param int $groupid the group to check, default to active group. Use -1 to check if the user can post in all the groups.
1123      * @return array of warnings and the status (true if the user can add discussions)
1124      * @since Moodle 3.1
1125      * @throws moodle_exception
1126      */
1127     public static function can_add_discussion($forumid, $groupid = null) {
1128         global $DB, $CFG;
1129         require_once($CFG->dirroot . "/mod/forum/lib.php");
1131         $params = self::validate_parameters(self::can_add_discussion_parameters(),
1132                                             array(
1133                                                 'forumid' => $forumid,
1134                                                 'groupid' => $groupid,
1135                                             ));
1136         $warnings = array();
1138         // Request and permission validation.
1139         $forum = $DB->get_record('forum', array('id' => $params['forumid']), '*', MUST_EXIST);
1140         list($course, $cm) = get_course_and_cm_from_instance($forum, 'forum');
1142         $context = context_module::instance($cm->id);
1143         self::validate_context($context);
1145         $status = forum_user_can_post_discussion($forum, $params['groupid'], -1, $cm, $context);
1147         $result = array();
1148         $result['status'] = $status;
1149         $result['canpindiscussions'] = has_capability('mod/forum:pindiscussions', $context);
1150         $result['cancreateattachment'] = forum_can_create_attachment($forum, $context);
1151         $result['warnings'] = $warnings;
1152         return $result;
1153     }
1155     /**
1156      * Returns description of method result value
1157      *
1158      * @return external_description
1159      * @since Moodle 3.1
1160      */
1161     public static function can_add_discussion_returns() {
1162         return new external_single_structure(
1163             array(
1164                 'status' => new external_value(PARAM_BOOL, 'True if the user can add discussions, false otherwise.'),
1165                 'canpindiscussions' => new external_value(PARAM_BOOL, 'True if the user can pin discussions, false otherwise.',
1166                     VALUE_OPTIONAL),
1167                 'cancreateattachment' => new external_value(PARAM_BOOL, 'True if the user can add attachments, false otherwise.',
1168                     VALUE_OPTIONAL),
1169                 'warnings' => new external_warnings()
1170             )
1171         );
1172     }