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.

author Zaahid Bateson
package MailMimeParser

 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

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

Returns the message/part as a string.

__toString() : string

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

Returns

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

Parameters

$stream

\Psr\Http\Message\StreamInterface

$streamCharset

string

Detaches and closes the content stream.

detachContentStream() 

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

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

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 charset of the content, or null if not applicable/defined.

getCharset() : string

Returns

string

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

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.

getContentDisposition() : string

Returns

string

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

getContentId() : string | null

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

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

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.

getContentTransferEncoding() : string

Returns

string

Returns the mime type of the content.

getContentType() : string

Returns

string

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

getFilename() : string

Returns

string

Returns this part's parent.

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

Returns

\ZBateson\MailMimeParser\Message\Part\MimePart

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

getResourceHandle() : resource

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

Returns

\Psr\Http\Message\StreamInterfacethe resource handle

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

hasContent() : boolean

Returns

boolean

Returns true if the current part is a mime part.

isMime() : 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

Returns

boolean

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

markAsChanged() 

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

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

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

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) 

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

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

Parameters

$resource

stringresource\Psr\Http\Message\StreamInterface

$charset

string

Called when operations change the content of the MessagePart.

onChange() 

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

 

a Psr7 stream containing this part's content

$contentStream : \Psr\Http\Message\StreamInterface

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

 

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