MDL-49203 webservices: New WS core_comment_get_comments
[moodle.git] / comment / classes / external.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
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.
8 //
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.
13 //
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/>.
17 /**
18  * External comment API
19  *
20  * @package    core_comment
21  * @category   external
22  * @copyright  Costantino Cito <ccito@cvaconsulting.com>
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  * @since      Moodle 2.9
25  */
27 require_once("$CFG->libdir/externallib.php");
28 require_once("$CFG->dirroot/comment/lib.php");
30 /**
31  * External comment API functions
32  *
33  * @package    core_comment
34  * @category   external
35  * @copyright  Costantino Cito <ccito@cvaconsulting.com>
36  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
37  * @since      Moodle 2.9
38  */
39 class core_comment_external extends external_api {
40     /**
41      * Returns description of method parameters
42      *
43      * @return external_function_parameters
44      * @since Moodle 2.9
45      */
46     public static function get_comments_parameters() {
48         return new external_function_parameters(
49             array(
50                 'contextlevel' => new external_value(PARAM_ALPHA, 'contextlevel'),
51                 'instanceid'   => new external_value(PARAM_INT, 'The Instance id of item associated with the context level'),
52                 'component'    => new external_value(PARAM_COMPONENT, 'component'),
53                 'itemid'       => new external_value(PARAM_INT, 'associated id'),
54                 'area'         => new external_value(PARAM_TEXT, 'string comment area', VALUE_DEFAULT, ''),
55                 'page'         => new external_value(PARAM_INT, 'page number', VALUE_DEFAULT, 0),
56             )
57         );
58     }
60     /**
61      * Get comments
62      *
63      * @param string $contextlevel ('context_course', etc..)
64      * @param int $instanceid (eg. the 'id' in the 'book' table)
65      * @param string $component the name of the component
66      * @param int $itemid the item id
67      * @param string|null $area
68      * @param int $page page number
69      * @return array of comments and warnings
70      * @since Moodle 2.9
71      */
72     public static function get_comments($contextlevel, $instanceid, $component, $itemid, $area='', $page=0) {
74         $warnings = array();
75         $arrayparams = array(
76             'contextlevel' => $contextlevel,
77             'instanceid'   => $instanceid,
78             'component'    => $component,
79             'itemid'       => $itemid,
80             'area'         => $area,
81             'page'         => $page
82         );
83         $params = self::validate_parameters(self::get_comments_parameters(), $arrayparams);
85         $context = self::get_context_from_params($params);
86         self::validate_context($context);
88         require_capability('moodle/comment:view', $context);
90         $args = new stdClass;
91         $args->context   = $context;
92         $args->area      = $params['area'];
93         $args->itemid    = $params['itemid'];
94         $args->component = $params['component'];
96         $commentobject = new comment($args);
97         $comments = $commentobject->get_comments($arrayparams['page']);
99         if ($comments === false) {
100             throw new moodle_exception('nopermissions', 'error', '', 'view comments');
101         }
103         foreach ($comments as &$comment) {
105                 list($comment->content, $comment->format) = external_format_text($comment->content,
106                                                                                  $comment->format,
107                                                                                  $context->id,
108                                                                                  $params['component'],
109                                                                                  '',
110                                                                                  0);
111                 $comment = (array)$comment;
112         }
114         $results = array(
115             'comments' => $comments,
116             'warnings' => $warnings
117         );
118         return $results;
119     }
121     /**
122      * Returns description of method result value
123      *
124      * @return external_description
125      * @since Moodle 2.9
126      */
127     public static function get_comments_returns() {
128         return new external_single_structure(
129             array(
130                 'comments' => new external_multiple_structure(
131                     new external_single_structure(
132                         array(
133                             'id'             => new external_value(PARAM_INT,  'Comment ID'),
134                             'content'        => new external_value(PARAM_RAW,  'The content text formated'),
135                             'format'         => new external_format_value('content'),
136                             'timecreated'    => new external_value(PARAM_INT,  'Time created (timestamp)'),
137                             'strftimeformat' => new external_value(PARAM_RAW, 'Time format'),
138                             'profileurl'     => new external_value(PARAM_URL,  'URL profile'),
139                             'fullname'       => new external_value(PARAM_TEXT, 'fullname'),
140                             'time'           => new external_value(PARAM_RAW, 'Time in human format'),
141                             'avatar'         => new external_value(PARAM_RAW,  'HTML user picture'),
142                             'userid'         => new external_value(PARAM_INT,  'User ID'),
143                             'delete'         => new external_value(PARAM_BOOL, 'Permission to delete=true/false', VALUE_OPTIONAL)
144                         ), 'comment'
145                     ), 'List of comments'
146                 ),
147                 'warnings' => new external_warnings()
148             )
149         );
150     }