glastree_on_gitea

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

@@ -0,0 +1,433 @@
+<?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;
+}