MailMimeParser 3.0

ReceivedHeader extends ParameterHeader
in package

Represents a Received header.

The returned header value (as returned by a call to ReceivedHeader::getValue()) for a ReceivedHeader is the same as the raw value (as returned by a call to ReceivedHeader::getRawValue()) since the header doesn't have a single 'value' to consider 'the value'.

The parsed parts of a Received header can be accessed as parameters. To check if a part exists, call ReceivedHeader::hasParameter() with the name of the part, for example: php $header->hasParameter('from') or php $header->hasParameter('id') . The value of the part can be obtained by calling ReceivedHeader::getValueFor(), for example php $header->getValueFor('with'); .

Additional parsing is performed on the "FROM" and "BY" parts of a received header in an attempt to extract the self-identified name of the server, its hostname, and its address (depending on what's included). These can be accessed directly from the ReceivedHeader object by calling one of the following methods:

o ReceivedHeader::getFromName() -- the name portion of the FROM part o ReceivedHeader::getFromHostname() -- the hostname of the FROM part o ReceivedHeader::getFromAddress() -- the adddress portion of the FROM part o ReceivedHeader::getByName() -- same as getFromName, but for the BY part, and etc... below o ReceivedHeader::getByHostname() o ReceivedHeader::getByAddress()

The parsed parts of the FROM and BY parts are determined as follows:

o Anything outside and before a parenthesized expression is considered "the name", for example "FROM AlainDeBotton", "AlainDeBotton" would be the name, but also if the name is an address, but exists outside the parenthesized expression, it's still considered "the name". For example: "From [1.2.3.4]", getFromName would return "[1.2.3.4]". o A parenthesized expression MUST match what looks like either a domain name on its own, or a domain name and an address. Otherwise the parenthesized expression is considered a comment, and not parsed into hostname and address. The rules are defined loosely because many implementations differ in how strictly they follow the standard. For a domain, it's enough that the expression starts with any alphanumeric character and contains at least one '.', followed by any number of '.', '-' and alphanumeric characters. The address portion must be surrounded in square brackets, and contain any sequence of '.', ':', numbers, and characters 'a' through 'f'. In addition the string 'ipv6' may start the expression (for instance, '[ipv6:::1]' would be valid). A port number may also be considered valid as part of the address, for example: [1.2.3.4:3231]. No additional validation on the address is done, and so an invalid address such as '....' could be returned, so users using the 'address' header are encouraged to validate it before using it. The square brackets are parsed out of the returned address, so the value returned by getFromAddress() would be "2.2.2.2", not "[2.2.2.2]".

The date/time stamp can be accessed as a DateTime object by calling ReceivedHeader::getDateTime().

Parsed comments can be accessed by calling ReceivedHeader::getComments(). Some implementations may include connection encryption information or other details in non-standardized comments.

Tags
author

Zaahid Bateson

Table of Contents

$allParts  : array<string|int, mixed>
$logger  : LoggerInterface
$name  : string
$parameters  : array<string|int, mixed>
$parts  : array<string|int, mixed>
$rawValue  : string
$comments  : array<string|int, mixed>|null
$date  : DateTime|null
$dateSet  : bool
$errors  : array<string|int, mixed>
$validated  : bool
__construct()  : mixed
Assigns the header's name and raw value, then calls parseHeaderValue to extract a parsed value.
__toString()  : string
Returns the string representation of the header.
addError()  : static
Creates and adds an Error object to this ErrorBag.
from()  : IHeader
Parses the passed parameters into an IHeader object.
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).
getAllParts()  : array<string|int, IHeaderPart>
Returns an array of all IHeaderPart objects the header's value has been parsed into, including any CommentParts.
getByAddress()  : string|null
Returns the address part of a parenthesized BY part or null if not defined or the format wasn't parsed.
getByHostname()  : string|null
Returns the hostname part of a parenthesized BY part or null if not defined or the format wasn't parsed.
getByName()  : string|null
Returns the name identified in the BY part of the header or null if not defined or the format wasn't parsed.
getComments()  : array<string|int, string>
Returns an array of comments parsed from the header. If there are no comments in the header, an empty array is returned.
getDateTime()  : DateTime|null
Returns the date/time stamp for the received header if set, or null otherwise.
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).
getFromAddress()  : string|null
Returns the address part of a parenthesized FROM part or null if not defined or the format wasn't parsed.
getFromHostname()  : string|null
Returns the hostname part of a parenthesized FROM part or null if not defined or the format wasn't parsed.
getFromName()  : string|null
Returns the name identified in the FROM part of the header or null if not defined or the format wasn't parsed.
getName()  : string
Returns the name of the header.
getParts()  : array<string|int, IHeaderPart>
Returns an array of IHeaderPart objects the header's value has been parsed into, excluding any {@see \ZBateson\MailMimeParser\Header\Part\CommentPart}s.
getRawValue()  : string
Returns the raw value of the header.
getValue()  : string|null
Returns the raw, unparsed header value, same as {@see ReceivedHeader::getRawValue()}.
getValueFor()  : string|null
Returns the value of the parameter with the given name, or $defaultValue if not set.
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.
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.
hasParameter()  : bool
Returns true if a parameter exists with the passed name.
filterAndAssignToParts()  : void
Filters $this->allParts into the parts required by $this->parts and assigns it.
getErrorBagChildren()  : array<string|int, IErrorBag>
Return any children ErrorBag objects.
getHeaderPartsFrom()  : array<string|int, string>
Checks if the passed $value parameter is null, and if so tries to parse a header line from $nameOrLine splitting on first occurrence of a ':' character.
parseHeaderValue()  : void
Calls the consumer and assigns the parsed parts to member variables.
validate()  : void
Perform any extra validation and call 'addError'.

