MDL-42098 - mod_forum: Update webservice sql query to include all name fields.
[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_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, $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());
66         } else {
67             $courseids = $params['courseids'];
68         }
70         // Array to store the forums to return.
71         $arrforums = array();
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])) {
91                             continue;
92                         }
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;
106                     }
107                 }
108             }
109         }
111         return $arrforums;
112     }
114     /**
115      * Describes the get_forum return value.
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     }
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     }
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;
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.
192         $arrusers = array();
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                     }
243                     $usernamefields = user_picture::fields();
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),
247                                 $usernamefields, MUST_EXIST);
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),
288                                 $usernamefields, MUST_EXIST);
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         }
301         return $arrdiscussions;
302     }
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     }