MDL-69848 upgrade: Delete notifications in chunks
[moodle.git] / message / output / popup / externallib.php
CommitLineData
7d69958e
RW
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/>.
16
17defined('MOODLE_INTERNAL') || die();
18
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 */
27
28require_once("$CFG->libdir/externallib.php");
29require_once($CFG->dirroot . "/message/lib.php");
30
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 */
39class message_popup_external extends external_api {
40
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 }
59
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;
74
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 );
84
85 $context = context_system::instance();
86 self::validate_context($context);
87
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');
94
95 if (empty($useridto)) {
96 $useridto = $USER->id;
97 }
98
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 }
103
104 if (!empty($useridto)) {
105 if (!core_user::is_real_user($useridto)) {
106 throw new moodle_exception('invaliduser');
107 }
108 }
109
110 $sort = $newestfirst ? 'DESC' : 'ASC';
111 $notifications = \message_popup\api::get_popup_notifications($useridto, $sort, $limit, $offset);
112 $notificationcontexts = [];
113
114 if ($notifications) {
115 foreach ($notifications as $notification) {
116
117 $notificationoutput = new \message_popup\output\popup_notification($notification);
118
119 $notificationcontext = $notificationoutput->export_for_template($renderer);
883ce421
MN
120
121 // Keep this for BC.
122 $notificationcontext->deleted = false;
7d69958e
RW
123 $notificationcontexts[] = $notificationcontext;
124 }
125 }
126
127 return array(
128 'notifications' => $notificationcontexts,
129 'unreadcount' => \message_popup\api::count_unread_popup_notifications($useridto),
130 );
131 }
132
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),
333d11c9
JL
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),
7d69958e
RW
170 ), 'message'
171 )
172 ),
173 'unreadcount' => new external_value(PARAM_INT, 'the number of unread message for the given user'),
174 )
175 );
176 }
177
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 }
191
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;
203
204 $params = self::validate_parameters(
205 self::get_unread_popup_notification_count_parameters(),
206 array('useridto' => $useridto)
207 );
208
209 $context = context_system::instance();
210 self::validate_context($context);
211
212 $useridto = $params['useridto'];
213
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 }
221
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 }
226
227 return \message_popup\api::count_unread_popup_notifications($useridto);
228 }
229
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 }
239}