0 follower

Final Class Yiisoft\Validator\Rule\Email

InheritanceYiisoft\Validator\Rule\Email
ImplementsYiisoft\Validator\DumpedRuleInterface, Yiisoft\Validator\SkipOnEmptyInterface, Yiisoft\Validator\SkipOnErrorInterface, Yiisoft\Validator\WhenInterface
Uses TraitsYiisoft\Validator\Rule\Trait\SkipOnEmptyTrait, Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait, Yiisoft\Validator\Rule\Trait\WhenTrait

Defines validation options to check that the value is a valid email address.

See also Yiisoft\Validator\Rule\EmailHandler.

Public Methods

Hide inherited methods

Method Description Defined By
__construct() Yiisoft\Validator\Rule\Email
getFullPattern() Get the regular expression used to validate email addresses with the name part. Yiisoft\Validator\Rule\Email
getHandler() Yiisoft\Validator\Rule\Email
getIdnEmailPattern() Get the regular expression used to validate complex emails when {@see $enableIdn} is true. Yiisoft\Validator\Rule\Email
getIncorrectInputMessage() Get a message used when the input is incorrect. Yiisoft\Validator\Rule\Email
getMessage() Get a message used when the value is not valid. Yiisoft\Validator\Rule\Email
getName() Yiisoft\Validator\Rule\Email
getOptions() Yiisoft\Validator\Rule\Email
getPattern() Get the regular expression used to validate the value. Yiisoft\Validator\Rule\Email
getSkipOnEmpty() A getter for $skipOnEmpty property. Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait
getWhen() A getter for $when property. Yiisoft\Validator\Rule\Trait\WhenTrait
isIdnEnabled() Whether validation process should take IDN (internationalized domain names) into account. Yiisoft\Validator\Rule\Email
isNameAllowed() Whether to allow a name in the email address (e.g. "John Smith john.smith@example.com"). Yiisoft\Validator\Rule\Email
shouldCheckDns() Whether to check email's domain exists and has either an A or MX record. Yiisoft\Validator\Rule\Email
shouldSkipOnError() A getter for $skipOnError property. Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait
skipOnEmpty() An immutable setter to change $skipOnEmpty property. Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait
skipOnError() An immutable setter to change $skipOnError property. Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait
when() An immutable setter to change $when property. Yiisoft\Validator\Rule\Trait\WhenTrait

Method Details

Hide inherited methods

__construct() public method

public mixed __construct ( string $pattern '/^[a-zA-Z0-9!#$%&\'*+\\/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&\'*+\\/=?^_`{|}~-]+)*@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/', string $fullPattern '/^[^@]*<[a-zA-Z0-9!#$%&\'*+\\/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&\'*+\\/=?^_`{|}~-]+)*@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?>$/', string $idnEmailPattern '/^([a-zA-Z0-9._%+-]+)@((\\[\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.)|(([\\w-]+\\.)+))([a-zA-Z]{2,4}|\\d{1,3})(\\]?)$/', boolean $allowName false, boolean $checkDns false, boolean $enableIdn false, string $incorrectInputMessage '{Property} must be a string. {type} given.', string $message '{Property} is not a valid email address.', boolean|callable|null $skipOnEmpty null, boolean $skipOnError false, Closure|null $when null )
$pattern string

