MailMimeParser 3.0

MultiPart extends MessagePart
in package

MailMimeParser

implements IMultiPart

A message part that contains children.

Interfaces, Classes, Traits and Enums

IMultiPart: An interface representing a message part that contains children.

$charsetOverride : string|null
$ignoreTransferEncoding : bool
$logger : LoggerInterface
$observers : SplObjectStorage
$parent : IMimePart|null
$partChildrenContainer : PartChildrenContainer
$partStreamContainer : PartStreamContainer
$errors : array<string|int, mixed>
$validated : bool
__construct() : mixed
__toString() : string: Returns the message/part as a string, containing its headers, content and children.
addChild() : static: Registers the passed part as a child of the current part.
addError() : static: Creates and adds an Error object to this ErrorBag.
attach() : void
attachContentStream() : static: Attaches the stream or resource handle for the part's content. The stream is closed when another stream is attached, or the MimePart is destroyed.
detach() : void
detachContentStream() : static: Detaches the content stream.
getAllErrors() : array<string|int, Error>: Returns any errors on this object, and all IErrorBag children of this object at or above the passed PSR log level from Psr\Log\LogLevel (defaulting to LogLevel::ERROR).
getAllParts() : array<string|int, IMessagePart>: Returns the current part, all child parts, and child parts of all children optionally filtering them with the provided PartFilter.
getAllPartsByMimeType() : array<string|int, IMessagePart>: Returns an array of all parts that have a content type matching the passed mime type.
getBinaryContentResourceHandle() : resource|null: Returns a resource handle for the content's raw data stream, or null if the part doesn't have a content stream.
getBinaryContentStream() : StreamInterface|null: Returns the raw data stream for the current part, if it exists, or null if there's no content associated with the stream.
getChild() : IMessagePart|null: Returns the direct child at the given 0-based index and optional filter, or null if none exist or do not match.
getChildCount() : int: Returns the number of direct children under this part (optionally counting only filtered items if a callable filter is passed).
getChildIterator() : RecursiveIterator<string|int, IMessagePart>: Returns a \RecursiveIterator of child parts.
getChildParts() : array<string|int, IMessagePart>: Returns an array of all direct child parts, optionally filtering them with a passed callable.
getContent() : string|null: Shortcut to reading stream content and assigning it to a string. Returns null if the part doesn't have a content stream.
getContentStream() : StreamInterface|null: Returns the StreamInterface for the part's content or null if the part doesn't have a content section.
getCountOfPartsByMimeType() : int: Returns the number of parts that have content types matching the passed mime type.
getErrorLoggingContextName() : string: Returns the class name. Override to identify objects in logs.
getErrors() : array<string|int, Error>: Returns any local errors this object has at or above the passed PSR log level in Psr\Log\LogLevel (defaulting to LogLevel::ERROR).
getFilename() : string|null: Returns a filename for the part if one is defined, or null otherwise.
getParent() : IMimePart|null: Returns this part's parent.
getPart() : IMessagePart|null: Returns the part at the given 0-based index for this part (part 0) and all parts under it, or null if not found with the passed filter function.
getPartByContentId() : IMessagePart|null: Returns a part that has the given Content ID, or null if not found.
getPartByMimeType() : IMessagePart|null: Returns the part that has a content type matching the passed mime type at the given index, or null if there are no matching parts.
getPartCount() : int: Returns the total number of parts in this and all children.
getResourceHandle() : resource: Returns a resource handle for the string representation of this part, containing its headers, content and children. For an IMessage, this would be the entire RFC822 (or greater) email.
getStream() : StreamInterface: Returns a Psr7 StreamInterface for the string representation of this part, containing its headers, content and children.
hasAnyErrors() : bool: Returns true if there are errors on this object, or any IErrorBag child of this object at or above the passed PSR log level in Psr\Log\LogLevel (defaulting to LogLevel::ERROR). Note that this will stop after finding the first error and return, so may be slightly more performant if an error actually exists over calling getAllErrors if only interested in whether an error exists.
hasContent() : bool: Returns true if the part contains a 'body' (content).
hasErrors() : bool: Returns true if this object has an error in its error bag at or above the passed $minPsrLevel (defaults to ERROR). If $validate is true, additional validation may be performed.
notify() : void
removeAllParts() : int: Removes all parts below the current part. If a callable filter is passed, removes only those matching the passed filter. The number of removed parts is returned.
removePart() : int|null: Removes the child part from this part and returns its previous position or null if it wasn't found.
save() : static: Writes a string representation of this part, including its headers, content and children to the passed file, resource, or stream.
saveContent() : static: Saves the binary content of the stream to the passed file, resource or stream.
setCharsetOverride() : static: Overrides the default character set used for reading content from content streams in cases where a user knows the source charset is not what is specified.
setContent() : static: Sets the content of the part to the passed string, resource, or stream.
getErrorBagChildren() : array<string|int, IErrorBag>: Return any children ErrorBag objects.
validate() : void: Perform any extra validation and call 'addError'.
getAllPartsIterator() : AppendIterator
iteratorFindAt() : IMessagePart|null

