2 // This file is part of Moodle - http://moodle.org/
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 // GNU General Public License for more details.
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
18 * External comment API
20 * @package core_comment
22 * @copyright Costantino Cito <ccito@cvaconsulting.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27 defined('MOODLE_INTERNAL') ||
die();
29 require_once("$CFG->libdir/externallib.php");
30 require_once("$CFG->dirroot/comment/lib.php");
33 * External comment API functions
35 * @package core_comment
37 * @copyright Costantino Cito <ccito@cvaconsulting.com>
38 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
41 class core_comment_external
extends external_api
{
43 * Returns description of method parameters
45 * @return external_function_parameters
48 public static function get_comments_parameters() {
50 return new external_function_parameters(
52 'contextlevel' => new external_value(PARAM_ALPHA
, 'contextlevel system, course, user...'),
53 'instanceid' => new external_value(PARAM_INT
, 'the Instance id of item associated with the context level'),
54 'component' => new external_value(PARAM_COMPONENT
, 'component'),
55 'itemid' => new external_value(PARAM_INT
, 'associated id'),
56 'area' => new external_value(PARAM_AREA
, 'string comment area', VALUE_DEFAULT
, ''),
57 'page' => new external_value(PARAM_INT
, 'page number (0 based)', VALUE_DEFAULT
, 0),
63 * Return a list of comments
65 * @param string $contextlevel ('system, course, user', etc..)
66 * @param int $instanceid
67 * @param string $component the name of the component
68 * @param int $itemid the item id
69 * @param string $area comment area
70 * @param int $page page number
71 * @return array of comments and warnings
74 public static function get_comments($contextlevel, $instanceid, $component, $itemid, $area = '', $page = 0) {
78 'contextlevel' => $contextlevel,
79 'instanceid' => $instanceid,
80 'component' => $component,
85 $params = self
::validate_parameters(self
::get_comments_parameters(), $arrayparams);
87 $context = self
::get_context_from_params($params);
88 self
::validate_context($context);
90 require_capability('moodle/comment:view', $context);
93 $args->context
= $context;
94 $args->area
= $params['area'];
95 $args->itemid
= $params['itemid'];
96 $args->component
= $params['component'];
98 $commentobject = new comment($args);
99 $comments = $commentobject->get_comments($params['page']);
101 // False means no permissions to see comments.
102 if ($comments === false) {
103 throw new moodle_exception('nopermissions', 'error', '', 'view comments');
106 foreach ($comments as $key => $comment) {
108 list($comments[$key]->content
, $comments[$key]->format
) = external_format_text($comment->content
,
111 $params['component'],
117 'comments' => $comments,
118 'warnings' => $warnings
124 * Returns description of method result value
126 * @return external_description
129 public static function get_comments_returns() {
130 return new external_single_structure(
132 'comments' => new external_multiple_structure(
133 new external_single_structure(
135 'id' => new external_value(PARAM_INT
, 'Comment ID'),
136 'content' => new external_value(PARAM_RAW
, 'The content text formated'),
137 'format' => new external_format_value('content'),
138 'timecreated' => new external_value(PARAM_INT
, 'Time created (timestamp)'),
139 'strftimeformat' => new external_value(PARAM_NOTAGS
, 'Time format'),
140 'profileurl' => new external_value(PARAM_URL
, 'URL profile'),
141 'fullname' => new external_value(PARAM_NOTAGS
, 'fullname'),
142 'time' => new external_value(PARAM_NOTAGS
, 'Time in human format'),
143 'avatar' => new external_value(PARAM_RAW
, 'HTML user picture'),
144 'userid' => new external_value(PARAM_INT
, 'User ID'),
145 'delete' => new external_value(PARAM_BOOL
, 'Permission to delete=true/false', VALUE_OPTIONAL
)
147 ), 'List of comments'
149 'warnings' => new external_warnings()