MailMimeParser 1.3

MessagePart

Represents a single part of a message.

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

Tags
author

Zaahid Bateson

Table of Contents

$charsetOverride  : string
$contentStream  : StreamInterface
$ignoreTransferEncoding  : bool
$parent  : ParentPart
$partStreamFilterManager  : PartStreamFilterManager
$stream  : StreamInterface
$streamFactory  : StreamFactory
__construct()  : mixed
Constructor
__destruct()  : mixed
Overridden to close streams.
__toString()  : string
Returns the message/part as a string.
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.
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.
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.
getFilename()  : string
Returns a filename for the part if one is defined, or null otherwise.
getParent()  : MimePart
Returns this part's parent.
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.
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.
onChange()  : mixed
Called when operations change the content of the MessagePart.

Properties

$contentStream

protected StreamInterface $contentStream

$ignoreTransferEncoding

protected bool $ignoreTransferEncoding

Methods

__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

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

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

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
see
MessagePart::getContentStream()
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
deprecated

since version 1.2.1

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

getFilename()

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

public getFilename() : string
Return values
string

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

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

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.

Return values
mixed

Search results