$charsetOverride


    protected
        string|null
    $charsetOverride
     = null

can be used to set an override for content's charset in cases where a user knows the charset on the content is not what it claims to be.

$ignoreTransferEncoding


    protected
        bool
    $ignoreTransferEncoding
     = false

set to true when a user attaches a stream manually, it's assumed to already be decoded or to have relevant transfer encoding decorators attached already.

$logger


    protected
        LoggerInterface
    $logger

$observers


    protected
        SplObjectStorage
    $observers

attached observers that need to be notified of modifications to this part.

$parent


    protected
        IMimePart|null
    $parent

parent part

$partChildrenContainer


    protected
        PartChildrenContainer
    $partChildrenContainer

child part container

$partStreamContainer


    protected
        PartStreamContainer
    $partStreamContainer

holds 'stream' and 'content stream'.

$errors


    private
        array<string|int, mixed>
    $errors
     = []

array of Error objects belonging to this object.

$validated


    private
        bool
    $validated
     = false

true once the object has been validated.

__construct()


    public
                    __construct(LoggerInterface $logger, PartStreamContainer $streamContainer, PartChildrenContainer $partChildrenContainer[, IMimePart|null $parent = null ]) : mixed

Parameters

$logger : LoggerInterface
$streamContainer : PartStreamContainer
$partChildrenContainer : PartChildrenContainer
$parent : IMimePart|null = null

Return values

mixed —

__toString()

Returns the message/part as a string, containing its headers, content and children.


    public
                    __toString() : string

Convenience method for calling getContents() on IMessagePart::getStream().

Return values

string —

addChild()

Registers the passed part as a child of the current part.


    public
                    addChild(MessagePart $part[, int|null $position = null ]) : static

If the $position parameter is non-null, adds the part at the passed position index, otherwise adds it as the last child.

Parameters

$part : MessagePart: The part to add.
$position : int|null = null: Optional insertion position 0-based index.

Return values

static —

addError()

Creates and adds an Error object to this ErrorBag.


    public
                    addError(string $message, string $psrLogLevel[, Throwable|null $exception = null ]) : static

Parameters

$message : string
$psrLogLevel : string
$exception : Throwable|null = null

Return values

static —

attach()


    public
                    attach(SplObserver $observer) : void

Parameters

$observer : SplObserver

Return values

void —

attachContentStream()

Attaches the stream or resource handle for the part's content. The stream is closed when another stream is attached, or the MimePart is destroyed.


    public
                    attachContentStream(StreamInterface $stream[, string $streamCharset = MailMimeParser::DEFAULT_CHARSET ]) : static

Parameters

$stream : StreamInterface: the content
$streamCharset : string = MailMimeParser::DEFAULT_CHARSET: the charset of $stream

Return values

static —

detach()


    public
                    detach(SplObserver $observer) : void

Parameters

$observer : SplObserver

Return values

void —

detachContentStream()

Detaches the content stream.


    public
                    detachContentStream() : static

Return values

static —

getAllErrors()

Returns any errors on this object, and all IErrorBag children of this object at or above the passed PSR log level from Psr\Log\LogLevel (defaulting to LogLevel::ERROR).


    public
                    getAllErrors([bool $validate = false ][, string $minPsrLevel = LogLevel::ERROR ]) : array<string|int, Error>

Care should be taken using this if the intention is to only 'preview' a message without parsing it entirely, since this will cause the whole message to be parsed as it traverses children, and could be slow on messages with large attachments, etc...

