acymailing / vendor / zbateson / mail-mime-parser / src / IMessage.php

IMessage.php in AcyMailing – An Ultimate Newsletter Plugin and Marketing Automation Solution for WordPress trunk, at vendor/zbateson/mail-mime-parser/src/IMessage.php

433 lines 18.2 KB

Raw Download Zip

1	<?php
2	/**
3	* This file is part of the ZBateson\MailMimeParser project.
4	*
5	* @license http://opensource.org/licenses/bsd-license.php BSD
6	*/
7
8	namespace ZBateson\MailMimeParser;
9
10	use ZBateson\MailMimeParser\Message\IMimePart;
11
12	/**
13	* An interface representing an email message.
14	*
15	* Defines an interface to retrieve content, attachments and other parts of an
16	* email message.
17	*
18	* @author Zaahid Bateson
19	*/
20	interface IMessage extends IMimePart
21	{
22	/**
23	* Returns the inline text/plain IMessagePart for a message.
24	*
25	* If the message contains more than one text/plain 'inline' part, the
26	* default behavior is to return the first part. Additional parts can be
27	* returned by passing a 0-based index.
28	*
29	* If there are no inline text/plain parts in this message, null is
30	* returned.
31	*
32	* @see IMessage::getTextPartCount() to get a count of text parts.
33	* @see IMessage::getTextStream() to get the text content stream directly.
34	* @see IMessage::getTextContent() to get the text content in a string.
35	* @see IMessage::getHtmlPart() to get the HTML part(s).
36	* @see IMessage::getHtmlPartCount() to get a count of html parts.
37	* @param int $index Optional index of part to return.
38	* @return \ZBateson\MailMimeParser\Message\IMessagePart\|null
39	*/
40	public function getTextPart($index = 0);
41
42	/**
43	* Returns the number of inline text/plain parts this message contains.
44	*
45	* @see IMessage::getTextPart() to get the text part(s).
46	* @see IMessage::getHtmlPart() to get the HTML part(s).
47	* @see IMessage::getHtmlPartCount() to get a count of html parts.
48	* @return int
49	*/
50	public function getTextPartCount();
51
52	/**
53	* Returns the inline text/html IMessagePart for a message.
54	*
55	* If the message contains more than one text/html 'inline' part, the
56	* default behavior is to return the first part. Additional parts can be
57	* returned by passing a 0-based index.
58	*
59	* If there are no inline text/plain parts in this message, null is
60	* returned.
61	*
62	* @see IMessage::getHtmlStream() to get the html content stream directly.
63	* @see IMessage::getHtmlStream() to get the html content in a string.
64	* @see IMessage::getTextPart() to get the text part(s).
65	* @see IMessage::getTextPartCount() to get a count of text parts.
66	* @see IMessage::getHtmlPartCount() to get a count of html parts.
67	* @param int $index Optional index of part to return.
68	* @return \ZBateson\MailMimeParser\Message\IMessagePart\|null
69	*/
70	public function getHtmlPart($index = 0);
71
72	/**
73	* Returns the number of inline text/html parts this message contains.
74	*
75	* @see IMessage::getTextPart() to get the text part(s).
76	* @see IMessage::getTextPartCount() to get a count of text parts.
77	* @see IMessage::getHtmlPart() to get the HTML part(s).
78	* @return int
79	*/
80	public function getHtmlPartCount();
81
82	/**
83	* Returns a Psr7 Stream for the 'inline' text/plain content.
84	*
85	* If the message contains more than one text/plain 'inline' part, the
86	* default behavior is to return the first part. The streams for additional
87	* parts can be returned by passing a 0-based index.
88	*
89	* If a part at the passed index doesn't exist, null is returned.
90	*
91	* @see IMessage::getTextPart() to get the text part(s).
92	* @see IMessage::getTextContent() to get the text content in a string.
93	* @param int $index Optional 0-based index of inline text part stream.
94	* @param string $charset Optional charset to encode the stream with.
95	* @return \Psr\Http\Message\StreamInterface\|null
96	*/
97	public function getTextStream($index = 0, $charset = MailMimeParser::DEFAULT_CHARSET);
98
99	/**
100	* Returns the content of the inline text/plain part as a string.
101	*
102	* If the message contains more than one text/plain 'inline' part, the
103	* default behavior is to return the first part. The content for additional
104	* parts can be returned by passing a 0-based index.
105	*
106	* If a part at the passed index doesn't exist, null is returned.
107	*
108	* @see IMessage::getTextPart() to get the text part(s).
109	* @see IMessage::getTextStream() to get the text content stream directly.
110	* @param int $index Optional 0-based index of inline text part content.
111	* @param string $charset Optional charset for the returned string to be
112	* encoded in.
113	* @return string\|null
114	*/
115	public function getTextContent($index = 0, $charset = MailMimeParser::DEFAULT_CHARSET);
116
117	/**
118	* Returns a Psr7 Stream for the 'inline' text/html content.
119	*
120	* If the message contains more than one text/html 'inline' part, the
121	* default behavior is to return the first part. The streams for additional
122	* parts can be returned by passing a 0-based index.
123	*
124	* If a part at the passed index doesn't exist, null is returned.
125	*
126	* @see IMessage::getHtmlPart() to get the html part(s).
127	* @see IMessage::getHtmlContent() to get the html content in a string.
128	* @param int $index Optional 0-based index of inline html part stream.
129	* @param string $charset Optional charset to encode the stream with.
130	* @return \Psr\Http\Message\StreamInterface\|null
131	*/
132	public function getHtmlStream($index = 0, $charset = MailMimeParser::DEFAULT_CHARSET);
133
134	/**
135	* Returns the content of the inline text/html part as a string.
136	*
137	* If the message contains more than one text/html 'inline' part, the
138	* default behavior is to return the first part. The content for additional
139	* parts can be returned by passing a 0-based index.
140	*
141	* If a part at the passed index doesn't exist, null is returned.
142	*
143	* @see IMessage::getHtmlPart() to get the html part(s).
144	* @see IMessage::getHtmlStream() to get the html content stream directly.
145	* @param int $index Optional 0-based index of inline html part content.
146	* @param string $charset Optional charset for the returned string to be
147	* encoded in.
148	* @return string\|null
149	*/
150	public function getHtmlContent($index = 0, $charset = MailMimeParser::DEFAULT_CHARSET);
151
152	/**
153	* Sets the text/plain part of the message to the passed $resource, either
154	* creating a new part if one doesn't exist for text/plain, or assigning the
155	* value of $resource to an existing text/plain part.
156	*
157	* The optional $contentTypeCharset parameter is the charset for the
158	* text/plain part's Content-Type, not the charset of the passed $resource.
159	* $resource must be encoded in UTF-8 regardless of the target charset.
160	*
161	* @see IMessage::setHtmlPart() to set the html part
162	* @see IMessage::removeTextPart() to remove a text part
163	* @see IMessage::removeAllTextParts() to remove all text parts
164	* @param string\|resource\|\Psr\Http\Message\StreamInterface $resource UTF-8
165	* encoded content.
166	* @param string $contentTypeCharset the charset to use as the text/plain
167	* part's content-type header charset value.
168	*/
169	public function setTextPart($resource, string $contentTypeCharset = 'UTF-8');
170
171	/**
172	* Sets the text/html part of the message to the passed $resource, either
173	* creating a new part if one doesn't exist for text/html, or assigning the
174	* value of $resource to an existing text/html part.
175	*
176	* The optional $contentTypeCharset parameter is the charset for the
177	* text/html part's Content-Type, not the charset of the passed $resource.
178	* $resource must be encoded in UTF-8 regardless of the target charset.
179	*
180	* @see IMessage::setTextPart() to set the text part
181	* @see IMessage::removeHtmlPart() to remove an html part
182	* @see IMessage::removeAllHtmlParts() to remove all html parts
183	* @param string\|resource\|\Psr\Http\Message\StreamInterface $resource UTF-8
184	* encoded content.
185	* @param string $contentTypeCharset the charset to use as the text/html
186	* part's content-type header charset value.
187	*/
188	public function setHtmlPart($resource, string $contentTypeCharset = 'UTF-8');
189
190	/**
191	* Removes the text/plain part of the message at the passed index if one
192	* exists (defaults to first part if an index isn't passed).
193	*
194	* Returns true if a part exists at the passed index and has been removed.
195	*
196	* @see IMessage::setTextPart() to set the text part
197	* @see IMessage::removeHtmlPart() to remove an html part
198	* @see IMessage::removeAllTextParts() to remove all text parts
199	* @param int $index Optional 0-based index of inline text part to remove.
200	* @return bool true on success
201	*/
202	public function removeTextPart(int $index = 0) : bool;
203
204	/**
205	* Removes all text/plain inline parts in this message.
206	*
207	* If the message contains a multipart/alternative part, the text parts are
208	* removed from below the alternative part only. If there is only one
209	* remaining part after that, it is moved up, replacing the
210	* multipart/alternative part.
211	*
212	* If the multipart/alternative part further contains a multipart/related
213	* (or mixed) part which holds an inline text part, only parts from that
214	* child multipart are removed, and if the passed
215	* $moveRelatedPartsBelowMessage is true, any non-text parts are moved to be
216	* below the message directly (changing the message into a multipart/mixed
217	* message if need be).
218	*
219	* For more control, call
220	* {@see \ZBateson\MailMimeParser\Message\IMessagePart::removePart()} with
221	* parts you wish to remove.
222	*
223	* @see IMessage::setTextPart() to set the text part
224	* @see IMessage::removeTextPart() to remove a text part
225	* @see IMessage::removeAllHtmlParts() to remove all html parts
226	* @param bool $moveRelatedPartsBelowMessage Optionally pass false to remove
227	* related parts.
228	* @return bool true on success
229	*/
230	public function removeAllTextParts(bool $moveRelatedPartsBelowMessage = true) : bool;
231
232	/**
233	* Removes the text/html part of the message at the passed index if one
234	* exists (defaults to first part if an index isn't passed).
235	*
236	* Returns true if a part exists at the passed index and has been removed.
237	*
238	* @see IMessage::setHtmlPart() to set the html part
239	* @see IMessage::removeTextPart() to remove a text part
240	* @see IMessage::removeAllHtmlParts() to remove all html parts
241	* @param int $index Optional 0-based index of inline html part to remove.
242	* @return bool true on success
243	*/
244	public function removeHtmlPart(int $index = 0) : bool;
245
246	/**
247	* Removes all text/html inline parts in this message.
248	*
249	* If the message contains a multipart/alternative part, the html parts are
250	* removed from below the alternative part only. If there is only one
251	* remaining part after that, it is moved up, replacing the
252	* multipart/alternative part.
253	*
254	* If the multipart/alternative part further contains a multipart/related
255	* (or mixed) part which holds an inline html part, only parts from that
256	* child multipart are removed, and if the passed
257	* $moveRelatedPartsBelowMessage is true, any non-html parts are moved to be
258	* below the message directly (changing the message into a multipart/mixed
259	* message if need be).
260	*
261	* For more control, call
262	* {@see \ZBateson\MailMimeParser\Message\IMessagePart::removePart()} with
263	* parts you wish to remove.
264	*
265	* @see IMessage::setHtmlPart() to set the html part
266	* @see IMessage::removeHtmlPart() to remove an html part
267	* @see IMessage::removeAllTextParts() to remove all html parts
268	* @param bool $moveRelatedPartsBelowMessage Optionally pass false to remove
269	* related parts.
270	* @return bool true on success
271	*/
272	public function removeAllHtmlParts(bool $moveRelatedPartsBelowMessage = true) : bool;
273
274	/**
275	* Returns the attachment part at the given 0-based index, or null if none
276	* is set.
277	*
278	* The method returns all parts other than the main content part for a
279	* non-mime message, and all parts under a mime message except:
280	* - text/plain and text/html parts with a Content-Disposition not set to
281	* 'attachment'
282	* - all multipart/* parts
283	* - any signature part
284	*
285	* @see IMessage::getAllAttachmentParts() to get an array of all parts.
286	* @see IMessage::getAttachmentCount() to get the number of attachments.
287	* @param int $index the 0-based index of the attachment part to return.
288	* @return \ZBateson\MailMimeParser\Message\IMessagePart\|null
289	*/
290	public function getAttachmentPart(int $index);
291
292	/**
293	* Returns all attachment parts.
294	*
295	* The method returns all parts other than the main content part for a
296	* non-mime message, and all parts under a mime message except:
297	* - text/plain and text/html parts with a Content-Disposition not set to
298	* 'attachment'
299	* - all multipart/* parts
300	* - any signature part
301	*
302	* @see IMessage::getAllAttachmentPart() to get a single attachment.
303	* @see IMessage::getAttachmentCount() to get the number of attachments.
304	* @return \ZBateson\MailMimeParser\Message\IMessagePart[]
305	*/
306	public function getAllAttachmentParts();
307
308	/**
309	* Returns the number of attachments available.
310	*
311	* @see IMessage::getAllAttachmentPart() to get a single attachment.
312	* @see IMessage::getAllAttachmentParts() to get an array of all parts.
313	* @return int
314	*/
315	public function getAttachmentCount();
316
317	/**
318	* Adds an attachment part for the passed raw data string, handle, or stream
319	* and given parameters.
320	*
321	* Note that $disposition must be one of 'inline' or 'attachment', and will
322	* default to 'attachment' if a different value is passed.
323	*
324	* @param string\|resource\|\Psr\Http\Message\StreamInterface $resource the
325	* part's content
326	* @param string $mimeType the mime-type of the attachment
327	* @param string $filename Optional filename (to set relevant header params)
328	* @param string $disposition Optional Content-Disposition value.
329	* @param string $encoding defaults to 'base64', only applied for a mime
330	* email
331	*/
332	public function addAttachmentPart($resource, string $mimeType, ?string $filename = null, string $disposition = 'attachment', string $encoding = 'base64');
333
334	/**
335	* Adds an attachment part using the passed file.
336	*
337	* Essentially creates a psr7 stream and calls
338	* {@see IMessage::addAttachmentPart}.
339	*
340	* Note that $disposition must be one of 'inline' or 'attachment', and will
341	* default to 'attachment' if a different value is passed.
342	*
343	* @param string $filePath file to attach
344	* @param string $mimeType the mime-type of the attachment
345	* @param string $filename Optional filename (to set relevant header params)
346	* @param string $disposition Optional Content-Disposition value.
347	* @param string $encoding defaults to 'base64', only applied for a mime
348	* email
349	*/
350	public function addAttachmentPartFromFile($filePath, string $mimeType, ?string $filename = null, string $disposition = 'attachment', string $encoding = 'base64');
351
352	/**
353	* Removes the attachment at the given index.
354	*
355	* Attachments are considered to be all parts other than the main content
356	* part for a non-mime message, and all parts under a mime message except:
357	* - text/plain and text/html parts with a Content-Disposition not set to
358	* 'attachment'
359	* - all multipart/* parts
360	* - any signature part
361	*
362	*/
363	public function removeAttachmentPart(int $index);
364
365	/**
366	* Returns a stream that can be used to read the content part of a signed
367	* message, which can be used to sign an email or verify a signature.
368	*
369	* The method simply returns the stream for the first child. No
370	* verification of whether the message is in fact a signed message is
371	* performed.
372	*
373	* Note that unlike getSignedMessageAsString, getSignedMessageStream doesn't
374	* replace new lines, and before calculating a signature, LFs not preceded
375	* by CR should be replaced with CRLFs.
376	*
377	* @see IMessage::getSignedMessageAsString to get a string with CRLFs
378	* normalized
379	* @return \Psr\Http\Message\StreamInterface or null if the message doesn't
380	* have any children
381	*/
382	public function getSignedMessageStream();
383
384	/**
385	* Returns a string containing the entire body of a signed message for
386	* verification or calculating a signature.
387	*
388	* Non-CRLF new lines are replaced to always be CRLF.
389	*
390	* @see IMessage::setAsMultipartSigned to make the message a
391	* multipart/signed message.
392	* @return string or null if the message doesn't have any children
393	*/
394	public function getSignedMessageAsString();
395
396	/**
397	* Returns the signature part of a multipart/signed message or null.
398	*
399	* The signature part is determined to always be the 2nd child of a
400	* multipart/signed message, the first being the 'body'.
401	*
402	* Using the 'protocol' parameter of the Content-Type header is unreliable
403	* in some instances (for instance a difference of x-pgp-signature versus
404	* pgp-signature).
405	*
406	* @return IMimePart
407	*/
408	public function getSignaturePart();
409
410	/**
411	* Turns the message into a multipart/signed message, moving the actual
412	* message into a child part, sets the content-type of the main message to
413	* multipart/signed and adds an empty signature part as well.
414	*
415	* After calling setAsMultipartSigned, call getSignedMessageAsString to
416	* get the normalized string content to be used for calculated the message's
417	* hash.
418	*
419	* @see IMessage::getSignedMessageAsString
420	* @param string $micalg The Message Integrity Check algorithm being used
421	* @param string $protocol The mime-type of the signature body
422	*/
423	public function setAsMultipartSigned(string $micalg, string $protocol);
424
425	/**
426	* Sets the signature body of the message to the passed $body for a
427	* multipart/signed message.
428	*
429	* @param string $body the message's hash
430	*/
431	public function setSignature(string $body);
432	}
433