MailMimeParser 3.0

MessagePart extends ErrorBag
in package
implements IMessagePart

Most basic representation of a single part of an email.

Tags
author

Zaahid Bateson

Interfaces, Classes, Traits and Enums

IMessagePart
An interface representing a single part of an email.

Table of Contents

$charsetOverride  : string|null
$ignoreTransferEncoding  : bool
$logger  : LoggerInterface
$observers  : SplObjectStorage
$parent  : IMimePart|null
$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.
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).
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.
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.
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.
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
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'.

Properties

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

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

Methods

__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

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>

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

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

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

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

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

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

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

Search results