If $validate is true, additional validation may be performed on children to check for errors.

Parameters

$validate : bool = false
$minPsrLevel : string = LogLevel::ERROR

Return values

array<string|int, Error> —

getAllParts()

Returns the current part, all child parts, and child parts of all children optionally filtering them with the provided PartFilter.


    public
                    getAllParts([callable|null $fnFilter = null ]) : array<string|int, IMessagePart>

Note that the first part returned is the current part itself. This is often desirable for queries with a passed filter, e.g. looking for an IMessagePart with a specific Content-Type that may be satisfied by the current part.

The passed callable must accept an IMessagePart as an argument, and return true if it should be accepted, or false to filter the part out. Some default filters are provided by static functions returning callables in PartFilter.

Parameters

$fnFilter : callable|null = null: Optional function accepting an IMessagePart and returning true if the part should be included.

Return values

array<string|int, IMessagePart> —

An array of matching parts.

getAllPartsByMimeType()

Returns an array of all parts that have a content type matching the passed mime type.


    public
                    getAllPartsByMimeType(string $mimeType) : array<string|int, IMessagePart>

Creates a filter that looks at the return value of IMessagePart::getContentType() for all parts (including the current part), returning an array of matching parts.

Parameters

$mimeType : string: The mime type to find.

Return values

array<string|int, IMessagePart> —

An array of matching parts.

getBinaryContentResourceHandle()

Returns a resource handle for the content's raw data stream, or null if the part doesn't have a content stream.


    public
                    getBinaryContentResourceHandle() : resource|null

The method wraps a call to IMessagePart::getBinaryContentStream() and returns a resource handle for the returned Stream.

Return values

resource|null —

the resource

getBinaryContentStream()

Returns the raw data stream for the current part, if it exists, or null if there's no content associated with the stream.


    public
                    getBinaryContentStream() : StreamInterface|null

This is basically the same as calling IMessagePart::getContentStream(), except no automatic charset conversion is done. Note that for non-text streams, this doesn't have an effect, as charset conversion is not performed in that case, and is useful only when:

The charset defined is not correct, and the conversion produces errors; or
You'd like to read the raw contents without conversion, for instance to save it to file or allow a user to download it as-is (in a download link for example).

Return values

StreamInterface|null —

the stream

getChild()

Returns the direct child at the given 0-based index and optional filter, or null if none exist or do not match.


    public
                    getChild(int $index[, callable|null $fnFilter = null ]) : IMessagePart|null

Parameters

$index : int: 0-based index
$fnFilter : callable|null = null: Optional function accepting an IMessagePart and returning true if the part should be included.

Return values

IMessagePart|null —

The matching direct child part or null if not found.

getChildCount()

Returns the number of direct children under this part (optionally counting only filtered items if a callable filter is passed).


    public
                    getChildCount([callable|null $fnFilter = null ]) : int

Parameters

$fnFilter : callable|null = null: Optional function accepting an IMessagePart and returning true if the part should be included.

Return values

int —

The number of children, or number of children matching the the passed filtering callable.

getChildIterator()

Returns a \RecursiveIterator of child parts.


    public
                    getChildIterator() : RecursiveIterator<string|int, IMessagePart>

The https://www.php.net/manual/en/class.recursiveiterator.php allows iterating over direct children, or using a https://www.php.net/manual/en/class.recursiveiteratoriterator.php to iterate over direct children, and all their children.

Return values

RecursiveIterator<string|int, IMessagePart> —

getChildParts()

Returns an array of all direct child parts, optionally filtering them with a passed callable.


    public
                    getChildParts([callable|null $fnFilter = null ]) : array<string|int, IMessagePart>

Parameters

$fnFilter : callable|null = null: Optional function accepting an IMessagePart and returning true if the part should be included.

Return values

array<string|int, IMessagePart> —

An array of matching child parts.

getContent()

Shortcut to reading stream content and assigning it to a string. Returns null if the part doesn't have a content stream.


    public
                    getContent([string $charset = MailMimeParser::DEFAULT_CHARSET ]) : string|null

The returned string is encoded to the passed $charset character encoding.

Parameters

$charset : string = MailMimeParser::DEFAULT_CHARSET: the target charset for the returned string

