Moodle release 2.7rc1
[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);
a9a0cb69
MN
85 // Get the forum instances.
86 $foruminstances = $modinfo->get_instances_of('forum');
87 // Loop through the forums returned by modinfo.
88 foreach ($foruminstances as $forumid => $cm) {
0c246ae5
MN
89 // If it is not visible or present in the forums get_records call, continue.
90 if (!$cm->uservisible || !isset($forums[$forumid])) {
91 continue;
92 }
93 // Set the forum object.
94 $forum = $forums[$forumid];
0c246ae5
MN
95 // Get the module context.
96 $context = context_module::instance($cm->id);
97 // Check they have the view forum capability.
98 require_capability('mod/forum:viewdiscussion', $context);
99 // Format the intro before being returning using the format setting.
100 list($forum->intro, $forum->introformat) = external_format_text($forum->intro, $forum->introformat,
101 $context->id, 'mod_forum', 'intro', 0);
102 // Add the course module id to the object, this information is useful.
103 $forum->cmid = $cm->id;
104 // Add the forum to the array to return.
105 $arrforums[$forum->id] = (array) $forum;
2b9fe87d 106 }
2b9fe87d
MN
107 }
108 }
109 }
110
111 return $arrforums;
112 }
113
114 /**
a9a0cb69 115 * Describes the get_forum return value.
2b9fe87d
MN
116 *
117 * @return external_single_structure
118 * @since Moodle 2.5
119 */
120 public static function get_forums_by_courses_returns() {
121 return new external_multiple_structure(
122 new external_single_structure(
123 array(
124 'id' => new external_value(PARAM_INT, 'Forum id'),
125 'course' => new external_value(PARAM_TEXT, 'Course id'),
126 'type' => new external_value(PARAM_TEXT, 'The forum type'),
127 'name' => new external_value(PARAM_TEXT, 'Forum name'),
128 'intro' => new external_value(PARAM_RAW, 'The forum intro'),
129 'introformat' => new external_format_value('intro'),
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 ), 'forum'
149 )
150 );
151 }
a9a0cb69
MN
152
153 /**
154 * Describes the parameters for get_forum_discussions.
155 *
156 * @return external_external_function_parameters
157 * @since Moodle 2.5
158 */
159 public static function get_forum_discussions_parameters() {
160 return new external_function_parameters (
161 array(
162 'forumids' => new external_multiple_structure(new external_value(PARAM_INT, 'forum ID',
163 '', VALUE_REQUIRED, '', NULL_NOT_ALLOWED), 'Array of Forum IDs', VALUE_REQUIRED),
1fee2cd4
JL
164 'limitfrom' => new external_value(PARAM_INT, 'limit from', VALUE_OPTIONAL, 0),
165 'limitnum' => new external_value(PARAM_INT, 'limit number', VALUE_OPTIONAL, 0)
a9a0cb69
MN
166 )
167 );
168 }
169
170 /**
171 * Returns a list of forum discussions as well as a summary of the discussion
172 * in a provided list of forums.
173 *
174 * @param array $forumids the forum ids
1fee2cd4
JL
175 * @param int $limitfrom limit from SQL data
176 * @param int $limitnum limit number SQL data
177 *
a9a0cb69
MN
178 * @return array the forum discussion details
179 * @since Moodle 2.5
180 */
1fee2cd4 181 public static function get_forum_discussions($forumids, $limitfrom = 0, $limitnum = 0) {
a9a0cb69
MN
182 global $CFG, $DB, $USER;
183
184 require_once($CFG->dirroot . "/mod/forum/lib.php");
185
186 // Validate the parameter.
1fee2cd4
JL
187 $params = self::validate_parameters(self::get_forum_discussions_parameters(),
188 array(
189 'forumids' => $forumids,
190 'limitfrom' => $limitfrom,
191 'limitnum' => $limitnum,
192 ));
193 $forumids = $params['forumids'];
194 $limitfrom = $params['limitfrom'];
195 $limitnum = $params['limitnum'];
a9a0cb69
MN
196
197 // Array to store the forum discussions to return.
198 $arrdiscussions = array();
199 // Keep track of the course ids we have performed a require_course_login check on to avoid repeating.
200 $arrcourseschecked = array();
201 // Store the modinfo for the forums in an individual courses.
202 $arrcoursesforuminfo = array();
203 // Keep track of the users we have looked up in the DB.
204 $arrusers = array();
205
206 // Loop through them.
207 foreach ($forumids as $id) {
208 // Get the forum object.
209 $forum = $DB->get_record('forum', array('id' => $id), '*', MUST_EXIST);
210 // Check that that user can view this course if check not performed yet.
211 if (!in_array($forum->course, $arrcourseschecked)) {
212 // Check the user can function in this context.
213 self::validate_context(context_course::instance($forum->course));
214 // Add to the array.
215 $arrcourseschecked[] = $forum->course;
216 }
217 // Get the modinfo for the course if we haven't already.
218 if (!isset($arrcoursesforuminfo[$forum->course])) {
219 $modinfo = get_fast_modinfo($forum->course);
220 $arrcoursesforuminfo[$forum->course] = $modinfo->get_instances_of('forum');
221 }
222 // Check if this forum does not exist in the modinfo array, should always be false unless DB is borked.
223 if (empty($arrcoursesforuminfo[$forum->course][$forum->id])) {
224 throw new moodle_exception('invalidmodule', 'error');
225 }
226 // We now have the course module.
227 $cm = $arrcoursesforuminfo[$forum->course][$forum->id];
228 // If the forum is not visible throw an exception.
229 if (!$cm->uservisible) {
230 throw new moodle_exception('nopermissiontoshow', 'error');
231 }
232 // Get the module context.
233 $modcontext = context_module::instance($cm->id);
234 // Check they have the view forum capability.
235 require_capability('mod/forum:viewdiscussion', $modcontext);
236 // Check if they can view full names.
237 $canviewfullname = has_capability('moodle/site:viewfullnames', $modcontext);
238 // Get the unreads array, this takes a forum id and returns data for all discussions.
239 $unreads = array();
240 if ($cantrack = forum_tp_can_track_forums($forum)) {
241 if ($forumtracked = forum_tp_is_tracked($forum)) {
242 $unreads = forum_get_discussions_unread($cm);
243 }
244 }
245 // The forum function returns the replies for all the discussions in a given forum.
246 $replies = forum_count_discussion_replies($id);
247 // Get the discussions for this forum.
4595c79b
JL
248 $order = 'timemodified DESC';
249 if ($discussions = $DB->get_records('forum_discussions', array('forum' => $id), $order, '*', $limitfrom, $limitnum)) {
a9a0cb69
MN
250 foreach ($discussions as $discussion) {
251 // If the forum is of type qanda and the user has not posted in the discussion
252 // we need to ensure that they have the required capability.
253 if ($forum->type == 'qanda' && !forum_user_has_posted($discussion->forum, $discussion->id, $USER->id)) {
254 require_capability('mod/forum:viewqandawithoutposting', $modcontext);
255 }
94b1577a 256 $usernamefields = user_picture::fields();
a9a0cb69
MN
257 // If we don't have the users details then perform DB call.
258 if (empty($arrusers[$discussion->userid])) {
259 $arrusers[$discussion->userid] = $DB->get_record('user', array('id' => $discussion->userid),
94b1577a 260 $usernamefields, MUST_EXIST);
a9a0cb69
MN
261 }
262 // Get the subject.
263 $subject = $DB->get_field('forum_posts', 'subject', array('id' => $discussion->firstpost), MUST_EXIST);
264 // Create object to return.
265 $return = new stdClass();
266 $return->id = (int) $discussion->id;
267 $return->course = $discussion->course;
268 $return->forum = $discussion->forum;
269 $return->name = $discussion->name;
270 $return->userid = $discussion->userid;
271 $return->groupid = $discussion->groupid;
272 $return->assessed = $discussion->assessed;
273 $return->timemodified = (int) $discussion->timemodified;
274 $return->usermodified = $discussion->usermodified;
275 $return->timestart = $discussion->timestart;
276 $return->timeend = $discussion->timeend;
277 $return->firstpost = (int) $discussion->firstpost;
278 $return->firstuserfullname = fullname($arrusers[$discussion->userid], $canviewfullname);
279 $return->firstuserimagealt = $arrusers[$discussion->userid]->imagealt;
280 $return->firstuserpicture = $arrusers[$discussion->userid]->picture;
281 $return->firstuseremail = $arrusers[$discussion->userid]->email;
282 $return->subject = $subject;
283 $return->numunread = '';
284 if ($cantrack && $forumtracked) {
285 if (isset($unreads[$discussion->id])) {
286 $return->numunread = (int) $unreads[$discussion->id];
287 }
288 }
289 // Check if there are any replies to this discussion.
290 if (!empty($replies[$discussion->id])) {
291 $return->numreplies = (int) $replies[$discussion->id]->replies;
292 $return->lastpost = (int) $replies[$discussion->id]->lastpostid;
293 } else { // No replies, so the last post will be the first post.
294 $return->numreplies = 0;
295 $return->lastpost = (int) $discussion->firstpost;
296 }
297 // Get the last post as well as the user who made it.
298 $lastpost = $DB->get_record('forum_posts', array('id' => $return->lastpost), '*', MUST_EXIST);
299 if (empty($arrusers[$lastpost->userid])) {
300 $arrusers[$lastpost->userid] = $DB->get_record('user', array('id' => $lastpost->userid),
94b1577a 301 $usernamefields, MUST_EXIST);
a9a0cb69
MN
302 }
303 $return->lastuserid = $lastpost->userid;
304 $return->lastuserfullname = fullname($arrusers[$lastpost->userid], $canviewfullname);
305 $return->lastuserimagealt = $arrusers[$lastpost->userid]->imagealt;
306 $return->lastuserpicture = $arrusers[$lastpost->userid]->picture;
307 $return->lastuseremail = $arrusers[$lastpost->userid]->email;
308 // Add the discussion statistics to the array to return.
309 $arrdiscussions[$return->id] = (array) $return;
310 }
311 }
312 }
313
314 return $arrdiscussions;
315 }
316
317 /**
318 * Describes the get_forum_discussions return value.
319 *
320 * @return external_single_structure
321 * @since Moodle 2.5
322 */
323 public static function get_forum_discussions_returns() {
324 return new external_multiple_structure(
325 new external_single_structure(
326 array(
327 'id' => new external_value(PARAM_INT, 'Forum id'),
328 'course' => new external_value(PARAM_INT, 'Course id'),
329 'forum' => new external_value(PARAM_INT, 'The forum id'),
330 'name' => new external_value(PARAM_TEXT, 'Discussion name'),
331 'userid' => new external_value(PARAM_INT, 'User id'),
332 'groupid' => new external_value(PARAM_INT, 'Group id'),
333 'assessed' => new external_value(PARAM_INT, 'Is this assessed?'),
334 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
335 'usermodified' => new external_value(PARAM_INT, 'The id of the user who last modified'),
336 'timestart' => new external_value(PARAM_INT, 'Time discussion can start'),
337 'timeend' => new external_value(PARAM_INT, 'Time discussion ends'),
338 'firstpost' => new external_value(PARAM_INT, 'The first post in the discussion'),
339 'firstuserfullname' => new external_value(PARAM_TEXT, 'The discussion creators fullname'),
340 'firstuserimagealt' => new external_value(PARAM_TEXT, 'The discussion creators image alt'),
341 'firstuserpicture' => new external_value(PARAM_INT, 'The discussion creators profile picture'),
342 'firstuseremail' => new external_value(PARAM_TEXT, 'The discussion creators email'),
343 'subject' => new external_value(PARAM_TEXT, 'The discussion subject'),
344 'numreplies' => new external_value(PARAM_TEXT, 'The number of replies in the discussion'),
345 'numunread' => new external_value(PARAM_TEXT, 'The number of unread posts, blank if this value is
346 not available due to forum settings.'),
347 'lastpost' => new external_value(PARAM_INT, 'The id of the last post in the discussion'),
348 'lastuserid' => new external_value(PARAM_INT, 'The id of the user who made the last post'),
349 'lastuserfullname' => new external_value(PARAM_TEXT, 'The last person to posts fullname'),
350 'lastuserimagealt' => new external_value(PARAM_TEXT, 'The last person to posts image alt'),
351 'lastuserpicture' => new external_value(PARAM_INT, 'The last person to posts profile picture'),
352 'lastuseremail' => new external_value(PARAM_TEXT, 'The last person to posts email'),
353 ), 'discussion'
354 )
355 );
356 }
2b9fe87d 357}