Represents a single part of a multi-part mime message.

A MimePart object may have any number of child parts, or may be a child itself with its own parent or parents.

The content of the part can be read from its PartStream resource handle, accessible via MessagePart::getContentResourceHandle.

author Zaahid Bateson
package MailMimeParser
inherited_from \ZBateson\MailMimeParser\Message\Part\ParentHeaderPart

 Methods

Constructor

__construct(\ZBateson\MailMimeParser\Message\Part\PartStreamFilterManager $partStreamFilterManager, \ZBateson\MailMimeParser\Stream\StreamFactory $streamFactory, \Psr\Http\Message\StreamInterface $stream = null, \Psr\Http\Message\StreamInterface $contentStream = null
Inherited

Parameters

$partStreamFilterManager

\ZBateson\MailMimeParser\Message\Part\PartStreamFilterManager

$streamFactory

\ZBateson\MailMimeParser\Stream\StreamFactory

$stream

\Psr\Http\Message\StreamInterface

$contentStream

\Psr\Http\Message\StreamInterface

Overridden to close streams.

__destruct() 
Inherited

Returns the message/part as a string.

__toString() : string
Inherited

Convenience method for calling getStream()->getContents().

Returns

string

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

addChild(\ZBateson\MailMimeParser\Message\Part\MessagePart $part, integer $position = null
Inherited

If the $position parameter is non-null, adds the part at the passed position index.

Parameters

$part

\ZBateson\MailMimeParser\Message\Part\MessagePart

$position

integer

Adds a header with the given $name and $value.

addRawHeader(string $name, string $value) 
Inherited

Note: If a header with the passed name already exists, a new header is created with the same name. This should only be used when that is intentional - in most cases setRawHeader should be called.

Creates a new \ZBateson\MailMimeParser\Header\AbstractHeader object and registers it as a header.

Parameters

$name

string

$value

string

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.

attachContentStream(\Psr\Http\Message\StreamInterface $stream, string $streamCharset = \ZBateson\MailMimeParser\MailMimeParser::DEFAULT_CHARSET
Inherited

Parameters

$stream

\Psr\Http\Message\StreamInterface

$streamCharset

string

Detaches and closes the content stream.

detachContentStream() 
Inherited

Returns an array of headers in this part.

getAllHeaders() : array<mixed,\ZBateson\MailMimeParser\Header\AbstractHeader>
Inherited

Returns

array<mixed,\ZBateson\MailMimeParser\Header\AbstractHeader>

Returns an array of headers that match the passed name.

getAllHeadersByName(string $name) : array<mixed,\ZBateson\MailMimeParser\Header\AbstractHeader>
Inherited

Parameters

$name

string

Returns

array<mixed,\ZBateson\MailMimeParser\Header\AbstractHeader>

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

getAllParts(\ZBateson\MailMimeParser\Message\PartFilter $filter = null) : array<mixed,\ZBateson\MailMimeParser\Message\Part\MessagePart>
Inherited

The first part returned is always the current MimePart. This is often desirable as it may be a valid MimePart for the provided PartFilter.

Parameters

$filter

\ZBateson\MailMimeParser\Message\PartFilter

an optional filter

Returns

array<mixed,\ZBateson\MailMimeParser\Message\Part\MessagePart>

Returns an array of all parts associated with the passed mime type if any exist or null otherwise.

getAllPartsByMimeType(string $mimeType) : array<mixed,\ZBateson\MailMimeParser\Message\Part\MessagePart>
Inherited

Parameters

$mimeType

string

Returns

array<mixed,\ZBateson\MailMimeParser\Message\Part\MessagePart>or null

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

getBinaryContentResourceHandle() : resource | null
Inherited

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

Returns

resourcenull

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

getBinaryContentStream() : \Psr\Http\Message\StreamInterface
Inherited

This is basically the same as calling \MessagePart::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).

Returns

\Psr\Http\Message\StreamInterface

Returns the upper-cased charset of the Content-Type header's charset parameter if set, ISO-8859-1 if the Content-Type is text/plain or text/html and the charset parameter isn't set, or null otherwise.

getCharset() : string

Returns

string

Returns the charset of the content, or null if not applicable/defined.

getCharset() : string
Inherited

Returns

string

Returns the direct child at the given 0-based index, or null if none is set.

getChild(integer $index, \ZBateson\MailMimeParser\Message\PartFilter $filter = null) : \ZBateson\MailMimeParser\Message\Part\MessagePart
Inherited

Parameters

$index

integer

$filter

\ZBateson\MailMimeParser\Message\PartFilter

Returns

\ZBateson\MailMimeParser\Message\Part\MessagePart

Returns the number of direct children under this part.

getChildCount(\ZBateson\MailMimeParser\Message\PartFilter $filter = null) : integer
Inherited

Parameters

$filter

\ZBateson\MailMimeParser\Message\PartFilter

Returns

integer

Returns all direct child parts.

getChildParts(\ZBateson\MailMimeParser\Message\PartFilter $filter = null) : array<mixed,\ZBateson\MailMimeParser\Message\Part\MessagePart>
Inherited

If a PartFilter is provided, the PartFilter is applied before returning.

Parameters

$filter

\ZBateson\MailMimeParser\Message\PartFilter

Returns

array<mixed,\ZBateson\MailMimeParser\Message\Part\MessagePart>

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

getContent(string $charset = \ZBateson\MailMimeParser\MailMimeParser::DEFAULT_CHARSET) : string
Inherited

The returned string is encoded to the passed $charset character encoding, defaulting to UTF-8.

see

Parameters

$charset

string

Returns

string

Returns the content's disposition, defaulting to 'inline' if not set.

getContentDisposition(string $default = 'inline') : string

Parameters

$default

string

pass to override the default returned disposition when not set.

Returns

string

Returns the content's disposition.

getContentDisposition() : string
Inherited

Returns

string

Returns the Content ID of the part.

getContentId() : string | null

In MimePart, this is merely a shortcut to calling $part->getHeaderValue('Content-ID');.

Returns

stringnull

Returns the Content ID of the part, or null if not defined.

getContentId() : string | null
Inherited

Returns

stringnull

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

getContentResourceHandle(string $charset = \ZBateson\MailMimeParser\MailMimeParser::DEFAULT_CHARSET) : resource | null
Inherited

The method wraps a call to \MessagePart::getContentStream() and returns a resource handle for the returned Stream.

Parameters

$charset

string

Returns

resourcenull

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

getContentStream(string $charset = \ZBateson\MailMimeParser\MailMimeParser::DEFAULT_CHARSET) : \Psr\Http\Message\StreamInterface
Inherited

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

Note that the returned Stream is a shared object. If called multiple time with the same $charset, and the value of the part's Content-Transfer-Encoding header not having 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

Returns

\Psr\Http\Message\StreamInterface

Returns the content-transfer-encoding used for this part, defaulting to '7bit' if not set.

getContentTransferEncoding(string $default = '7bit') : string

Parameters

$default

string

pass to override the default when not set.

Returns

string

Returns the content-transfer-encoding used for this part.

getContentTransferEncoding() : string
Inherited

Returns

string

Returns the lower-cased, trimmed value of the Content-Type header.

getContentType(string $default = 'text/plain') : string

Parses the Content-Type header, defaults to returning text/plain if not defined.

Parameters

$default

string

pass to override the returned value when not set

Returns

string

Returns the mime type of the content.

getContentType() : string
Inherited

Returns

string

Returns the number of parts matching the passed $mimeType

getCountOfPartsByMimeType(string $mimeType) : integer
Inherited

Parameters

$mimeType

string

Returns

integer

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

getFilename() : string

Returns

string

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

getFilename() : string
Inherited

Returns

string

Returns the AbstractHeader object for the header with the given $name.

getHeader(string $name, integer $offset = 0) : \ZBateson\MailMimeParser\Header\AbstractHeader
Inherited

If the optional $offset is passed, and multiple headers exist with the same name, the one at the passed offset is returned.

Note that mime headers aren't case sensitive.

Parameters

$name

string

$offset

integer

Returns

\ZBateson\MailMimeParser\Header\AbstractHeader\ZBateson\MailMimeParser\Header\AddressHeader| \ZBateson\MailMimeParser\Header\DateHeader| \ZBateson\MailMimeParser\Header\GenericHeader| \ZBateson\MailMimeParser\Header\IdHeader| \ZBateson\MailMimeParser\Header\ParameterHeader| \ZBateson\MailMimeParser\Header\ReceivedHeader| \ZBateson\MailMimeParser\Header\SubjectHeader

Returns a parameter of the header $header, given the parameter named $param.

getHeaderParameter(string $header, string $param, string $defaultValue = null) : string
Inherited

Only headers of type \ZBateson\MailMimeParser\Header\ParameterHeader have parameters. Content-Type and Content-Disposition are examples of headers with parameters. "Charset" is a common parameter of Content-Type.

Parameters

$header

string

$param

string

$defaultValue

string

Returns

string

Returns the string value for the header with the given $name.

getHeaderValue(string $name, string $defaultValue = null) : string
Inherited

Note that mime headers aren't case sensitive.

Parameters

$name

string

$defaultValue

string

Returns

string

Returns this part's parent.

getParent() : \ZBateson\MailMimeParser\Message\Part\MimePart
Inherited

Returns

\ZBateson\MailMimeParser\Message\Part\MimePart

Returns the part at the given 0-based index, or null if none is set.

getPart(integer $index, \ZBateson\MailMimeParser\Message\PartFilter $filter = null) : \ZBateson\MailMimeParser\Message\Part\MessagePart
Inherited

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

Parameters

$index

integer

$filter

\ZBateson\MailMimeParser\Message\PartFilter

Returns

\ZBateson\MailMimeParser\Message\Part\MessagePart

Convenience method to find a part by its Content-ID header.

getPartByContentId(string $contentId) : \ZBateson\MailMimeParser\Message\Part\MessagePart

Parameters

$contentId

string

Returns

\ZBateson\MailMimeParser\Message\Part\MessagePart

Returns the part associated with the passed mime type, at the passed index, if it exists.

getPartByMimeType(string $mimeType, integer $index = 0) : \ZBateson\MailMimeParser\Message\Part\MessagePart | null
Inherited

Parameters

$mimeType

string

$index

integer

Returns

\ZBateson\MailMimeParser\Message\Part\MessagePartnull

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

getPartCount(\ZBateson\MailMimeParser\Message\PartFilter $filter = null) : integer
Inherited

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

Parameters

$filter

\ZBateson\MailMimeParser\Message\PartFilter

Returns

integer

Returns an iterator to the headers in this collection. Each returned element is an array with its first element set to the header's name, and the second to its raw value:

getRawHeaderIterator() : \Iterator
Inherited

[ 'Header-Name', 'Header Value' ]

Returns

\Iterator

Returns an array of all headers for the mime part with the first element holding the name, and the second its value.

getRawHeaders() : array<mixed,string[]>
Inherited

Returns

array<mixed,string[]>

Returns a resource handle containing this part, including any headers for a MimePart, its content, and all its children.

getResourceHandle() : resource
Inherited

Returns

resourcethe resource handle

Returns a Psr7 StreamInterface containing this part, including any headers for a MimePart, its content, and all its children.

getStream() : \Psr\Http\Message\StreamInterface
Inherited

Returns

\Psr\Http\Message\StreamInterfacethe resource handle

Returns true if there's a content stream associated with the part.

hasContent() : boolean
Inherited

Returns

boolean

Returns true.

isMime() : boolean

Returns

boolean

Returns true if the current part is a mime part.

isMime() : boolean
Inherited

Returns

boolean

Returns true if this part's mime type is multipart/*

isMultiPart() : boolean

Returns

boolean

Returns true if this part's mime type is text/plain, text/html or if the Content-Type header defines a charset.

isTextPart() : boolean

Returns

boolean

Returns true if this part's mime type is text/plain, text/html or has a text/* and has a defined 'charset' attribute.

isTextPart() : boolean
Inherited

Returns

boolean

Marks the part as changed, forcing the part to be rewritten when saved.

markAsChanged() 
Inherited

Normal operations to a MessagePart automatically mark the part as changed and markAsChanged() doesn't need to be called in those cases.

The function can be called to indicate an external change that requires rewriting this part, for instance changing a message from a non-mime message to a mime one, would require rewriting non-mime children to insure suitable headers are written.

Internally, the function discards the part's stream, forcing a stream to be created when calling getStream().

Removes all parts that are matched by the passed PartFilter.

removeAllParts(\ZBateson\MailMimeParser\Message\PartFilter $filter = null
Inherited

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

$filter

\ZBateson\MailMimeParser\Message\PartFilter

Removes all headers from this part with the passed name.

removeHeader(string $name) 
Inherited

Parameters

$name

string

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

removePart(\ZBateson\MailMimeParser\Message\Part\MessagePart $part) : integer
Inherited

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).

Parameters

$part

\ZBateson\MailMimeParser\Message\Part\MessagePart

Returns

integeror null if not found

Removes a single header with the passed name (in cases where more than one may exist, and others should be preserved).

removeSingleHeader(string $name, $offset = 0
Inherited

Parameters

$name

string

$offset

Saves the message/part to the passed file, resource, or stream.

save(string|resource|\Psr\Http\Message\StreamInterface $filenameResourceOrStream) 
Inherited

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

stringresource\Psr\Http\Message\StreamInterface

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

saveContent(string|resource|\ZBateson\MailMimeParser\Message\Part\Stream $filenameResourceOrStream) 
Inherited

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). {@see MessagePart::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

stringresource\ZBateson\MailMimeParser\Message\Part\Stream

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.

setCharsetOverride(string $charsetOverride, boolean $onlyIfNoCharset = false
Inherited

If set, the returned value from MessagePart::getCharset is ignored.

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

Parameters

$charsetOverride

string

$onlyIfNoCharset

boolean

if true, $charsetOverride is used only if getCharset returns null.

Sets the content of the part to the passed resource.

setContent(string|resource|\Psr\Http\Message\StreamInterface $resource, string $charset = \ZBateson\MailMimeParser\MailMimeParser::DEFAULT_CHARSET
Inherited

Parameters

$resource

stringresource\Psr\Http\Message\StreamInterface

$charset

string

Adds a header with the given $name and $value. An optional $offset may be passed, which will overwrite a header if one exists with the given name and offset. Otherwise a new header is added. The passed $offset may be ignored in that case if it doesn't represent the next insert position for the header with the passed name.

setRawHeader(string $name, string $value, integer $offset = 0
Inherited

.. instead it would be 'pushed' on at the next position.

$part = $myParentHeaderPart;
$part->setRawHeader('New-Header', 'value');
echo $part->getHeaderValue('New-Header');        // 'value'

$part->setRawHeader('New-Header', 'second', 4);
echo is_null($part->getHeader('New-Header', 4)); // '1' (true)
echo $part->getHeader('New-Header', 1)
     ->getValue();                               // 'second'

A new \ZBateson\MailMimeParser\Header\AbstractHeader object is created from the passed value. No processing on the passed string is performed, and so the passed name and value must be formatted correctly according to related RFCs. In particular, be careful to encode non-ascii data, to keep lines under 998 characters in length, and to follow any special formatting required for the type of header.

Parameters

$name

string

$value

string

$offset

integer

Returns all parts, including the current object, and all children below it (including children of children, etc.

getAllNonFilteredParts() : array<mixed,\ZBateson\MailMimeParser\Message\Part\MessagePart>
Inherited

..)

Returns

array<mixed,\ZBateson\MailMimeParser\Message\Part\MessagePart>

Called when operations change the content of the MessagePart.

onChange() 
Inherited

The function causes calls to getStream() to return a dynamic MessagePartStream instead of the read stream for this MessagePart and all parent MessageParts.

 Properties

 

can be used to set an override for content's charset in cases where a user wants to set a default other than ISO-8859-1.

$charsetOverride : string

Default

 

array of child parts

$children : array<mixed,\ZBateson\MailMimeParser\Message\Part\MessagePart>

Default

array()
 

a Psr7 stream containing this part's content

$contentStream : \Psr\Http\Message\StreamInterface

Default

 

Contains headers for this part.

$headerContainer : \ZBateson\MailMimeParser\Header\HeaderContainer

Default

 

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.

$ignoreTransferEncoding : boolean

Default

 

parent part

$parent : \ZBateson\MailMimeParser\Message\Part\ParentPart

Default

 

factory object responsible for create PartFilters

$partFilterFactory : \ZBateson\MailMimeParser\Message\PartFilterFactory

Default

 

manages attached filters to $contentHandle

$partStreamFilterManager : \ZBateson\MailMimeParser\Message\Part\PartStreamFilterManager

Default

 

a Psr7 stream containing this part's headers, content and children

$stream : \Psr\Http\Message\StreamInterface

Default

 

for creating MessagePartStream objects

$streamFactory : \ZBateson\MailMimeParser\Stream\StreamFactory

Default