AddressHeader
extends AbstractHeader
in package
A header containing one or more email addresses and/or groups of addresses.
An address is separated by a comma, and each group separated by a semi-colon. The AddressHeader provides a complete list of all addresses referenced in a header including any addresses in groups, in addition to being able to access the groups separately if needed.
Tags
Table of Contents
- $addresses : array<string|int, mixed>
- $allParts : array<string|int, mixed>
- $groups : array<string|int, mixed>
- $logger : LoggerInterface
- $name : string
- $parts : array<string|int, mixed>
- $rawValue : string
- $comments : array<string|int, mixed>|null
- $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.
- getAddresses() : array<string|int, AddressPart>
- Returns all address parts in the header including any addresses that are in groups (lists).
- 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.
- 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.
- getEmail() : string|null
- Returns the first email address in the header.
- 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).
- getGroups() : array<string|int, AddressGroupPart>
- Returns all group parts (lists) in the header.
- 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.
- getPersonName() : string|null
- Returns the name associated with the first email address to complement getEmail() if one is set, or null if not.
- getRawValue() : string
- Returns the raw value of the header.
- getValue() : string
- Returns the parsed 'value' of the header.
- hasAddress() : bool
- Returns true if an address exists with the passed email address.
- 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.
- filterAndAssignToParts() : void
- Filters $this->allParts into the parts required by $this->parts and assignes 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
$addresses
protected
array<string|int, mixed>
$addresses
= []
array of addresses, included all addresses contained in groups.
$allParts
protected
array<string|int, mixed>
$allParts
= []
the header's parts (as returned from the consumer), including commentParts
$groups
protected
array<string|int, mixed>
$groups
= []
array of address groups (lists).
$logger
protected
LoggerInterface
$logger
$name
protected
string
$name
the name of the header
$parts
protected
array<string|int, mixed>
$parts
= []
all parts not including CommentParts.
$rawValue
protected
string
$rawValue
the raw value
$comments
private
array<string|int, mixed>|null
$comments
= null
array of comments, initialized on demand in getComments()
$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 ][, AddressBaseConsumerService|null $consumerService = null ]) : mixed
Parameters
- $name : string
-
Name of the header.
- $value : string
-
Value of the header.
- $logger : LoggerInterface|null = null
- $consumerService : AddressBaseConsumerService|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 —getAddresses()
Returns all address parts in the header including any addresses that are in groups (lists).
public
getAddresses() : array<string|int, AddressPart>
Return values
array<string|int, AddressPart> —The addresses.
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> —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> —getEmail()
Returns the first email address in the header.
public
getEmail() : string|null
Return values
string|null —The email address
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> —getGroups()
Returns all group parts (lists) in the header.
public
getGroups() : array<string|int, AddressGroupPart>
Return values
array<string|int, AddressGroupPart> —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> —getPersonName()
Returns the name associated with the first email address to complement getEmail() if one is set, or null if not.
public
getPersonName() : string|null
Return values
string|null —The person name.
getRawValue()
Returns the raw value of the header.
public
getRawValue() : string
Return values
string —The raw value.
getValue()
Returns the parsed 'value' of the header.
public
getValue() : string
For headers that contain multiple parts, like address headers (To, From) or parameter headers (Content-Type), the 'value' is the value of the first parsed part that isn't a comment.
Return values
string —The value
hasAddress()
Returns true if an address exists with the passed email address.
public
hasAddress(string $email) : bool
Comparison is done case insensitively.
Parameters
- $email : string
Return values
bool —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 —filterAndAssignToParts()
Filters $this->allParts into the parts required by $this->parts and assignes 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.