Proyectos de Subversion Moodle

<?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/>.

use mod_forum\local\exporters\post as post_exporter;

use mod_forum\local\exporters\discussion as discussion_exporter;

use core_external\external_api;

use core_external\external_files;

use core_external\external_format_value;

use core_external\external_function_parameters;

use core_external\external_multiple_structure;

use core_external\external_single_structure;

use core_external\external_value;

use core_external\external_warnings;

use core_external\util as external_util;

/**

 * 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

 */

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 = \core_external\util::format_string($forum->name, $context);

                // Format the intro before being returning using the format setting.

                $options = array('noclean' => true);

                [$forum->intro, $forum->introformat] = \core_external\util::format_text(

                    $forum->intro,

                    $forum->introformat,

                    $context,

                    'mod_forum',

                    'intro',

                    null,

                    $options

                );

                $forum->introfiles = external_util::get_area_files($context->id, 'mod_forum', 'intro', false, false);

                $forum->lang = clean_param($forum->lang, PARAM_LANG);

                // 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() {

        // This should be using helper_for_get_mods_by_courses::standard_coursemodule_elements_returns, but it is so horribly

        // inconsistent with all similar web serviecs in other modules that we just can't.

        // Also, the return type declaration is wrong, but I am not changing it now because I don't want ot break things.

        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),

                    'lang' => new external_value(PARAM_SAFEDIR, 'Forced activity language', 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

     * @param   bool $includeinlineattachments Whether inline attachments should be included or not.

     * @return  array

     */

    public static function get_discussion_posts(int $discussionid, ?string $sortby, ?string $sortdirection, bool $includeinlineattachments = false) {

        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));

        }

        $orderbysql = "{$sortby} {$sortdirection}";

        if (!empty($sortby) && $sortby != 'id') {

            $orderbysql .= ", id {$sortdirection}";

        }

        $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),

                $orderbysql

            );

        $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, $includeinlineattachments),

            'forumid' => $discussion->get_forum_id(),

            'courseid' => $discussion->get_course_id(),

            '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'),

            'includeinlineattachments' => new external_value(PARAM_BOOL, 'Whether inline attachments should be included or not', VALUE_DEFAULT,

                false),

        ]);

    }

    /**

     * 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()),

            'forumid' => new external_value(PARAM_INT, 'The forum id'),

            'courseid' => new external_value(PARAM_INT, 'The forum course id'),

            'ratinginfo' => \core_rating\external\util::external_ratings_structure(),

            '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 = \core_external\util::format_string($discussion->get_name(), $modcontext);

                $discussionobject->subject = \core_external\util::format_string($discussionobject->subject, $modcontext);

                // Rewrite embedded images URLs.

                $options = array('trusted' => $discussionobject->messagetrust);

                list($discussionobject->message, $discussionobject->messageformat) =

                    \core_external\util::format_text($discussionobject->message, $discussionobject->messageformat,

                        $modcontext, '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_RAW, '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_RAW, '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'),

                            'starred' => new external_value(PARAM_BOOL, 'Is the discussion starred'),

                            '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'),

                            'canfavourite' => new external_value(PARAM_BOOL, 'Can the user star the discussion'),

                        ), 'post'

                    )

                ),

                'warnings' => new external_warnings()

            )

        );

    }

    /**

     * Returns description of method parameters

     *

     * @return external_function_parameters

     * @since Moodle 2.9

     */

    public static function view_forum_parameters() {

        return new external_function_parameters(

            array(

                'forumid' => new external_value(PARAM_INT, 'forum instance id')

            )

        );

    }

    /**

     * Trigger the course module viewed event and update the module completion status.

     *

     * @param int $forumid the forum instance id

     * @return array of warnings and status result

     * @since Moodle 2.9

     * @throws moodle_exception

     */

    public static function view_forum($forumid) {

        global $DB, $CFG;

        require_once($CFG->dirroot . "/mod/forum/lib.php");

        $params = self::validate_parameters(self::view_forum_parameters(),

                                            array(

                                                'forumid' => $forumid

                                            ));

        $warnings = array();

        // Request and permission validation.

        $forum = $DB->get_record('forum', array('id' => $params['forumid']), '*', MUST_EXIST);

        list($course, $cm) = get_course_and_cm_from_instance($forum, 'forum');

        $context = context_module::instance($cm->id);

        self::validate_context($context);

        require_capability('mod/forum:viewdiscussion', $context, null, true, 'noviewdiscussionspermission', 'forum');

        // Call the forum/lib API.

        forum_view($forum, $course, $cm, $context);

        $result = array();

        $result['status'] = true;

        $result['warnings'] = $warnings;

        return $result;

    }

    /**

     * Returns description of method result value

     *

     * @return \core_external\external_description

     * @since Moodle 2.9

     */

    public static function view_forum_returns() {

        return new external_single_structure(

            array(

                'status' => new external_value(PARAM_BOOL, 'status: true if success'),

                'warnings' => new external_warnings()

            )

        );

    }

    /**

     * Returns description of method parameters

     *

     * @return external_function_parameters

     * @since Moodle 2.9

     */

    public static function view_forum_discussion_parameters() {

        return new external_function_parameters(

            array(

                'discussionid' => new external_value(PARAM_INT, 'discussion id')

            )

        );

    }

    /**

     * Trigger the discussion viewed event.

     *

     * @param int $discussionid the discussion id

     * @return array of warnings and status result

     * @since Moodle 2.9

     * @throws moodle_exception

     */

    public static function view_forum_discussion($discussionid) {

        global $DB, $CFG, $USER;

        require_once($CFG->dirroot . "/mod/forum/lib.php");

        $params = self::validate_parameters(self::view_forum_discussion_parameters(),

                                            array(

                                                'discussionid' => $discussionid

                                            ));

        $warnings = array();

        $discussion = $DB->get_record('forum_discussions', array('id' => $params['discussionid']), '*', MUST_EXIST);

        $forum = $DB->get_record('forum', array('id' => $discussion->forum), '*', MUST_EXIST);

        list($course, $cm) = get_course_and_cm_from_instance($forum, 'forum');

        // 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);

        require_capability('mod/forum:viewdiscussion', $modcontext, null, true, 'noviewdiscussionspermission', 'forum');

        // Call the forum/lib API.

        forum_discussion_view($modcontext, $forum, $discussion);

        // Mark as read if required.

        if (!$CFG->forum_usermarksread && forum_tp_is_tracked($forum)) {

            forum_tp_mark_discussion_read($USER, $discussion->id);

        }

        $result = array();

        $result['status'] = true;

        $result['warnings'] = $warnings;

        return $result;

    }

    /**

     * Returns description of method result value

     *

     * @return \core_external\external_description

     * @since Moodle 2.9

     */

    public static function view_forum_discussion_returns() {

        return new external_single_structure(

            array(

                'status' => new external_value(PARAM_BOOL, 'status: true if success'),

                'warnings' => new external_warnings()

            )

        );

    }

    /**

     * Returns description of method parameters

     *

     * @return external_function_parameters

     * @since Moodle 3.0

     */

    public static function add_discussion_post_parameters() {

        return new external_function_parameters(

            array(

                'postid' => new external_value(PARAM_INT, 'the post id we are going to reply to

                                                (can be the initial discussion post'),

                'subject' => new external_value(PARAM_TEXT, 'new post subject'),

                'message' => new external_value(PARAM_RAW, 'new post message (html assumed if messageformat is not provided)'),

                'options' => new external_multiple_structure (

                    new external_single_structure(

                        array(

                            'name' => new external_value(PARAM_ALPHANUM,

                                        'The allowed keys (value format) are:

                                        discussionsubscribe (bool); subscribe to the discussion?, default to true

                                        private (bool); make this reply private to the author of the parent post, default to false.

                                        inlineattachmentsid              (int); the draft file area id for inline attachments

                                        attachmentsid       (int); the draft file area id for attachments

                                        topreferredformat (bool); convert the message & messageformat to FORMAT_HTML, defaults to false

                            '),

                            'value' => new external_value(PARAM_RAW, 'the value of the option,

                                                            this param is validated in the external function.'

                        )

                    )

                ), 'Options', VALUE_DEFAULT, array()),

                'messageformat' => new external_format_value('message', VALUE_DEFAULT)

            )

        );

    }

    /**

     * Create new posts into an existing discussion.

     *

     * @param int $postid the post id we are going to reply to

     * @param string $subject new post subject

     * @param string $message new post message (html assumed if messageformat is not provided)

     * @param array $options optional settings

     * @param string $messageformat The format of the message, defaults to FORMAT_HTML for BC

     * @return array of warnings and the new post id

     * @since Moodle 3.0

     * @throws moodle_exception

     */

    public static function add_discussion_post($postid, $subject, $message, $options = array(), $messageformat = FORMAT_HTML) {

        global $CFG, $USER;

        require_once($CFG->dirroot . "/mod/forum/lib.php");

        // Get all the factories that are required.

        $vaultfactory = mod_forum\local\container::get_vault_factory();

        $entityfactory = mod_forum\local\container::get_entity_factory();

        $datamapperfactory = mod_forum\local\container::get_legacy_data_mapper_factory();

        $managerfactory = mod_forum\local\container::get_manager_factory();

        $discussionvault = $vaultfactory->get_discussion_vault();

        $forumvault = $vaultfactory->get_forum_vault();

        $discussiondatamapper = $datamapperfactory->get_discussion_data_mapper();

        $forumdatamapper = $datamapperfactory->get_forum_data_mapper();

        $params = self::validate_parameters(self::add_discussion_post_parameters(),

            array(

                'postid' => $postid,

                'subject' => $subject,

                'message' => $message,

                'options' => $options,

                'messageformat' => $messageformat,

            )

        );

        $warnings = array();

        if (!$parent = forum_get_post_full($params['postid'])) {

            throw new moodle_exception('invalidparentpostid', 'forum');

        }

        if (!$discussion = $discussionvault->get_from_id($parent->discussion)) {

            throw new moodle_exception('notpartofdiscussion', 'forum');

        }

        // Request and permission validation.

        $forum = $forumvault->get_from_id($discussion->get_forum_id());

        $capabilitymanager = $managerfactory->get_capability_manager($forum);

        $course = $forum->get_course_record();

        $cm = $forum->get_course_module_record();

        $discussionrecord = $discussiondatamapper->to_legacy_object($discussion);

        $forumrecord = $forumdatamapper->to_legacy_object($forum);

        $context = context_module::instance($cm->id);

        self::validate_context($context);

        $coursecontext = \context_course::instance($forum->get_course_id());

        $discussionsubscribe = \mod_forum\subscriptions::get_user_default_subscription($forumrecord, $coursecontext,

            $cm, null);

        // Validate options.

        $options = array(

            'discussionsubscribe' => $discussionsubscribe,

            'private'             => false,

            'inlineattachmentsid' => 0,

            'attachmentsid' => null,

            'topreferredformat'   => false

        );

        foreach ($params['options'] as $option) {

            $name = trim($option['name']);

            switch ($name) {

                case 'discussionsubscribe':

                    $value = clean_param($option['value'], PARAM_BOOL);

                    break;

                case 'private':

                    $value = clean_param($option['value'], PARAM_BOOL);

                    break;

                case 'inlineattachmentsid':

                    $value = clean_param($option['value'], PARAM_INT);

                    break;

                case 'attachmentsid':

                    $value = clean_param($option['value'], PARAM_INT);

                    // Ensure that the user has permissions to create attachments.

                    if (!has_capability('mod/forum:createattachment', $context)) {

                        $value = 0;

                    }

                    break;

                case 'topreferredformat':

                    $value = clean_param($option['value'], PARAM_BOOL);

                    break;

                default:

                    throw new moodle_exception('errorinvalidparam', 'webservice', '', $name);

            }

            $options[$name] = $value;

        }

        if (!$capabilitymanager->can_post_in_discussion($USER, $discussion)) {

            throw new moodle_exception('nopostforum', 'forum');

        }

        $thresholdwarning = forum_check_throttling($forumrecord, $cm);

        forum_check_blocking_threshold($thresholdwarning);

        // If we want to force a conversion to the preferred format, let's do it now.

        if ($options['topreferredformat']) {

            // We always are going to honor the preferred format. We are creating a new post.

            $preferredformat = editors_get_preferred_format();

            // If the post is not HTML and the preferred format is HTML, convert to it.

            if ($params['messageformat'] != FORMAT_HTML and $preferredformat == FORMAT_HTML) {

                $params['message'] = format_text($params['message'], $params['messageformat'], ['filter' => false]);

            }

            $params['messageformat'] = $preferredformat;

        }

        // Create the post.

        $post = new stdClass();

        $post->discussion = $discussion->get_id();

        $post->parent = $parent->id;

        $post->subject = $params['subject'];

        $post->message = $params['message'];

        $post->messageformat = $params['messageformat'];

        $post->messagetrust = trusttext_trusted($context);

        $post->itemid = $options['inlineattachmentsid'];

        $post->attachments = $options['attachmentsid'];

        $post->isprivatereply = $options['private'];

        $post->deleted = 0;

        $fakemform = $post->attachments;

        if ($postid = forum_add_new_post($post, $fakemform)) {

            $post->id = $postid;

            // Trigger events and completion.

            $params = array(

                'context' => $context,

                'objectid' => $post->id,

                'other' => array(

                    'discussionid' => $discussion->get_id(),

                    'forumid' => $forum->get_id(),

                    'forumtype' => $forum->get_type(),

                )

            );

            $event = \mod_forum\event\post_created::create($params);

            $event->add_record_snapshot('forum_posts', $post);

            $event->add_record_snapshot('forum_discussions', $discussionrecord);

            $event->trigger();

            // Update completion state.

            $completion = new completion_info($course);

            if ($completion->is_enabled($cm) &&

                    ($forum->get_completion_replies() || $forum->get_completion_posts())) {

                $completion->update_state($cm, COMPLETION_COMPLETE);

            }

            if ($options['discussionsubscribe']) {

                $settings = new stdClass();

                $settings->discussionsubscribe = $options['discussionsubscribe'];

                forum_post_subscription($settings, $forumrecord, $discussionrecord);

            }

        } else {

            throw new moodle_exception('couldnotadd', 'forum');

        }

        $builderfactory = \mod_forum\local\container::get_builder_factory();

        $exportedpostsbuilder = $builderfactory->get_exported_posts_builder();

        $postentity = $entityfactory->get_post_from_stdClass($post);

        $exportedposts = $exportedpostsbuilder->build($USER, [$forum], [$discussion], [$postentity]);

        $exportedpost = $exportedposts[0];

        $message = [];

        $message[] = [

            'type' => 'success',

            'message' => get_string("postaddedsuccess", "forum")

        ];

        $message[] = [

            'type' => 'success',

            'message' => get_string("postaddedtimeleft", "forum", format_time($CFG->maxeditingtime))

        ];

        $result = array();

        $result['postid'] = $postid;

        $result['warnings'] = $warnings;

        $result['post'] = $exportedpost;

        $result['messages'] = $message;

        return $result;

    }

    /**

     * Returns description of method result value

     *

     * @return \core_external\external_description

     * @since Moodle 3.0

     */

    public static function add_discussion_post_returns() {

        return new external_single_structure(

            array(

                'postid' => new external_value(PARAM_INT, 'new post id'),

                'warnings' => new external_warnings(),

                'post' => post_exporter::get_read_structure(),

                'messages' => new external_multiple_structure(

                    new external_single_structure(

                        array(

                            'type' => new external_value(PARAM_TEXT, "The classification to be used in the client side", VALUE_REQUIRED),

                            'message' => new external_value(PARAM_TEXT,'untranslated english message to explain the warning', VALUE_REQUIRED)

                        ), 'Messages'), 'list of warnings', VALUE_OPTIONAL

                ),

                //'alertmessage' => new external_value(PARAM_RAW, 'Success message to be displayed to the user.'),

            )

        );

    }

    /**

     * Toggle the favouriting value for the discussion provided

     *

     * @param int $discussionid The discussion we need to favourite

     * @param bool $targetstate The state of the favourite value

     * @return array The exported discussion

     */

    public static function toggle_favourite_state($discussionid, $targetstate) {

        global $DB, $PAGE, $USER;

        $params = self::validate_parameters(self::toggle_favourite_state_parameters(), [

            'discussionid' => $discussionid,

            'targetstate' => $targetstate

        ]);

        $vaultfactory = mod_forum\local\container::get_vault_factory();

        // Get the discussion vault and the corresponding discussion entity.

        $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());

        $forumcontext = $forum->get_context();

        self::validate_context($forumcontext);

        $managerfactory = mod_forum\local\container::get_manager_factory();

        $capabilitymanager = $managerfactory->get_capability_manager($forum);

        // Does the user have the ability to favourite the discussion?

        if (!$capabilitymanager->can_favourite_discussion($USER)) {

            throw new moodle_exception('cannotfavourite', 'forum');

        }

        $usercontext = context_user::instance($USER->id);

        $ufservice = \core_favourites\service_factory::get_service_for_user_context($usercontext);

        $isfavourited = $ufservice->favourite_exists('mod_forum', 'discussions', $discussion->get_id(), $forumcontext);

        $favouritefunction = $targetstate ? 'create_favourite' : 'delete_favourite';

        if ($isfavourited != (bool) $params['targetstate']) {