3 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
22 * @copyright 2012 Mark Nelson <markn@moodle.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26 defined('MOODLE_INTERNAL') ||
die;
28 require_once("$CFG->libdir/externallib.php");
30 class mod_forum_external
extends external_api
{
33 * Describes the parameters for get_forum.
35 * @return external_external_function_parameters
38 public static function get_forums_by_courses_parameters() {
39 return new external_function_parameters (
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()),
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
52 * @param array $courseids the course ids
53 * @return array the forum details
56 public static function get_forums_by_courses($courseids = array()) {
57 global $CFG, $DB, $USER;
59 require_once($CFG->dirroot
. "/mod/forum/lib.php");
61 $params = self
::validate_parameters(self
::get_forums_by_courses_parameters(), array('courseids' => $courseids));
63 if (empty($params['courseids'])) {
64 // Get all the courses the user can view.
65 $courseids = array_keys(enrol_get_my_courses());
67 $courseids = $params['courseids'];
70 // Array to store the forums to return.
73 // Ensure there are courseids to loop through.
74 if (!empty($courseids)) {
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);
81 // Get the forums in this course.
82 if ($forums = $DB->get_records('forum', array('course' => $cid))) {
83 // Get the modinfo for the course.
84 $modinfo = get_fast_modinfo($cid);
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) {
89 // If it is not visible or present in the forums get_records call, continue.
90 if (!$cm->uservisible ||
!isset($forums[$forumid])) {
93 // Set the forum object.
94 $forum = $forums[$forumid];
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;
115 * Describes the get_forum return value.
117 * @return external_single_structure
120 public static function get_forums_by_courses_returns() {
121 return new external_multiple_structure(
122 new external_single_structure(
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')
154 * Describes the parameters for get_forum_discussions.
156 * @return external_external_function_parameters
159 public static function get_forum_discussions_parameters() {
160 return new external_function_parameters (
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
),
169 * Returns a list of forum discussions as well as a summary of the discussion
170 * in a provided list of forums.
172 * @param array $forumids the forum ids
173 * @return array the forum discussion details
176 public static function get_forum_discussions($forumids) {
177 global $CFG, $DB, $USER;
179 require_once($CFG->dirroot
. "/mod/forum/lib.php");
181 // Validate the parameter.
182 $params = self
::validate_parameters(self
::get_forum_discussions_parameters(), array('forumids' => $forumids));
183 $forumids = $params['forumids'];
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.
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
));
203 $arrcourseschecked[] = $forum->course
;
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');
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');
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');
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.
228 if ($cantrack = forum_tp_can_track_forums($forum)) {
229 if ($forumtracked = forum_tp_is_tracked($forum)) {
230 $unreads = forum_get_discussions_unread($cm);
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);
243 // If we don't have the users details then perform DB call.
244 if (empty($arrusers[$discussion->userid
])) {
245 $arrusers[$discussion->userid
] = $DB->get_record('user', array('id' => $discussion->userid
),
246 'firstname, lastname, email, picture, imagealt', MUST_EXIST
);
249 $subject = $DB->get_field('forum_posts', 'subject', array('id' => $discussion->firstpost
), MUST_EXIST
);
250 // Create object to return.
251 $return = new stdClass();
252 $return->id
= (int) $discussion->id
;
253 $return->course
= $discussion->course
;
254 $return->forum
= $discussion->forum
;
255 $return->name
= $discussion->name
;
256 $return->userid
= $discussion->userid
;
257 $return->groupid
= $discussion->groupid
;
258 $return->assessed
= $discussion->assessed
;
259 $return->timemodified
= (int) $discussion->timemodified
;
260 $return->usermodified
= $discussion->usermodified
;
261 $return->timestart
= $discussion->timestart
;
262 $return->timeend
= $discussion->timeend
;
263 $return->firstpost
= (int) $discussion->firstpost
;
264 $return->firstuserfullname
= fullname($arrusers[$discussion->userid
], $canviewfullname);
265 $return->firstuserimagealt
= $arrusers[$discussion->userid
]->imagealt
;
266 $return->firstuserpicture
= $arrusers[$discussion->userid
]->picture
;
267 $return->firstuseremail
= $arrusers[$discussion->userid
]->email
;
268 $return->subject
= $subject;
269 $return->numunread
= '';
270 if ($cantrack && $forumtracked) {
271 if (isset($unreads[$discussion->id
])) {
272 $return->numunread
= (int) $unreads[$discussion->id
];
275 // Check if there are any replies to this discussion.
276 if (!empty($replies[$discussion->id
])) {
277 $return->numreplies
= (int) $replies[$discussion->id
]->replies
;
278 $return->lastpost
= (int) $replies[$discussion->id
]->lastpostid
;
279 } else { // No replies, so the last post will be the first post.
280 $return->numreplies
= 0;
281 $return->lastpost
= (int) $discussion->firstpost
;
283 // Get the last post as well as the user who made it.
284 $lastpost = $DB->get_record('forum_posts', array('id' => $return->lastpost
), '*', MUST_EXIST
);
285 if (empty($arrusers[$lastpost->userid
])) {
286 $arrusers[$lastpost->userid
] = $DB->get_record('user', array('id' => $lastpost->userid
),
287 'firstname, lastname, email, picture, imagealt', MUST_EXIST
);
289 $return->lastuserid
= $lastpost->userid
;
290 $return->lastuserfullname
= fullname($arrusers[$lastpost->userid
], $canviewfullname);
291 $return->lastuserimagealt
= $arrusers[$lastpost->userid
]->imagealt
;
292 $return->lastuserpicture
= $arrusers[$lastpost->userid
]->picture
;
293 $return->lastuseremail
= $arrusers[$lastpost->userid
]->email
;
294 // Add the discussion statistics to the array to return.
295 $arrdiscussions[$return->id
] = (array) $return;
300 return $arrdiscussions;
304 * Describes the get_forum_discussions return value.
306 * @return external_single_structure
309 public static function get_forum_discussions_returns() {
310 return new external_multiple_structure(
311 new external_single_structure(
313 'id' => new external_value(PARAM_INT
, 'Forum id'),
314 'course' => new external_value(PARAM_INT
, 'Course id'),
315 'forum' => new external_value(PARAM_INT
, 'The forum id'),
316 'name' => new external_value(PARAM_TEXT
, 'Discussion name'),
317 'userid' => new external_value(PARAM_INT
, 'User id'),
318 'groupid' => new external_value(PARAM_INT
, 'Group id'),
319 'assessed' => new external_value(PARAM_INT
, 'Is this assessed?'),
320 'timemodified' => new external_value(PARAM_INT
, 'Time modified'),
321 'usermodified' => new external_value(PARAM_INT
, 'The id of the user who last modified'),
322 'timestart' => new external_value(PARAM_INT
, 'Time discussion can start'),
323 'timeend' => new external_value(PARAM_INT
, 'Time discussion ends'),
324 'firstpost' => new external_value(PARAM_INT
, 'The first post in the discussion'),
325 'firstuserfullname' => new external_value(PARAM_TEXT
, 'The discussion creators fullname'),
326 'firstuserimagealt' => new external_value(PARAM_TEXT
, 'The discussion creators image alt'),
327 'firstuserpicture' => new external_value(PARAM_INT
, 'The discussion creators profile picture'),
328 'firstuseremail' => new external_value(PARAM_TEXT
, 'The discussion creators email'),
329 'subject' => new external_value(PARAM_TEXT
, 'The discussion subject'),
330 'numreplies' => new external_value(PARAM_TEXT
, 'The number of replies in the discussion'),
331 'numunread' => new external_value(PARAM_TEXT
, 'The number of unread posts, blank if this value is
332 not available due to forum settings.'),
333 'lastpost' => new external_value(PARAM_INT
, 'The id of the last post in the discussion'),
334 'lastuserid' => new external_value(PARAM_INT
, 'The id of the user who made the last post'),
335 'lastuserfullname' => new external_value(PARAM_TEXT
, 'The last person to posts fullname'),
336 'lastuserimagealt' => new external_value(PARAM_TEXT
, 'The last person to posts image alt'),
337 'lastuserpicture' => new external_value(PARAM_INT
, 'The last person to posts profile picture'),
338 'lastuseremail' => new external_value(PARAM_TEXT
, 'The last person to posts email'),