PartStreamContainer
extends ErrorBag
in package
Holds the stream and content stream objects for a part.
Note that streams are not explicitly closed or detached on destruction of the PartSreamContainer by design: the passed StreamInterfaces will be closed on their destruction when no references to them remain, which is useful when the streams are passed around.
In addition, all the streams passed to PartStreamContainer should be wrapping a ZBateson\StreamDecorators\NonClosingStream unless attached to a part by a user, this is because MMP uses a single seekable stream for content and wraps it in ZBateson\StreamDecorators\SeekingLimitStream objects for each part.
Tags
Table of Contents
- $charsetStream : StreamInterface|null
- $contentStream : StreamInterface|null
- $decodedStream : StreamInterface|null
- $detachParsedStream : bool
- $logger : LoggerInterface
- $mbWrapper : MbWrapper
- $stream : MessagePartStreamDecorator
- $streamFactory : StreamFactory
- $throwExceptionReadingPartContentFromUnsupportedCharsets : bool
- $charset : array<string|int, mixed>
- $encoding : array<string|int, mixed>
- $errors : array<string|int, mixed>
- $validated : bool
- __construct() : mixed
- addError() : static
- Creates and adds an Error object to this ErrorBag.
- 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).
- getBinaryContentStream() : MessagePartStreamDecorator|null
- Checks what transfer-encoding decoder stream is attached on the underlying stream, and resets it if the requested arguments differ.
- getContentStream() : MessagePartStreamDecorator|null
- Checks what transfer-encoding decoder stream and charset conversion stream are currently attached on the underlying contentStream, and resets them if the requested arguments differ from the currently assigned ones.
- 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).
- getStream() : MessagePartStreamDecorator
- Returns the part's stream containing the part's 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 there's a content stream associated with the part.
- 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.
- reset() : static
- Resets cached encoding and charset streams, and rewinds the stream.
- setContentStream() : static
- Attaches the passed stream as the content portion of this StreamContainer.
- setStream() : static
- Sets the part's stream containing the part's headers, content, and children.
- attachCharsetFilter() : static
- Attaches a charset conversion filter to the attached content handle, for the passed arguments.
- attachTransferEncodingFilter() : static
- Attaches a decoding filter to the attached content handle, for the passed $transferEncoding.
- getErrorBagChildren() : array<string|int, IErrorBag>
- Return any children ErrorBag objects.
- validate() : void
- Perform any extra validation and call 'addError'.
- isCharsetFilterChanged() : bool
- Returns true if the attached stream filter used for charset conversion on the current handle is different from the one needed based on the passed arguments.
- isTransferEncodingFilterChanged() : bool
- Returns true if the attached stream filter used for decoding the content on the current handle is different from the one passed as an argument.
- resetCharsetStream() : static
- Resets just the charset stream, and rewinds the decodedStream.
Properties
$charsetStream
protected
StreamInterface|null
$charsetStream
= null
attached charset stream to $decodedStream
$contentStream
protected
StreamInterface|null
$contentStream
= null
a stream containing this part's content
$decodedStream
protected
StreamInterface|null
$decodedStream
= null
the content stream after attaching transfer encoding streams to $contentStream.
$detachParsedStream
protected
bool
$detachParsedStream
= false
true if the stream should be detached when this container is destroyed.
$logger
protected
LoggerInterface
$logger
$mbWrapper
protected
MbWrapper
$mbWrapper
to test charsets and see if they're supported.
$stream
protected
MessagePartStreamDecorator
$stream
stream containing the part's headers, content and children wrapped in a MessagePartStreamDecorator
$streamFactory
protected
StreamFactory
$streamFactory
used to apply psr7 stream decorators to the attached StreamInterface based on encoding.
$throwExceptionReadingPartContentFromUnsupportedCharsets
protected
bool
$throwExceptionReadingPartContentFromUnsupportedCharsets
if false, reading from a content stream with an unsupported charset will be tried with the default charset, otherwise the stream created with the unsupported charset, and an exception will be thrown when read from.
$charset
private
array<string|int, mixed>
$charset
= ['from' => null, 'to' => null, 'filter' => null]
map of the active charset filter on the current handle.
$encoding
private
array<string|int, mixed>
$encoding
= ['type' => null, 'filter' => null]
map of the active encoding filter on the current handle.
$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
__construct()
public
__construct(LoggerInterface $logger, StreamFactory $streamFactory, MbWrapper $mbWrapper, bool $throwExceptionReadingPartContentFromUnsupportedCharsets) : mixed
Parameters
- $logger : LoggerInterface
- $streamFactory : StreamFactory
- $mbWrapper : MbWrapper
- $throwExceptionReadingPartContentFromUnsupportedCharsets : bool
Return values
mixed —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 —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> —getBinaryContentStream()
Checks what transfer-encoding decoder stream is attached on the underlying stream, and resets it if the requested arguments differ.
public
getBinaryContentStream(IMessagePart $part[, string|null $transferEncoding = null ]) : MessagePartStreamDecorator|null
Parameters
- $part : IMessagePart
- $transferEncoding : string|null = null
Return values
MessagePartStreamDecorator|null —getContentStream()
Checks what transfer-encoding decoder stream and charset conversion stream are currently attached on the underlying contentStream, and resets them if the requested arguments differ from the currently assigned ones.
public
getContentStream(IMessagePart $part, string $transferEncoding, string $fromCharset, string $toCharset) : MessagePartStreamDecorator|null
Parameters
- $part : IMessagePart
-
the part the stream belongs to
- $transferEncoding : string
-
the transfer encoding
- $fromCharset : string
-
the character set the content is encoded in
- $toCharset : string
-
the target encoding to return
Return values
MessagePartStreamDecorator|null —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> —getStream()
Returns the part's stream containing the part's headers, content, and children.
public
getStream() : MessagePartStreamDecorator
Return values
MessagePartStreamDecorator —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 there's a content stream associated with the part.
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 —reset()
Resets cached encoding and charset streams, and rewinds the stream.
public
reset() : static
Return values
static —setContentStream()
Attaches the passed stream as the content portion of this StreamContainer.
public
setContentStream([StreamInterface|null $contentStream = null ]) : static
The content stream would represent the content portion of $this->stream.
If the content is overridden, $this->stream should point to a dynamic MessagePartStream that dynamically creates the RFC822 formatted message based on the IMessagePart this PartStreamContainer belongs to.
setContentStream can be called with 'null' to indicate the IMessagePart does not contain any content.
Parameters
- $contentStream : StreamInterface|null = null
Return values
static —setStream()
Sets the part's stream containing the part's headers, content, and children.
public
setStream(MessagePartStreamDecorator $stream) : static
Parameters
- $stream : MessagePartStreamDecorator
Return values
static —attachCharsetFilter()
Attaches a charset conversion filter to the attached content handle, for the passed arguments.
protected
attachCharsetFilter(string $fromCharset, string $toCharset) : static
Parameters
- $fromCharset : string
-
the character set the content is encoded in
- $toCharset : string
-
the target encoding to return
Return values
static —attachTransferEncodingFilter()
Attaches a decoding filter to the attached content handle, for the passed $transferEncoding.
protected
attachTransferEncodingFilter(string|null $transferEncoding) : static
Parameters
- $transferEncoding : string|null
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 —isCharsetFilterChanged()
Returns true if the attached stream filter used for charset conversion on the current handle is different from the one needed based on the passed arguments.
private
isCharsetFilterChanged(string $fromCharset, string $toCharset) : bool
Parameters
- $fromCharset : string
- $toCharset : string
Return values
bool —isTransferEncodingFilterChanged()
Returns true if the attached stream filter used for decoding the content on the current handle is different from the one passed as an argument.
private
isTransferEncodingFilterChanged(string|null $transferEncoding) : bool
Parameters
- $transferEncoding : string|null
Return values
bool —resetCharsetStream()
Resets just the charset stream, and rewinds the decodedStream.
private
resetCharsetStream() : static