Return values

string|null —

the content

getContentStream()

Returns the StreamInterface for the part's content or null if the part doesn't have a content section.


    public
                    getContentStream([string $charset = MailMimeParser::DEFAULT_CHARSET ]) : StreamInterface|null

To get a stream without charset conversion if you know the part's content contains a binary stream, call self::getBinaryContentStream() instead.

The library automatically handles decoding and charset conversion (to the target passed $charset) based on the part's transfer encoding as returned by IMessagePart::getContentTransferEncoding() and the part's charset as returned by IMessagePart::getCharset(). The returned stream is ready to be read from directly.

Note that the returned Stream is a shared object. If called multiple times with the same $charset, and the value of the part's Content-Transfer-Encoding header has not changed, the stream will be rewound. This would affect other existing variables referencing the stream, for example:

// assuming $part is a part containing the following
// string for its content: '12345678'
$stream = $part->getContentStream();
$someChars = $part->read(4);

$stream2 = $part->getContentStream();
$moreChars = $part->read(4);
echo ($someChars === $moreChars);    //1

In this case the Stream was rewound, and $stream's second call to read 4 bytes reads the same first 4.

Parameters

$charset : string = MailMimeParser::DEFAULT_CHARSET: Optional charset for the returned stream.

Return values

StreamInterface|null —

the stream

getCountOfPartsByMimeType()

Returns the number of parts that have content types matching the passed mime type.


    public
                    getCountOfPartsByMimeType(string $mimeType) : int

Parameters

$mimeType : string: The mime type to find.

Return values

int —

The number of matching parts.

getErrorLoggingContextName()

Returns the class name. Override to identify objects in logs.


    public
                    getErrorLoggingContextName() : string

Return values

string —

getErrors()

Returns any local errors this object has at or above the passed PSR log level in Psr\Log\LogLevel (defaulting to LogLevel::ERROR).


    public
                    getErrors([bool $validate = false ][, string $minPsrLevel = LogLevel::ERROR ]) : array<string|int, Error>

If $validate is true, additional validation may be performed on the object to check for errors.

Parameters

$validate : bool = false
$minPsrLevel : string = LogLevel::ERROR

Return values

array<string|int, Error> —

getFilename()

Returns a filename for the part if one is defined, or null otherwise.


    public
                    getFilename() : string|null

Return values

string|null —

the file name

getParent()

Returns this part's parent.


    public
                    getParent() : IMimePart|null

Return values

IMimePart|null —

getPart()

Returns the part at the given 0-based index for this part (part 0) and all parts under it, or null if not found with the passed filter function.


    public
                    getPart(int $index[, callable|null $fnFilter = null ]) : IMessagePart|null

Note that the first part returned is the current part itself. This is usually desirable for queries with a passed filter, e.g. looking for an part with a specific Content-Type that may be satisfied by the current part.

Parameters

$index : int: The 0-based index (0 being this part if $fnFilter is null or this part is satisfied by the filter).
$fnFilter : callable|null = null: Optional function accepting an IMessagePart and returning true if the part should be included.

Return values

IMessagePart|null —

A matching part, or null if not found.

getPartByContentId()

Returns a part that has the given Content ID, or null if not found.


    public
                    getPartByContentId(string $contentId) : IMessagePart|null

Calls IMessagePart::getContentId() to find a matching part.

Parameters

$contentId : string: The content ID to find a part for.

Return values

IMessagePart|null —

The matching part.

getPartByMimeType()

Returns the part that has a content type matching the passed mime type at the given index, or null if there are no matching parts.


    public
                    getPartByMimeType(string $mimeType, int $index) : IMessagePart|null

Creates a filter that looks at the return value of IMessagePart::getContentType() for all parts (including the current part) and returns a matching one at the given 0-based index.

Parameters

$mimeType : string: The mime type to find.
$index : int: Optional 0-based index (defaulting to '0').

Return values

IMessagePart|null —

The part.

getPartCount()

Returns the total number of parts in this and all children.


    public
                    getPartCount([callable|null $fnFilter = null ]) : int

Note that the current part is considered, so the minimum getPartCount is 1 without a filter.

Parameters

$fnFilter : callable|null = null: Optional function accepting an IMessagePart and returning true if the part should be included.

