| [ Index ] |
PHP Cross Reference of moodle-2.8 |
[Summary view] [Print] [Text view]
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 <[email protected]> 23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 24 */ 25 26 defined('MOODLE_INTERNAL') || die; 27 28 require_once("$CFG->libdir/externallib.php"); 29 30 class mod_forum_external extends external_api { 31 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 } 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 61 $params = self::validate_parameters(self::get_forums_by_courses_parameters(), array('courseids' => $courseids)); 62 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 } 69 70 // Array to store the forums to return. 71 $arrforums = array(); 72 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 course object. 86 $course = $modinfo->get_course(); 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) { 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]; 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; 106 107 // Discussions count. This function does static request cache. 108 $forum->numdiscussions = forum_count_discussions($forum, $cm, $course); 109 110 // Add the forum to the array to return. 111 $arrforums[$forum->id] = (array) $forum; 112 } 113 } 114 } 115 } 116 117 return $arrforums; 118 } 119 120 /** 121 * Describes the get_forum return value. 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'), 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) 155 ), 'forum' 156 ) 157 ); 158 } 159 160 /** 161 * Describes the parameters for get_forum_discussions. 162 * 163 * @return external_external_function_parameters 164 * @since Moodle 2.5 165 * @deprecated Moodle 2.8 MDL-46458 - Please do not call this function any more. 166 * @see get_forum_discussions_paginated 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), 173 'limitfrom' => new external_value(PARAM_INT, 'limit from', VALUE_DEFAULT, 0), 174 'limitnum' => new external_value(PARAM_INT, 'limit number', VALUE_DEFAULT, 0) 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 184 * @param int $limitfrom limit from SQL data 185 * @param int $limitnum limit number SQL data 186 * 187 * @return array the forum discussion details 188 * @since Moodle 2.5 189 * @deprecated Moodle 2.8 MDL-46458 - Please do not call this function any more. 190 * @see get_forum_discussions_paginated 191 */ 192 public static function get_forum_discussions($forumids, $limitfrom = 0, $limitnum = 0) { 193 global $CFG, $DB, $USER; 194 195 require_once($CFG->dirroot . "/mod/forum/lib.php"); 196 197 // Validate the parameter. 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']; 207 208 // Array to store the forum discussions to return. 209 $arrdiscussions = array(); 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); 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 223 // Get the module context. 224 $modcontext = context_module::instance($cm->id); 225 226 // Validate the context. 227 self::validate_context($modcontext); 228 229 require_capability('mod/forum:viewdiscussion', $modcontext); 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)"; 243 } 244 } 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 263 foreach ($discussions as $discussion) { 264 // This function checks capabilities, timed discussions, groups and qanda forums posting. 265 if (!forum_user_can_see_discussion($forum, $discussion, $modcontext)) { 266 continue; 267 } 268 269 $usernamefields = user_picture::fields(); 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), 273 $usernamefields, MUST_EXIST); 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; 306 } else { // No replies, so the last post will be the first post. 307 $return->numreplies = 0; 308 $return->lastpost = (int) $discussion->firstpost; 309 } 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), 314 $usernamefields, MUST_EXIST); 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 335 * @deprecated Moodle 2.8 MDL-46458 - Please do not call this function any more. 336 * @see get_forum_discussions_paginated 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 } 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 */ 400 public static function get_forum_discussion_posts($discussionid, $sortby = "created", $sortdirection = "DESC") { 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. 477 // Note that the value returned can be a boolean or an integer. The WS expects a boolean. 478 if (empty($post->postread)) { 479 $posts[$pid]->postread = false; 480 } else { 481 $posts[$pid]->postread = true; 482 } 483 484 $posts[$pid]->canreply = $canreply; 485 if (!empty($posts[$pid]->children)) { 486 $posts[$pid]->children = array_keys($posts[$pid]->children); 487 } else { 488 $posts[$pid]->children = array(); 489 } 490 491 $user = new stdclass(); 492 $user->id = $post->userid; 493 $user = username_load_fields_from_object($user, $post); 494 $post->userfullname = fullname($user, $canviewfullname); 495 $post->userpictureurl = moodle_url::make_webservice_pluginfile_url( 496 context_user::instance($user->id)->id, 'user', 'icon', null, '/', 'f1')->out(false); 497 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(); 510 $fileurl = moodle_url::make_webservice_pluginfile_url( 511 $modcontext->id, 'mod_forum', 'attachment', $post->id, '/', $filename); 512 513 $post->attachments[] = array( 514 'filename' => $filename, 515 'mimetype' => $file->get_mimetype(), 516 'fileurl' => $fileurl->out(false) 517 ); 518 } 519 } 520 } 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'), 552 'messageformat' => new external_format_value('message'), 553 'messagetrust' => new external_value(PARAM_INT, 'Can we trust?'), 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 ), 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'), 569 'userfullname' => new external_value(PARAM_TEXT, 'Post author full name'), 570 'userpictureurl' => new external_value(PARAM_URL, 'Post author picture.', VALUE_OPTIONAL) 571 ), 'post' 572 ) 573 ), 574 'warnings' => new external_warnings() 575 ) 576 ); 577 } 578 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 812 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Fri Nov 28 20:29:05 2014 | Cross-referenced by PHPXref 0.7.1 |