defender-security / lib / packages / Safe / generated / imap.php

imap.php in Defender Security – Malware Scanner, Login Security & Firewall 6.3.0, at lib/packages/Safe/generated/imap.php

1,486 lines 31.1 KB

Raw Download Zip

1	<?php
2
3	namespace WP_DEFENDER_VENDOR\Safe;
4
5	use WP_DEFENDER_VENDOR\Safe\Exceptions\ImapException;
6
7	/**
8	* Appends a string message to the specified mailbox.
9	*
10	* @param resource $imap_stream An IMAP stream returned by
11	* imap_open.
12	* @param string $mailbox The mailbox name, see imap_open for more
13	* information
14	* @param string $message The message to be append, as a string
15	*
16	* When talking to the Cyrus IMAP server, you must use "\r\n" as
17	* your end-of-line terminator instead of "\n" or the operation will
18	* fail
19	* @param string\|null $options If provided, the options will also be written
20	* to the mailbox
21	* @param string\|null $internal_date If this parameter is set, it will set the INTERNALDATE on the appended message. The parameter should be a date string that conforms to the rfc2060 specifications for a date_time value.
22	*
23	* @throws ImapException
24	*
25	*/
26	function imap_append($imap_stream, string $mailbox, string $message, ?string $options = null, ?string $internal_date = null): void
27	{
28	error_clear_last();
29	$result = \imap_append($imap_stream, $mailbox, $message, $options, $internal_date);
30	if ($result === false) {
31	throw ImapException::createFromPhpError();
32	}
33	}
34
35
36	/**
37	* Checks information about the current mailbox.
38	*
39	* @param resource $imap_stream An IMAP stream returned by
40	* imap_open.
41	* @return \stdClass Returns the information in an object with following properties:
42	*
43	*
44	*
45	* Date - current system time formatted according to RFC2822
46	*
47	*
48	*
49	*
50	* Driver - protocol used to access this mailbox:
51	* POP3, IMAP, NNTP
52	*
53	*
54	*
55	*
56	* Mailbox - the mailbox name
57	*
58	*
59	*
60	*
61	* Nmsgs - number of messages in the mailbox
62	*
63	*
64	*
65	*
66	* Recent - number of recent messages in the mailbox
67	*
68	*
69	*
70	*
71	* Returns FALSE on failure.
72	* @throws ImapException
73	*
74	*/
75	function imap_check($imap_stream): \stdClass
76	{
77	error_clear_last();
78	$result = \imap_check($imap_stream);
79	if ($result === false) {
80	throw ImapException::createFromPhpError();
81	}
82	return $result;
83	}
84
85
86	/**
87	* This function causes a store to delete the specified
88	* flag to the flags set for the
89	* messages in the specified sequence.
90	*
91	* @param resource $imap_stream An IMAP stream returned by
92	* imap_open.
93	* @param string $sequence A sequence of message numbers. You can enumerate desired messages
94	* with the X,Y syntax, or retrieve all messages
95	* within an interval with the X:Y syntax
96	* @param string $flag The flags which you can unset are "\\Seen", "\\Answered", "\\Flagged",
97	* "\\Deleted", and "\\Draft" (as defined by RFC2060)
98	* @param int $options options are a bit mask and may contain
99	* the single option:
100	*
101	*
102	*
103	* ST_UID - The sequence argument contains UIDs
104	* instead of sequence numbers
105	*
106	*
107	*
108	* @throws ImapException
109	*
110	*/
111	function imap_clearflag_full($imap_stream, string $sequence, string $flag, int $options = 0): void
112	{
113	error_clear_last();
114	$result = \imap_clearflag_full($imap_stream, $sequence, $flag, $options);
115	if ($result === false) {
116	throw ImapException::createFromPhpError();
117	}
118	}
119
120
121	/**
122	* Closes the imap stream.
123	*
124	* @param resource $imap_stream An IMAP stream returned by
125	* imap_open.
126	* @param int $flag If set to CL_EXPUNGE, the function will silently
127	* expunge the mailbox before closing, removing all messages marked for
128	* deletion. You can achieve the same thing by using
129	* imap_expunge
130	* @throws ImapException
131	*
132	*/
133	function imap_close($imap_stream, int $flag = 0): void
134	{
135	error_clear_last();
136	$result = \imap_close($imap_stream, $flag);
137	if ($result === false) {
138	throw ImapException::createFromPhpError();
139	}
140	}
141
142
143	/**
144	* Creates a new mailbox specified by mailbox.
145	*
146	* @param resource $imap_stream An IMAP stream returned by
147	* imap_open.
148	* @param string $mailbox The mailbox name, see imap_open for more
149	* information. Names containing international characters should be
150	* encoded by imap_utf7_encode
151	* @throws ImapException
152	*
153	*/
154	function imap_createmailbox($imap_stream, string $mailbox): void
155	{
156	error_clear_last();
157	$result = \imap_createmailbox($imap_stream, $mailbox);
158	if ($result === false) {
159	throw ImapException::createFromPhpError();
160	}
161	}
162
163
164	/**
165	* Deletes the specified mailbox.
166	*
167	* @param resource $imap_stream An IMAP stream returned by
168	* imap_open.
169	* @param string $mailbox The mailbox name, see imap_open for more
170	* information
171	* @throws ImapException
172	*
173	*/
174	function imap_deletemailbox($imap_stream, string $mailbox): void
175	{
176	error_clear_last();
177	$result = \imap_deletemailbox($imap_stream, $mailbox);
178	if ($result === false) {
179	throw ImapException::createFromPhpError();
180	}
181	}
182
183
184	/**
185	* Fetches all the structured information for a given message.
186	*
187	* @param resource $imap_stream An IMAP stream returned by
188	* imap_open.
189	* @param int $msg_number The message number
190	* @param int $options This optional parameter only has a single option,
191	* FT_UID, which tells the function to treat the
192	* msg_number argument as a
193	* UID.
194	* @return \stdClass Returns an object with properties listed in the table below.
195	*
196	*
197	*
198	* Returned Object for imap_fetchstructure
199	*
200	*
201	*
202	*
203	* type
204	* Primary body type
205	*
206	*
207	* encoding
208	* Body transfer encoding
209	*
210	*
211	* ifsubtype
212	* TRUE if there is a subtype string
213	*
214	*
215	* subtype
216	* MIME subtype
217	*
218	*
219	* ifdescription
220	* TRUE if there is a description string
221	*
222	*
223	* description
224	* Content description string
225	*
226	*
227	* ifid
228	* TRUE if there is an identification string
229	*
230	*
231	* id
232	* Identification string
233	*
234	*
235	* lines
236	* Number of lines
237	*
238	*
239	* bytes
240	* Number of bytes
241	*
242	*
243	* ifdisposition
244	* TRUE if there is a disposition string
245	*
246	*
247	* disposition
248	* Disposition string
249	*
250	*
251	* ifdparameters
252	* TRUE if the dparameters array exists
253	*
254	*
255	* dparameters
256	* An array of objects where each object has an
257	* "attribute" and a "value"
258	* property corresponding to the parameters on the
259	* Content-disposition MIME
260	* header.
261	*
262	*
263	* ifparameters
264	* TRUE if the parameters array exists
265	*
266	*
267	* parameters
268	* An array of objects where each object has an
269	* "attribute" and a "value"
270	* property.
271	*
272	*
273	* parts
274	* An array of objects identical in structure to the top-level
275	* object, each of which corresponds to a MIME body
276	* part.
277	*
278	*
279	*
280	*
281	*
282	*
283	* Primary body type (value may vary with used library, use of constants is recommended)
284	*
285	*
286	* ValueTypeConstant
287	*
288	*
289	* 0textTYPETEXT
290	* 1multipartTYPEMULTIPART
291	* 2messageTYPEMESSAGE
292	* 3applicationTYPEAPPLICATION
293	* 4audioTYPEAUDIO
294	* 5imageTYPEIMAGE
295	* 6videoTYPEVIDEO
296	* 7modelTYPEMODEL
297	* 8otherTYPEOTHER
298	*
299	*
300	*
301	*
302	*
303	* Transfer encodings (value may vary with used library, use of constants is recommended)
304	*
305	*
306	* ValueTypeConstant
307	*
308	*
309	* 07bitENC7BIT
310	* 18bitENC8BIT
311	* 2BinaryENCBINARY
312	* 3Base64ENCBASE64
313	* 4Quoted-PrintableENCQUOTEDPRINTABLE
314	* 5otherENCOTHER
315	*
316	*
317	*
318	* @throws ImapException
319	*
320	*/
321	function imap_fetchstructure($imap_stream, int $msg_number, int $options = 0): \stdClass
322	{
323	error_clear_last();
324	$result = \imap_fetchstructure($imap_stream, $msg_number, $options);
325	if ($result === false) {
326	throw ImapException::createFromPhpError();
327	}
328	return $result;
329	}
330
331
332	/**
333	* Purges the cache of entries of a specific type.
334	*
335	* @param resource $imap_stream An IMAP stream returned by
336	* imap_open.
337	* @param int $caches Specifies the cache to purge. It may one or a combination
338	* of the following constants:
339	* IMAP_GC_ELT (message cache elements),
340	* IMAP_GC_ENV (envelope and bodies),
341	* IMAP_GC_TEXTS (texts).
342	* @throws ImapException
343	*
344	*/
345	function imap_gc($imap_stream, int $caches): void
346	{
347	error_clear_last();
348	$result = \imap_gc($imap_stream, $caches);
349	if ($result === false) {
350	throw ImapException::createFromPhpError();
351	}
352	}
353
354
355	/**
356	* Gets information about the given message number by reading its headers.
357	*
358	* @param resource $imap_stream An IMAP stream returned by
359	* imap_open.
360	* @param int $msg_number The message number
361	* @param int $fromlength Number of characters for the fetchfrom property.
362	* Must be greater than or equal to zero.
363	* @param int $subjectlength Number of characters for the fetchsubject property
364	* Must be greater than or equal to zero.
365	* @param string\|null $defaulthost
366	*
367	* @return \stdClass Returns FALSE on error or, if successful, the information in an object with following properties:
368	*
369	*
370	*
371	* toaddress - full to: line, up to 1024 characters
372	*
373	*
374	*
375	*
376	* to - an array of objects from the To: line, with the following
377	* properties: personal, adl,
378	* mailbox, and host
379	*
380	*
381	*
382	*
383	* fromaddress - full from: line, up to 1024 characters
384	*
385	*
386	*
387	*
388	* from - an array of objects from the From: line, with the following
389	* properties: personal, adl,
390	* mailbox, and host
391	*
392	*
393	*
394	*
395	* ccaddress - full cc: line, up to 1024 characters
396	*
397	*
398	*
399	*
400	* cc - an array of objects from the Cc: line, with the following
401	* properties: personal, adl,
402	* mailbox, and host
403	*
404	*
405	*
406	*
407	* bccaddress - full bcc: line, up to 1024 characters
408	*
409	*
410	*
411	*
412	* bcc - an array of objects from the Bcc: line, with the following
413	* properties: personal, adl,
414	* mailbox, and host
415	*
416	*
417	*
418	*
419	* reply_toaddress - full Reply-To: line, up to 1024 characters
420	*
421	*
422	*
423	*
424	* reply_to - an array of objects from the Reply-To: line, with the following
425	* properties: personal, adl,
426	* mailbox, and host
427	*
428	*
429	*
430	*
431	* senderaddress - full sender: line, up to 1024 characters
432	*
433	*
434	*
435	*
436	* sender - an array of objects from the Sender: line, with the following
437	* properties: personal, adl,
438	* mailbox, and host
439	*
440	*
441	*
442	*
443	* return_pathaddress - full Return-Path: line, up to 1024 characters
444	*
445	*
446	*
447	*
448	* return_path - an array of objects from the Return-Path: line, with the
449	* following properties: personal,
450	* adl, mailbox, and
451	* host
452	*
453	*
454	*
455	*
456	* remail -
457	*
458	*
459	*
460	*
461	* date - The message date as found in its headers
462	*
463	*
464	*
465	*
466	* Date - Same as date
467	*
468	*
469	*
470	*
471	* subject - The message subject
472	*
473	*
474	*
475	*
476	* Subject - Same as subject
477	*
478	*
479	*
480	*
481	* in_reply_to -
482	*
483	*
484	*
485	*
486	* message_id -
487	*
488	*
489	*
490	*
491	* newsgroups -
492	*
493	*
494	*
495	*
496	* followup_to -
497	*
498	*
499	*
500	*
501	* references -
502	*
503	*
504	*
505	*
506	* Recent - R if recent and seen, N
507	* if recent and not seen, ' ' if not recent.
508	*
509	*
510	*
511	*
512	* Unseen - U if not seen AND not recent, ' ' if seen
513	* OR not seen and recent
514	*
515	*
516	*
517	*
518	* Flagged - F if flagged, ' ' if not flagged
519	*
520	*
521	*
522	*
523	* Answered - A if answered, ' ' if unanswered
524	*
525	*
526	*
527	*
528	* Deleted - D if deleted, ' ' if not deleted
529	*
530	*
531	*
532	*
533	* Draft - X if draft, ' ' if not draft
534	*
535	*
536	*
537	*
538	* Msgno - The message number
539	*
540	*
541	*
542	*
543	* MailDate -
544	*
545	*
546	*
547	*
548	* Size - The message size
549	*
550	*
551	*
552	*
553	* udate - mail message date in Unix time
554	*
555	*
556	*
557	*
558	* fetchfrom - from line formatted to fit fromlength
559	* characters
560	*
561	*
562	*
563	*
564	* fetchsubject - subject line formatted to fit
565	* subjectlength characters
566	*
567	*
568	*
569	* @throws ImapException
570	*
571	*/
572	function imap_headerinfo($imap_stream, int $msg_number, int $fromlength = 0, int $subjectlength = 0, ?string $defaulthost = null): \stdClass
573	{
574	error_clear_last();
575	$result = \imap_headerinfo($imap_stream, $msg_number, $fromlength, $subjectlength, $defaulthost);
576	if ($result === false) {
577	throw ImapException::createFromPhpError();
578	}
579	return $result;
580	}
581
582
583	/**
584	* Create a MIME message based on the given envelope
585	* and body sections.
586	*
587	* @param array $envelope An associative array of header fields. Valid keys are: "remail",
588	* "return_path", "date", "from", "reply_to", "in_reply_to", "subject",
589	* "to", "cc", "bcc" and "message_id", which set the respective message headers to the given string.
590	* To set additional headers, the key "custom_headers" is supported, which expects
591	* an array of those headers, e.g. ["User-Agent: My Mail Client"].
592	* @param array $body An indexed array of bodies. The first body is the main body of the message;
593	* only if it has a type of TYPEMULTIPART, further bodies
594	* are processed; these bodies constitute the bodies of the parts.
595	*
596	*
597	* Body Array Structure
598	*
599	*
600	*
601	* Key
602	* Type
603	* Description
604	*
605	*
606	*
607	*
608	* type
609	* int
610	*
611	* The MIME type.
612	* One of TYPETEXT (default), TYPEMULTIPART,
613	* TYPEMESSAGE, TYPEAPPLICATION,
614	* TYPEAUDIO, TYPEIMAGE,
615	* TYPEMODEL or TYPEOTHER.
616	*
617	*
618	*
619	* encoding
620	* int
621	*
622	* The Content-Transfer-Encoding.
623	* One of ENC7BIT (default), ENC8BIT,
624	* ENCBINARY, ENCBASE64,
625	* ENCQUOTEDPRINTABLE or ENCOTHER.
626	*
627	*
628	*
629	* charset
630	* string
631	* The charset parameter of the MIME type.
632	*
633	*
634	* type.parameters
635	* array
636	* An associative array of Content-Type parameter names and their values.
637	*
638	*
639	* subtype
640	* string
641	* The MIME subtype, e.g. 'jpeg' for TYPEIMAGE.
642	*
643	*
644	* id
645	* string
646	* The Content-ID.
647	*
648	*
649	* description
650	* string
651	* The Content-Description.
652	*
653	*
654	* disposition.type
655	* string
656	* The Content-Disposition, e.g. 'attachment'.
657	*
658	*
659	* disposition
660	* array
661	* An associative array of Content-Disposition parameter names and values.
662	*
663	*
664	* contents.data
665	* string
666	* The payload.
667	*
668	*
669	* lines
670	* int
671	* The size of the payload in lines.
672	*
673	*
674	* bytes
675	* int
676	* The size of the payload in bytes.
677	*
678	*
679	* md5
680	* string
681	* The MD5 checksum of the payload.
682	*
683	*
684	*
685	*
686	* @return string Returns the MIME message as string.
687	* @throws ImapException
688	*
689	*/
690	function imap_mail_compose(array $envelope, array $body): string
691	{
692	error_clear_last();
693	$result = \imap_mail_compose($envelope, $body);
694	if ($result === false) {
695	throw ImapException::createFromPhpError();
696	}
697	return $result;
698	}
699
700
701	/**
702	* Copies mail messages specified by msglist
703	* to specified mailbox.
704	*
705	* @param resource $imap_stream An IMAP stream returned by
706	* imap_open.
707	* @param string $msglist msglist is a range not just message
708	* numbers (as described in RFC2060).
709	* @param string $mailbox The mailbox name, see imap_open for more
710	* information
711	* @param int $options options is a bitmask of one or more of
712	*
713	*
714	*
715	* CP_UID - the sequence numbers contain UIDS
716	*
717	*
718	*
719	*
720	* CP_MOVE - Delete the messages from
721	* the current mailbox after copying
722	*
723	*
724	*
725	* @throws ImapException
726	*
727	*/
728	function imap_mail_copy($imap_stream, string $msglist, string $mailbox, int $options = 0): void
729	{
730	error_clear_last();
731	$result = \imap_mail_copy($imap_stream, $msglist, $mailbox, $options);
732	if ($result === false) {
733	throw ImapException::createFromPhpError();
734	}
735	}
736
737
738	/**
739	* Moves mail messages specified by msglist to the
740	* specified mailbox.
741	*
742	* @param resource $imap_stream An IMAP stream returned by
743	* imap_open.
744	* @param string $msglist msglist is a range not just message numbers
745	* (as described in RFC2060).
746	* @param string $mailbox The mailbox name, see imap_open for more
747	* information
748	* @param int $options options is a bitmask and may contain the single option:
749	*
750	*
751	*
752	* CP_UID - the sequence numbers contain UIDS
753	*
754	*
755	*
756	* @throws ImapException
757	*
758	*/
759	function imap_mail_move($imap_stream, string $msglist, string $mailbox, int $options = 0): void
760	{
761	error_clear_last();
762	$result = \imap_mail_move($imap_stream, $msglist, $mailbox, $options);
763	if ($result === false) {
764	throw ImapException::createFromPhpError();
765	}
766	}
767
768
769	/**
770	* This function allows sending of emails with correct handling of
771	* Cc and Bcc receivers.
772	*
773	* The parameters to, cc
774	* and bcc are all strings and are all parsed
775	* as RFC822 address lists.
776	*
777	* @param string $to The receiver
778	* @param string $subject The mail subject
779	* @param string $message The mail body, see imap_mail_compose
780	* @param string\|null $additional_headers As string with additional headers to be set on the mail
781	* @param string\|null $cc
782	* @param string\|null $bcc The receivers specified in bcc will get the
783	* mail, but are excluded from the headers.
784	* @param string\|null $rpath Use this parameter to specify return path upon mail delivery failure.
785	* This is useful when using PHP as a mail client for multiple users.
786	*
787	* @throws ImapException
788	*
789	*/
790	function imap_mail(string $to, string $subject, string $message, ?string $additional_headers = null, ?string $cc = null, ?string $bcc = null, ?string $rpath = null): void
791	{
792	error_clear_last();
793	$result = \imap_mail($to, $subject, $message, $additional_headers, $cc, $bcc, $rpath);
794	if ($result === false) {
795	throw ImapException::createFromPhpError();
796	}
797	}
798
799
800	/**
801	* Checks the current mailbox status on the server. It is similar to
802	* imap_status, but will additionally sum up the size of
803	* all messages in the mailbox, which will take some additional time to
804	* execute.
805	*
806	* @param resource $imap_stream An IMAP stream returned by
807	* imap_open.
808	* @return \stdClass Returns the information in an object with following properties:
809	*
810	* Mailbox properties
811	*
812	*
813	*
814	* Date
815	* date of last change (current datetime)
816	*
817	*
818	* Driver
819	* driver
820	*
821	*
822	* Mailbox
823	* name of the mailbox
824	*
825	*
826	* Nmsgs
827	* number of messages
828	*
829	*
830	* Recent
831	* number of recent messages
832	*
833	*
834	* Unread
835	* number of unread messages
836	*
837	*
838	* Deleted
839	* number of deleted messages
840	*
841	*
842	* Size
843	* mailbox size
844	*
845	*
846	*
847	*
848	*
849	* Returns FALSE on failure.
850	* @throws ImapException
851	*
852	*/
853	function imap_mailboxmsginfo($imap_stream): \stdClass
854	{
855	error_clear_last();
856	$result = \imap_mailboxmsginfo($imap_stream);
857	if ($result === false) {
858	throw ImapException::createFromPhpError();
859	}
860	return $result;
861	}
862
863
864	/**
865	* Decode a modified UTF-7 (as specified in RFC 2060, section 5.1.3) string to UTF-8.
866	*
867	* @param string $in A string encoded in modified UTF-7.
868	* @return string Returns in converted to UTF-8.
869	* @throws ImapException
870	*
871	*/
872	function imap_mutf7_to_utf8(string $in): string
873	{
874	error_clear_last();
875	$result = \imap_mutf7_to_utf8($in);
876	if ($result === false) {
877	throw ImapException::createFromPhpError();
878	}
879	return $result;
880	}
881
882
883	/**
884	* Gets the number of messages in the current mailbox.
885	*
886	* @param resource $imap_stream An IMAP stream returned by
887	* imap_open.
888	* @return int Return the number of messages in the current mailbox, as an integer.
889	* @throws ImapException
890	*
891	*/
892	function imap_num_msg($imap_stream): int
893	{
894	error_clear_last();
895	$result = \imap_num_msg($imap_stream);
896	if ($result === false) {
897	throw ImapException::createFromPhpError();
898	}
899	return $result;
900	}
901
902
903	/**
904	* Opens an IMAP stream to a mailbox.
905	*
906	* This function can also be used to open streams to POP3 and
907	* NNTP servers, but some functions and features are only
908	* available on IMAP servers.
909	*
910	* @param string $mailbox A mailbox name consists of a server and a mailbox path on this server.
911	* The special name INBOX stands for the current users
912	* personal mailbox. Mailbox names that contain international characters
913	* besides those in the printable ASCII space have to be encoded with
914	* imap_utf7_encode.
915	*
916	* The server part, which is enclosed in '{' and '}', consists of the servers
917	* name or ip address, an optional port (prefixed by ':'), and an optional
918	* protocol specification (prefixed by '/').
919	*
920	* The server part is mandatory in all mailbox
921	* parameters.
922	*
923	* All names which start with { are remote names, and are
924	* in the form "{" remote_system_name [":" port] [flags] "}"
925	* [mailbox_name] where:
926	*
927	*
928	*
929	* remote_system_name - Internet domain name or
930	* bracketed IP address of server.
931	*
932	*
933	*
934	*
935	* port - optional TCP port number, default is the
936	* default port for that service
937	*
938	*
939	*
940	*
941	* flags - optional flags, see following table.
942	*
943	*
944	*
945	*
946	* mailbox_name - remote mailbox name, default is INBOX
947	*
948	*
949	*
950	*
951	*
952	* Optional flags for names
953	*
954	*
955	*
956	* Flag
957	* Description
958	*
959	*
960	*
961	*
962	* /service=service
963	* mailbox access service, default is "imap"
964	*
965	*
966	* /user=user
967	* remote user name for login on the server
968	*
969	*
970	* /authuser=user
971	* remote authentication user; if specified this is the user name
972	* whose password is used (e.g. administrator)
973	*
974	*
975	* /anonymous
976	* remote access as anonymous user
977	*
978	*
979	* /debug
980	* record protocol telemetry in application's debug log
981	*
982	*
983	* /secure
984	* do not transmit a plaintext password over the network
985	*
986	*
987	* /imap, /imap2,
988	* /imap2bis, /imap4,
989	* /imap4rev1
990	* equivalent to /service=imap
991	*
992	*
993	* /pop3
994	* equivalent to /service=pop3
995	*
996	*
997	* /nntp
998	* equivalent to /service=nntp
999	*
1000	*
1001	* /norsh
1002	* do not use rsh or ssh to establish a preauthenticated IMAP
1003	* session
1004	*
1005	*
1006	* /ssl
1007	* use the Secure Socket Layer to encrypt the session
1008	*
1009	*
1010	* /validate-cert
1011	* validate certificates from TLS/SSL server (this is the default
1012	* behavior)
1013	*
1014	*
1015	* /novalidate-cert
1016	* do not validate certificates from TLS/SSL server, needed if
1017	* server uses self-signed certificates
1018	*
1019	*
1020	* /tls
1021	* force use of start-TLS to encrypt the session, and reject
1022	* connection to servers that do not support it
1023	*
1024	*
1025	* /notls
1026	* do not do start-TLS to encrypt the session, even with servers
1027	* that support it
1028	*
1029	*
1030	* /readonly
1031	* request read-only mailbox open (IMAP only; ignored on NNTP, and
1032	* an error with SMTP and POP3)
1033	*
1034	*
1035	*
1036	*
1037	* @param string $username The user name
1038	* @param string $password The password associated with the username
1039	* @param int $options The options are a bit mask with one or more of
1040	* the following:
1041	*
1042	*
1043	*
1044	* OP_READONLY - Open mailbox read-only
1045	*
1046	*
1047	*
1048	*
1049	* OP_ANONYMOUS - Don't use or update a
1050	* .newsrc for news (NNTP only)
1051	*
1052	*
1053	*
1054	*
1055	* OP_HALFOPEN - For IMAP
1056	* and NNTP names, open a connection but
1057	* don't open a mailbox.
1058	*
1059	*
1060	*
1061	*
1062	* CL_EXPUNGE - Expunge mailbox automatically upon mailbox close
1063	* (see also imap_delete and
1064	* imap_expunge)
1065	*
1066	*
1067	*
1068	*
1069	* OP_DEBUG - Debug protocol negotiations
1070	*
1071	*
1072	*
1073	*
1074	* OP_SHORTCACHE - Short (elt-only) caching
1075	*
1076	*
1077	*
1078	*
1079	* OP_SILENT - Don't pass up events (internal use)
1080	*
1081	*
1082	*
1083	*
1084	* OP_PROTOTYPE - Return driver prototype
1085	*
1086	*
1087	*
1088	*
1089	* OP_SECURE - Don't do non-secure authentication
1090	*
1091	*
1092	*
1093	* @param int $n_retries Number of maximum connect attempts
1094	* @param array\|null $params Connection parameters, the following (string) keys maybe used
1095	* to set one or more connection parameters:
1096	*
1097	*
1098	*
1099	* DISABLE_AUTHENTICATOR - Disable authentication properties
1100	*
1101	*
1102	*
1103	* @return resource Returns an IMAP stream on success.
1104	* @throws ImapException
1105	*
1106	*/
1107	function imap_open(string $mailbox, string $username, string $password, int $options = 0, int $n_retries = 0, ?array $params = null)
1108	{
1109	error_clear_last();
1110	$result = \imap_open($mailbox, $username, $password, $options, $n_retries, $params);
1111	if ($result === false) {
1112	throw ImapException::createFromPhpError();
1113	}
1114	return $result;
1115	}
1116
1117
1118	/**
1119	* This function renames on old mailbox to new mailbox (see
1120	* imap_open for the format of
1121	* mbox names).
1122	*
1123	* @param resource $imap_stream An IMAP stream returned by
1124	* imap_open.
1125	* @param string $old_mbox The old mailbox name, see imap_open for more
1126	* information
1127	* @param string $new_mbox The new mailbox name, see imap_open for more
1128	* information
1129	* @throws ImapException
1130	*
1131	*/
1132	function imap_renamemailbox($imap_stream, string $old_mbox, string $new_mbox): void
1133	{
1134	error_clear_last();
1135	$result = \imap_renamemailbox($imap_stream, $old_mbox, $new_mbox);
1136	if ($result === false) {
1137	throw ImapException::createFromPhpError();
1138	}
1139	}
1140
1141
1142	/**
1143	* Saves a part or the whole body of the specified message.
1144	*
1145	* @param resource $imap_stream An IMAP stream returned by
1146	* imap_open.
1147	* @param string\|resource $file The path to the saved file as a string, or a valid file descriptor
1148	* returned by fopen.
1149	* @param int $msg_number The message number
1150	* @param string $part_number The part number. It is a string of integers delimited by period which
1151	* index into a body part list as per the IMAP4 specification
1152	* @param int $options A bitmask with one or more of the following:
1153	*
1154	*
1155	*
1156	* FT_UID - The msg_number is a UID
1157	*
1158	*
1159	*
1160	*
1161	* FT_PEEK - Do not set the \Seen flag if
1162	* not already set
1163	*
1164	*
1165	*
1166	*
1167	* FT_INTERNAL - The return string is in
1168	* internal format, will not canonicalize to CRLF.
1169	*
1170	*
1171	*
1172	* @throws ImapException
1173	*
1174	*/
1175	function imap_savebody($imap_stream, $file, int $msg_number, string $part_number = "", int $options = 0): void
1176	{
1177	error_clear_last();
1178	$result = \imap_savebody($imap_stream, $file, $msg_number, $part_number, $options);
1179	if ($result === false) {
1180	throw ImapException::createFromPhpError();
1181	}
1182	}
1183
1184
1185	/**
1186	* Sets an upper limit quota on a per mailbox basis.
1187	*
1188	* @param resource $imap_stream An IMAP stream returned by
1189	* imap_open.
1190	* @param string $quota_root The mailbox to have a quota set. This should follow the IMAP standard
1191	* format for a mailbox: user.name.
1192	* @param int $quota_limit The maximum size (in KB) for the quota_root
1193	* @throws ImapException
1194	*
1195	*/
1196	function imap_set_quota($imap_stream, string $quota_root, int $quota_limit): void
1197	{
1198	error_clear_last();
1199	$result = \imap_set_quota($imap_stream, $quota_root, $quota_limit);
1200	if ($result === false) {
1201	throw ImapException::createFromPhpError();
1202	}
1203	}
1204
1205
1206	/**
1207	* Sets the ACL for a giving mailbox.
1208	*
1209	* @param resource $imap_stream An IMAP stream returned by
1210	* imap_open.
1211	* @param string $mailbox The mailbox name, see imap_open for more
1212	* information
1213	* @param string $id The user to give the rights to.
1214	* @param string $rights The rights to give to the user. Passing an empty string will delete
1215	* acl.
1216	* @throws ImapException
1217	*
1218	*/
1219	function imap_setacl($imap_stream, string $mailbox, string $id, string $rights): void
1220	{
1221	error_clear_last();
1222	$result = \imap_setacl($imap_stream, $mailbox, $id, $rights);
1223	if ($result === false) {
1224	throw ImapException::createFromPhpError();
1225	}
1226	}
1227
1228
1229	/**
1230	* Causes a store to add the specified flag to the
1231	* flags set for the messages in the specified
1232	* sequence.
1233	*
1234	* @param resource $imap_stream An IMAP stream returned by
1235	* imap_open.
1236	* @param string $sequence A sequence of message numbers. You can enumerate desired messages
1237	* with the X,Y syntax, or retrieve all messages
1238	* within an interval with the X:Y syntax
1239	* @param string $flag The flags which you can set are \Seen,
1240	* \Answered, \Flagged,
1241	* \Deleted, and \Draft as
1242	* defined by RFC2060.
1243	* @param int $options A bit mask that may contain the single option:
1244	*
1245	*
1246	*
1247	* ST_UID - The sequence argument contains UIDs
1248	* instead of sequence numbers
1249	*
1250	*
1251	*
1252	* @throws ImapException
1253	*
1254	*/
1255	function imap_setflag_full($imap_stream, string $sequence, string $flag, int $options = NIL): void
1256	{
1257	error_clear_last();
1258	$result = \imap_setflag_full($imap_stream, $sequence, $flag, $options);
1259	if ($result === false) {
1260	throw ImapException::createFromPhpError();
1261	}
1262	}
1263
1264
1265	/**
1266	* Gets and sorts message numbers by the given parameters.
1267	*
1268	* @param resource $imap_stream An IMAP stream returned by
1269	* imap_open.
1270	* @param int $criteria Criteria can be one (and only one) of the following:
1271	*
1272	*
1273	*
1274	* SORTDATE - message Date
1275	*
1276	*
1277	*
1278	*
1279	* SORTARRIVAL - arrival date
1280	*
1281	*
1282	*
1283	*
1284	* SORTFROM - mailbox in first From address
1285	*
1286	*
1287	*
1288	*
1289	* SORTSUBJECT - message subject
1290	*
1291	*
1292	*
1293	*
1294	* SORTTO - mailbox in first To address
1295	*
1296	*
1297	*
1298	*
1299	* SORTCC - mailbox in first cc address
1300	*
1301	*
1302	*
1303	*
1304	* SORTSIZE - size of message in octets
1305	*
1306	*
1307	*
1308	* @param int $reverse Set this to 1 for reverse sorting
1309	* @param int $options The options are a bitmask of one or more of the
1310	* following:
1311	*
1312	*
1313	*
1314	* SE_UID - Return UIDs instead of sequence numbers
1315	*
1316	*
1317	*
1318	*
1319	* SE_NOPREFETCH - Don't prefetch searched messages
1320	*
1321	*
1322	*
1323	* @param string\|null $search_criteria IMAP2-format search criteria string. For details see
1324	* imap_search.
1325	* @param string\|null $charset MIME character set to use when sorting strings.
1326	*
1327	* @return array Returns an array of message numbers sorted by the given
1328	* parameters.
1329	* @throws ImapException
1330	*
1331	*/
1332	function imap_sort($imap_stream, int $criteria, int $reverse, int $options = 0, ?string $search_criteria = null, ?string $charset = null): array
1333	{
1334	error_clear_last();
1335	$result = \imap_sort($imap_stream, $criteria, $reverse, $options, $search_criteria, $charset);
1336	if ($result === false) {
1337	throw ImapException::createFromPhpError();
1338	}
1339	return $result;
1340	}
1341
1342
1343	/**
1344	* Subscribe to a new mailbox.
1345	*
1346	* @param resource $imap_stream An IMAP stream returned by
1347	* imap_open.
1348	* @param string $mailbox The mailbox name, see imap_open for more
1349	* information
1350	* @throws ImapException
1351	*
1352	*/
1353	function imap_subscribe($imap_stream, string $mailbox): void
1354	{
1355	error_clear_last();
1356	$result = \imap_subscribe($imap_stream, $mailbox);
1357	if ($result === false) {
1358	throw ImapException::createFromPhpError();
1359	}
1360	}
1361
1362
1363	/**
1364	* Gets a tree of a threaded message.
1365	*
1366	* @param resource $imap_stream An IMAP stream returned by
1367	* imap_open.
1368	* @param int $options
1369	* @return array imap_thread returns an associative array containing
1370	* a tree of messages threaded by REFERENCES.
1371	*
1372	* Every message in the current mailbox will be represented by three entries
1373	* in the resulting array:
1374	*
1375	*
1376	* $thread["XX.num"] - current message number
1377	*
1378	*
1379	* $thread["XX.next"]
1380	*
1381	*
1382	* $thread["XX.branch"]
1383	*
1384	*
1385	* @throws ImapException
1386	*
1387	*/
1388	function imap_thread($imap_stream, int $options = SE_FREE): array
1389	{
1390	error_clear_last();
1391	$result = \imap_thread($imap_stream, $options);
1392	if ($result === false) {
1393	throw ImapException::createFromPhpError();
1394	}
1395	return $result;
1396	}
1397
1398
1399	/**
1400	* Sets or fetches the imap timeout.
1401	*
1402	* @param int $timeout_type One of the following:
1403	* IMAP_OPENTIMEOUT,
1404	* IMAP_READTIMEOUT,
1405	* IMAP_WRITETIMEOUT, or
1406	* IMAP_CLOSETIMEOUT.
1407	* @param int $timeout The timeout, in seconds.
1408	* @return mixed If the timeout parameter is set, this function
1409	* returns TRUE on success.
1410	*
1411	* If timeout is not provided or evaluates to -1,
1412	* the current timeout value of timeout_type is
1413	* returned as an integer.
1414	* @throws ImapException
1415	*
1416	*/
1417	function imap_timeout(int $timeout_type, int $timeout = -1)
1418	{
1419	error_clear_last();
1420	$result = \imap_timeout($timeout_type, $timeout);
1421	if ($result === false) {
1422	throw ImapException::createFromPhpError();
1423	}
1424	return $result;
1425	}
1426
1427
1428	/**
1429	* Removes the deletion flag for a specified message, which is set by
1430	* imap_delete or imap_mail_move.
1431	*
1432	* @param resource $imap_stream An IMAP stream returned by
1433	* imap_open.
1434	* @param int $msg_number The message number
1435	* @param int $flags
1436	* @throws ImapException
1437	*
1438	*/
1439	function imap_undelete($imap_stream, int $msg_number, int $flags = 0): void
1440	{
1441	error_clear_last();
1442	$result = \imap_undelete($imap_stream, $msg_number, $flags);
1443	if ($result === false) {
1444	throw ImapException::createFromPhpError();
1445	}
1446	}
1447
1448
1449	/**
1450	* Unsubscribe from the specified mailbox.
1451	*
1452	* @param resource $imap_stream An IMAP stream returned by
1453	* imap_open.
1454	* @param string $mailbox The mailbox name, see imap_open for more
1455	* information
1456	* @throws ImapException
1457	*
1458	*/
1459	function imap_unsubscribe($imap_stream, string $mailbox): void
1460	{
1461	error_clear_last();
1462	$result = \imap_unsubscribe($imap_stream, $mailbox);
1463	if ($result === false) {
1464	throw ImapException::createFromPhpError();
1465	}
1466	}
1467
1468
1469	/**
1470	* Encode a UTF-8 string to modified UTF-7 (as specified in RFC 2060, section 5.1.3).
1471	*
1472	* @param string $in A UTF-8 encoded string.
1473	* @return string Returns in converted to modified UTF-7.
1474	* @throws ImapException
1475	*
1476	*/
1477	function imap_utf8_to_mutf7(string $in): string
1478	{
1479	error_clear_last();
1480	$result = \imap_utf8_to_mutf7($in);
1481	if ($result === false) {
1482	throw ImapException::createFromPhpError();
1483	}
1484	return $result;
1485	}
1486