Return values

int —

The number of matching parts.

getResourceHandle()

Returns a resource handle for the string representation of this part, containing its headers, content and children. For an IMessage, this would be the entire RFC822 (or greater) email.


    public
                    getResourceHandle() : resource

If the part has not been modified and represents a parsed part, the original stream should be returned. Otherwise a stream representation of the part including its modifications should be returned. This insures that an unmodified, signed message could be passed on that way even after parsing and reading.

The returned stream is not guaranteed to be RFC822 (or greater) compliant for the following reasons:

The original email or part, if not modified, is returned as-is and may not be compliant.
Although certain parts may have been modified, an original unmodified header from the original email or part may not be compliant.
A user may set headers in a non-compliant format.

Return values

resource —

the resource handle containing the part.

getStream()

Returns a Psr7 StreamInterface for the string representation of this part, containing its headers, content and children.


    public
                    getStream() : StreamInterface

The returned stream is not guaranteed to be RFC822 (or greater) compliant for the following reasons:

The original email or part, if not modified, is returned as-is and may not be compliant.
Although certain parts may have been modified, an original unmodified header from the original email or part may not be compliant.
A user may set headers in a non-compliant format.

Return values

StreamInterface —

the stream containing the part.

hasAnyErrors()

Returns true if there are errors on this object, or any IErrorBag child of this object at or above the passed PSR log level in Psr\Log\LogLevel (defaulting to LogLevel::ERROR). Note that this will stop after finding the first error and return, so may be slightly more performant if an error actually exists over calling getAllErrors if only interested in whether an error exists.


    public
                    hasAnyErrors([bool $validate = false ][, string $minPsrLevel = LogLevel::ERROR ]) : bool

If $validate is true, additional validation may be performed to check for errors.

Parameters

$validate : bool = false
$minPsrLevel : string = LogLevel::ERROR

Return values

bool —

hasContent()

Returns true if the part contains a 'body' (content).


    public
                    hasContent() : bool

Return values

bool —

hasErrors()

Returns true if this object has an error in its error bag at or above the passed $minPsrLevel (defaults to ERROR). If $validate is true, additional validation may be performed.


    public
                    hasErrors([bool $validate = false ][, string $minPsrLevel = LogLevel::ERROR ]) : bool

The PSR levels are defined in Psr\Log\LogLevel.

Parameters

$validate : bool = false
$minPsrLevel : string = LogLevel::ERROR

Return values

bool —

notify()


    public
                    notify() : void

Return values

void —

removeAllParts()

Removes all parts below the current part. If a callable filter is passed, removes only those matching the passed filter. The number of removed parts is returned.


    public
                    removeAllParts([callable|null $fnFilter = null ]) : int

Note: the current part will not be removed. Although the function naming matches getAllParts, which returns the current part, it also doesn't only remove direct children like getChildParts. Internally this function uses getAllParts but the current part is filtered out if returned.

Parameters

$fnFilter : callable|null = null: Optional function accepting an IMessagePart and returning true if the part should be included.

Return values

int —

The number of removed parts.

removePart()

Removes the child part from this part and returns its previous position or null if it wasn't found.


    public
                    removePart(IMessagePart $part) : int|null

Note that if the part is not a direct child of this part, the returned position is its index within its parent (calls removePart on its direct parent).

This also means that parts from unrelated parts/messages could be removed by a call to removePart -- it will always remove the part from its parent if it has one, essentially calling php $part->getParent()->removePart(); .

Parameters

$part : IMessagePart: The part to remove

Return values

int|null —

The previous index position of the part within its old parent.

save()

Writes a string representation of this part, including its headers, content and children to the passed file, resource, or stream.


    public
                    save(mixed $filenameResourceOrStream[, string $filemode = 'w+' ]) : static

If the part has not been modified and represents a parsed part, the original stream should be written to the file. Otherwise a stream representation of the part including its modifications should be written. This insures that an unmodified, signed message could be passed on this way even after parsing and reading.

The written stream is not guaranteed to be RFC822 (or greater) compliant for the following reasons:

The original email or part, if not modified, is returned as-is and may not be compliant.
Although certain parts may have been modified, an original unmodified header from the original email or part may not be compliant.
A user may set headers in a non-compliant format.

