MailMimeParser 3.0

IMessage extends IMimePart
in

An interface representing an email message.

Defines an interface to retrieve content, attachments and other parts of an email message.

Tags
author

Zaahid Bateson

Table of Contents

__toString()  : string
Returns the message/part as a string, containing its headers, content and children.
addAttachmentPart()  : static
Adds an attachment part for the passed raw data string, handle, or stream and given parameters.
addAttachmentPartFromFile()  : static
Adds an attachment part using the passed file.
addChild()  : static
Registers the passed part as a child of the current part.
addError()  : static
Creates and adds an Error object to this ErrorBag.
addRawHeader()  : static
Adds a header with the given $name and $value.
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.
detachContentStream()  : static
Detaches the content stream.
getAllAttachmentParts()  : array<string|int, IMessagePart>
Returns all attachment parts.
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).
getAllHeaders()  : array<string|int, IHeader>
Returns an array of all headers in this part.
getAllHeadersByName()  : array<string|int, IHeader>
Returns an array of headers that match the passed name.
getAllParts()  : array<string|int, IMessagePart>
Returns the current part, all child parts, and child parts of all children optionally filtering them with the provided PartFilter.
getAllPartsByMimeType()  : array<string|int, IMessagePart>
Returns an array of all parts that have a content type matching the passed mime type.
getAttachmentCount()  : int
Returns the number of attachments available.
getAttachmentPart()  : IMessagePart|null
Returns the attachment part at the given 0-based index, or null if none is set.
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.
getCharset()  : string|null
Returns the charset of the content, or null if not applicable/defined.
getChild()  : IMessagePart|null
Returns the direct child at the given 0-based index and optional filter, or null if none exist or do not match.
getChildCount()  : int
Returns the number of direct children under this part (optionally counting only filtered items if a callable filter is passed).
getChildIterator()  : RecursiveIterator<string|int, IMessagePart>
Returns a \RecursiveIterator of child parts.
getChildParts()  : array<string|int, IMessagePart>
Returns an array of all direct child parts, optionally filtering them with a passed callable.
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.
getContentDisposition()  : string|null
Returns the content's disposition, or returns the value of $default if not defined.
getContentId()  : string|null
Returns the Content ID of the part, or null if not defined.
getContentStream()  : StreamInterface|null
Returns the StreamInterface for the part's content or null if the part doesn't have a content section.
getContentTransferEncoding()  : string|null
Returns the content transfer encoding used to encode the content on this part, or the value of $default if not defined.
getContentType()  : string
Returns the mime type of the content, or $default if one is not set.
getCountOfPartsByMimeType()  : int
Returns the number of parts that have content types matching the passed mime type.
getErrorLoggingContextName()  : string
Returns a context name for the current object to help identify it 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.
getHeader()  : IHeader|null
Returns the IHeader object for the header with the given $name.
getHeaderAs()  : IHeader|null
Returns the IHeader object for the header with the given $name, using the passed $iHeaderClass to construct it.
getHeaderParameter()  : string|null
Returns the value of the parameter named $param on a header with the passed $header name, or null if the parameter doesn't exist and a $defaultValue isn't passed.
getHeaderValue()  : string|null
Returns the string value for the header with the given $name, or null if the header doesn't exist and no alternative $defaultValue is passed.
getHtmlContent()  : string|null
Returns the content of the inline text/html part as a string.
getHtmlPart()  : IMessagePart|null
Returns the inline text/html IMessagePart for a message.
getHtmlPartCount()  : int
Returns the number of inline text/html parts this message contains.
getHtmlStream()  : StreamInterface|null
Returns a Psr7 Stream for the 'inline' text/html content.
getMessageId()  : string|null
Returns the value of the 'Message-ID' header, or null if not set.
getParent()  : IMimePart|null
Returns this part's parent.
getPart()  : IMessagePart|null
Returns the part at the given 0-based index for this part (part 0) and all parts under it, or null if not found with the passed filter function.
getPartByContentId()  : IMessagePart|null
Returns a part that has the given Content ID, or null if not found.
getPartByMimeType()  : IMessagePart|null
Returns the part that has a content type matching the passed mime type at the given index, or null if there are no matching parts.
getPartCount()  : int
Returns the total number of parts in this and all children.
getRawHeaderIterator()  : Traversable<string|int, array<string|int, string>>
Returns an iterator to all headers in this part. Each returned element is an array with its first element set to the header's name, and the second to its raw value:
getRawHeaders()  : array<string|int, array<string|int, string>>
Returns a two dimensional string array of all headers for the mime part with the first element holding the name, and the second its raw string value:
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.
getSignaturePart()  : IMessagePart|null
Returns the signature part of a multipart/signed message or null.
getSignedMessageAsString()  : string|null
Returns a string containing the entire body of a signed message for verification or calculating a signature.
getSignedMessageStream()  : StreamInterface|null
Returns a stream that can be used to read the content part of a signed message, which can be used to sign an email or verify a signature.
getStream()  : StreamInterface
Returns a Psr7 StreamInterface for the string representation of this part, containing its headers, content and children.
getSubject()  : string|null
Returns the subject of the message, retrieved from the 'Subject' header, or null if the message has none set.
getTextContent()  : string|null
Returns the content of the inline text/plain part as a string.
getTextPart()  : IMessagePart|null
Returns the inline text/plain IMessagePart for a message.
getTextPartCount()  : int
Returns the number of inline text/plain parts this message contains.
getTextStream()  : StreamInterface|null
Returns a Psr7 Stream for the 'inline' text/plain content.
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.
isMime()  : bool
Returns true if the current part is a mime part.
isMultiPart()  : bool
Returns true if this part's content type matches multipart/*
isSignaturePart()  : bool
Returns true if this part is the 'signature' part of a signed message.
isTextPart()  : bool
Returns true if the content of this part is plain text.
removeAllHtmlParts()  : bool
Removes all text/html inline parts in this message.
removeAllParts()  : int
Removes all parts below the current part. If a callable filter is passed, removes only those matching the passed filter. The number of removed parts is returned.
removeAllTextParts()  : bool
Removes all text/plain inline parts in this message.
removeAttachmentPart()  : static
Removes the attachment at the given index.
removeHeader()  : static
Removes all headers from this part with the passed name.
removeHtmlPart()  : bool
Removes the text/html part of the message at the passed index if one exists (defaults to first part if an index isn't passed).
removePart()  : int|null
Removes the child part from this part and returns its previous position or null if it wasn't found.
removeSingleHeader()  : static
Removes a single header with the passed name (in cases where more than one may exist, and others should be preserved).
removeTextPart()  : bool
Removes the text/plain part of the message at the passed index if one exists (defaults to first part if an index isn't passed).
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.
setAsMultipartSigned()  : static
Turns the message into a multipart/signed message, moving the actual message into a child part, sets the content-type of the main message to multipart/signed and adds an empty signature part as well.
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.
setHtmlPart()  : static
Sets the text/html part of the message to the passed $resource, either creating a new part if one doesn't exist for text/html, or assigning the value of $resource to an existing text/html part.
setRawHeader()  : static
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 only. 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... instead it would be 'pushed' on at the next position.
setSignature()  : static
Sets the signature body of the message to the passed $body for a multipart/signed message.
setTextPart()  : static
Sets the text/plain part of the message to the passed $resource, either creating a new part if one doesn't exist for text/plain, or assigning the value of $resource to an existing text/plain part.

Methods

addAttachmentPart()

Adds an attachment part for the passed raw data string, handle, or stream and given parameters.

public addAttachmentPart(string|resource|StreamInterface $resource, string $mimeType[, string $filename = null ][, string $disposition = 'attachment' ][, string $encoding = 'base64' ]) : static

Note that $disposition must be one of 'inline' or 'attachment', and will default to 'attachment' if a different value is passed.

Parameters
$resource : string|resource|StreamInterface

the part's content

$mimeType : string

the mime-type of the attachment

$filename : string = null

Optional filename (to set relevant header params)

$disposition : string = 'attachment'

Optional Content-Disposition value.

$encoding : string = 'base64'

defaults to 'base64', only applied for a mime email

Return values
static —

addAttachmentPartFromFile()

Adds an attachment part using the passed file.

public addAttachmentPartFromFile(string $filePath, string $mimeType[, string $filename = null ][, string $disposition = 'attachment' ][, string $encoding = 'base64' ]) : static

Essentially creates a psr7 stream and calls IMessage::addAttachmentPart.

Note that $disposition must be one of 'inline' or 'attachment', and will default to 'attachment' if a different value is passed.

Parameters
$filePath : string

file to attach

$mimeType : string

the mime-type of the attachment

$filename : string = null

Optional filename (to set relevant header params)

$disposition : string = 'attachment'

Optional Content-Disposition value.

$encoding : string = 'base64'

defaults to 'base64', only applied for a mime email

Return values
static —

addChild()

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

public addChild(MessagePart $part[, int $position = null ]) : static

If the $position parameter is non-null, adds the part at the passed position index, otherwise adds it as the last child.

Parameters
$part : MessagePart

The part to add.

$position : int = null

Optional insertion position 0-based index.

Return values
static —

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 —

addRawHeader()

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

public addRawHeader(string $name, string $value) : static

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 IMimePart::setRawHeader() should be called instead.

A new IHeader 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

The name of the header

$value : string

The raw value of the header.

Tags
see
IMimePart::setRawHeader()

Sets a header, potentially overwriting one if it already exists.

see
IMimePart::removeHeader()

Removes all headers on this part with the passed name

see
IMimePart::removeSingleHeader()

Removes a single header if more than one with the passed name exists.

Return values
static —

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

Tags
see
IMessagePart::setContent()

to pass a string as the content.

see
IMessagePart::getContentStream()

to get the content stream.

see
IMessagePart::detachContentStream()

to detach the content stream.

Return values
static —

getAllAttachmentParts()

Returns all attachment parts.

public getAllAttachmentParts() : array<string|int, IMessagePart>

The method returns all parts other than the main content part for a non-mime message, and all parts under a mime message except:

  • text/plain and text/html parts with a Content-Disposition not set to 'attachment'
  • all multipart/* parts
  • any signature part
Tags
see
IMessage::getAttachmentPart()

to get a single attachment.

see
IMessage::getAttachmentCount()

to get the number of attachments.

Return values
array<string|int, IMessagePart> —

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

getAllHeaders()

Returns an array of all headers in this part.

public getAllHeaders() : array<string|int, IHeader>
Tags
see
IMimePart::getHeader()

to retrieve a single header object.

see
IMimePart::getHeaderValue()

to get the string value portion of a specific header only.

see
IMimePart::getHeaderParameter()

to get the string value portion of a specific header's parameter only.

see
IMimePart::getAllHeadersByName()

to retrieve an array of all headers with a certain name.

see
IMimePart::getRawHeaders()

to retrieve a two-dimensional string[][] array of raw headers in this part.

see
IMimePart::getRawHeaderIterator()

to retrieve an iterator traversing a two-dimensional string[] array of raw headers.

Return values
array<string|int, IHeader> —

an array of header objects

getAllHeadersByName()

Returns an array of headers that match the passed name.

public getAllHeadersByName(string $name) : array<string|int, IHeader>
Parameters
$name : string
Tags
see
IMimePart::getHeader()

to retrieve a single header object.

see
IMimePart::getHeaderValue()

to get the string value portion of a specific header only.

see
IMimePart::getHeaderParameter()

to get the string value portion of a specific header's parameter only.

see
IMimePart::getAllHeaders()

to retrieve an array of all header objects for this part.

see
IMimePart::getRawHeaders()

to retrieve a two-dimensional string[][] array of raw headers in this part.

see
IMimePart::getRawHeaderIterator()

to retrieve an iterator traversing a two-dimensional string[] array of raw headers.

Return values
array<string|int, IHeader> —

an array of header objects

getAllParts()

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

public getAllParts([callable $fnFilter = null ]) : array<string|int, IMessagePart>

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

The passed callable must accept an IMessagePart as an argument, and return true if it should be accepted, or false to filter the part out. Some default filters are provided by static functions returning callables in PartFilter.

Parameters
$fnFilter : callable = null

Optional function accepting an IMessagePart and returning true if the part should be included.

Tags
see
IMultiPart::getPart()

to find a part at a specific 0-based index with an optional filter.

see
IMultiPart::getPartCount()

to get the number of parts with an optional filter.

see
IMultiPart::getChildParts()

to get an array of all direct children of the current part.

Return values
array<string|int, IMessagePart> —

An array of matching parts.

getAllPartsByMimeType()

Returns an array of all parts that have a content type matching the passed mime type.

public getAllPartsByMimeType(string $mimeType) : array<string|int, IMessagePart>

Creates a filter that looks at the return value of IMessagePart::getContentType() for all parts (including the current part), returning an array of matching parts.

Parameters
$mimeType : string

The mime type to find.

Tags
see
IMultiPart::getPartByMimeType()

to get a part by mime type.

see
IMultiPart::getCountOfPartsByMimeType()

to get a count of parts with a mime type.

Return values
array<string|int, IMessagePart> —

An array of matching parts.

getAttachmentPart()

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

public getAttachmentPart(int $index) : IMessagePart|null

The method returns all parts other than the main content part for a non-mime message, and all parts under a mime message except:

  • text/plain and text/html parts with a Content-Disposition not set to 'attachment'
  • all multipart/* parts
  • any signature part
Parameters
$index : int

the 0-based index of the attachment part to return.

Tags
see
IMessage::getAllAttachmentParts()

to get an array of all parts.

see
IMessage::getAttachmentCount()

to get the number of attachments.

Return values
IMessagePart|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 IMessagePart::getBinaryContentStream() and returns a resource handle for the returned Stream.

Tags
see
IMessagePart::getBinaryContentStream()

to get a stream instead.

see
IMessagePart::saveContent()

to save the binary contents to file.

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).
Tags
see
IMessagePart::getContentStream()

to get the content stream with charset conversions applied.

see
IMessagePart::getBinaryContentResourceHandle()

to get a resource handle instead.

see
IMessagePart::saveContent()

to save the binary contents to file.

Return values
StreamInterface|null —

the stream

getCharset()

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

public getCharset() : string|null
Return values
string|null —

the charset

getChild()

Returns the direct child at the given 0-based index and optional filter, or null if none exist or do not match.

public getChild(int $index[, callable $fnFilter = null ]) : IMessagePart|null

The passed callable must accept an IMessagePart as an argument, and return true if it should be accepted, or false to filter the part out. Some default filters are provided by static functions returning callables in PartFilter.

Parameters
$index : int

0-based index

$fnFilter : callable = null

Optional function accepting an IMessagePart and returning true if the part should be included.

Tags
see
IMultiPart::getChildParts()

to get an array of all direct children of the current part.

see
IMultiPart::getChildCount()

to get a count of direct children of this part.

see
IMultiPart::getChildIterator()

to get an iterator of children of this part.

see
IMultiPart::getPart()

to find a part at a specific 0-based index with an optional filter.

Return values
IMessagePart|null —

The matching direct child part or null if not found.

getChildCount()

Returns the number of direct children under this part (optionally counting only filtered items if a callable filter is passed).

public getChildCount([callable $fnFilter = null ]) : int

The passed callable must accept an IMessagePart as an argument, and return true if it should be accepted, or false to filter the part out. Some default filters are provided by static functions returning callables in PartFilter.

Parameters
$fnFilter : callable = null

Optional function accepting an IMessagePart and returning true if the part should be included.

Tags
see
IMultiPart::getChild()

to get a direct child of the current part.

see
IMultiPart::getChildParts()

to get an array of all direct children of the current part.

see
IMultiPart::getChildIterator()

to get an iterator of children of this part.

see
IMultiPart::getPartCount()

to get the number of parts with an optional filter.

Return values
int —

The number of children, or number of children matching the the passed filtering callable.

getChildIterator()

Returns a \RecursiveIterator of child parts.

public getChildIterator() : RecursiveIterator<string|int, IMessagePart>

The https://www.php.net/manual/en/class.recursiveiterator.php allows iterating over direct children, or using a https://www.php.net/manual/en/class.recursiveiteratoriterator.php to iterate over direct children, and all their children.

Tags
see
https://www.php.net/manual/en/class.recursiveiterator.php

RecursiveIterator

see
https://www.php.net/manual/en/class.recursiveiteratoriterator.php

RecursiveIteratorIterator

see
IMultiPart::getChild()

to get a direct child of the current part.

see
IMultiPart::getChildParts()

to get an array of all direct children of the current part.

see
IMultiPart::getChildCount()

to get a count of direct children of this part.

see
IMultiPart::getAllParts()

to get an array of all parts with an optional filter.

Return values
RecursiveIterator<string|int, IMessagePart> —

getChildParts()

Returns an array of all direct child parts, optionally filtering them with a passed callable.

public getChildParts([callable $fnFilter = null ]) : array<string|int, IMessagePart>

The passed callable must accept an IMessagePart as an argument, and return true if it should be accepted, or false to filter the part out. Some default filters are provided by static functions returning callables in PartFilter.

Parameters
$fnFilter : callable = null

Optional function accepting an IMessagePart and returning true if the part should be included.

Tags
see
IMultiPart::getChild()

to get a direct child of the current part.

see
IMultiPart::getChildCount()

to get a count of direct children of this part.

see
IMultiPart::getChildIterator()

to get an iterator of children of this part.

see
IMultiPart::getAllParts()

to get an array of all parts with an optional filter.

Return values
array<string|int, IMessagePart> —

An array of matching child parts.

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

Tags
see
IMessagePart::getContentStream()
Return values
string|null —

the content

getContentDisposition()

Returns the content's disposition, or returns the value of $default if not defined.

public getContentDisposition([string $default = null ]) : string|null
Parameters
$default : string = null

Optional default value to return if not applicable/defined

Return values
string|null —

the disposition.

getContentId()

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

public getContentId() : string|null
Return values
string|null —

the content ID.

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.

Tags
see
IMessagePart::getBinaryContentStream()

to get the content stream without any charset conversions.

see
IMessagePart::saveContent()

to save the binary contents to file.

see
IMessagePart::setCharsetOverride()

to override the charset of the content and ignore the charset returned from calling IMessagePart::getCharset() when reading.

Return values
StreamInterface|null —

the stream

getContentTransferEncoding()

Returns the content transfer encoding used to encode the content on this part, or the value of $default if not defined.

public getContentTransferEncoding([string|null $default = null ]) : string|null
Parameters
$default : string|null = null

Optional default value to return if not applicable/defined

Return values
string|null —

the transfer encoding defined for the part.

getContentType()

Returns the mime type of the content, or $default if one is not set.

public getContentType([string $default = 'text/plain' ]) : string
Parameters
$default : string = 'text/plain'

Optional override for the default return value of 'text/plain.

Return values
string —

the mime type

getCountOfPartsByMimeType()

Returns the number of parts that have content types matching the passed mime type.

public getCountOfPartsByMimeType(string $mimeType) : int
Parameters
$mimeType : string

The mime type to find.

Tags
see
IMultiPart::getPartByMimeType()

to get a part by mime type.

see
IMultiPart::getAllPartsByMimeType()

to get all parts that match a mime type.

Return values
int —

The number of matching parts.

getErrorLoggingContextName()

Returns a context name for the current object to help identify it 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

getHeader()

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

public getHeader(string $name, int $offset) : IHeader|null

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 header names aren't case sensitive, and the '-' character is ignored, so ret

If a header with the given $name and $offset doesn't exist, null is returned.

Parameters
$name : string

The name of the header to retrieve.

$offset : int

Optional offset if there are multiple headers with the given name.

Tags
see
IMimePart::getHeaderAs()

to parse a header into a provided IHeader type and return it.

see
IMimePart::getHeaderValue()

to get the string value portion of a specific header only.

see
IMimePart::getHeaderParameter()

to get the string value portion of a specific header's parameter only.

see
IMimePart::getAllHeaders()

to retrieve an array of all header objects for this part.

see
IMimePart::getAllHeadersByName()

to retrieve an array of all headers with a certain name.

see
IMimePart::getRawHeaders()

to retrieve a two-dimensional string[][] array of raw headers in this part.

see
IMimePart::getRawHeaderIterator()

to retrieve an iterator traversing a two-dimensional string[] array of raw headers.

Return values
IHeader|null —

the header object if it exists, or null if not

getHeaderAs()

Returns the IHeader object for the header with the given $name, using the passed $iHeaderClass to construct it.

public getHeaderAs(string $name, string $iHeaderClass, int $offset) : IHeader|null

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, and the '-' character is

If a header with the given $name and $offset doesn't exist, null is returned.

Parameters
$name : string

The name of the header to retrieve.

$iHeaderClass : string
$offset : int

Optional offset if there are multiple headers with the given name.

Tags
see
IMimePart::getHeaderValue()

to get the string value portion of a specific header only.

see
IMimePart::getHeaderParameter()

to get the string value portion of a specific header's parameter only.

see
IMimePart::getAllHeaders()

to retrieve an array of all header objects for this part.

see
IMimePart::getAllHeadersByName()

to retrieve an array of all headers with a certain name.

see
IMimePart::getRawHeaders()

to retrieve a two-dimensional string[][] array of raw headers in this part.

see
IMimePart::getRawHeaderIterator()

to retrieve an iterator traversing a two-dimensional string[] array of raw headers.

Return values
IHeader|null —

the header object

getHeaderParameter()

Returns the value of the parameter named $param on a header with the passed $header name, or null if the parameter doesn't exist and a $defaultValue isn't passed.

public getHeaderParameter(string $header, string $param[, string|null $defaultValue = null ]) : string|null

Only headers of type 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

The name of the header.

$param : string

The name of the parameter.

$defaultValue : string|null = null

Optional default value to return if the parameter doesn't exist.

Tags
see
IMimePart::getHeader()

to retrieve a single header object.

see
IMimePart::getHeaderValue()

to get the string value portion of a specific header only.

see
IMimePart::getAllHeaders()

to retrieve an array of all header objects for this part.

see
IMimePart::getAllHeadersByName()

to retrieve an array of all headers with a certain name.

see
IMimePart::getRawHeaders()

to retrieve the array the returned iterator iterates over.

see
IMimePart::getRawHeaderIterator()

to retrieve an iterator instead of the returned two-dimensional array

Return values
string|null —

The value of the parameter.

getHeaderValue()

Returns the string value for the header with the given $name, or null if the header doesn't exist and no alternative $defaultValue is passed.

public getHeaderValue(string $name[, string|null $defaultValue = null ]) : string|null

Note that mime headers aren't case sensitive.

Parameters
$name : string

The name of the header

$defaultValue : string|null = null

Optional default value to return if the header doesn't exist on this part.

Tags
see
IMimePart::getHeader()

to retrieve a single header object.

see
IMimePart::getHeaderParameter()

to get the string value portion of a specific header's parameter only.

see
IMimePart::getAllHeaders()

to retrieve an array of all header objects for this part.

see
IMimePart::getAllHeadersByName()

to retrieve an array of all headers with a certain name.

see
IMimePart::getRawHeaders()

to retrieve the array the returned iterator iterates over.

see
IMimePart::getRawHeaderIterator()

to retrieve an iterator instead of the returned two-dimensional array

Return values
string|null —

the value of the header

getHtmlContent()

Returns the content of the inline text/html part as a string.

public getHtmlContent(int $index[, string $charset = MailMimeParser::DEFAULT_CHARSET ]) : string|null

If the message contains more than one text/html 'inline' part, the default behavior is to return the first part. The content for additional parts can be returned by passing a 0-based index.

If a part at the passed index doesn't exist, null is returned.

Parameters
$index : int

Optional 0-based index of inline html part content.

$charset : string = MailMimeParser::DEFAULT_CHARSET

Optional charset for the returned string to be encoded in.

Tags
see
IMessage::getHtmlPart()

to get the html part(s).

see
IMessage::getHtmlStream()

to get the html content stream directly.

Return values
string|null —

getHtmlPart()

Returns the inline text/html IMessagePart for a message.

public getHtmlPart(int $index) : IMessagePart|null

If the message contains more than one text/html 'inline' part, the default behavior is to return the first part. Additional parts can be returned by passing a 0-based index.

If there are no inline text/html parts in this message, null is returned.

Parameters
$index : int

Optional index of part to return.

Tags
see
IMessage::getHtmlStream()

to get the html content stream directly.

see
IMessage::getHtmlStream()

to get the html content in a string.

see
IMessage::getTextPart()

to get the text part(s).

see
IMessage::getTextPartCount()

to get a count of text parts.

see
IMessage::getHtmlPartCount()

to get a count of html parts.

Return values
IMessagePart|null —

getHtmlStream()

Returns a Psr7 Stream for the 'inline' text/html content.

public getHtmlStream(int $index[, string $charset = MailMimeParser::DEFAULT_CHARSET ]) : StreamInterface|null

If the message contains more than one text/html 'inline' part, the default behavior is to return the first part. The streams for additional parts can be returned by passing a 0-based index.

If a part at the passed index doesn't exist, null is returned.

Parameters
$index : int

Optional 0-based index of inline html part stream.

$charset : string = MailMimeParser::DEFAULT_CHARSET

Optional charset to encode the stream with.

Tags
see
IMessage::getHtmlPart()

to get the html part(s).

see
IMessage::getHtmlContent()

to get the html content in a string.

Return values
StreamInterface|null —

getMessageId()

Returns the value of the 'Message-ID' header, or null if not set.

public getMessageId() : string|null
Return values
string|null —

the ID.

getPart()

Returns the part at the given 0-based index for this part (part 0) and all parts under it, or null if not found with the passed filter function.

public getPart(int $index[, callable $fnFilter = null ]) : IMessagePart|null

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

The passed callable must accept an IMessagePart as an argument, and return true if it should be accepted, or false to filter the part out. Some default filters are provided by static functions returning callables in PartFilter.

Parameters
$index : int

The 0-based index (0 being this part if $fnFilter is null or this part is satisfied by the filter).

$fnFilter : callable = null

Optional function accepting an IMessagePart and returning true if the part should be included.

Tags
see
IMultiPart::getAllParts()

to get an array of all parts with an optional filter.

see
IMultiPart::getPartCount()

to get the number of parts with an optional filter.

see
IMultiPart::getChild()

to get a direct child of the current part.

Return values
IMessagePart|null —

A matching part, or null if not found.

getPartByContentId()

Returns a part that has the given Content ID, or null if not found.

public getPartByContentId(string $contentId) : IMessagePart|null

Calls IMessagePart::getContentId() to find a matching part.

Parameters
$contentId : string

The content ID to find a part for.

Return values
IMessagePart|null —

The matching part.

getPartByMimeType()

Returns the part that has a content type matching the passed mime type at the given index, or null if there are no matching parts.

public getPartByMimeType(string $mimeType, int $index) : IMessagePart|null

Creates a filter that looks at the return value of IMessagePart::getContentType() for all parts (including the current part) and returns a matching one at the given 0-based index.

Parameters
$mimeType : string

The mime type to find.

$index : int

Optional 0-based index (defaulting to '0').

Tags
see
IMultiPart::getAllPartsByMimeType()

to get all parts that match a mime type.

see
IMultiPart::getCountOfPartsByMimeType()

to get a count of parts with a mime type.

Return values
IMessagePart|null —

The part.

getPartCount()

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

public getPartCount([callable $fnFilter = null ]) : int

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

The passed callable must accept an IMessagePart as an argument, and return true if it should be accepted, or false to filter the part out. Some default filters are provided by static functions returning callables in PartFilter.

Parameters
$fnFilter : callable = null

Optional function accepting an IMessagePart and returning true if the part should be included.

Tags
see
IMultiPart::getPart()

to find a part at a specific 0-based index with an optional filter.

see
IMultiPart::getAllParts()

to get an array of all parts with an optional filter.

see
IMultiPart::getChildCount()

to get a count of direct children of this part.

Return values
int —

The number of matching parts.

getRawHeaderIterator()

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

public getRawHeaderIterator() : Traversable<string|int, array<string|int, string>>

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

Tags
see
IMimePart::getHeader()

to retrieve a single header object.

see
IMimePart::getHeaderValue()

to get the string value portion of a specific header only.

see
IMimePart::getHeaderParameter()

to get the string value portion of a specific header's parameter only.

see
IMimePart::getAllHeaders()

to retrieve an array of all header objects for this part.

see
IMimePart::getAllHeadersByName()

to retrieve an array of all headers with a certain name.

see
IMimePart::getRawHeaders()

to retrieve the array the returned iterator iterates over.

Return values
Traversable<string|int, array<string|int, string>> —

an iterator for raw headers

getRawHeaders()

Returns a two dimensional string array of all headers for the mime part with the first element holding the name, and the second its raw string value:

public getRawHeaders() : array<string|int, array<string|int, string>>

[ [ '1st-Header-Name', 'Header Value' ], [ '2nd-Header-Name', 'Header Value' ] ]

Tags
see
IMimePart::getHeader()

to retrieve a single header object.

see
IMimePart::getHeaderValue()

to get the string value portion of a specific header only.

see
IMimePart::getHeaderParameter()

to get the string value portion of a specific header's parameter only.

see
IMimePart::getAllHeaders()

to retrieve an array of all header objects for this part.

see
IMimePart::getAllHeadersByName()

to retrieve an array of all headers with a certain name.

see
IMimePart::getRawHeaderIterator()

to retrieve an iterator instead of the returned two-dimensional array

Return values
array<string|int, array<string|int, string>> —

an array of raw headers

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.
Tags
see
IMessagePart::getStream()

to get a Psr7 StreamInterface instead of a resource handle.

see
IMessagePart::__toString()

to write the part to a string and return it.

see
IMessage::save()

to write the part to a file, resource handle or Psr7 stream.

Return values
resource —

the resource handle containing the part.

getSignaturePart()

Returns the signature part of a multipart/signed message or null.

public getSignaturePart() : IMessagePart|null

The signature part is determined to always be the 2nd child of a multipart/signed message, the first being the 'body'.

Using the 'protocol' parameter of the Content-Type header is unreliable in some instances (for instance a difference of x-pgp-signature versus pgp-signature).

Return values
IMessagePart|null —

getSignedMessageAsString()

Returns a string containing the entire body of a signed message for verification or calculating a signature.

public getSignedMessageAsString() : string|null

Non-CRLF new lines are replaced to always be CRLF.

Tags
see
IMessage::setAsMultipartSigned

to make the message a multipart/signed message.

Return values
string|null —

null if the message doesn't have any children

getSignedMessageStream()

Returns a stream that can be used to read the content part of a signed message, which can be used to sign an email or verify a signature.

public getSignedMessageStream() : StreamInterface|null

The method simply returns the stream for the first child. No verification of whether the message is in fact a signed message is performed.

Note that unlike getSignedMessageAsString, getSignedMessageStream doesn't replace new lines, and before calculating a signature, LFs not preceded by CR should be replaced with CRLFs.

Tags
see
IMessage::getSignedMessageAsString

to get a string with CRLFs normalized

Return values
StreamInterface|null —

null if the message doesn't have any children

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.
Tags
see
IMessagePart::getResourceHandle()

to get a resource handle.

see
IMessagePart::__toString()

to write the part to a string and return it.

see
IMessage::save()

to write the part to a file, resource handle or Psr7 stream.

Return values
StreamInterface —

the stream containing the part.

getSubject()

Returns the subject of the message, retrieved from the 'Subject' header, or null if the message has none set.

public getSubject() : string|null
Return values
string|null —

getTextContent()

Returns the content of the inline text/plain part as a string.

public getTextContent(int $index[, string $charset = MailMimeParser::DEFAULT_CHARSET ]) : string|null

If the message contains more than one text/plain 'inline' part, the default behavior is to return the first part. The content for additional parts can be returned by passing a 0-based index.

If a part at the passed index doesn't exist, null is returned.

Parameters
$index : int

Optional 0-based index of inline text part content.

$charset : string = MailMimeParser::DEFAULT_CHARSET

Optional charset for the returned string to be encoded in.

Tags
see
IMessage::getTextPart()

to get the text part(s).

see
IMessage::getTextStream()

to get the text content stream directly.

Return values
string|null —

getTextPart()

Returns the inline text/plain IMessagePart for a message.

public getTextPart(int $index) : IMessagePart|null

If the message contains more than one text/plain 'inline' part, the default behavior is to return the first part. Additional parts can be returned by passing a 0-based index.

If there are no inline text/plain parts in this message, null is returned.

Parameters
$index : int

Optional index of part to return.

Tags
see
IMessage::getTextPartCount()

to get a count of text parts.

see
IMessage::getTextStream()

to get the text content stream directly.

see
IMessage::getTextContent()

to get the text content in a string.

see
IMessage::getHtmlPart()

to get the HTML part(s).

see
IMessage::getHtmlPartCount()

to get a count of html parts.

Return values
IMessagePart|null —

getTextStream()

Returns a Psr7 Stream for the 'inline' text/plain content.

public getTextStream(int $index[, string $charset = MailMimeParser::DEFAULT_CHARSET ]) : StreamInterface|null

If the message contains more than one text/plain 'inline' part, the default behavior is to return the first part. The streams for additional parts can be returned by passing a 0-based index.

If a part at the passed index doesn't exist, null is returned.

Parameters
$index : int

Optional 0-based index of inline text part stream.

$charset : string = MailMimeParser::DEFAULT_CHARSET

Optional charset to encode the stream with.

Tags
see
IMessage::getTextPart()

to get the text part(s).

see
IMessage::getTextContent()

to get the text content in a string.

Return values
StreamInterface|null —

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 —

isMime()

Returns true if the current part is a mime part.

public isMime() : bool
Return values
bool —

isMultiPart()

Returns true if this part's content type matches multipart/*

public isMultiPart() : bool
Return values
bool —

isSignaturePart()

Returns true if this part is the 'signature' part of a signed message.

public isSignaturePart() : bool
Return values
bool —

isTextPart()

Returns true if the content of this part is plain text.

public isTextPart() : bool
Return values
bool —

removeAllHtmlParts()

Removes all text/html inline parts in this message.

public removeAllHtmlParts([bool $moveRelatedPartsBelowMessage = true ]) : bool

If the message contains a multipart/alternative part, the html parts are removed from below the alternative part only. If there is only one remaining part after that, it is moved up, replacing the multipart/alternative part.

If the multipart/alternative part further contains a multipart/related (or mixed) part which holds an inline html part, only parts from that child multipart are removed, and if the passed $moveRelatedPartsBelowMessage is true, any non-html parts are moved to be below the message directly (changing the message into a multipart/mixed message if need be).

For more control, call IMessagePart::removePart() with parts you wish to remove.

Parameters
$moveRelatedPartsBelowMessage : bool = true

Optionally pass false to remove related parts.

Tags
see
IMessage::setHtmlPart()

to set the html part

see
IMessage::removeHtmlPart()

to remove an html part

see
IMessage::removeAllTextParts()

to remove all html parts

Return values
bool —

true on success

removeAllParts()

Removes all parts below the current part. If a callable filter is passed, removes only those matching the passed filter. The number of removed parts is returned.

public removeAllParts([callable $fnFilter = null ]) : int

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
$fnFilter : callable = null

Optional function accepting an IMessagePart and returning true if the part should be included.

Return values
int —

The number of removed parts.

removeAllTextParts()

Removes all text/plain inline parts in this message.

public removeAllTextParts([bool $moveRelatedPartsBelowMessage = true ]) : bool

If the message contains a multipart/alternative part, the text parts are removed from below the alternative part only. If there is only one remaining part after that, it is moved up, replacing the multipart/alternative part.

If the multipart/alternative part further contains a multipart/related (or mixed) part which holds an inline text part, only parts from that child multipart are removed, and if the passed $moveRelatedPartsBelowMessage is true, any non-text parts are moved to be below the message directly (changing the message into a multipart/mixed message if need be).

For more control, call IMessagePart::removePart() with parts you wish to remove.

Parameters
$moveRelatedPartsBelowMessage : bool = true

Optionally pass false to remove related parts.

Tags
see
IMessage::setTextPart()

to set the text part

see
IMessage::removeTextPart()

to remove a text part

see
IMessage::removeAllHtmlParts()

to remove all html parts

Return values
bool —

true on success

removeAttachmentPart()

Removes the attachment at the given index.

public removeAttachmentPart(int $index) : static

Attachments are considered to be all parts other than the main content part for a non-mime message, and all parts under a mime message except:

  • text/plain and text/html parts with a Content-Disposition not set to 'attachment'
  • all multipart/* parts
  • any signature part
Parameters
$index : int
Return values
static —

removeHeader()

Removes all headers from this part with the passed name.

public removeHeader(string $name) : static
Parameters
$name : string

The name of the header(s) to remove.

Tags
see
IMimePart::addRawHeader()

Adds a header to the part regardless of whether or not a header with that name already exists.

see
IMimePart::setRawHeader()

Sets a header, potentially overwriting one if it already exists.

see
IMimePart::removeSingleHeader()

Removes a single header if more than one with the passed name exists.

Return values
static —

removeHtmlPart()

Removes the text/html part of the message at the passed index if one exists (defaults to first part if an index isn't passed).

public removeHtmlPart(int $index) : bool

Returns true if a part exists at the passed index and has been removed.

Parameters
$index : int

Optional 0-based index of inline html part to remove.

Tags
see
IMessage::setHtmlPart()

to set the html part

see
IMessage::removeTextPart()

to remove a text part

see
IMessage::removeAllHtmlParts()

to remove all html parts

Return values
bool —

true on success

removePart()

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

public removePart(IMessagePart $part) : int|null

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

This also means that parts from unrelated parts/messages could be removed by a call to removePart -- it will always remove the part from its parent if it has one, essentially calling php $part->getParent()->removePart(); .

Parameters
$part : IMessagePart

The part to remove

Return values
int|null —

The previous index position of the part within its old parent.

removeSingleHeader()

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

public removeSingleHeader(string $name, int $offset) : static
Parameters
$name : string

The name of the header to remove

$offset : int

Optional offset of the header to remove (defaults to 0 -- the first header).

Tags
see
IMimePart::addRawHeader()

Adds a header to the part regardless of whether or not a header with that name already exists.

see
IMimePart::setRawHeader()

Sets a header, potentially overwriting one if it already exists.

see
IMimePart::removeHeader()

Removes all headers on this part with the passed name

Return values
static —

removeTextPart()

Removes the text/plain part of the message at the passed index if one exists (defaults to first part if an index isn't passed).

public removeTextPart(int $index) : bool

Returns true if a part exists at the passed index and has been removed.

Parameters
$index : int

Optional 0-based index of inline text part to remove.

Tags
see
IMessage::setTextPart()

to set the text part

see
IMessage::removeHtmlPart()

to remove an html part

see
IMessage::removeAllTextParts()

to remove all text parts

Return values
bool —

true on success

save()

Writes a string representation of this part, including its headers, content and children to the passed file, resource, or stream.

public save(string|resource|StreamInterface $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 : string|resource|StreamInterface

the file, resource, or stream to write to.

$filemode : string = 'w+'

Optional filemode to open a file in (if $filenameResourceOrStream is a string)

Tags
see
IMessagePart::getResourceHandle()

to get a resource handle.

see
IMessagePart::__toString()

to get the part in a string.

see
IMessage::save()

to write the part to a file, resource handle or Psr7 stream.

Return values
static —

saveContent()

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

public saveContent(string|resource|StreamInterface $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 : string|resource|StreamInterface
Tags
see
IMessagePart::getContentStream()

to get the content stream with charset conversions applied.

see
IMessagePart::getBinaryContentStream()

to get the content as a binary stream.

see
IMessagePart::getBinaryContentResourceHandle()

to get the content as a resource handle.

Return values
static —

setAsMultipartSigned()

Turns the message into a multipart/signed message, moving the actual message into a child part, sets the content-type of the main message to multipart/signed and adds an empty signature part as well.

public setAsMultipartSigned(string $micalg, string $protocol) : static

After calling setAsMultipartSigned, call getSignedMessageAsString to get the normalized string content to be used for calculated the message's hash.

Parameters
$micalg : string

The Message Integrity Check algorithm being used

$protocol : string

The mime-type of the signature body

Tags
see
IMessage::getSignedMessageAsString
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.

Tags
see
IMessagePart::getContentStream()

to get the content stream.

Return values
static —

setContent()

Sets the content of the part to the passed string, resource, or stream.

public setContent(string|resource|StreamInterface $resource[, string $resourceCharset = MailMimeParser::DEFAULT_CHARSET ]) : static
Parameters
$resource : string|resource|StreamInterface

the content.

$resourceCharset : string = MailMimeParser::DEFAULT_CHARSET

the charset of the passed $resource.

Tags
see
IMessagePart::getContentStream()

to get the content stream.

see
IMessagePart::attachContentStream()

to attach a content stream.

see
IMessagePart::detachContentStream()

to detach the content stream.

Return values
static —

setHtmlPart()

Sets the text/html part of the message to the passed $resource, either creating a new part if one doesn't exist for text/html, or assigning the value of $resource to an existing text/html part.

public setHtmlPart(string|resource|StreamInterface $resource[, string $contentTypeCharset = 'UTF-8' ]) : static

The optional $contentTypeCharset parameter is the charset for the text/html part's Content-Type, not the charset of the passed $resource. $resource must be encoded in UTF-8 regardless of the target charset.

Parameters
$resource : string|resource|StreamInterface

UTF-8 encoded content.

$contentTypeCharset : string = 'UTF-8'

the charset to use as the text/html part's content-type header charset value.

Tags
see
IMessage::setTextPart()

to set the text part

see
IMessage::removeHtmlPart()

to remove an html part

see
IMessage::removeAllHtmlParts()

to remove all html parts

Return values
static —

setRawHeader()

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 only. 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... instead it would be 'pushed' on at the next position.

public setRawHeader(string $name, string|null $value, int $offset) : static 
$part = $myMimePart;
$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 IHeader 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

The name of the new header, e.g. 'Content-Type'.

$value : string|null

The raw value of the new header.

$offset : int

An optional offset, defaulting to '0' and therefore overriding the first header of the given $name if one exists.

Tags
see
IMimePart::addRawHeader()

Adds a header to the part regardless of whether or not a header with that name already exists.

see
IMimePart::removeHeader()

Removes all headers on this part with the passed name

see
IMimePart::removeSingleHeader()

Removes a single header if more than one with the passed name exists.

Return values
static —

setSignature()

Sets the signature body of the message to the passed $body for a multipart/signed message.

public setSignature(string $body) : static
Parameters
$body : string

the message's hash

Return values
static —

setTextPart()

Sets the text/plain part of the message to the passed $resource, either creating a new part if one doesn't exist for text/plain, or assigning the value of $resource to an existing text/plain part.

public setTextPart(string|resource|StreamInterface $resource[, string $contentTypeCharset = 'UTF-8' ]) : static

The optional $contentTypeCharset parameter is the charset for the text/plain part's Content-Type, not the charset of the passed $resource. $resource must be encoded in UTF-8 regardless of the target charset.

Parameters
$resource : string|resource|StreamInterface

UTF-8 encoded content.

$contentTypeCharset : string = 'UTF-8'

the charset to use as the text/plain part's content-type header charset value.

Tags
see
IMessage::setHtmlPart()

to set the html part

see
IMessage::removeTextPart()

to remove a text part

see
IMessage::removeAllTextParts()

to remove all text parts

Return values
static —

Search results