The regular expression used to validate the value. See {@link https://www.regular-expressions.info/email.html}.

$fullPattern string

The regular expression used to validate email addresses with the name part. This property is used only when {@see $allowName} is true.

$idnEmailPattern string

The regular expression used to validate complex emails when {@see $enableIdn} is true.

$allowName boolean

Bool Whether to allow a name in the email address (e.g. "John Smith john.smith@example.com"). Defaults to false. See {@see $fullPattern}.

$checkDns boolean

Bool Whether to check email's domain exists and has either an A or MX record. Be aware that this check can fail due to temporary DNS problems even if the email address is valid and an email would be deliverable. Defaults to false.

$enableIdn boolean

Whether validation process should take IDN (internationalized domain names) into account. Defaults to false meaning that validation of emails containing IDN will always fail. Note that in order to use IDN validation you have to install and enable intl PHP extension, otherwise an exception will be thrown.

$incorrectInputMessage string

A message used when the input is incorrect.

You may use the following placeholders in the message:

  • {property}: the translated label of the property being validated.
  • {type}: the type of the value being validated.
$message string

A message used when the value is not valid.

You may use the following placeholders in the message:

  • {property}: the translated label of the property being validated.
  • {value}: the value of the property being validated.
$skipOnEmpty boolean|callable|null

Whether to skip this rule if the value validated is empty. See {@see \Yiisoft\Validator\SkipOnEmptyInterface}.

$skipOnError boolean

Whether to skip this rule if any of the previous rules gave an error. See {@see \Yiisoft\Validator\SkipOnErrorInterface}.

$when Closure|null

A callable to define a condition for applying the rule. See {@see \Yiisoft\Validator\WhenInterface}.

throws RuntimeException

If there was an attempt to enable IDN ({@see $enableIdn}), but "intl" PHP extension is not installed or not enabled.

                public function __construct(
    string $pattern = '/^[a-zA-Z0-9!#$%&\'*+\\/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&\'*+\\/=?^_`{|}~-]+)*@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/',
    string $fullPattern = '/^[^@]*<[a-zA-Z0-9!#$%&\'*+\\/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&\'*+\\/=?^_`{|}~-]+)*@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?>$/',
    string $idnEmailPattern = '/^([a-zA-Z0-9._%+-]+)@((\[\d{1,3}\.\d{1,3}\.\d{1,3}\.)|(([\w-]+\.)+))([a-zA-Z]{2,4}|\d{1,3})(\]?)$/',
    private bool $allowName = false,
    private bool $checkDns = false,
    private bool $enableIdn = false,
    private string $incorrectInputMessage = '{Property} must be a string. {type} given.',
    private string $message = '{Property} is not a valid email address.',
    bool|callable|null $skipOnEmpty = null,
    private bool $skipOnError = false,
    private ?Closure $when = null,
) {
    if ($pattern === '') {
        throw new InvalidArgumentException('Pattern can\'t be empty.');
    }
    $this->pattern = $pattern;
    if ($fullPattern === '') {
        throw new InvalidArgumentException('Full pattern can\'t be empty.');
    }
    $this->fullPattern = $fullPattern;
    if ($idnEmailPattern === '') {
        throw new InvalidArgumentException('IDN e-mail pattern can\'t be empty.');
    }
    $this->idnEmailPattern = $idnEmailPattern;
    if ($enableIdn && !function_exists('idn_to_ascii')) {
        // Tested via separate CI configuration (see ".github/workflows/build.yml").
        // @codeCoverageIgnoreStart
        throw new RuntimeException('In order to use IDN validation intl extension must be installed and enabled.');
        // @codeCoverageIgnoreEnd
    }
    $this->skipOnEmpty = $skipOnEmpty;
}

            
getFullPattern() public method

Get the regular expression used to validate email addresses with the name part.

public string getFullPattern ( )
return string

The regular expression.

                public function getFullPattern(): string
{
    return $this->fullPattern;
}

            
getHandler() public method

public string getHandler ( )

                public function getHandler(): string
{
    return EmailHandler::class;
}

            
getIdnEmailPattern() public method

Get the regular expression used to validate complex emails when {@see $enableIdn} is true.

public string getIdnEmailPattern ( )
return string

The regular expression.

                public function getIdnEmailPattern(): string
{
    return $this->idnEmailPattern;
}

            
getIncorrectInputMessage() public method

Get a message used when the input is incorrect.

public string getIncorrectInputMessage ( )
return string

A message used when the input is incorrect.

                public function getIncorrectInputMessage(): string
{
    return $this->incorrectInputMessage;
}

            
getMessage() public method

Get a message used when the value is not valid.

public string getMessage ( )
return string

A message used when the value is not valid.

                public function getMessage(): string
{
    return $this->message;
}

            
getName() public method

public string getName ( )

                public function getName(): string
{
    return self::class;
}

            
getOptions() public method

public array getOptions ( )

                public function getOptions(): array
{
    return [
        'pattern' => $this->pattern,
        'fullPattern' => $this->fullPattern,
        'idnEmailPattern' => $this->idnEmailPattern,
        'allowName' => $this->allowName,
        'checkDns' => $this->checkDns,
        'enableIdn' => $this->enableIdn,
        'incorrectInputMessage' => [
            'template' => $this->incorrectInputMessage,
            'parameters' => [],
        ],
        'message' => [
            'template' => $this->message,
            'parameters' => [],
        ],
        'skipOnEmpty' => $this->getSkipOnEmptyOption(),
        'skipOnError' => $this->skipOnError,
    ];
}

            
getPattern() public method

Get the regular expression used to validate the value.

public string getPattern ( )
return string

The regular expression.

                public function getPattern(): string
{
    return $this->pattern;
}

            
getSkipOnEmpty() public method

Defined in: Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait::getSkipOnEmpty()

A getter for $skipOnEmpty property.

public boolean|callable|null getSkipOnEmpty ( )
return boolean|callable|null

A current raw (non-normalized) value.

                public function getSkipOnEmpty(): bool|callable|null
{
    return $this->skipOnEmpty;
}

            
getWhen() public method

Defined in: Yiisoft\Validator\Rule\Trait\WhenTrait::getWhen()

A getter for $when property.

public Closure|null getWhen ( )
return Closure|null

Current value:

  • null - always apply the validation.
  • callable - apply the validation depending on a return value: true - apply, false - do not apply.

                public function getWhen(): ?Closure
{
    return $this->when;
}

            
isIdnEnabled() public method

Whether validation process should take IDN (internationalized domain names) into account.

public boolean isIdnEnabled ( )
return boolean

Whether validation process should take IDN (internationalized domain names) into account.

                public function isIdnEnabled(): bool
{
    return $this->enableIdn;
}

            
isNameAllowed() public method

Whether to allow a name in the email address (e.g. "John Smith john.smith@example.com").

public boolean isNameAllowed ( )
return boolean

Whether to allow a name in the email address.

                public function isNameAllowed(): bool
{
    return $this->allowName;
}

            
shouldCheckDns() public method

Whether to check email's domain exists and has either an A or MX record.

public boolean shouldCheckDns ( )
return boolean

Whether to check email's domain exists and has either an A or MX record.

                public function shouldCheckDns(): bool
{
    return $this->checkDns;
}

            
shouldSkipOnError() public method

Defined in: Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait::shouldSkipOnError()

A getter for $skipOnError property.

public boolean shouldSkipOnError ( )
return boolean

Current value. true means to skip the current rule when the previous one errored and false - do not skip.

                public function shouldSkipOnError(): bool
{
    return $this->skipOnError;
}

            
skipOnEmpty() public method

Defined in: Yiisoft\Validator\Rule\Trait\SkipOnEmptyTrait::skipOnEmpty()

An immutable setter to change $skipOnEmpty property.

public $this skipOnEmpty ( boolean|callable|null $value )
$value boolean|callable|null

A new value.

return $this

The new instance with a changed value.

                public function skipOnEmpty(bool|callable|null $value): static
{
    $new = clone $this;
    $new->skipOnEmpty = $value;
    return $new;
}

            
skipOnError() public method

Defined in: Yiisoft\Validator\Rule\Trait\SkipOnErrorTrait::skipOnError()

An immutable setter to change $skipOnError property.

public $this skipOnError ( boolean $value )
$value boolean

A new value. true means to skip the current rule when the previous one errored and false - do not skip.

return $this

The new instance with a changed value.

                public function skipOnError(bool $value): static
{
    $new = clone $this;
    $new->skipOnError = $value;
    return $new;
}

            
when() public method

Defined in: Yiisoft\Validator\Rule\Trait\WhenTrait::when()

An immutable setter to change $when property.

public $this when ( Closure|null $value )
$value Closure|null

A new value:

  • null - always apply the validation.
  • callable - apply the validation depending on a return value: true - apply, false - do not apply.
return $this

The new instance with a changed value.

                public function when(?Closure $value): static
{
    $new = clone $this;
    $new->when = $value;
    return $new;
}