MDL-42098 - mod_forum: Update webservice sql query to include all name fields.
[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),
164 )
165 );
166 }
167
168 /**
169 * Returns a list of forum discussions as well as a summary of the discussion
170 * in a provided list of forums.
171 *
172 * @param array $forumids the forum ids
173 * @return array the forum discussion details
174 * @since Moodle 2.5
175 */
176 public static function get_forum_discussions($forumids) {
177 global $CFG, $DB, $USER;
178
179 require_once($CFG->dirroot . "/mod/forum/lib.php");
180
181 // Validate the parameter.
182 $params = self::validate_parameters(self::get_forum_discussions_parameters(), array('forumids' => $forumids));
183 $forumids = $params['forumids'];
184
185 // Array to store the forum discussions to return.
186 $arrdiscussions = array();
187 // Keep track of the course ids we have performed a require_course_login check on to avoid repeating.
188 $arrcourseschecked = array();
189 // Store the modinfo for the forums in an individual courses.
190 $arrcoursesforuminfo = array();
191 // Keep track of the users we have looked up in the DB.
192 $arrusers = array();
193
194 // Loop through them.
195 foreach ($forumids as $id) {
196 // Get the forum object.
197 $forum = $DB->get_record('forum', array('id' => $id), '*', MUST_EXIST);
198 // Check that that user can view this course if check not performed yet.
199 if (!in_array($forum->course, $arrcourseschecked)) {
200 // Check the user can function in this context.
201 self::validate_context(context_course::instance($forum->course));
202 // Add to the array.
203 $arrcourseschecked[] = $forum->course;
204 }
205 // Get the modinfo for the course if we haven't already.
206 if (!isset($arrcoursesforuminfo[$forum->course])) {
207 $modinfo = get_fast_modinfo($forum->course);
208 $arrcoursesforuminfo[$forum->course] = $modinfo->get_instances_of('forum');
209 }
210 // Check if this forum does not exist in the modinfo array, should always be false unless DB is borked.
211 if (empty($arrcoursesforuminfo[$forum->course][$forum->id])) {
212 throw new moodle_exception('invalidmodule', 'error');
213 }
214 // We now have the course module.
215 $cm = $arrcoursesforuminfo[$forum->course][$forum->id];
216 // If the forum is not visible throw an exception.
217 if (!$cm->uservisible) {
218 throw new moodle_exception('nopermissiontoshow', 'error');
219 }
220 // Get the module context.
221 $modcontext = context_module::instance($cm->id);
222 // Check they have the view forum capability.
223 require_capability('mod/forum:viewdiscussion', $modcontext);
224 // Check if they can view full names.
225 $canviewfullname = has_capability('moodle/site:viewfullnames', $modcontext);
226 // Get the unreads array, this takes a forum id and returns data for all discussions.
227 $unreads = array();
228 if ($cantrack = forum_tp_can_track_forums($forum)) {
229 if ($forumtracked = forum_tp_is_tracked($forum)) {
230 $unreads = forum_get_discussions_unread($cm);
231 }
232 }
233 // The forum function returns the replies for all the discussions in a given forum.
234 $replies = forum_count_discussion_replies($id);
235 // Get the discussions for this forum.
236 if ($discussions = $DB->get_records('forum_discussions', array('forum' => $id))) {
237 foreach ($discussions as $discussion) {
238 // If the forum is of type qanda and the user has not posted in the discussion
239 // we need to ensure that they have the required capability.
240 if ($forum->type == 'qanda' && !forum_user_has_posted($discussion->forum, $discussion->id, $USER->id)) {
241 require_capability('mod/forum:viewqandawithoutposting', $modcontext);
242 }
94b1577a 243 $usernamefields = user_picture::fields();
a9a0cb69
MN
244 // If we don't have the users details then perform DB call.
245 if (empty($arrusers[$discussion->userid])) {
246 $arrusers[$discussion->userid] = $DB->get_record('user', array('id' => $discussion->userid),
94b1577a 247 $usernamefields, MUST_EXIST);
a9a0cb69
MN
248 }
249 // Get the subject.
250 $subject = $DB->get_field('forum_posts', 'subject', array('id' => $discussion->firstpost), MUST_EXIST);
251 // Create object to return.
252 $return = new stdClass();
253 $return->id = (int) $discussion->id;
254 $return->course = $discussion->course;
255 $return->forum = $discussion->forum;
256 $return->name = $discussion->name;
257 $return->userid = $discussion->userid;
258 $return->groupid = $discussion->groupid;
259 $return->assessed = $discussion->assessed;
260 $return->timemodified = (int) $discussion->timemodified;
261 $return->usermodified = $discussion->usermodified;
262 $return->timestart = $discussion->timestart;
263 $return->timeend = $discussion->timeend;
264 $return->firstpost = (int) $discussion->firstpost;
265 $return->firstuserfullname = fullname($arrusers[$discussion->userid], $canviewfullname);
266 $return->firstuserimagealt = $arrusers[$discussion->userid]->imagealt;
267 $return->firstuserpicture = $arrusers[$discussion->userid]->picture;
268 $return->firstuseremail = $arrusers[$discussion->userid]->email;
269 $return->subject = $subject;
270 $return->numunread = '';
271 if ($cantrack && $forumtracked) {
272 if (isset($unreads[$discussion->id])) {
273 $return->numunread = (int) $unreads[$discussion->id];
274 }
275 }
276 // Check if there are any replies to this discussion.
277 if (!empty($replies[$discussion->id])) {
278 $return->numreplies = (int) $replies[$discussion->id]->replies;
279 $return->lastpost = (int) $replies[$discussion->id]->lastpostid;
280 } else { // No replies, so the last post will be the first post.
281 $return->numreplies = 0;
282 $return->lastpost = (int) $discussion->firstpost;
283 }
284 // Get the last post as well as the user who made it.
285 $lastpost = $DB->get_record('forum_posts', array('id' => $return->lastpost), '*', MUST_EXIST);
286 if (empty($arrusers[$lastpost->userid])) {
287 $arrusers[$lastpost->userid] = $DB->get_record('user', array('id' => $lastpost->userid),
94b1577a 288 $usernamefields, MUST_EXIST);
a9a0cb69
MN
289 }
290 $return->lastuserid = $lastpost->userid;
291 $return->lastuserfullname = fullname($arrusers[$lastpost->userid], $canviewfullname);
292 $return->lastuserimagealt = $arrusers[$lastpost->userid]->imagealt;
293 $return->lastuserpicture = $arrusers[$lastpost->userid]->picture;
294 $return->lastuseremail = $arrusers[$lastpost->userid]->email;
295 // Add the discussion statistics to the array to return.
296 $arrdiscussions[$return->id] = (array) $return;
297 }
298 }
299 }
300
301 return $arrdiscussions;
302 }
303
304 /**
305 * Describes the get_forum_discussions return value.
306 *
307 * @return external_single_structure
308 * @since Moodle 2.5
309 */
310 public static function get_forum_discussions_returns() {
311 return new external_multiple_structure(
312 new external_single_structure(
313 array(
314 'id' => new external_value(PARAM_INT, 'Forum id'),
315 'course' => new external_value(PARAM_INT, 'Course id'),
316 'forum' => new external_value(PARAM_INT, 'The forum id'),
317 'name' => new external_value(PARAM_TEXT, 'Discussion name'),
318 'userid' => new external_value(PARAM_INT, 'User id'),
319 'groupid' => new external_value(PARAM_INT, 'Group id'),
320 'assessed' => new external_value(PARAM_INT, 'Is this assessed?'),
321 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
322 'usermodified' => new external_value(PARAM_INT, 'The id of the user who last modified'),
323 'timestart' => new external_value(PARAM_INT, 'Time discussion can start'),
324 'timeend' => new external_value(PARAM_INT, 'Time discussion ends'),
325 'firstpost' => new external_value(PARAM_INT, 'The first post in the discussion'),
326 'firstuserfullname' => new external_value(PARAM_TEXT, 'The discussion creators fullname'),
327 'firstuserimagealt' => new external_value(PARAM_TEXT, 'The discussion creators image alt'),
328 'firstuserpicture' => new external_value(PARAM_INT, 'The discussion creators profile picture'),
329 'firstuseremail' => new external_value(PARAM_TEXT, 'The discussion creators email'),
330 'subject' => new external_value(PARAM_TEXT, 'The discussion subject'),
331 'numreplies' => new external_value(PARAM_TEXT, 'The number of replies in the discussion'),
332 'numunread' => new external_value(PARAM_TEXT, 'The number of unread posts, blank if this value is
333 not available due to forum settings.'),
334 'lastpost' => new external_value(PARAM_INT, 'The id of the last post in the discussion'),
335 'lastuserid' => new external_value(PARAM_INT, 'The id of the user who made the last post'),
336 'lastuserfullname' => new external_value(PARAM_TEXT, 'The last person to posts fullname'),
337 'lastuserimagealt' => new external_value(PARAM_TEXT, 'The last person to posts image alt'),
338 'lastuserpicture' => new external_value(PARAM_INT, 'The last person to posts profile picture'),
339 'lastuseremail' => new external_value(PARAM_TEXT, 'The last person to posts email'),
340 ), 'discussion'
341 )
342 );
343 }
2b9fe87d 344}