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 $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 __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 ): mixed
$pattern string

The regular expression used to validate the value. See 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 $allowName is true.

$idnEmailPattern string

The regular expression used to validate complex emails when $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 $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 Yiisoft\Validator\SkipOnEmptyInterface.

$skipOnError boolean

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

$when Closure|null

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

throws RuntimeException

If there was an attempt to enable IDN ($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 getFullPattern( ): string
return string

The regular expression.

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

            
getHandler() public method

public getHandler( ): string

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

            
getIdnEmailPattern() public method

Get the regular expression used to validate complex emails when $enableIdn is true.

public getIdnEmailPattern( ): string
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 getIncorrectInputMessage( ): string
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 getMessage( ): string
return string

A message used when the value is not valid.

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

            
getName() public method

public getName( ): string

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

            
getOptions() public method

public getOptions( ): array

                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 getPattern( ): string
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 getSkipOnEmpty( ): boolean|callable|null
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 getWhen( ): Closure|null
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 isIdnEnabled( ): boolean
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 isNameAllowed( ): boolean
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 shouldCheckDns( ): boolean
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 shouldSkipOnError( ): boolean
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 skipOnEmpty( boolean|callable|null $value ): $this
$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 skipOnError( boolean $value ): $this
$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 when( Closure|null $value ): $this
$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;
}