defender-security / vendor / thecodingmachine / safe / generated / imap.php

imap.php in Defender Security – Malware Scanner, Login Security & Firewall 5.5.1, at vendor/thecodingmachine/safe/generated/imap.php

1,482 lines 30.9 KB

Raw Download Zip

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