434 lines
18 KiB
PHP
434 lines
18 KiB
PHP
<?php
|
|
/**
|
|
* This file is part of the ZBateson\MailMimeParser project.
|
|
*
|
|
* @license http://opensource.org/licenses/bsd-license.php BSD
|
|
*/
|
|
|
|
namespace ZBateson\MailMimeParser;
|
|
|
|
use Psr\Http\Message\StreamInterface;
|
|
use ZBateson\MailMimeParser\Message\IMessagePart;
|
|
use ZBateson\MailMimeParser\Message\IMimePart;
|
|
|
|
/**
|
|
* An interface representing an email message.
|
|
*
|
|
* Defines an interface to retrieve content, attachments and other parts of an
|
|
* email message.
|
|
*
|
|
* @author Zaahid Bateson
|
|
*/
|
|
interface IMessage extends IMimePart
|
|
{
|
|
/**
|
|
* Returns the subject of the message, retrieved from the 'Subject' header,
|
|
* or null if the message has none set.
|
|
*/
|
|
public function getSubject() : ?string;
|
|
|
|
/**
|
|
* Returns the inline text/plain IMessagePart for a message.
|
|
*
|
|
* If the message contains more than one text/plain 'inline' part, the
|
|
* default behavior is to return the first part. Additional parts can be
|
|
* returned by passing a 0-based index.
|
|
*
|
|
* If there are no inline text/plain parts in this message, null is
|
|
* returned.
|
|
*
|
|
* @see IMessage::getTextPartCount() to get a count of text parts.
|
|
* @see IMessage::getTextStream() to get the text content stream directly.
|
|
* @see IMessage::getTextContent() to get the text content in a string.
|
|
* @see IMessage::getHtmlPart() to get the HTML part(s).
|
|
* @see IMessage::getHtmlPartCount() to get a count of html parts.
|
|
* @param int $index Optional index of part to return.
|
|
*/
|
|
public function getTextPart(int $index = 0) : ?IMessagePart;
|
|
|
|
/**
|
|
* Returns the number of inline text/plain parts this message contains.
|
|
*
|
|
* @see IMessage::getTextPart() to get the text part(s).
|
|
* @see IMessage::getHtmlPart() to get the HTML part(s).
|
|
* @see IMessage::getHtmlPartCount() to get a count of html parts.
|
|
*/
|
|
public function getTextPartCount() : int;
|
|
|
|
/**
|
|
* Returns the inline text/html IMessagePart for a message.
|
|
*
|
|
* If the message contains more than one text/html 'inline' part, the
|
|
* default behavior is to return the first part. Additional parts can be
|
|
* returned by passing a 0-based index.
|
|
*
|
|
* If there are no inline text/html parts in this message, null is
|
|
* returned.
|
|
*
|
|
* @see IMessage::getHtmlStream() to get the html content stream directly.
|
|
* @see IMessage::getHtmlStream() to get the html content in a string.
|
|
* @see IMessage::getTextPart() to get the text part(s).
|
|
* @see IMessage::getTextPartCount() to get a count of text parts.
|
|
* @see IMessage::getHtmlPartCount() to get a count of html parts.
|
|
* @param int $index Optional index of part to return.
|
|
*/
|
|
public function getHtmlPart(int $index = 0) : ?IMessagePart;
|
|
|
|
/**
|
|
* Returns the number of inline text/html parts this message contains.
|
|
*
|
|
* @see IMessage::getTextPart() to get the text part(s).
|
|
* @see IMessage::getTextPartCount() to get a count of text parts.
|
|
* @see IMessage::getHtmlPart() to get the HTML part(s).
|
|
*/
|
|
public function getHtmlPartCount() : int;
|
|
|
|
/**
|
|
* Returns a Psr7 Stream for the 'inline' text/plain content.
|
|
*
|
|
* If the message contains more than one text/plain 'inline' part, the
|
|
* default behavior is to return the first part. The streams for additional
|
|
* parts can be returned by passing a 0-based index.
|
|
*
|
|
* If a part at the passed index doesn't exist, null is returned.
|
|
*
|
|
* @see IMessage::getTextPart() to get the text part(s).
|
|
* @see IMessage::getTextContent() to get the text content in a string.
|
|
* @param int $index Optional 0-based index of inline text part stream.
|
|
* @param string $charset Optional charset to encode the stream with.
|
|
*/
|
|
public function getTextStream(int $index = 0, string $charset = MailMimeParser::DEFAULT_CHARSET) : ?StreamInterface;
|
|
|
|
/**
|
|
* Returns the content of the inline text/plain part as a string.
|
|
*
|
|
* If the message contains more than one text/plain 'inline' part, the
|
|
* default behavior is to return the first part. The content for additional
|
|
* parts can be returned by passing a 0-based index.
|
|
*
|
|
* If a part at the passed index doesn't exist, null is returned.
|
|
*
|
|
* @see IMessage::getTextPart() to get the text part(s).
|
|
* @see IMessage::getTextStream() to get the text content stream directly.
|
|
* @param int $index Optional 0-based index of inline text part content.
|
|
* @param string $charset Optional charset for the returned string to be
|
|
* encoded in.
|
|
*/
|
|
public function getTextContent(int $index = 0, string $charset = MailMimeParser::DEFAULT_CHARSET) : ?string;
|
|
|
|
/**
|
|
* Returns a Psr7 Stream for the 'inline' text/html content.
|
|
*
|
|
* If the message contains more than one text/html 'inline' part, the
|
|
* default behavior is to return the first part. The streams for additional
|
|
* parts can be returned by passing a 0-based index.
|
|
*
|
|
* If a part at the passed index doesn't exist, null is returned.
|
|
*
|
|
* @see IMessage::getHtmlPart() to get the html part(s).
|
|
* @see IMessage::getHtmlContent() to get the html content in a string.
|
|
* @param int $index Optional 0-based index of inline html part stream.
|
|
* @param string $charset Optional charset to encode the stream with.
|
|
*/
|
|
public function getHtmlStream(int $index = 0, string $charset = MailMimeParser::DEFAULT_CHARSET) : ?StreamInterface;
|
|
|
|
/**
|
|
* Returns the content of the inline text/html part as a string.
|
|
*
|
|
* If the message contains more than one text/html 'inline' part, the
|
|
* default behavior is to return the first part. The content for additional
|
|
* parts can be returned by passing a 0-based index.
|
|
*
|
|
* If a part at the passed index doesn't exist, null is returned.
|
|
*
|
|
* @see IMessage::getHtmlPart() to get the html part(s).
|
|
* @see IMessage::getHtmlStream() to get the html content stream directly.
|
|
* @param int $index Optional 0-based index of inline html part content.
|
|
* @param string $charset Optional charset for the returned string to be
|
|
* encoded in.
|
|
*/
|
|
public function getHtmlContent(int $index = 0, string $charset = MailMimeParser::DEFAULT_CHARSET) : ?string;
|
|
|
|
/**
|
|
* Sets the text/plain part of the message to the passed $resource, either
|
|
* creating a new part if one doesn't exist for text/plain, or assigning the
|
|
* value of $resource to an existing text/plain part.
|
|
*
|
|
* The optional $contentTypeCharset parameter is the charset for the
|
|
* text/plain part's Content-Type, not the charset of the passed $resource.
|
|
* $resource must be encoded in UTF-8 regardless of the target charset.
|
|
*
|
|
* @see IMessage::setHtmlPart() to set the html part
|
|
* @see IMessage::removeTextPart() to remove a text part
|
|
* @see IMessage::removeAllTextParts() to remove all text parts
|
|
* @param string|resource|\Psr\Http\Message\StreamInterface $resource UTF-8
|
|
* encoded content.
|
|
* @param string $contentTypeCharset the charset to use as the text/plain
|
|
* part's content-type header charset value.
|
|
*/
|
|
public function setTextPart(mixed $resource, string $contentTypeCharset = 'UTF-8') : static;
|
|
|
|
/**
|
|
* Sets the text/html part of the message to the passed $resource, either
|
|
* creating a new part if one doesn't exist for text/html, or assigning the
|
|
* value of $resource to an existing text/html part.
|
|
*
|
|
* The optional $contentTypeCharset parameter is the charset for the
|
|
* text/html part's Content-Type, not the charset of the passed $resource.
|
|
* $resource must be encoded in UTF-8 regardless of the target charset.
|
|
*
|
|
* @see IMessage::setTextPart() to set the text part
|
|
* @see IMessage::removeHtmlPart() to remove an html part
|
|
* @see IMessage::removeAllHtmlParts() to remove all html parts
|
|
* @param string|resource|\Psr\Http\Message\StreamInterface $resource UTF-8
|
|
* encoded content.
|
|
* @param string $contentTypeCharset the charset to use as the text/html
|
|
* part's content-type header charset value.
|
|
*/
|
|
public function setHtmlPart(mixed $resource, string $contentTypeCharset = 'UTF-8') : static;
|
|
|
|
/**
|
|
* Removes the text/plain part of the message at the passed index if one
|
|
* exists (defaults to first part if an index isn't passed).
|
|
*
|
|
* Returns true if a part exists at the passed index and has been removed.
|
|
*
|
|
* @see IMessage::setTextPart() to set the text part
|
|
* @see IMessage::removeHtmlPart() to remove an html part
|
|
* @see IMessage::removeAllTextParts() to remove all text parts
|
|
* @param int $index Optional 0-based index of inline text part to remove.
|
|
* @return bool true on success
|
|
*/
|
|
public function removeTextPart(int $index = 0) : bool;
|
|
|
|
/**
|
|
* Removes all text/plain inline parts in this message.
|
|
*
|
|
* If the message contains a multipart/alternative part, the text parts are
|
|
* removed from below the alternative part only. If there is only one
|
|
* remaining part after that, it is moved up, replacing the
|
|
* multipart/alternative part.
|
|
*
|
|
* If the multipart/alternative part further contains a multipart/related
|
|
* (or mixed) part which holds an inline text part, only parts from that
|
|
* child multipart are removed, and if the passed
|
|
* $moveRelatedPartsBelowMessage is true, any non-text parts are moved to be
|
|
* below the message directly (changing the message into a multipart/mixed
|
|
* message if need be).
|
|
*
|
|
* For more control, call
|
|
* {@see \ZBateson\MailMimeParser\Message\IMessagePart::removePart()} with
|
|
* parts you wish to remove.
|
|
*
|
|
* @see IMessage::setTextPart() to set the text part
|
|
* @see IMessage::removeTextPart() to remove a text part
|
|
* @see IMessage::removeAllHtmlParts() to remove all html parts
|
|
* @param bool $moveRelatedPartsBelowMessage Optionally pass false to remove
|
|
* related parts.
|
|
* @return bool true on success
|
|
*/
|
|
public function removeAllTextParts(bool $moveRelatedPartsBelowMessage = true) : bool;
|
|
|
|
/**
|
|
* Removes the text/html part of the message at the passed index if one
|
|
* exists (defaults to first part if an index isn't passed).
|
|
*
|
|
* Returns true if a part exists at the passed index and has been removed.
|
|
*
|
|
* @see IMessage::setHtmlPart() to set the html part
|
|
* @see IMessage::removeTextPart() to remove a text part
|
|
* @see IMessage::removeAllHtmlParts() to remove all html parts
|
|
* @param int $index Optional 0-based index of inline html part to remove.
|
|
* @return bool true on success
|
|
*/
|
|
public function removeHtmlPart(int $index = 0) : bool;
|
|
|
|
/**
|
|
* Removes all text/html inline parts in this message.
|
|
*
|
|
* If the message contains a multipart/alternative part, the html parts are
|
|
* removed from below the alternative part only. If there is only one
|
|
* remaining part after that, it is moved up, replacing the
|
|
* multipart/alternative part.
|
|
*
|
|
* If the multipart/alternative part further contains a multipart/related
|
|
* (or mixed) part which holds an inline html part, only parts from that
|
|
* child multipart are removed, and if the passed
|
|
* $moveRelatedPartsBelowMessage is true, any non-html parts are moved to be
|
|
* below the message directly (changing the message into a multipart/mixed
|
|
* message if need be).
|
|
*
|
|
* For more control, call
|
|
* {@see \ZBateson\MailMimeParser\Message\IMessagePart::removePart()} with
|
|
* parts you wish to remove.
|
|
*
|
|
* @see IMessage::setHtmlPart() to set the html part
|
|
* @see IMessage::removeHtmlPart() to remove an html part
|
|
* @see IMessage::removeAllTextParts() to remove all html parts
|
|
* @param bool $moveRelatedPartsBelowMessage Optionally pass false to remove
|
|
* related parts.
|
|
* @return bool true on success
|
|
*/
|
|
public function removeAllHtmlParts(bool $moveRelatedPartsBelowMessage = true) : bool;
|
|
|
|
/**
|
|
* Returns the attachment part at the given 0-based index, or null if none
|
|
* is set.
|
|
*
|
|
* The method returns all parts other than the main content part for a
|
|
* non-mime message, and all parts under a mime message except:
|
|
* - text/plain and text/html parts with a Content-Disposition not set to
|
|
* 'attachment'
|
|
* - all multipart/* parts
|
|
* - any signature part
|
|
*
|
|
* @see IMessage::getAllAttachmentParts() to get an array of all parts.
|
|
* @see IMessage::getAttachmentCount() to get the number of attachments.
|
|
* @param int $index the 0-based index of the attachment part to return.
|
|
*/
|
|
public function getAttachmentPart(int $index) : ?IMessagePart;
|
|
|
|
/**
|
|
* Returns all attachment parts.
|
|
*
|
|
* The method returns all parts other than the main content part for a
|
|
* non-mime message, and all parts under a mime message except:
|
|
* - text/plain and text/html parts with a Content-Disposition not set to
|
|
* 'attachment'
|
|
* - all multipart/* parts
|
|
* - any signature part
|
|
*
|
|
* @see IMessage::getAttachmentPart() to get a single attachment.
|
|
* @see IMessage::getAttachmentCount() to get the number of attachments.
|
|
* @return IMessagePart[]
|
|
*/
|
|
public function getAllAttachmentParts() : array;
|
|
|
|
/**
|
|
* Returns the number of attachments available.
|
|
*
|
|
* @see IMessage::getAttachmentPart() to get a single attachment.
|
|
* @see IMessage::getAllAttachmentParts() to get an array of all parts.
|
|
*/
|
|
public function getAttachmentCount() : int;
|
|
|
|
/**
|
|
* Adds an attachment part for the passed raw data string, handle, or stream
|
|
* and given parameters.
|
|
*
|
|
* Note that $disposition must be one of 'inline' or 'attachment', and will
|
|
* default to 'attachment' if a different value is passed.
|
|
*
|
|
* @param string|resource|\Psr\Http\Message\StreamInterface $resource the
|
|
* part's content
|
|
* @param string $mimeType the mime-type of the attachment
|
|
* @param string $filename Optional filename (to set relevant header params)
|
|
* @param string $disposition Optional Content-Disposition value.
|
|
* @param string $encoding defaults to 'base64', only applied for a mime
|
|
* email
|
|
*/
|
|
public function addAttachmentPart(mixed $resource, string $mimeType, ?string $filename = null, string $disposition = 'attachment', string $encoding = 'base64') : static;
|
|
|
|
/**
|
|
* Adds an attachment part using the passed file.
|
|
*
|
|
* Essentially creates a psr7 stream and calls
|
|
* {@see IMessage::addAttachmentPart}.
|
|
*
|
|
* Note that $disposition must be one of 'inline' or 'attachment', and will
|
|
* default to 'attachment' if a different value is passed.
|
|
*
|
|
* @param string $filePath file to attach
|
|
* @param string $mimeType the mime-type of the attachment
|
|
* @param string $filename Optional filename (to set relevant header params)
|
|
* @param string $disposition Optional Content-Disposition value.
|
|
* @param string $encoding defaults to 'base64', only applied for a mime
|
|
* email
|
|
*/
|
|
public function addAttachmentPartFromFile(string $filePath, string $mimeType, ?string $filename = null, string $disposition = 'attachment', string $encoding = 'base64') : static;
|
|
|
|
/**
|
|
* Removes the attachment at the given index.
|
|
*
|
|
* Attachments are considered to be all parts other than the main content
|
|
* part for a non-mime message, and all parts under a mime message except:
|
|
* - text/plain and text/html parts with a Content-Disposition not set to
|
|
* 'attachment'
|
|
* - all multipart/* parts
|
|
* - any signature part
|
|
*/
|
|
public function removeAttachmentPart(int $index) : static;
|
|
|
|
/**
|
|
* Returns a stream that can be used to read the content part of a signed
|
|
* message, which can be used to sign an email or verify a signature.
|
|
*
|
|
* The method simply returns the stream for the first child. No
|
|
* verification of whether the message is in fact a signed message is
|
|
* performed.
|
|
*
|
|
* Note that unlike getSignedMessageAsString, getSignedMessageStream doesn't
|
|
* replace new lines, and before calculating a signature, LFs not preceded
|
|
* by CR should be replaced with CRLFs.
|
|
*
|
|
* @see IMessage::getSignedMessageAsString to get a string with CRLFs
|
|
* normalized
|
|
* @return ?StreamInterface null if the message doesn't have any children
|
|
*/
|
|
public function getSignedMessageStream() : ?StreamInterface;
|
|
|
|
/**
|
|
* Returns a string containing the entire body of a signed message for
|
|
* verification or calculating a signature.
|
|
*
|
|
* Non-CRLF new lines are replaced to always be CRLF.
|
|
*
|
|
* @see IMessage::setAsMultipartSigned to make the message a
|
|
* multipart/signed message.
|
|
* @return ?string null if the message doesn't have any children
|
|
*/
|
|
public function getSignedMessageAsString() : ?string;
|
|
|
|
/**
|
|
* Returns the signature part of a multipart/signed message or null.
|
|
*
|
|
* The signature part is determined to always be the 2nd child of a
|
|
* multipart/signed message, the first being the 'body'.
|
|
*
|
|
* Using the 'protocol' parameter of the Content-Type header is unreliable
|
|
* in some instances (for instance a difference of x-pgp-signature versus
|
|
* pgp-signature).
|
|
*/
|
|
public function getSignaturePart() : ?IMessagePart;
|
|
|
|
/**
|
|
* Turns the message into a multipart/signed message, moving the actual
|
|
* message into a child part, sets the content-type of the main message to
|
|
* multipart/signed and adds an empty signature part as well.
|
|
*
|
|
* After calling setAsMultipartSigned, call getSignedMessageAsString to
|
|
* get the normalized string content to be used for calculated the message's
|
|
* hash.
|
|
*
|
|
* @see IMessage::getSignedMessageAsString
|
|
* @param string $micalg The Message Integrity Check algorithm being used
|
|
* @param string $protocol The mime-type of the signature body
|
|
*/
|
|
public function setAsMultipartSigned(string $micalg, string $protocol) : static;
|
|
|
|
/**
|
|
* Sets the signature body of the message to the passed $body for a
|
|
* multipart/signed message.
|
|
*
|
|
* @param string $body the message's hash
|
|
*/
|
|
public function setSignature(string $body) : static;
|
|
|
|
/**
|
|
* Returns the value of the 'Message-ID' header, or null if not set.
|
|
*
|
|
* @return string|null the ID.
|
|
*/
|
|
public function getMessageId() : ?string;
|
|
}
|