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