/mod/forum/externallib.php
PHP | 2761 lines | 1873 code | 341 blank | 547 comment | 134 complexity | f0542cf2404bd980d83e69b81e7e5182 MD5 | raw file
Possible License(s): MIT, AGPL-3.0, MPL-2.0-no-copyleft-exception, LGPL-3.0, GPL-3.0, Apache-2.0, LGPL-2.1, BSD-3-Clause
Large files files are truncated, but you can click here to view the full file
- <?php
- // This file is part of Moodle - http://moodle.org/
- //
- // Moodle is free software: you can redistribute it and/or modify
- // it under the terms of the GNU General Public License as published by
- // the Free Software Foundation, either version 3 of the License, or
- // (at your option) any later version.
- //
- // Moodle is distributed in the hope that it will be useful,
- // but WITHOUT ANY WARRANTY; without even the implied warranty of
- // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- // GNU General Public License for more details.
- //
- // You should have received a copy of the GNU General Public License
- // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
- /**
- * External forum API
- *
- * @package mod_forum
- * @copyright 2012 Mark Nelson <markn@moodle.com>
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- */
- defined('MOODLE_INTERNAL') || die;
- require_once("$CFG->libdir/externallib.php");
- use mod_forum\local\exporters\post as post_exporter;
- use mod_forum\local\exporters\discussion as discussion_exporter;
- class mod_forum_external extends external_api {
- /**
- * Describes the parameters for get_forum.
- *
- * @return external_function_parameters
- * @since Moodle 2.5
- */
- public static function get_forums_by_courses_parameters() {
- return new external_function_parameters (
- array(
- 'courseids' => new external_multiple_structure(new external_value(PARAM_INT, 'course ID',
- VALUE_REQUIRED, '', NULL_NOT_ALLOWED), 'Array of Course IDs', VALUE_DEFAULT, array()),
- )
- );
- }
- /**
- * Returns a list of forums in a provided list of courses,
- * if no list is provided all forums that the user can view
- * will be returned.
- *
- * @param array $courseids the course ids
- * @return array the forum details
- * @since Moodle 2.5
- */
- public static function get_forums_by_courses($courseids = array()) {
- global $CFG;
- require_once($CFG->dirroot . "/mod/forum/lib.php");
- $params = self::validate_parameters(self::get_forums_by_courses_parameters(), array('courseids' => $courseids));
- $courses = array();
- if (empty($params['courseids'])) {
- $courses = enrol_get_my_courses();
- $params['courseids'] = array_keys($courses);
- }
- // Array to store the forums to return.
- $arrforums = array();
- $warnings = array();
- // Ensure there are courseids to loop through.
- if (!empty($params['courseids'])) {
- list($courses, $warnings) = external_util::validate_courses($params['courseids'], $courses);
- // Get the forums in this course. This function checks users visibility permissions.
- $forums = get_all_instances_in_courses("forum", $courses);
- foreach ($forums as $forum) {
- $course = $courses[$forum->course];
- $cm = get_coursemodule_from_instance('forum', $forum->id, $course->id);
- $context = context_module::instance($cm->id);
- // Skip forums we are not allowed to see discussions.
- if (!has_capability('mod/forum:viewdiscussion', $context)) {
- continue;
- }
- $forum->name = external_format_string($forum->name, $context->id);
- // Format the intro before being returning using the format setting.
- $options = array('noclean' => true);
- list($forum->intro, $forum->introformat) =
- external_format_text($forum->intro, $forum->introformat, $context->id, 'mod_forum', 'intro', null, $options);
- $forum->introfiles = external_util::get_area_files($context->id, 'mod_forum', 'intro', false, false);
- // Discussions count. This function does static request cache.
- $forum->numdiscussions = forum_count_discussions($forum, $cm, $course);
- $forum->cmid = $forum->coursemodule;
- $forum->cancreatediscussions = forum_user_can_post_discussion($forum, null, -1, $cm, $context);
- $forum->istracked = forum_tp_is_tracked($forum);
- if ($forum->istracked) {
- $forum->unreadpostscount = forum_tp_count_forum_unread_posts($cm, $course);
- }
- // Add the forum to the array to return.
- $arrforums[$forum->id] = $forum;
- }
- }
- return $arrforums;
- }
- /**
- * Describes the get_forum return value.
- *
- * @return external_single_structure
- * @since Moodle 2.5
- */
- public static function get_forums_by_courses_returns() {
- return new external_multiple_structure(
- new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'Forum id'),
- 'course' => new external_value(PARAM_INT, 'Course id'),
- 'type' => new external_value(PARAM_TEXT, 'The forum type'),
- 'name' => new external_value(PARAM_RAW, 'Forum name'),
- 'intro' => new external_value(PARAM_RAW, 'The forum intro'),
- 'introformat' => new external_format_value('intro'),
- 'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL),
- 'duedate' => new external_value(PARAM_INT, 'duedate for the user', VALUE_OPTIONAL),
- 'cutoffdate' => new external_value(PARAM_INT, 'cutoffdate for the user', VALUE_OPTIONAL),
- 'assessed' => new external_value(PARAM_INT, 'Aggregate type'),
- 'assesstimestart' => new external_value(PARAM_INT, 'Assess start time'),
- 'assesstimefinish' => new external_value(PARAM_INT, 'Assess finish time'),
- 'scale' => new external_value(PARAM_INT, 'Scale'),
- 'grade_forum' => new external_value(PARAM_INT, 'Whole forum grade'),
- 'grade_forum_notify' => new external_value(PARAM_INT, 'Whether to send notifications to students upon grading by default'),
- 'maxbytes' => new external_value(PARAM_INT, 'Maximum attachment size'),
- 'maxattachments' => new external_value(PARAM_INT, 'Maximum number of attachments'),
- 'forcesubscribe' => new external_value(PARAM_INT, 'Force users to subscribe'),
- 'trackingtype' => new external_value(PARAM_INT, 'Subscription mode'),
- 'rsstype' => new external_value(PARAM_INT, 'RSS feed for this activity'),
- 'rssarticles' => new external_value(PARAM_INT, 'Number of RSS recent articles'),
- 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
- 'warnafter' => new external_value(PARAM_INT, 'Post threshold for warning'),
- 'blockafter' => new external_value(PARAM_INT, 'Post threshold for blocking'),
- 'blockperiod' => new external_value(PARAM_INT, 'Time period for blocking'),
- 'completiondiscussions' => new external_value(PARAM_INT, 'Student must create discussions'),
- 'completionreplies' => new external_value(PARAM_INT, 'Student must post replies'),
- 'completionposts' => new external_value(PARAM_INT, 'Student must post discussions or replies'),
- 'cmid' => new external_value(PARAM_INT, 'Course module id'),
- 'numdiscussions' => new external_value(PARAM_INT, 'Number of discussions in the forum', VALUE_OPTIONAL),
- 'cancreatediscussions' => new external_value(PARAM_BOOL, 'If the user can create discussions', VALUE_OPTIONAL),
- 'lockdiscussionafter' => new external_value(PARAM_INT, 'After what period a discussion is locked', VALUE_OPTIONAL),
- 'istracked' => new external_value(PARAM_BOOL, 'If the user is tracking the forum', VALUE_OPTIONAL),
- 'unreadpostscount' => new external_value(PARAM_INT, 'The number of unread posts for tracked forums',
- VALUE_OPTIONAL),
- ), 'forum'
- )
- );
- }
- /**
- * Get the forum posts in the specified discussion.
- *
- * @param int $discussionid
- * @param string $sortby
- * @param string $sortdirection
- * @return array
- */
- public static function get_discussion_posts(int $discussionid, ?string $sortby, ?string $sortdirection) {
- global $USER;
- // Validate the parameter.
- $params = self::validate_parameters(self::get_discussion_posts_parameters(), [
- 'discussionid' => $discussionid,
- 'sortby' => $sortby,
- 'sortdirection' => $sortdirection,
- ]);
- $warnings = [];
- $vaultfactory = mod_forum\local\container::get_vault_factory();
- $discussionvault = $vaultfactory->get_discussion_vault();
- $discussion = $discussionvault->get_from_id($params['discussionid']);
- $forumvault = $vaultfactory->get_forum_vault();
- $forum = $forumvault->get_from_id($discussion->get_forum_id());
- $context = $forum->get_context();
- self::validate_context($context);
- $sortby = $params['sortby'];
- $sortdirection = $params['sortdirection'];
- $sortallowedvalues = ['id', 'created', 'modified'];
- $directionallowedvalues = ['ASC', 'DESC'];
- if (!in_array(strtolower($sortby), $sortallowedvalues)) {
- throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $sortby . '),' .
- 'allowed values are: ' . implode(', ', $sortallowedvalues));
- }
- $sortdirection = strtoupper($sortdirection);
- if (!in_array($sortdirection, $directionallowedvalues)) {
- throw new invalid_parameter_exception('Invalid value for sortdirection parameter (value: ' . $sortdirection . '),' .
- 'allowed values are: ' . implode(',', $directionallowedvalues));
- }
- $managerfactory = mod_forum\local\container::get_manager_factory();
- $capabilitymanager = $managerfactory->get_capability_manager($forum);
- $postvault = $vaultfactory->get_post_vault();
- $posts = $postvault->get_from_discussion_id(
- $USER,
- $discussion->get_id(),
- $capabilitymanager->can_view_any_private_reply($USER),
- "{$sortby} {$sortdirection}"
- );
- $builderfactory = mod_forum\local\container::get_builder_factory();
- $postbuilder = $builderfactory->get_exported_posts_builder();
- $legacydatamapper = mod_forum\local\container::get_legacy_data_mapper_factory();
- return [
- 'posts' => $postbuilder->build($USER, [$forum], [$discussion], $posts),
- 'ratinginfo' => \core_rating\external\util::get_rating_info(
- $legacydatamapper->get_forum_data_mapper()->to_legacy_object($forum),
- $forum->get_context(),
- 'mod_forum',
- 'post',
- $legacydatamapper->get_post_data_mapper()->to_legacy_objects($posts)
- ),
- 'warnings' => $warnings,
- ];
- }
- /**
- * Describe the post parameters.
- *
- * @return external_function_parameters
- */
- public static function get_discussion_posts_parameters() {
- return new external_function_parameters ([
- 'discussionid' => new external_value(PARAM_INT, 'The ID of the discussion from which to fetch posts.', VALUE_REQUIRED),
- 'sortby' => new external_value(PARAM_ALPHA, 'Sort by this element: id, created or modified', VALUE_DEFAULT, 'created'),
- 'sortdirection' => new external_value(PARAM_ALPHA, 'Sort direction: ASC or DESC', VALUE_DEFAULT, 'DESC')
- ]);
- }
- /**
- * Describe the post return format.
- *
- * @return external_single_structure
- */
- public static function get_discussion_posts_returns() {
- return new external_single_structure([
- 'posts' => new external_multiple_structure(\mod_forum\local\exporters\post::get_read_structure()),
- 'ratinginfo' => \core_rating\external\util::external_ratings_structure(),
- 'warnings' => new external_warnings()
- ]);
- }
- /**
- * Describes the parameters for get_forum_discussion_posts.
- *
- * @return external_function_parameters
- * @since Moodle 2.7
- */
- public static function get_forum_discussion_posts_parameters() {
- return new external_function_parameters (
- array(
- 'discussionid' => new external_value(PARAM_INT, 'discussion ID', VALUE_REQUIRED),
- 'sortby' => new external_value(PARAM_ALPHA,
- 'sort by this element: id, created or modified', VALUE_DEFAULT, 'created'),
- 'sortdirection' => new external_value(PARAM_ALPHA, 'sort direction: ASC or DESC', VALUE_DEFAULT, 'DESC')
- )
- );
- }
- /**
- * Returns a list of forum posts for a discussion
- *
- * @param int $discussionid the post ids
- * @param string $sortby sort by this element (id, created or modified)
- * @param string $sortdirection sort direction: ASC or DESC
- *
- * @return array the forum post details
- * @since Moodle 2.7
- * @todo MDL-65252 This will be removed in Moodle 4.1
- */
- public static function get_forum_discussion_posts($discussionid, $sortby = "created", $sortdirection = "DESC") {
- global $CFG, $DB, $USER, $PAGE;
- $posts = array();
- $warnings = array();
- // Validate the parameter.
- $params = self::validate_parameters(self::get_forum_discussion_posts_parameters(),
- array(
- 'discussionid' => $discussionid,
- 'sortby' => $sortby,
- 'sortdirection' => $sortdirection));
- // Compact/extract functions are not recommended.
- $discussionid = $params['discussionid'];
- $sortby = $params['sortby'];
- $sortdirection = $params['sortdirection'];
- $sortallowedvalues = array('id', 'created', 'modified');
- if (!in_array($sortby, $sortallowedvalues)) {
- throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $sortby . '),' .
- 'allowed values are: ' . implode(',', $sortallowedvalues));
- }
- $sortdirection = strtoupper($sortdirection);
- $directionallowedvalues = array('ASC', 'DESC');
- if (!in_array($sortdirection, $directionallowedvalues)) {
- throw new invalid_parameter_exception('Invalid value for sortdirection parameter (value: ' . $sortdirection . '),' .
- 'allowed values are: ' . implode(',', $directionallowedvalues));
- }
- $discussion = $DB->get_record('forum_discussions', array('id' => $discussionid), '*', MUST_EXIST);
- $forum = $DB->get_record('forum', array('id' => $discussion->forum), '*', MUST_EXIST);
- $course = $DB->get_record('course', array('id' => $forum->course), '*', MUST_EXIST);
- $cm = get_coursemodule_from_instance('forum', $forum->id, $course->id, false, MUST_EXIST);
- // Validate the module context. It checks everything that affects the module visibility (including groupings, etc..).
- $modcontext = context_module::instance($cm->id);
- self::validate_context($modcontext);
- // This require must be here, see mod/forum/discuss.php.
- require_once($CFG->dirroot . "/mod/forum/lib.php");
- // Check they have the view forum capability.
- require_capability('mod/forum:viewdiscussion', $modcontext, null, true, 'noviewdiscussionspermission', 'forum');
- if (! $post = forum_get_post_full($discussion->firstpost)) {
- throw new moodle_exception('notexists', 'forum');
- }
- // This function check groups, qanda, timed discussions, etc.
- if (!forum_user_can_see_post($forum, $discussion, $post, null, $cm)) {
- throw new moodle_exception('noviewdiscussionspermission', 'forum');
- }
- $canviewfullname = has_capability('moodle/site:viewfullnames', $modcontext);
- // We will add this field in the response.
- $canreply = forum_user_can_post($forum, $discussion, $USER, $cm, $course, $modcontext);
- $forumtracked = forum_tp_is_tracked($forum);
- $sort = 'p.' . $sortby . ' ' . $sortdirection;
- $allposts = forum_get_all_discussion_posts($discussion->id, $sort, $forumtracked);
- foreach ($allposts as $post) {
- if (!forum_user_can_see_post($forum, $discussion, $post, null, $cm, false)) {
- $warning = array();
- $warning['item'] = 'post';
- $warning['itemid'] = $post->id;
- $warning['warningcode'] = '1';
- $warning['message'] = 'You can\'t see this post';
- $warnings[] = $warning;
- continue;
- }
- // Function forum_get_all_discussion_posts adds postread field.
- // Note that the value returned can be a boolean or an integer. The WS expects a boolean.
- if (empty($post->postread)) {
- $post->postread = false;
- } else {
- $post->postread = true;
- }
- $post->isprivatereply = !empty($post->privatereplyto);
- $post->canreply = $canreply;
- if (!empty($post->children)) {
- $post->children = array_keys($post->children);
- } else {
- $post->children = array();
- }
- if (!forum_user_can_see_post($forum, $discussion, $post, null, $cm)) {
- // The post is available, but has been marked as deleted.
- // It will still be available but filled with a placeholder.
- $post->userid = null;
- $post->userfullname = null;
- $post->userpictureurl = null;
- $post->subject = get_string('privacy:request:delete:post:subject', 'mod_forum');
- $post->message = get_string('privacy:request:delete:post:message', 'mod_forum');
- $post->deleted = true;
- $posts[] = $post;
- continue;
- }
- $post->deleted = false;
- if (forum_is_author_hidden($post, $forum)) {
- $post->userid = null;
- $post->userfullname = null;
- $post->userpictureurl = null;
- } else {
- $user = new stdclass();
- $user->id = $post->userid;
- $user = username_load_fields_from_object($user, $post, null, array('picture', 'imagealt', 'email'));
- $post->userfullname = fullname($user, $canviewfullname);
- $userpicture = new user_picture($user);
- $userpicture->size = 1; // Size f1.
- $post->userpictureurl = $userpicture->get_url($PAGE)->out(false);
- }
- $post->subject = external_format_string($post->subject, $modcontext->id);
- // Rewrite embedded images URLs.
- $options = array('trusted' => $post->messagetrust);
- list($post->message, $post->messageformat) =
- external_format_text($post->message, $post->messageformat, $modcontext->id, 'mod_forum', 'post', $post->id,
- $options);
- // List attachments.
- if (!empty($post->attachment)) {
- $post->attachments = external_util::get_area_files($modcontext->id, 'mod_forum', 'attachment', $post->id);
- }
- $messageinlinefiles = external_util::get_area_files($modcontext->id, 'mod_forum', 'post', $post->id);
- if (!empty($messageinlinefiles)) {
- $post->messageinlinefiles = $messageinlinefiles;
- }
- // Post tags.
- $post->tags = \core_tag\external\util::get_item_tags('mod_forum', 'forum_posts', $post->id);
- $posts[] = $post;
- }
- $result = array();
- $result['posts'] = $posts;
- $result['ratinginfo'] = \core_rating\external\util::get_rating_info($forum, $modcontext, 'mod_forum', 'post', $posts);
- $result['warnings'] = $warnings;
- return $result;
- }
- /**
- * Describes the get_forum_discussion_posts return value.
- *
- * @return external_single_structure
- * @since Moodle 2.7
- */
- public static function get_forum_discussion_posts_returns() {
- return new external_single_structure(
- array(
- 'posts' => new external_multiple_structure(
- new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'Post id'),
- 'discussion' => new external_value(PARAM_INT, 'Discussion id'),
- 'parent' => new external_value(PARAM_INT, 'Parent id'),
- 'userid' => new external_value(PARAM_INT, 'User id'),
- 'created' => new external_value(PARAM_INT, 'Creation time'),
- 'modified' => new external_value(PARAM_INT, 'Time modified'),
- 'mailed' => new external_value(PARAM_INT, 'Mailed?'),
- 'subject' => new external_value(PARAM_TEXT, 'The post subject'),
- 'message' => new external_value(PARAM_RAW, 'The post message'),
- 'messageformat' => new external_format_value('message'),
- 'messagetrust' => new external_value(PARAM_INT, 'Can we trust?'),
- 'messageinlinefiles' => new external_files('post message inline files', VALUE_OPTIONAL),
- 'attachment' => new external_value(PARAM_RAW, 'Has attachments?'),
- 'attachments' => new external_files('attachments', VALUE_OPTIONAL),
- 'totalscore' => new external_value(PARAM_INT, 'The post message total score'),
- 'mailnow' => new external_value(PARAM_INT, 'Mail now?'),
- 'children' => new external_multiple_structure(new external_value(PARAM_INT, 'children post id')),
- 'canreply' => new external_value(PARAM_BOOL, 'The user can reply to posts?'),
- 'postread' => new external_value(PARAM_BOOL, 'The post was read'),
- 'userfullname' => new external_value(PARAM_TEXT, 'Post author full name'),
- 'userpictureurl' => new external_value(PARAM_URL, 'Post author picture.', VALUE_OPTIONAL),
- 'deleted' => new external_value(PARAM_BOOL, 'This post has been removed.'),
- 'isprivatereply' => new external_value(PARAM_BOOL, 'The post is a private reply'),
- 'tags' => new external_multiple_structure(
- \core_tag\external\tag_item_exporter::get_read_structure(), 'Tags', VALUE_OPTIONAL
- ),
- ), 'post'
- )
- ),
- 'ratinginfo' => \core_rating\external\util::external_ratings_structure(),
- 'warnings' => new external_warnings()
- )
- );
- }
- /**
- * Mark the get_forum_discussion_posts web service as deprecated.
- *
- * @return bool
- */
- public static function get_forum_discussion_posts_is_deprecated() {
- return true;
- }
- /**
- * Describes the parameters for get_forum_discussions_paginated.
- *
- * @deprecated since 3.7
- * @return external_function_parameters
- * @since Moodle 2.8
- */
- public static function get_forum_discussions_paginated_parameters() {
- return new external_function_parameters (
- array(
- 'forumid' => new external_value(PARAM_INT, 'forum instance id', VALUE_REQUIRED),
- 'sortby' => new external_value(PARAM_ALPHA,
- 'sort by this element: id, timemodified, timestart or timeend', VALUE_DEFAULT, 'timemodified'),
- 'sortdirection' => new external_value(PARAM_ALPHA, 'sort direction: ASC or DESC', VALUE_DEFAULT, 'DESC'),
- 'page' => new external_value(PARAM_INT, 'current page', VALUE_DEFAULT, -1),
- 'perpage' => new external_value(PARAM_INT, 'items per page', VALUE_DEFAULT, 0),
- )
- );
- }
- /**
- * Returns a list of forum discussions optionally sorted and paginated.
- *
- * @deprecated since 3.7
- * @param int $forumid the forum instance id
- * @param string $sortby sort by this element (id, timemodified, timestart or timeend)
- * @param string $sortdirection sort direction: ASC or DESC
- * @param int $page page number
- * @param int $perpage items per page
- *
- * @return array the forum discussion details including warnings
- * @since Moodle 2.8
- */
- public static function get_forum_discussions_paginated($forumid, $sortby = 'timemodified', $sortdirection = 'DESC',
- $page = -1, $perpage = 0) {
- global $CFG, $DB, $USER, $PAGE;
- require_once($CFG->dirroot . "/mod/forum/lib.php");
- $warnings = array();
- $discussions = array();
- $params = self::validate_parameters(self::get_forum_discussions_paginated_parameters(),
- array(
- 'forumid' => $forumid,
- 'sortby' => $sortby,
- 'sortdirection' => $sortdirection,
- 'page' => $page,
- 'perpage' => $perpage
- )
- );
- // Compact/extract functions are not recommended.
- $forumid = $params['forumid'];
- $sortby = $params['sortby'];
- $sortdirection = $params['sortdirection'];
- $page = $params['page'];
- $perpage = $params['perpage'];
- $sortallowedvalues = array('id', 'timemodified', 'timestart', 'timeend');
- if (!in_array($sortby, $sortallowedvalues)) {
- throw new invalid_parameter_exception('Invalid value for sortby parameter (value: ' . $sortby . '),' .
- 'allowed values are: ' . implode(',', $sortallowedvalues));
- }
- $sortdirection = strtoupper($sortdirection);
- $directionallowedvalues = array('ASC', 'DESC');
- if (!in_array($sortdirection, $directionallowedvalues)) {
- throw new invalid_parameter_exception('Invalid value for sortdirection parameter (value: ' . $sortdirection . '),' .
- 'allowed values are: ' . implode(',', $directionallowedvalues));
- }
- $forum = $DB->get_record('forum', array('id' => $forumid), '*', MUST_EXIST);
- $course = $DB->get_record('course', array('id' => $forum->course), '*', MUST_EXIST);
- $cm = get_coursemodule_from_instance('forum', $forum->id, $course->id, false, MUST_EXIST);
- // Validate the module context. It checks everything that affects the module visibility (including groupings, etc..).
- $modcontext = context_module::instance($cm->id);
- self::validate_context($modcontext);
- // Check they have the view forum capability.
- require_capability('mod/forum:viewdiscussion', $modcontext, null, true, 'noviewdiscussionspermission', 'forum');
- $sort = 'd.pinned DESC, d.' . $sortby . ' ' . $sortdirection;
- $alldiscussions = forum_get_discussions($cm, $sort, true, -1, -1, true, $page, $perpage, FORUM_POSTS_ALL_USER_GROUPS);
- if ($alldiscussions) {
- $canviewfullname = has_capability('moodle/site:viewfullnames', $modcontext);
- // Get the unreads array, this takes a forum id and returns data for all discussions.
- $unreads = array();
- if ($cantrack = forum_tp_can_track_forums($forum)) {
- if ($forumtracked = forum_tp_is_tracked($forum)) {
- $unreads = forum_get_discussions_unread($cm);
- }
- }
- // The forum function returns the replies for all the discussions in a given forum.
- $canseeprivatereplies = has_capability('mod/forum:readprivatereplies', $modcontext);
- $canlock = has_capability('moodle/course:manageactivities', $modcontext, $USER);
- $replies = forum_count_discussion_replies($forumid, $sort, -1, $page, $perpage, $canseeprivatereplies);
- foreach ($alldiscussions as $discussion) {
- // This function checks for qanda forums.
- // Note that the forum_get_discussions returns as id the post id, not the discussion id so we need to do this.
- $discussionrec = clone $discussion;
- $discussionrec->id = $discussion->discussion;
- if (!forum_user_can_see_discussion($forum, $discussionrec, $modcontext)) {
- $warning = array();
- // Function forum_get_discussions returns forum_posts ids not forum_discussions ones.
- $warning['item'] = 'post';
- $warning['itemid'] = $discussion->id;
- $warning['warningcode'] = '1';
- $warning['message'] = 'You can\'t see this discussion';
- $warnings[] = $warning;
- continue;
- }
- $discussion->numunread = 0;
- if ($cantrack && $forumtracked) {
- if (isset($unreads[$discussion->discussion])) {
- $discussion->numunread = (int) $unreads[$discussion->discussion];
- }
- }
- $discussion->numreplies = 0;
- if (!empty($replies[$discussion->discussion])) {
- $discussion->numreplies = (int) $replies[$discussion->discussion]->replies;
- }
- $discussion->name = external_format_string($discussion->name, $modcontext->id);
- $discussion->subject = external_format_string($discussion->subject, $modcontext->id);
- // Rewrite embedded images URLs.
- $options = array('trusted' => $discussion->messagetrust);
- list($discussion->message, $discussion->messageformat) =
- external_format_text($discussion->message, $discussion->messageformat,
- $modcontext->id, 'mod_forum', 'post', $discussion->id, $options);
- // List attachments.
- if (!empty($discussion->attachment)) {
- $discussion->attachments = external_util::get_area_files($modcontext->id, 'mod_forum', 'attachment',
- $discussion->id);
- }
- $messageinlinefiles = external_util::get_area_files($modcontext->id, 'mod_forum', 'post', $discussion->id);
- if (!empty($messageinlinefiles)) {
- $discussion->messageinlinefiles = $messageinlinefiles;
- }
- $discussion->locked = forum_discussion_is_locked($forum, $discussion);
- $discussion->canlock = $canlock;
- $discussion->canreply = forum_user_can_post($forum, $discussion, $USER, $cm, $course, $modcontext);
- if (forum_is_author_hidden($discussion, $forum)) {
- $discussion->userid = null;
- $discussion->userfullname = null;
- $discussion->userpictureurl = null;
- $discussion->usermodified = null;
- $discussion->usermodifiedfullname = null;
- $discussion->usermodifiedpictureurl = null;
- } else {
- $picturefields = explode(',', user_picture::fields());
- // Load user objects from the results of the query.
- $user = new stdclass();
- $user->id = $discussion->userid;
- $user = username_load_fields_from_object($user, $discussion, null, $picturefields);
- // Preserve the id, it can be modified by username_load_fields_from_object.
- $user->id = $discussion->userid;
- $discussion->userfullname = fullname($user, $canviewfullname);
- $userpicture = new user_picture($user);
- $userpicture->size = 1; // Size f1.
- $discussion->userpictureurl = $userpicture->get_url($PAGE)->out(false);
- $usermodified = new stdclass();
- $usermodified->id = $discussion->usermodified;
- $usermodified = username_load_fields_from_object($usermodified, $discussion, 'um', $picturefields);
- // Preserve the id (it can be overwritten due to the prefixed $picturefields).
- $usermodified->id = $discussion->usermodified;
- $discussion->usermodifiedfullname = fullname($usermodified, $canviewfullname);
- $userpicture = new user_picture($usermodified);
- $userpicture->size = 1; // Size f1.
- $discussion->usermodifiedpictureurl = $userpicture->get_url($PAGE)->out(false);
- }
- $discussions[] = $discussion;
- }
- }
- $result = array();
- $result['discussions'] = $discussions;
- $result['warnings'] = $warnings;
- return $result;
- }
- /**
- * Describes the get_forum_discussions_paginated return value.
- *
- * @deprecated since 3.7
- * @return external_single_structure
- * @since Moodle 2.8
- */
- public static function get_forum_discussions_paginated_returns() {
- return new external_single_structure(
- array(
- 'discussions' => new external_multiple_structure(
- new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'Post id'),
- 'name' => new external_value(PARAM_TEXT, 'Discussion name'),
- 'groupid' => new external_value(PARAM_INT, 'Group id'),
- 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
- 'usermodified' => new external_value(PARAM_INT, 'The id of the user who last modified'),
- 'timestart' => new external_value(PARAM_INT, 'Time discussion can start'),
- 'timeend' => new external_value(PARAM_INT, 'Time discussion ends'),
- 'discussion' => new external_value(PARAM_INT, 'Discussion id'),
- 'parent' => new external_value(PARAM_INT, 'Parent id'),
- 'userid' => new external_value(PARAM_INT, 'User who started the discussion id'),
- 'created' => new external_value(PARAM_INT, 'Creation time'),
- 'modified' => new external_value(PARAM_INT, 'Time modified'),
- 'mailed' => new external_value(PARAM_INT, 'Mailed?'),
- 'subject' => new external_value(PARAM_TEXT, 'The post subject'),
- 'message' => new external_value(PARAM_RAW, 'The post message'),
- 'messageformat' => new external_format_value('message'),
- 'messagetrust' => new external_value(PARAM_INT, 'Can we trust?'),
- 'messageinlinefiles' => new external_files('post message inline files', VALUE_OPTIONAL),
- 'attachment' => new external_value(PARAM_RAW, 'Has attachments?'),
- 'attachments' => new external_files('attachments', VALUE_OPTIONAL),
- 'totalscore' => new external_value(PARAM_INT, 'The post message total score'),
- 'mailnow' => new external_value(PARAM_INT, 'Mail now?'),
- 'userfullname' => new external_value(PARAM_TEXT, 'Post author full name'),
- 'usermodifiedfullname' => new external_value(PARAM_TEXT, 'Post modifier full name'),
- 'userpictureurl' => new external_value(PARAM_URL, 'Post author picture.'),
- 'usermodifiedpictureurl' => new external_value(PARAM_URL, 'Post modifier picture.'),
- 'numreplies' => new external_value(PARAM_INT, 'The number of replies in the discussion'),
- 'numunread' => new external_value(PARAM_INT, 'The number of unread discussions.'),
- 'pinned' => new external_value(PARAM_BOOL, 'Is the discussion pinned'),
- 'locked' => new external_value(PARAM_BOOL, 'Is the discussion locked'),
- 'canreply' => new external_value(PARAM_BOOL, 'Can the user reply to the discussion'),
- 'canlock' => new external_value(PARAM_BOOL, 'Can the user lock the discussion'),
- ), 'post'
- )
- ),
- 'warnings' => new external_warnings()
- )
- );
- }
- /**
- * Describes the parameters for get_forum_discussions.
- *
- * @return external_function_parameters
- * @since Moodle 3.7
- */
- public static function get_forum_discussions_parameters() {
- return new external_function_parameters (
- array(
- 'forumid' => new external_value(PARAM_INT, 'forum instance id', VALUE_REQUIRED),
- 'sortorder' => new external_value(PARAM_INT,
- 'sort by this element: numreplies, , created or timemodified', VALUE_DEFAULT, -1),
- 'page' => new external_value(PARAM_INT, 'current page', VALUE_DEFAULT, -1),
- 'perpage' => new external_value(PARAM_INT, 'items per page', VALUE_DEFAULT, 0),
- 'groupid' => new external_value(PARAM_INT, 'group id', VALUE_DEFAULT, 0),
- )
- );
- }
- /**
- * Returns a list of forum discussions optionally sorted and paginated.
- *
- * @param int $forumid the forum instance id
- * @param int $sortorder The sort order
- * @param int $page page number
- * @param int $perpage items per page
- * @param int $groupid the user course group
- *
- *
- * @return array the forum discussion details including warnings
- * @since Moodle 3.7
- */
- public static function get_forum_discussions(int $forumid, ?int $sortorder = -1, ?int $page = -1,
- ?int $perpage = 0, ?int $groupid = 0) {
- global $CFG, $DB, $USER;
- require_once($CFG->dirroot . "/mod/forum/lib.php");
- $warnings = array();
- $discussions = array();
- $params = self::validate_parameters(self::get_forum_discussions_parameters(),
- array(
- 'forumid' => $forumid,
- 'sortorder' => $sortorder,
- 'page' => $page,
- 'perpage' => $perpage,
- 'groupid' => $groupid
- )
- );
- // Compact/extract functions are not recommended.
- $forumid = $params['forumid'];
- $sortorder = $params['sortorder'];
- $page = $params['page'];
- $perpage = $params['perpage'];
- $groupid = $params['groupid'];
- $vaultfactory = \mod_forum\local\container::get_vault_factory();
- $discussionlistvault = $vaultfactory->get_discussions_in_forum_vault();
- $sortallowedvalues = array(
- $discussionlistvault::SORTORDER_LASTPOST_DESC,
- $discussionlistvault::SORTORDER_LASTPOST_ASC,
- $discussionlistvault::SORTORDER_CREATED_DESC,
- $discussionlistvault::SORTORDER_CREATED_ASC,
- $discussionlistvault::SORTORDER_REPLIES_DESC,
- $discussionlistvault::SORTORDER_REPLIES_ASC
- );
- // If sortorder not defined set a default one.
- if ($sortorder == -1) {
- $sortorder = $discussionlistvault::SORTORDER_LASTPOST_DESC;
- }
- if (!in_array($sortorder, $sortallowedvalues)) {
- throw new invalid_parameter_exception('Invalid value for sortorder parameter (value: ' . $sortorder . '),' .
- ' allowed values are: ' . implode(',', $sortallowedvalues));
- }
- $managerfactory = \mod_forum\local\container::get_manager_factory();
- $urlfactory = \mod_forum\local\container::get_url_factory();
- $legacydatamapperfactory = mod_forum\local\container::get_legacy_data_mapper_factory();
- $forumvault = $vaultfactory->get_forum_vault();
- $forum = $forumvault->get_from_id($forumid);
- if (!$forum) {
- throw new \moodle_exception("Unable to find forum with id {$forumid}");
- }
- $forumdatamapper = $legacydatamapperfactory->get_forum_data_mapper();
- $forumrecord = $forumdatamapper->to_legacy_object($forum);
- $capabilitymanager = $managerfactory->get_capability_manager($forum);
- $course = $DB->get_record('course', array('id' => $forum->get_course_id()), '*', MUST_EXIST);
- $cm = get_coursemodule_from_instance('forum', $forum->get_id(), $course->id, false, MUST_EXIST);
- // Validate the module context. It checks everything that affects the module visibility (including groupings, etc..).
- $modcontext = context_module::instance($cm->id);
- self::validate_context($modcontext);
- $canseeanyprivatereply = $capabilitymanager->can_view_any_private_reply($USER);
- // Check they have the view forum capability.
- if (!$capabilitymanager->can_view_discussions($USER)) {
- throw new moodle_exception('noviewdiscussionspermission', 'forum');
- }
- $alldiscussions = mod_forum_get_discussion_summaries($forum, $USER, $groupid, $sortorder, $page, $perpage);
- if ($alldiscussions) {
- $discussionids = array_keys($alldiscussions);
- $postvault = $vaultfactory->get_post_vault();
- $postdatamapper = $legacydatamapperfactory->get_post_data_mapper();
- // Return the reply count for each discussion in a given forum.
- $replies = $postvault->get_reply_count_for_discussion_ids($USER, $discussionids, $canseeanyprivatereply);
- // Return the first post for each discussion in a given forum.
- $firstposts = $postvault->get_first_post_for_discussion_ids($discussionids);
- // Get the unreads array, this takes a forum id and returns data for all discussions.
- $unreads = array();
- if ($cantrack = forum_tp_can_track_forums($forumrecord)) {
- if ($forumtracked = forum_tp_is_tracked($forumrecord)) {
- $unreads = $postvault->get_unread_count_for_discussion_ids($USER, $discussionids, $canseeanyprivatereply);
- }
- }
- $canlock = $capabilitymanager->can_manage_forum($USER);
- $usercontext = context_user::instance($USER->id);
- $ufservice = core_favourites\service_factory::get_service_for_user_context($usercontext);
- $canfavourite = has_capability('mod/forum:cantogglefavourite', $modcontext, $USER);
- foreach ($alldiscussions as $discussionsummary) {
- $discussion = $discussionsummary->get_discussion();
- $firstpostauthor = $discussionsummary->get_first_post_author();
- $latestpostauthor = $discussionsummary->get_latest_post_author();
- // This function checks for qanda forums.
- $canviewdiscussion = $capabilitymanager->can_view_discussion($USER, $discussion);
- if (!$canviewdiscussion) {
- $warning = array();
- // Function forum_get_discussions returns forum_posts ids not forum_discussions ones.
- $warning['item'] = 'post';
- $warning['itemid'] = $discussion->get_id();
- $warning['warningcode'] = '1';
- $warning['message'] = 'You can\'t see this discussion';
- $warnings[] = $warning;
- continue;
- }
- $firstpost = $firstposts[$discussion->get_first_post_id()];
- $discussionobject = $postdatamapper->to_legacy_object($firstpost);
- // Fix up the types for these properties.
- $discussionobject->mailed = $discussionobject->mailed ? 1 : 0;
- $discussionobject->messagetrust = $discussionobject->messagetrust ? 1 : 0;
- $discussionobject->mailnow = $discussionobject->mailnow ? 1 : 0;
- $discussionobject->groupid = $discussion->get_group_id();
- $discussionobject->timemodified = $discussion->get_time_modified();
- $discussionobject->usermodified = $discussion->get_user_modified();
- $discussionobject->timestart = $discussion->get_time_start();
- $discussionobject->timeend = $discussion->get_time_end();
- $discussionobject->pinned = $discussion->is_pinned();
- $discussionobject->numunread = 0;
- if ($cantrack && $forumtracked) {
- if (isset($unreads[$discussion->get_id()])) {
- $discussionobject->numunread = (int) $unreads[$discussion->get_id()];
- }
- }
- $discussionobject->numreplies = 0;
- if (!empty($replies[$discussion->get_id()])) {
- $discussionobject->numreplies = (int) $replies[$discussion->get_id()];
- }
- $discussionobject->name = external_format_string($discussion->get_name(), $modcontext->id);
- $discussionobject->subject = external_format_string($discussionobject->subject, $modcontext->id);
- // Rewrite embedded images URLs.
- $options = array('trusted' => $discussionobject->messagetrust);
- list($discussionobject->message, $discussionobject->messageformat) =
- external_format_text($discussionobject->message, $discussionobject->messageformat,
- $modcontext->id, 'mod_forum', 'post', $discussionobject->id, $options);
- // List attachments.
- if (!empty($discussionobject->attachment)) {
- $discussionobject->attachments = external_util::get_area_files($modcontext->id, 'mod_forum',
- 'attachment', $discussionobject->id);
- }
- $messageinlinefiles = external_util::get_area_files($modcontext->id, 'mod_forum', 'post',
- $discussionobject->id);
- if (!empty($messageinlinefiles)) {
- $discussionobject->messageinlinefiles = $messageinlinefiles;
- }
- $discussionobject->locked = $forum->is_discussion_locked($discussion);
- $discussionobject->canlock = $canlock;
- $discussionobject->starred = !empty($ufservice) ? $ufservice->favourite_exists('mod_forum', 'discussions',
- $discussion->get_id(), $modcontext) : false;
- $discussionobject->canreply = $capabilitymanager->can_post_in_discussion($USER, $discussion);
- $discussionobject->canfavourite = $canfavourite;
- if (forum_is_author_hidden($discussionobject, $forumrecord)) {
- $discussionobject->userid = null;
- $discussionobject->userfullname = null;
- $discussionobject->userpictureurl = null;
- $discussionobject->usermodified = null;
- $discussionobject->usermodifiedfullname = null;
- $discussionobject->usermodifiedpictureurl = null;
- } else {
- $discussionobject->userfullname = $firstpostauthor->get_full_name();
- $discussionobject->userpictureurl = $urlfactory->get_author_profile_image_url($firstpostauthor, null, 2)
- ->out(false);
- $discussionobject->usermodifiedfullname = $latestpostauthor->get_full_name();
- $discussionobject->usermodifiedpictureurl = $urlfactory->get_author_profile_image_url(
- $latestpostauthor, null, 2)->out(false);
- }
- $discussions[] = (array) $discussionobject;
- }
- }
- $result = array();
- $result['discussions'] = $discussions;
- $result['warnings'] = $warnings;
- return $result;
- }
- /**
- * Describes the get_forum_discussions return value.
- *
- * @return external_single_structure
- * @since Moodle 3.7
- */
- public static function get_forum_discussions_returns() {
- return new external_single_structure(
- array(
- 'discussions' => new external_multiple_structure(
- new external_single_structure(
- array(
- 'id' => new external_value(PARAM_INT, 'Post id'),
- 'name' => new external_value(PARAM_TEXT, 'Discussion name'),
- …
Large files files are truncated, but you can click here to view the full file