Merge branch 'master_MDL-69848' of https://github.com/golenkovm/moodle
[moodle.git] / message / output / popup / externallib.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 defined('MOODLE_INTERNAL') || die();
19 /**
20  * External message popup API
21  *
22  * @package    message_popup
23  * @category   external
24  * @copyright  2016 Ryan Wyllie <ryan@moodle.com>
25  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
26  */
28 require_once("$CFG->libdir/externallib.php");
29 require_once($CFG->dirroot . "/message/lib.php");
31 /**
32  * Message external functions
33  *
34  * @package    message_popup
35  * @category   external
36  * @copyright  2016 Ryan Wyllie <ryan@moodle.com>
37  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38  */
39 class message_popup_external extends external_api {
41     /**
42      * Get popup notifications parameters description.
43      *
44      * @return external_function_parameters
45      * @since 3.2
46      */
47     public static function get_popup_notifications_parameters() {
48         return new external_function_parameters(
49             array(
50                 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for current user'),
51                 'newestfirst' => new external_value(
52                     PARAM_BOOL, 'true for ordering by newest first, false for oldest first',
53                     VALUE_DEFAULT, true),
54                 'limit' => new external_value(PARAM_INT, 'the number of results to return', VALUE_DEFAULT, 0),
55                 'offset' => new external_value(PARAM_INT, 'offset the result set by a given amount', VALUE_DEFAULT, 0)
56             )
57         );
58     }
60     /**
61      * Get notifications function.
62      *
63      * @since  3.2
64      * @throws invalid_parameter_exception
65      * @throws moodle_exception
66      * @param  int      $useridto           the user id who received the message
67      * @param  bool     $newestfirst        true for ordering by newest first, false for oldest first
68      * @param  int      $limit              the number of results to return
69      * @param  int      $offset             offset the result set by a given amount
70      * @return external_description
71      */
72     public static function get_popup_notifications($useridto, $newestfirst, $limit, $offset) {
73         global $USER, $PAGE;
75         $params = self::validate_parameters(
76             self::get_popup_notifications_parameters(),
77             array(
78                 'useridto' => $useridto,
79                 'newestfirst' => $newestfirst,
80                 'limit' => $limit,
81                 'offset' => $offset,
82             )
83         );
85         $context = context_system::instance();
86         self::validate_context($context);
88         $useridto = $params['useridto'];
89         $newestfirst = $params['newestfirst'];
90         $limit = $params['limit'];
91         $offset = $params['offset'];
92         $issuperuser = has_capability('moodle/site:readallmessages', $context);
93         $renderer = $PAGE->get_renderer('core_message');
95         if (empty($useridto)) {
96             $useridto = $USER->id;
97         }
99         // Check if the current user is the sender/receiver or just a privileged user.
100         if ($useridto != $USER->id and !$issuperuser) {
101             throw new moodle_exception('accessdenied', 'admin');
102         }
104         if (!empty($useridto)) {
105             if (!core_user::is_real_user($useridto)) {
106                 throw new moodle_exception('invaliduser');
107             }
108         }
110         $sort = $newestfirst ? 'DESC' : 'ASC';
111         $notifications = \message_popup\api::get_popup_notifications($useridto, $sort, $limit, $offset);
112         $notificationcontexts = [];
114         if ($notifications) {
115             foreach ($notifications as $notification) {
117                 $notificationoutput = new \message_popup\output\popup_notification($notification);
119                 $notificationcontext = $notificationoutput->export_for_template($renderer);
121                 // Keep this for BC.
122                 $notificationcontext->deleted = false;
123                 $notificationcontexts[] = $notificationcontext;
124             }
125         }
127         return array(
128             'notifications' => $notificationcontexts,
129             'unreadcount' => \message_popup\api::count_unread_popup_notifications($useridto),
130         );
131     }
133     /**
134      * Get notifications return description.
135      *
136      * @return external_single_structure
137      * @since 3.2
138      */
139     public static function get_popup_notifications_returns() {
140         return new external_single_structure(
141             array(
142                 'notifications' => new external_multiple_structure(
143                     new external_single_structure(
144                         array(
145                             'id' => new external_value(PARAM_INT, 'Notification id (this is not guaranteed to be unique
146                                 within this result set)'),
147                             'useridfrom' => new external_value(PARAM_INT, 'User from id'),
148                             'useridto' => new external_value(PARAM_INT, 'User to id'),
149                             'subject' => new external_value(PARAM_TEXT, 'The notification subject'),
150                             'shortenedsubject' => new external_value(PARAM_TEXT, 'The notification subject shortened
151                                 with ellipsis'),
152                             'text' => new external_value(PARAM_RAW, 'The message text formated'),
153                             'fullmessage' => new external_value(PARAM_RAW, 'The message'),
154                             'fullmessageformat' => new external_format_value('fullmessage'),
155                             'fullmessagehtml' => new external_value(PARAM_RAW, 'The message in html'),
156                             'smallmessage' => new external_value(PARAM_RAW, 'The shorten message'),
157                             'contexturl' => new external_value(PARAM_RAW, 'Context URL'),
158                             'contexturlname' => new external_value(PARAM_TEXT, 'Context URL link name'),
159                             'timecreated' => new external_value(PARAM_INT, 'Time created'),
160                             'timecreatedpretty' => new external_value(PARAM_TEXT, 'Time created in a pretty format'),
161                             'timeread' => new external_value(PARAM_INT, 'Time read'),
162                             'read' => new external_value(PARAM_BOOL, 'notification read status'),
163                             'deleted' => new external_value(PARAM_BOOL, 'notification deletion status'),
164                             'iconurl' => new external_value(PARAM_URL, 'URL for notification icon'),
165                             'component' => new external_value(PARAM_TEXT, 'The component that generated the notification',
166                                 VALUE_OPTIONAL),
167                             'eventtype' => new external_value(PARAM_TEXT, 'The type of notification', VALUE_OPTIONAL),
168                             'customdata' => new external_value(PARAM_RAW, 'Custom data to be passed to the message processor.
169                                 The data here is serialised using json_encode().', VALUE_OPTIONAL),
170                         ), 'message'
171                     )
172                 ),
173                 'unreadcount' => new external_value(PARAM_INT, 'the number of unread message for the given user'),
174             )
175         );
176     }
178     /**
179      * Get unread notification count parameters description.
180      *
181      * @return external_function_parameters
182      * @since 3.2
183      */
184     public static function get_unread_popup_notification_count_parameters() {
185         return new external_function_parameters(
186             array(
187                 'useridto' => new external_value(PARAM_INT, 'the user id who received the message, 0 for any user', VALUE_REQUIRED),
188             )
189         );
190     }
192     /**
193      * Get unread notification count function.
194      *
195      * @since  3.2
196      * @throws invalid_parameter_exception
197      * @throws moodle_exception
198      * @param  int      $useridto       the user id who received the message
199      * @return external_description
200      */
201     public static function get_unread_popup_notification_count($useridto) {
202         global $USER;
204         $params = self::validate_parameters(
205             self::get_unread_popup_notification_count_parameters(),
206             array('useridto' => $useridto)
207         );
209         $context = context_system::instance();
210         self::validate_context($context);
212         $useridto = $params['useridto'];
214         if (!empty($useridto)) {
215             if (core_user::is_real_user($useridto)) {
216                 $userto = core_user::get_user($useridto, '*', MUST_EXIST);
217             } else {
218                 throw new moodle_exception('invaliduser');
219             }
220         }
222         // Check if the current user is the sender/receiver or just a privileged user.
223         if ($useridto != $USER->id and !has_capability('moodle/site:readallmessages', $context)) {
224             throw new moodle_exception('accessdenied', 'admin');
225         }
227         return \message_popup\api::count_unread_popup_notifications($useridto);
228     }
230     /**
231      * Get unread popup notification count return description.
232      *
233      * @return external_single_structure
234      * @since 3.2
235      */
236     public static function get_unread_popup_notification_count_returns() {
237         return new external_value(PARAM_INT, 'The count of unread popup notifications');
238     }