Properties

$allParts

protected array<string|int, mixed> $allParts = []

the header's parts (as returned from the consumer), including commentParts

$logger

protected LoggerInterface $logger

$parameters

protected array<string|int, mixed> $parameters = []

key map of lower-case parameter names and associated ParameterParts.

$parts

protected array<string|int, mixed> $parts = []

all parts not including CommentParts.

$comments

private array<string|int, mixed>|null $comments = null

array of comments, initialized on demand in getComments()

$date

private DateTime|null $date = null

the date/time stamp in the header.

$dateSet

private bool $dateSet = false

set to true once $date has been looked for

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

Assigns the header's name and raw value, then calls parseHeaderValue to extract a parsed value.

public __construct(string $name, string $value[, LoggerInterface|null $logger = null ][, ReceivedConsumerService|null $consumerService = null ]) : mixed
Parameters
$name : string

Name of the header.

$value : string

Value of the header.

$logger : LoggerInterface|null = null
$consumerService : ReceivedConsumerService|null = null

For parsing the value.

Return values
mixed —

__toString()

Returns the string representation of the header.

public __toString() : string

i.e.: '<HeaderName>: <RawValue>'

Return values
string —

The string representation.

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 —

from()

Parses the passed parameters into an IHeader object.

public static from(string $nameOrLine[, string|null $value = null ]) : IHeader

The type of returned IHeader is determined by the name of the header. See HeaderFactory::newInstance for more details.

The required $nameOrLine parameter may contain either the name of a header to parse, or a full header line, e.g. From: email@example.com. If passing a full header line, the $value parameter must be set to null (the default).

Note that more specific types can be called on directly. For instance an AddressHeader may be created by calling AddressHeader::from() which will ignore the name of the header, and always return an AddressHeader, or by calling new AddressHeader('name', 'value') directly.

Parameters
$nameOrLine : string

The header's name or full header line.

$value : string|null = null

The header's value, or null if passing a full header line to parse.

Return values
IHeader —

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

getAllParts()

Returns an array of all IHeaderPart objects the header's value has been parsed into, including any CommentParts.

public getAllParts() : array<string|int, IHeaderPart>
Return values
array<string|int, IHeaderPart> —

getByAddress()

Returns the address part of a parenthesized BY part or null if not defined or the format wasn't parsed.

public getByAddress() : string|null

For example, "BY name ([1.2.3.4])" would return the string "1.2.3.4". Validation of the address is not performed, and the returned value may not be valid. More details on how the value is parsed and extracted can be found in the class description for ReceivedHeader.

Return values
string|null —

The 'BY' address.

getByHostname()

Returns the hostname part of a parenthesized BY part or null if not defined or the format wasn't parsed.

public getByHostname() : string|null

