1 | <?php |
||
2 | /* |
||
3 | * File: ImapProtocol.php |
||
4 | * Category: Protocol |
||
5 | * Author: M.Goldenbaum |
||
6 | * Created: 16.09.20 18:27 |
||
7 | * Updated: - |
||
8 | * |
||
9 | * Description: |
||
10 | * - |
||
11 | */ |
||
12 | |||
13 | namespace Webklex\PHPIMAP\Connection\Protocols; |
||
14 | |||
15 | use ErrorException; |
||
16 | use Webklex\PHPIMAP\Client; |
||
17 | use Webklex\PHPIMAP\Exceptions\AuthFailedException; |
||
18 | use Webklex\PHPIMAP\Exceptions\ConnectionFailedException; |
||
19 | use Webklex\PHPIMAP\Exceptions\ImapBadRequestException; |
||
20 | use Webklex\PHPIMAP\Exceptions\ImapServerErrorException; |
||
21 | use Webklex\PHPIMAP\Exceptions\InvalidMessageDateException; |
||
22 | use Webklex\PHPIMAP\Exceptions\MessageNotFoundException; |
||
23 | use Webklex\PHPIMAP\Exceptions\RuntimeException; |
||
24 | use Webklex\PHPIMAP\IMAP; |
||
25 | |||
26 | /** |
||
27 | * Interface ProtocolInterface |
||
28 | * |
||
29 | * @package Webklex\PHPIMAP\Connection\Protocols |
||
30 | */ |
||
31 | interface ProtocolInterface { |
||
32 | |||
33 | /** |
||
34 | * Public destructor |
||
35 | * |
||
36 | * @throws ImapBadRequestException |
||
37 | * @throws ImapServerErrorException |
||
38 | * @throws RuntimeException |
||
39 | */ |
||
40 | public function __destruct(); |
||
41 | |||
42 | /** |
||
43 | * Open a new connection / session |
||
44 | * @param string $host hostname or IP address of IMAP server |
||
45 | * @param int|null $port of service server |
||
46 | * |
||
47 | * @throws ErrorException |
||
48 | * @throws ConnectionFailedException |
||
49 | * @throws RuntimeException |
||
50 | */ |
||
51 | public function connect(string $host, $port = null); |
||
52 | |||
53 | /** |
||
54 | * Login to a new session. |
||
55 | * |
||
56 | * @param string $user username |
||
57 | * @param string $password password |
||
58 | * |
||
59 | * @return array success |
||
60 | * |
||
61 | * @throws AuthFailedException |
||
62 | * @throws ImapBadRequestException |
||
63 | * @throws ImapServerErrorException |
||
64 | */ |
||
65 | public function login(string $user, string $password): array; |
||
66 | |||
67 | /** |
||
68 | * Authenticate your current session. |
||
69 | * @param string $user username |
||
70 | * @param string $token access token |
||
71 | * |
||
72 | * @return bool|mixed |
||
73 | * @throws AuthFailedException |
||
74 | */ |
||
75 | public function authenticate(string $user, string $token); |
||
76 | |||
77 | /** |
||
78 | * Logout of the current server session |
||
79 | * |
||
80 | * @return array success |
||
81 | * |
||
82 | * @throws ImapBadRequestException |
||
83 | * @throws ImapServerErrorException |
||
84 | * @throws RuntimeException |
||
85 | */ |
||
86 | public function logout(): array; |
||
87 | |||
88 | /** |
||
89 | * Check if the current session is connected |
||
90 | * |
||
91 | * @return bool |
||
92 | */ |
||
93 | public function connected(): bool; |
||
94 | |||
95 | /** |
||
96 | * Get an array of available capabilities |
||
97 | * |
||
98 | * @return array list of capabilities |
||
99 | * @throws RuntimeException |
||
100 | */ |
||
101 | public function getCapabilities(): array; |
||
102 | |||
103 | /** |
||
104 | * Change the current folder |
||
105 | * |
||
106 | * @param string $folder change to this folder |
||
107 | * @return bool|array see examineOrSelect() |
||
108 | * @throws RuntimeException |
||
109 | */ |
||
110 | public function selectFolder(string $folder = 'INBOX'); |
||
111 | |||
112 | /** |
||
113 | * Examine a given folder |
||
114 | * |
||
115 | * @param string $folder |
||
116 | * @return bool|array |
||
117 | * @throws RuntimeException |
||
118 | */ |
||
119 | public function examineFolder(string $folder = 'INBOX'); |
||
120 | |||
121 | /** |
||
122 | * Fetch message headers |
||
123 | * @param array|int $uids |
||
124 | * @param string $rfc |
||
125 | * @param int|string $uid set to IMAP::ST_UID or any string representing the UID - set to IMAP::ST_MSGN to use |
||
126 | * message numbers instead. |
||
127 | * |
||
128 | * @return array |
||
129 | * @throws RuntimeException |
||
130 | */ |
||
131 | public function content($uids, string $rfc = "RFC822", $uid = IMAP::ST_UID): array; |
||
132 | |||
133 | /** |
||
134 | * Fetch message headers |
||
135 | * @param array|int $uids |
||
136 | * @param string $rfc |
||
137 | * @param int|string $uid set to IMAP::ST_UID or any string representing the UID - set to IMAP::ST_MSGN to use |
||
138 | * message numbers instead. |
||
139 | * |
||
140 | * @return array |
||
141 | * @throws RuntimeException |
||
142 | */ |
||
143 | public function headers($uids, string $rfc = "RFC822", $uid = IMAP::ST_UID): array; |
||
144 | |||
145 | /** |
||
146 | * Fetch message flags |
||
147 | * @param array|int $uids |
||
148 | * @param int|string $uid set to IMAP::ST_UID or any string representing the UID - set to IMAP::ST_MSGN to use |
||
149 | * message numbers instead. |
||
150 | * |
||
151 | * @return array |
||
152 | * @throws RuntimeException |
||
153 | */ |
||
154 | public function flags($uids, $uid = IMAP::ST_UID): array; |
||
155 | |||
156 | /** |
||
157 | * Get uid for a given id |
||
158 | * @param int|null $id message number |
||
159 | * |
||
160 | * @return array|string message number for given message or all messages as array |
||
161 | * @throws MessageNotFoundException |
||
162 | */ |
||
163 | public function getUid($id = null); |
||
164 | |||
165 | /** |
||
166 | * Get a message number for a uid |
||
167 | * @param string $id uid |
||
168 | * |
||
169 | * @return int message number |
||
170 | * @throws MessageNotFoundException |
||
171 | */ |
||
172 | public function getMessageNumber(string $id): int; |
||
173 | |||
174 | /** |
||
175 | * Get a list of available folders |
||
176 | * @param string $reference mailbox reference for list |
||
177 | * @param string $folder mailbox / folder name match with wildcards |
||
178 | * |
||
179 | * @return array mailboxes that matched $folder as array(globalName => array('delim' => .., 'flags' => ..)) |
||
180 | * @throws RuntimeException |
||
181 | */ |
||
182 | public function folders(string $reference = '', string $folder = '*'): array; |
||
183 | |||
184 | /** |
||
185 | * Set message flags |
||
186 | * @param array $flags flags to set, add or remove |
||
187 | * @param int $from message for items or start message if $to !== null |
||
188 | * @param int|null $to if null only one message ($from) is fetched, else it's the |
||
189 | * last message, INF means last message available |
||
190 | * @param string|null $mode '+' to add flags, '-' to remove flags, everything else sets the flags as given |
||
191 | * @param bool $silent if false the return values are the new flags for the wanted messages |
||
192 | * @param int|string $uid set to IMAP::ST_UID or any string representing the UID - set to IMAP::ST_MSGN to use |
||
193 | * message numbers instead. |
||
194 | * @param null|string $item command used to store a flag |
||
195 | * |
||
196 | * @return bool|array new flags if $silent is false, else true or false depending on success |
||
197 | * @throws RuntimeException |
||
198 | */ |
||
199 | public function store(array $flags, int $from, $to = null, $mode = null, bool $silent = true, $uid = IMAP::ST_UID, $item = null); |
||
200 | |||
201 | /** |
||
202 | * Append a new message to given folder |
||
203 | * @param string $folder name of target folder |
||
204 | * @param string $message full message content |
||
205 | * @param array|null $flags flags for new message |
||
206 | * @param string|null $date date for new message |
||
207 | * |
||
208 | * @return array success |
||
209 | * @throws RuntimeException |
||
210 | */ |
||
211 | public function appendMessage(string $folder, string $message, $flags = null, $date = null): array; |
||
212 | |||
213 | /** |
||
214 | * Copy message set from current folder to other folder |
||
215 | * |
||
216 | * @param string $folder destination folder |
||
217 | * @param $from |
||
218 | * @param int|null $to if null only one message ($from) is fetched, else it's the |
||
219 | * last message, INF means last message available |
||
220 | * @param int|string $uid set to IMAP::ST_UID or any string representing the UID - set to IMAP::ST_MSGN to use |
||
221 | * message numbers instead. |
||
222 | * |
||
223 | * @return array success |
||
224 | * @throws RuntimeException |
||
225 | */ |
||
226 | public function copyMessage(string $folder, $from, $to = null, $uid = IMAP::ST_UID): array; |
||
227 | |||
228 | /** |
||
229 | * Copy multiple messages to the target folder |
||
230 | * @param array<string> $messages List of message identifiers |
||
231 | * @param string $folder Destination folder |
||
232 | * @param int|string $uid set to IMAP::ST_UID or any string representing the UID - set to IMAP::ST_MSGN to use |
||
233 | * message numbers instead. |
||
234 | * |
||
235 | * @return array Tokens if operation successful, false if an error occurred |
||
236 | * @throws RuntimeException |
||
237 | */ |
||
238 | public function copyManyMessages(array $messages, string $folder, $uid = IMAP::ST_UID): array; |
||
239 | |||
240 | /** |
||
241 | * Move a message set from current folder to another folder |
||
242 | * @param string $folder destination folder |
||
243 | * @param $from |
||
244 | * @param int|null $to if null only one message ($from) is fetched, else it's the |
||
245 | * last message, INF means last message available |
||
246 | * @param int|string $uid set to IMAP::ST_UID or any string representing the UID - set to IMAP::ST_MSGN to use |
||
247 | * message numbers instead. |
||
248 | * |
||
249 | * @return array success |
||
250 | */ |
||
251 | public function moveMessage(string $folder, $from, $to = null, $uid = IMAP::ST_UID): array; |
||
252 | |||
253 | /** |
||
254 | * Move multiple messages to the target folder |
||
255 | * |
||
256 | * @param array<string> $messages List of message identifiers |
||
257 | * @param string $folder Destination folder |
||
258 | * @param int|string $uid set to IMAP::ST_UID or any string representing the UID - set to IMAP::ST_MSGN to use |
||
259 | * message numbers instead. |
||
260 | * |
||
261 | * @return array Tokens if operation successful, false if an error occurred |
||
262 | * @throws RuntimeException |
||
263 | */ |
||
264 | public function moveManyMessages(array $messages, string $folder, $uid = IMAP::ST_UID): array; |
||
265 | |||
266 | /** |
||
267 | * Exchange identification information |
||
268 | * Ref.: https://datatracker.ietf.org/doc/html/rfc2971 |
||
269 | * |
||
270 | * @param null $ids |
||
0 ignored issues
–
show
Documentation
Bug
introduced
by
Loading history...
|
|||
271 | * @return array|bool|void|null |
||
272 | * |
||
273 | * @throws RuntimeException |
||
274 | */ |
||
275 | public function ID($ids = null); |
||
276 | |||
277 | /** |
||
278 | * Create a new folder |
||
279 | * |
||
280 | * @param string $folder folder name |
||
281 | * @return array success |
||
282 | * @throws RuntimeException |
||
283 | */ |
||
284 | public function createFolder(string $folder): array; |
||
285 | |||
286 | /** |
||
287 | * Rename an existing folder |
||
288 | * |
||
289 | * @param string $old old name |
||
290 | * @param string $new new name |
||
291 | * @return array success |
||
292 | * @throws RuntimeException |
||
293 | */ |
||
294 | public function renameFolder(string $old, string $new): array; |
||
295 | |||
296 | /** |
||
297 | * Delete a folder |
||
298 | * |
||
299 | * @param string $folder folder name |
||
300 | * @return array success |
||
301 | * |
||
302 | * @throws ImapBadRequestException |
||
303 | * @throws ImapServerErrorException |
||
304 | * @throws RuntimeException |
||
305 | */ |
||
306 | public function deleteFolder(string $folder): array; |
||
307 | |||
308 | /** |
||
309 | * Subscribe to a folder |
||
310 | * |
||
311 | * @param string $folder folder name |
||
312 | * @return array success |
||
313 | * |
||
314 | * @throws ImapBadRequestException |
||
315 | * @throws ImapServerErrorException |
||
316 | * @throws RuntimeException |
||
317 | */ |
||
318 | public function subscribeFolder(string $folder): array; |
||
319 | |||
320 | /** |
||
321 | * Unsubscribe from a folder |
||
322 | * |
||
323 | * @param string $folder folder name |
||
324 | * @return array success |
||
325 | * |
||
326 | * @throws ImapBadRequestException |
||
327 | * @throws ImapServerErrorException |
||
328 | * @throws RuntimeException |
||
329 | */ |
||
330 | public function unsubscribeFolder(string $folder): array; |
||
331 | |||
332 | /** |
||
333 | * Send idle command |
||
334 | * |
||
335 | * @throws RuntimeException |
||
336 | */ |
||
337 | public function idle(); |
||
338 | |||
339 | /** |
||
340 | * Send done command |
||
341 | * @throws RuntimeException |
||
342 | */ |
||
343 | public function done(); |
||
344 | |||
345 | /** |
||
346 | * Apply session saved changes to the server |
||
347 | * |
||
348 | * @return array success |
||
349 | * |
||
350 | * @throws ImapBadRequestException |
||
351 | * @throws ImapServerErrorException |
||
352 | * @throws RuntimeException |
||
353 | */ |
||
354 | public function expunge(): array; |
||
355 | |||
356 | /** |
||
357 | * Retrieve the quota level settings, and usage statics per mailbox |
||
358 | * @param $username |
||
359 | * |
||
360 | * @return array |
||
361 | * @throws RuntimeException |
||
362 | */ |
||
363 | public function getQuota($username): array; |
||
364 | |||
365 | /** |
||
366 | * Retrieve the quota settings per user |
||
367 | * |
||
368 | * @param string $quota_root |
||
369 | * |
||
370 | * @return array |
||
371 | * @throws ConnectionFailedException |
||
372 | */ |
||
373 | public function getQuotaRoot(string $quota_root = 'INBOX'): array; |
||
374 | |||
375 | /** |
||
376 | * Send noop command |
||
377 | * |
||
378 | * @return array success |
||
379 | * |
||
380 | * @throws ImapBadRequestException |
||
381 | * @throws ImapServerErrorException |
||
382 | * @throws RuntimeException |
||
383 | */ |
||
384 | public function noop(): array; |
||
385 | |||
386 | /** |
||
387 | * Do a search request |
||
388 | * |
||
389 | * @param array $params |
||
390 | * @param int|string $uid set to IMAP::ST_UID or any string representing the UID - set to IMAP::ST_MSGN to use |
||
391 | * message numbers instead. |
||
392 | * |
||
393 | * @return array message ids |
||
394 | * @throws RuntimeException |
||
395 | */ |
||
396 | public function search(array $params, $uid = IMAP::ST_UID): array; |
||
397 | |||
398 | /** |
||
399 | * Get a message overview |
||
400 | * @param string $sequence uid sequence |
||
401 | * @param int|string $uid set to IMAP::ST_UID or any string representing the UID - set to IMAP::ST_MSGN to use |
||
402 | * message numbers instead. |
||
403 | * |
||
404 | * @return array |
||
405 | * @throws RuntimeException |
||
406 | * @throws MessageNotFoundException |
||
407 | * @throws InvalidMessageDateException |
||
408 | */ |
||
409 | public function overview(string $sequence, $uid = IMAP::ST_UID): array; |
||
410 | |||
411 | /** |
||
412 | * Enable the debug mode |
||
413 | */ |
||
414 | public function enableDebug(); |
||
415 | |||
416 | /** |
||
417 | * Disable the debug mode |
||
418 | */ |
||
419 | public function disableDebug(); |
||
420 | |||
421 | /** |
||
422 | * Enable uid caching |
||
423 | */ |
||
424 | public function enableUidCache(); |
||
425 | |||
426 | /** |
||
427 | * Disable uid caching |
||
428 | */ |
||
429 | public function disableUidCache(); |
||
430 | |||
431 | /** |
||
432 | * Set the uid cache of current active folder |
||
433 | * |
||
434 | * @param array|null $uids |
||
435 | */ |
||
436 | public function setUidCache($uids); |
||
437 | } |
||
438 |