moodle/comment/classes/external.php

<?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 comment API
 *
 * @package    core_comment
 * @category   external
 * @copyright  Costantino Cito <ccito@cvaconsulting.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 * @since      Moodle 2.9
 */

use core_external\external_api;
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;

defined('MOODLE_INTERNAL') || die();

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

/**
 * External comment API functions
 *
 * @package    core_comment
 * @category   external
 * @copyright  Costantino Cito <ccito@cvaconsulting.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 * @since      Moodle 2.9
 */
class core_comment_external extends external_api {
    /**
     * Returns description of method parameters
     *
     * @return external_function_parameters
     * @since Moodle 2.9
     */
    public static function get_comments_parameters() {

        return new external_function_parameters(
            array(
                'contextlevel'  => new external_value(PARAM_ALPHA, 'contextlevel system, course, user...'),
                'instanceid'    => new external_value(PARAM_INT, 'the Instance id of item associated with the context level'),
                'component'     => new external_value(PARAM_COMPONENT, 'component'),
                'itemid'        => new external_value(PARAM_INT, 'associated id'),
                'area'          => new external_value(PARAM_AREA, 'string comment area', VALUE_DEFAULT, ''),
                'page'          => new external_value(PARAM_INT, 'page number (0 based)', VALUE_DEFAULT, 0),
                'sortdirection' => new external_value(PARAM_ALPHA, 'Sort direction: ASC or DESC', VALUE_DEFAULT, 'DESC'),
            )
        );
    }