If the passed $filenameResourceOrStream is a string, it's assumed to be a filename to write to.

When passing a resource or Psr7 Stream, the resource is not closed, nor rewound after being written to.

Parameters

$filenameResourceOrStream : mixed: the file, resource, or stream to write to.
$filemode : string = 'w+': Optional filemode to open a file in (if $filenameResourceOrStream is a string)

Return values

static —

saveContent()

Saves the binary content of the stream to the passed file, resource or stream.


    public
                    saveContent(mixed $filenameResourceOrStream) : static

Note that charset conversion is not performed in this case, and the contents of the part are saved in their binary format as transmitted (but after any content-transfer decoding is performed). IMessagePart::getBinaryContentStream() for a more detailed description of the stream.

If the passed parameter is a string, it's assumed to be a filename to write to. The file is opened in 'w+' mode, and closed before returning.

When passing a resource or Psr7 Stream, the resource is not closed, nor rewound.

Parameters

$filenameResourceOrStream : mixed

Return values

static —

setCharsetOverride()

Overrides the default character set used for reading content from content streams in cases where a user knows the source charset is not what is specified.


    public
                    setCharsetOverride(string $charsetOverride[, bool $onlyIfNoCharset = false ]) : static

If set, the returned value from IMessagePart::getCharset() must be ignored during subsequent read operations and streams created out of this part's content.

Note that setting an override on an IMessage and calling getTextStream, getTextContent, getHtmlStream or getHtmlContent will not be applied to those sub-parts, unless the text/html part is the IMessage itself. Instead, IMessage::getTextPart() should be called, and setCharsetOverride called on the returned IMessagePart.

Parameters

$charsetOverride : string: the actual charset of the content.
$onlyIfNoCharset : bool = false: if true, $charsetOverride is used only if getCharset returns null.

Return values

static —

setContent()

Sets the content of the part to the passed string, resource, or stream.


    public
                    setContent(mixed $resource[, string $charset = MailMimeParser::DEFAULT_CHARSET ]) : static

Parameters

$resource : mixed: the content.
$charset : string = MailMimeParser::DEFAULT_CHARSET

Return values

static —

getErrorBagChildren()

Return any children ErrorBag objects.


    protected
                    getErrorBagChildren() : array<string|int, IErrorBag>

Return values

array<string|int, IErrorBag> —

validate()

Perform any extra validation and call 'addError'.


    protected
                    validate() : void

getErrors and getAllErrors call validate() if their $validate parameter is true. validate() is only called once on an object with getErrors getAllErrors.

Return values

void —

getAllPartsIterator()


    private
                    getAllPartsIterator() : AppendIterator

Return values

AppendIterator —

iteratorFindAt()


    private
                    iteratorFindAt(Iterator $iter, int $index[, callable|null $fnFilter = null ]) : IMessagePart|null

Parameters

$iter : Iterator
$index : int
$fnFilter : callable|null = null

Return values

IMessagePart|null —

MultiPart extends MessagePart in package MailMimeParser implements IMultiPart

Tags

Interfaces, Classes, Traits and Enums

Table of Contents

Properties

$charsetOverride

$ignoreTransferEncoding

$logger

$observers

$parent

$partChildrenContainer

$partStreamContainer

$errors

$validated

Methods

__construct()

Parameters

Return values

__toString()

Return values

addChild()

Parameters

Return values

addError()

Parameters

Return values

attach()

Parameters

Return values

attachContentStream()

Parameters

Return values

detach()

Parameters

Return values

detachContentStream()

Return values

getAllErrors()

Parameters

Return values

getAllParts()

Parameters

Return values

getAllPartsByMimeType()

Parameters

Return values

getBinaryContentResourceHandle()

Return values

getBinaryContentStream()

Return values

getChild()

Parameters

Return values

getChildCount()

Parameters

Return values

getChildIterator()

Return values

getChildParts()

Parameters

Return values

getContent()

Parameters

Return values

getContentStream()

Parameters

Return values

getCountOfPartsByMimeType()

Parameters

Return values

getErrorLoggingContextName()

Return values

getErrors()

Parameters

Return values

getFilename()

Return values

getParent()

Return values

getPart()

MultiPart extends MessagePart
in package

MailMimeParser

implements IMultiPart