ParentPart extends MessagePart
A MessagePart that contains children.
Tags
Table of Contents
- $charsetOverride : string
- $children : array<string|int, MessagePart>
- $contentStream : StreamInterface
- $ignoreTransferEncoding : bool
- $parent : ParentPart
- $partFilterFactory : PartFilterFactory
- $partStreamFilterManager : PartStreamFilterManager
- $stream : StreamInterface
- $streamFactory : StreamFactory
- __construct() : mixed
- Constructor
- __destruct() : mixed
- Overridden to close streams.
- __toString() : string
- Returns the message/part as a string.
- addChild() : mixed
- Registers the passed part as a child of the current part.
- attachContentStream() : mixed
- 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.
- detachContentStream() : mixed
- Detaches and closes the content stream.
- getAllParts() : array<string|int, MessagePart>
- Returns the current part, all child parts, and child parts of all children optionally filtering them with the provided PartFilter.
- getAllPartsByMimeType() : array<string|int, MessagePart>
- Returns an array of all parts associated with the passed mime type if any exist or null otherwise.
- 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
- Returns the raw data stream for the current part, if it exists, or null if there's no content associated with the stream.
- getCharset() : string
- Returns the charset of the content, or null if not applicable/defined.
- getChild() : MessagePart
- Returns the direct child at the given 0-based index, or null if none is set.
- getChildCount() : int
- Returns the number of direct children under this part.
- getChildParts() : array<string|int, MessagePart>
- Returns all direct child parts.
- getContent() : string
- Shortcut to reading stream content and assigning it to a string. Returns null if the part doesn't have a content stream.
- getContentDisposition() : string
- Returns the content's disposition.
- getContentId() : string|null
- Returns the Content ID of the part, or null if not defined.
- getContentResourceHandle() : resource|null
- Returns a resource handle for the content's stream, or null if the part doesn't have a content stream.
- getContentStream() : StreamInterface
- Returns the StreamInterface for the part's content or null if the part doesn't have a content section.
- getContentTransferEncoding() : string
- Returns the content-transfer-encoding used for this part.
- getContentType() : string
- Returns the mime type of the content.
- getCountOfPartsByMimeType() : int
- Returns the number of parts matching the passed $mimeType
- getFilename() : string
- Returns a filename for the part if one is defined, or null otherwise.
- getParent() : MimePart
- Returns this part's parent.
- getPart() : MessagePart
- Returns the part at the given 0-based index, or null if none is set.
- getPartByMimeType() : MessagePart|null
- Returns the part associated with the passed mime type, at the passed index, if it exists.
- getPartCount() : int
- Returns the total number of parts in this and all children.
- getResourceHandle() : resource
- Returns a resource handle containing this part, including any headers for a MimePart, its content, and all its children.
- getStream() : StreamInterface
- Returns a Psr7 StreamInterface containing this part, including any headers for a MimePart, its content, and all its children.
- hasContent() : bool
- Returns true if there's a content stream associated with the part.
- isMime() : bool
- Returns true if the current part is a mime part.
- isTextPart() : bool
- Returns true if this part's mime type is text/plain, text/html or has a text/* and has a defined 'charset' attribute.
- markAsChanged() : mixed
- Marks the part as changed, forcing the part to be rewritten when saved.
- removeAllParts() : mixed
- Removes all parts that are matched by the passed PartFilter.
- removePart() : int
- Removes the child part from this part and returns its position or null if it wasn't found.
- save() : mixed
- Saves the message/part to the passed file, resource, or stream.
- saveContent() : mixed
- Saves the binary content of the stream to the passed file, resource or stream.
- setCharsetOverride() : mixed
- 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() : mixed
- Sets the content of the part to the passed resource.
- getAllNonFilteredParts() : array<string|int, MessagePart>
- Returns all parts, including the current object, and all children below it (including children of children, etc...)
- onChange() : mixed
- Called when operations change the content of the MessagePart.
Properties
$charsetOverride
protected
string
$charsetOverride
$children
protected
array<string|int, MessagePart>
$children
= []
$contentStream
protected
StreamInterface
$contentStream
$ignoreTransferEncoding
protected
bool
$ignoreTransferEncoding
$parent
protected
ParentPart
$parent
$partFilterFactory
protected
PartFilterFactory
$partFilterFactory
$partStreamFilterManager
protected
PartStreamFilterManager
$partStreamFilterManager
$stream
protected
StreamInterface
$stream
$streamFactory
protected
StreamFactory
$streamFactory
Methods
__construct()
Constructor
public
__construct(PartStreamFilterManager $partStreamFilterManager, StreamFactory $streamFactory, PartFilterFactory $partFilterFactory, PartBuilder $partBuilder[, StreamInterface $stream = null ][, StreamInterface $contentStream = null ]) : mixed
Parameters
- $partStreamFilterManager : PartStreamFilterManager
- $streamFactory : StreamFactory
- $partFilterFactory : PartFilterFactory
- $partBuilder : PartBuilder
- $stream : StreamInterface = null
- $contentStream : StreamInterface = null
Return values
mixed —__destruct()
Overridden to close streams.
public
__destruct() : mixed
Return values
mixed —__toString()
Returns the message/part as a string.
public
__toString() : string
Convenience method for calling getStream()->getContents().
Return values
string —addChild()
Registers the passed part as a child of the current part.
public
addChild(MessagePart $part[, int $position = null ]) : mixed
If the $position parameter is non-null, adds the part at the passed position index.
Parameters
- $part : MessagePart
- $position : int = null
Return values
mixed —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 ]) : mixed
Parameters
- $stream : StreamInterface
- $streamCharset : string = MailMimeParser::DEFAULT_CHARSET
Return values
mixed —detachContentStream()
Detaches and closes the content stream.
public
detachContentStream() : mixed
Return values
mixed —getAllParts()
Returns the current part, all child parts, and child parts of all children optionally filtering them with the provided PartFilter.
public
getAllParts([PartFilter $filter = null ]) : array<string|int, MessagePart>
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 : PartFilter = null
-
an optional filter
Return values
array<string|int, MessagePart> —getAllPartsByMimeType()
Returns an array of all parts associated with the passed mime type if any exist or null otherwise.
public
getAllPartsByMimeType(string $mimeType) : array<string|int, MessagePart>
Parameters
- $mimeType : string
Return values
array<string|int, MessagePart> —or null
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 MessagePart::getBinaryContentStream() and returns a resource handle for the returned Stream.
Return values
resource|null —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
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).
Return values
StreamInterface —getCharset()
Returns the charset of the content, or null if not applicable/defined.
public
abstract getCharset() : string
Return values
string —getChild()
Returns the direct child at the given 0-based index, or null if none is set.
public
getChild(int $index[, PartFilter $filter = null ]) : MessagePart
Parameters
- $index : int
- $filter : PartFilter = null
Return values
MessagePart —getChildCount()
Returns the number of direct children under this part.
public
getChildCount([PartFilter $filter = null ]) : int
Parameters
- $filter : PartFilter = null
Return values
int —getChildParts()
Returns all direct child parts.
public
getChildParts([PartFilter $filter = null ]) : array<string|int, MessagePart>
If a PartFilter is provided, the PartFilter is applied before returning.
Parameters
- $filter : PartFilter = null
Return values
array<string|int, MessagePart> —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
The returned string is encoded to the passed $charset character encoding, defaulting to UTF-8.
Parameters
- $charset : string = MailMimeParser::DEFAULT_CHARSET
Tags
Return values
string —getContentDisposition()
Returns the content's disposition.
public
abstract getContentDisposition() : string
Return values
string —getContentId()
Returns the Content ID of the part, or null if not defined.
public
abstract getContentId() : string|null
Return values
string|null —getContentResourceHandle()
Returns a resource handle for the content's stream, or null if the part doesn't have a content stream.
public
getContentResourceHandle([string $charset = MailMimeParser::DEFAULT_CHARSET ]) : resource|null
The method wraps a call to MessagePart::getContentStream() and returns a resource handle for the returned Stream.
Note: this method should not be used and has been deprecated. Instead, use Psr7 streams with getContentStream. Multibyte chars will not be read correctly with fread.
Parameters
- $charset : string = MailMimeParser::DEFAULT_CHARSET
Tags
Return values
resource|null —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
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 = MailMimeParser::DEFAULT_CHARSET
Return values
StreamInterface —getContentTransferEncoding()
Returns the content-transfer-encoding used for this part.
public
abstract getContentTransferEncoding() : string
Return values
string —getContentType()
Returns the mime type of the content.
public
abstract getContentType() : string
Return values
string —getCountOfPartsByMimeType()
Returns the number of parts matching the passed $mimeType
public
getCountOfPartsByMimeType(string $mimeType) : int
Parameters
- $mimeType : string
Return values
int —getFilename()
Returns a filename for the part if one is defined, or null otherwise.
public
getFilename() : string
Return values
string —getParent()
Returns this part's parent.
public
getParent() : MimePart
Return values
MimePart —getPart()
Returns the part at the given 0-based index, or null if none is set.
public
getPart(int $index[, PartFilter $filter = null ]) : MessagePart
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 : int
- $filter : PartFilter = null
Return values
MessagePart —getPartByMimeType()
Returns the part associated with the passed mime type, at the passed index, if it exists.
public
getPartByMimeType(string $mimeType, int $index) : MessagePart|null
Parameters
- $mimeType : string
- $index : int
Return values
MessagePart|null —getPartCount()
Returns the total number of parts in this and all children.
public
getPartCount([PartFilter $filter = null ]) : int
Note that the current part is considered, so the minimum getPartCount is 1 without a filter.
Parameters
- $filter : PartFilter = null
Return values
int —getResourceHandle()
Returns a resource handle containing this part, including any headers for a MimePart, its content, and all its children.
public
getResourceHandle() : resource
Return values
resource —the resource handle
getStream()
Returns a Psr7 StreamInterface containing this part, including any headers for a MimePart, its content, and all its children.
public
getStream() : StreamInterface
Return values
StreamInterface —the resource handle
hasContent()
Returns true if there's a content stream associated with the part.
public
hasContent() : bool
Return values
bool —isMime()
Returns true if the current part is a mime part.
public
abstract isMime() : bool
Return values
bool —isTextPart()
Returns true if this part's mime type is text/plain, text/html or has a text/* and has a defined 'charset' attribute.
public
abstract isTextPart() : bool
Return values
bool —markAsChanged()
Marks the part as changed, forcing the part to be rewritten when saved.
public
markAsChanged() : mixed
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().
Return values
mixed —removeAllParts()
Removes all parts that are matched by the passed PartFilter.
public
removeAllParts([PartFilter $filter = null ]) : mixed
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 : PartFilter = null
Return values
mixed —removePart()
Removes the child part from this part and returns its position or null if it wasn't found.
public
removePart(MessagePart $part) : int
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 : MessagePart
Return values
int —or null if not found
save()
Saves the message/part to the passed file, resource, or stream.
public
save(string|resource|StreamInterface $filenameResourceOrStream) : mixed
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 : string|resource|StreamInterface
Return values
mixed —saveContent()
Saves the binary content of the stream to the passed file, resource or stream.
public
saveContent(string|resource|Stream $filenameResourceOrStream) : mixed
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). 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 : string|resource|Stream
Return values
mixed —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 ]) : mixed
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 : bool = false
-
if true, $charsetOverride is used only if getCharset returns null.
Return values
mixed —setContent()
Sets the content of the part to the passed resource.
public
setContent(string|resource|StreamInterface $resource[, string $charset = MailMimeParser::DEFAULT_CHARSET ]) : mixed
Parameters
- $resource : string|resource|StreamInterface
- $charset : string = MailMimeParser::DEFAULT_CHARSET
Return values
mixed —getAllNonFilteredParts()
Returns all parts, including the current object, and all children below it (including children of children, etc...)
protected
getAllNonFilteredParts() : array<string|int, MessagePart>
Return values
array<string|int, MessagePart> —onChange()
Called when operations change the content of the MessagePart.
protected
onChange() : mixed
The function causes calls to getStream() to return a dynamic MessagePartStream instead of the read stream for this MessagePart and all parent MessageParts.