For example, "BY name (host.name)" would return the string "host.name". Validation of the hostname is not performed, and the returned value may not be valid. More details on how the value is parsed and extracted can be found in the class description for ReceivedHeader.

Return values
string|null —

The 'BY' hostname.

getByName()

Returns the name identified in the BY part of the header or null if not defined or the format wasn't parsed.

public getByName() : string|null

The returned value may either be a name or an address in the form "[1.2.3.4]". Validation is not performed on this value, and so whatever exists in this position is returned -- be it contains spaces, or invalid characters, etc...

Return values
string|null —

The 'BY' name.

getComments()

Returns an array of comments parsed from the header. If there are no comments in the header, an empty array is returned.

public getComments() : array<string|int, string>
Return values
array<string|int, string> —

getDateTime()

Returns the date/time stamp for the received header if set, or null otherwise.

public getDateTime() : DateTime|null
Return values
DateTime|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> —

getFromAddress()

Returns the address part of a parenthesized FROM part or null if not defined or the format wasn't parsed.

public getFromAddress() : string|null

For example, "FROM name ([1.2.3.4])" would return the string "1.2.3.4". Validation of the address is not performed, and the returned value may not be valid. More details on how the value is parsed and extracted can be found in the class description for ReceivedHeader.

Return values
string|null —

The 'FROM' address.

getFromHostname()

Returns the hostname part of a parenthesized FROM part or null if not defined or the format wasn't parsed.

public getFromHostname() : string|null

For example, "FROM name (host.name)" would return the string "host.name". Validation of the hostname is not performed, and the returned value may not be valid. More details on how the value is parsed and extracted can be found in the class description for ReceivedHeader.

Return values
string|null —

The 'FROM' hostname.

getFromName()

Returns the name identified in the FROM part of the header or null if not defined or the format wasn't parsed.

public getFromName() : string|null

The returned value may either be a name or an address in the form "[1.2.3.4]". Validation is not performed on this value, and so whatever exists in this position is returned -- be it contains spaces, or invalid characters, etc...

Return values
string|null —

The 'FROM' name.

getName()

Returns the name of the header.

public getName() : string
Return values
string —

The name.

getParts()

Returns an array of IHeaderPart objects the header's value has been parsed into, excluding any {@see \ZBateson\MailMimeParser\Header\Part\CommentPart}s.

public getParts() : array<string|int, IHeaderPart>
Return values
array<string|int, IHeaderPart> —

getRawValue()

Returns the raw value of the header.

public getRawValue() : string
Return values
string —

The raw value.

getValue()

Returns the raw, unparsed header value, same as {@see ReceivedHeader::getRawValue()}.

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

getValueFor()

Returns the value of the parameter with the given name, or $defaultValue if not set.

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

The parameter to retrieve.

$defaultValue : string = null

Optional default value (defaulting to null if not provided).

Return values
string|null —

The parameter's value.

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 —

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 —

hasParameter()

Returns true if a parameter exists with the passed name.

public hasParameter(string $name) : bool
Parameters
$name : string

The parameter to look up.

Return values
bool —

filterAndAssignToParts()

Filters $this->allParts into the parts required by $this->parts and assigns it.

protected filterAndAssignToParts() : void

The AbstractHeader::filterAndAssignToParts method filters out CommentParts.

Return values
void —

getErrorBagChildren()

Return any children ErrorBag objects.

protected abstract getErrorBagChildren() : array<string|int, IErrorBag>
Return values
array<string|int, IErrorBag> —

getHeaderPartsFrom()

Checks if the passed $value parameter is null, and if so tries to parse a header line from $nameOrLine splitting on first occurrence of a ':' character.

protected static getHeaderPartsFrom(string $nameOrLine[, string|null $value = null ]) : array<string|int, string>

The returned array always contains two elements. The first being the name (or blank if a ':' char wasn't found and $value is null), and the second being the value.

Parameters
$nameOrLine : string
$value : string|null = null
Return values
array<string|int, string> —

parseHeaderValue()

Calls the consumer and assigns the parsed parts to member variables.

protected parseHeaderValue(IConsumerService $consumer, string $value) : void

The default implementation assigns the returned value to $this->allParts and filters out comments from it, assigning the filtered array to $this->parts by calling filterAndAssignToParts.

Parameters
$consumer : IConsumerService
$value : string
Return values
void —

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