    /**
     * Return a list of comments
     *
     * @param string $contextlevel ('system, course, user', etc..)
     * @param int $instanceid
     * @param string $component the name of the component
     * @param int $itemid the item id
     * @param string $area comment area
     * @param int $page page number
     * @param string $sortdirection sort direction
     * @return array of comments and warnings
     * @since Moodle 2.9
     */
    public static function get_comments($contextlevel, $instanceid, $component, $itemid, $area = '', $page = 0,
            $sortdirection = 'DESC') {
        global $CFG;

        $warnings = array();
        $arrayparams = array(
            'contextlevel'  => $contextlevel,
            'instanceid'    => $instanceid,
            'component'     => $component,
            'itemid'        => $itemid,
            'area'          => $area,
            'page'          => $page,
            'sortdirection' => $sortdirection,
        );
        $params = self::validate_parameters(self::get_comments_parameters(), $arrayparams);

        $sortdirection = strtoupper($params['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));
        }

        $context = self::get_context_from_params($params);
        self::validate_context($context);

        require_capability('moodle/comment:view', $context);

        $args = new stdClass;
        $args->context   = $context;
        $args->area      = $params['area'];
        $args->itemid    = $params['itemid'];
        $args->component = $params['component'];

        $commentobject = new comment($args);
        $comments = $commentobject->get_comments($params['page'], $sortdirection);

        // False means no permissions to see comments.
        if ($comments === false) {
            throw new moodle_exception('nopermissions', 'error', '', 'view comments');
        }
        $options = array('blanktarget' => true);

        foreach ($comments as $key => $comment) {

                list($comments[$key]->content, $comments[$key]->format) = \core_external\util::format_text($comment->content,
                                                                                                 $comment->format,
                                                                                                 $context->id,
                                                                                                 $params['component'],
                                                                                                 '',
                                                                                                 0,
                                                                                                 $options);
        }

        $results = array(
            'comments' => $comments,
            'count' => $commentobject->count(),
            'perpage' => (!empty($CFG->commentsperpage)) ? $CFG->commentsperpage : 15,
            'canpost'  => $commentobject->can_post(),
            'warnings' => $warnings
        );
        return $results;
    }

    /**
     * Returns description of method result value
     *
     * @return \core_external\external_description
     * @since Moodle 2.9
     */
    public static function get_comments_returns() {
        return new external_single_structure(
            array(
                'comments' => new external_multiple_structure(
                    self::get_comment_structure(), 'List of comments'
                ),
                'count' => new external_value(PARAM_INT,  'Total number of comments.', VALUE_OPTIONAL),
                'perpage' => new external_value(PARAM_INT,  'Number of comments per page.', VALUE_OPTIONAL),
                'canpost' => new external_value(PARAM_BOOL, 'Whether the user can post in this comment area.', VALUE_OPTIONAL),
                'warnings' => new external_warnings()
            )
        );
    }

    /**
     * Helper to get the structure of a single comment.
     *
     * @return external_single_structure the comment structure.
     */
    protected static function get_comment_structure() {
        return new external_single_structure(
            array(
                'id'             => new external_value(PARAM_INT,  'Comment ID'),
                'content'        => new external_value(PARAM_RAW,  'The content text formatted'),
                'format'         => new external_format_value('content'),
                'timecreated'    => new external_value(PARAM_INT,  'Time created (timestamp)'),
                'strftimeformat' => new external_value(PARAM_NOTAGS, 'Time format'),
                'profileurl'     => new external_value(PARAM_URL,  'URL profile'),
                'fullname'       => new external_value(PARAM_NOTAGS, 'fullname'),
                'time'           => new external_value(PARAM_NOTAGS, 'Time in human format'),
                'avatar'         => new external_value(PARAM_RAW,  'HTML user picture'),
                'userid'         => new external_value(PARAM_INT,  'User ID'),
                'delete'         => new external_value(PARAM_BOOL, 'Permission to delete=true/false', VALUE_OPTIONAL)
            ), 'comment'
        );
    }

    /**
     * Returns description of method parameters for the add_comments method.
     *
     * @return external_function_parameters
     * @since Moodle 3.8
     */
    public static function add_comments_parameters() {
        return new external_function_parameters(
            [
                'comments' => new external_multiple_structure(
                    new external_single_structure(
                        [
                            'contextlevel' => new external_value(PARAM_ALPHA, 'contextlevel system, course, user...'),
                            'instanceid'   => new external_value(PARAM_INT, 'the id of item associated with the contextlevel'),
                            'component'    => new external_value(PARAM_COMPONENT, 'component'),
                            'content'      => new external_value(PARAM_RAW, 'component'),
                            'itemid'       => new external_value(PARAM_INT, 'associated id'),
                            'area'         => new external_value(PARAM_AREA, 'string comment area', VALUE_DEFAULT, ''),
                        ]
                    )
                )
            ]
        );
    }

    /**
     * Add a comment or comments.
     *
     * @param array $comments the array of comments to create.
     * @return array the array containing those comments created.
     * @throws comment_exception
     * @since Moodle 3.8
     */
    public static function add_comments($comments) {
        global $CFG, $SITE;

        if (empty($CFG->usecomments)) {
            throw new comment_exception('commentsnotenabled', 'moodle');
        }

        $params = self::validate_parameters(self::add_comments_parameters(), ['comments' => $comments]);

        // Validate every intended comment before creating anything, storing the validated comment for use below.
        foreach ($params['comments'] as $index => $comment) {
            $context = self::get_context_from_params($comment);
            self::validate_context($context);

            list($context, $course, $cm) = get_context_info_array($context->id);
            if ($context->id == SYSCONTEXTID) {
                $course = $SITE;
            }

            // Initialising comment object.
            $args = new stdClass();
            $args->context   = $context;
            $args->course    = $course;
            $args->cm        = $cm;
            $args->component = $comment['component'];
            $args->itemid    = $comment['itemid'];
            $args->area      = $comment['area'];

            $manager = new comment($args);
            if (!$manager->can_post()) {
                throw new comment_exception('nopermissiontocomment');
            }

            $params['comments'][$index]['preparedcomment'] = $manager;
        }

        // Create the comments.
        $results = [];
        foreach ($params['comments'] as $comment) {
            $manager = $comment['preparedcomment'];
            $newcomment = $manager->add($comment['content']);
            $newcomment->delete = true; // USER created the comment, so they can delete it.
            $results[] = $newcomment;
        }

        return $results;
    }

    /**
     * Returns description of method result value for the add_comments method.
     *
     * @return \core_external\external_description
     * @since Moodle 3.8
     */
    public static function add_comments_returns() {
        return new external_multiple_structure(
            self::get_comment_structure()
        );
    }

    /**
     * Returns description of method parameters for the delete_comments() method.
     *
     * @return external_function_parameters
     * @since Moodle 3.8
     */
    public static function delete_comments_parameters() {
        return new external_function_parameters(
            [
                'comments' => new external_multiple_structure(
                    new external_value(PARAM_INT, 'id of the comment', VALUE_DEFAULT, 0)
                )
            ]
        );
    }

    /**
     * Deletes a comment or comments.
     *
     * @param array $comments array of comment ids to be deleted
     * @return array
     * @throws comment_exception
     * @since Moodle 3.8
     */
    public static function delete_comments(array $comments) {
        global $CFG, $DB, $USER, $SITE;

        if (empty($CFG->usecomments)) {
            throw new comment_exception('commentsnotenabled', 'moodle');
        }

        $params = self::validate_parameters(self::delete_comments_parameters(), ['comments' => $comments]);
        $commentids = $params['comments'];

        list($insql, $inparams) = $DB->get_in_or_equal($commentids);
        $commentrecords = $DB->get_records_select('comments', "id {$insql}", $inparams);

        // If one or more of the records could not be found, report this and fail early.
        if (count($commentrecords) != count($comments)) {
            $invalidcomments = array_diff($commentids, array_column($commentrecords, 'id'));
            $invalidcommentsstr = implode(',', $invalidcomments);
            throw new comment_exception("One or more comments could not be found by id: $invalidcommentsstr");
        }

        // Make sure we can delete every one of the comments before actually doing so.
        $comments = []; // Holds the comment objects, for later deletion.
        foreach ($commentrecords as $commentrecord) {
            // Validate the context.
            list($context, $course, $cm) = get_context_info_array($commentrecord->contextid);
            if ($context->id == SYSCONTEXTID) {
                $course = $SITE;
            }
            self::validate_context($context);

            // Make sure the user is allowed to delete the comment.
            $args = new stdClass;
            $args->context   = $context;
            $args->course    = $course;
            $args->cm        = $cm;
            $args->component = $commentrecord->component;
            $args->itemid    = $commentrecord->itemid;
            $args->area      = $commentrecord->commentarea;
            $manager = new comment($args);

            if (!$manager->can_delete($commentrecord)) {
                throw new comment_exception('nopermissiontodelentry');
            }

            // User is allowed to delete it, so store the comment object, for use below in final deletion.
            $comments[$commentrecord->id] = $manager;
        }

        // All comments can be deleted by the user. Make it so.
        foreach ($comments as $commentid => $comment) {
            $comment->delete($commentid);
        }

        return [];
    }

    /**
     * Returns description of method result value for the delete_comments() method.
     *
     * @return \core_external\external_description
     * @since Moodle 3.8
     */
    public static function delete_comments_returns() {
        return new external_warnings();
    }
}