Fr3nch13/CakePHP Utilities

Validator
in package

Application

implements ArrayAccess, IteratorAggregate, Countable

Validator object encapsulates all methods related to data validations for a model It also provides an API to dynamically change validation rules for each model field.

Implements ArrayAccess to easily modify rules in the set

Interfaces

ArrayAccess
IteratorAggregate
Countable

Constants

EMPTY_ALL = self::EMPTY_STRING | self::EMPTY_ARRAY | self::EMPTY_FILE | self::EMPTY_DATE | self::EMPTY_TIME: A combination of the all EMPTY_* flags
EMPTY_ARRAY = 2: A flag for allowEmptyFor()
EMPTY_DATE = 8: A flag for allowEmptyFor()
EMPTY_FILE = 4: A flag for allowEmptyFor()
EMPTY_NULL = 0: A flag for allowEmptyFor()
EMPTY_STRING = 1: A flag for allowEmptyFor()
EMPTY_TIME = 16: A flag for allowEmptyFor()
NESTED = '_nested': Used to flag nested rules created with addNested() and addNestedMany()
WHEN_CREATE = 'create': By using 'create' you can make fields required when records are first created.
WHEN_UPDATE = 'update': By using 'update', you can make fields required when they are updated.

Properties

$_allowEmptyFlags : array<string, int>: Contains the flags which specify what is empty for each corresponding field.
$_allowEmptyMessages : array<string, string>: Contains the validation messages associated with checking the emptiness for each corresponding field.
$_defaultProviders : array<string, object|string>: An associative array of objects or classes used as a default provider list
$_fields : array<string, ValidationSet>: Holds the ValidationSet objects array
$_presenceMessages : array<string, string>: Contains the validation messages associated with checking the presence for each corresponding field.
$_providers : array<string, object|string>: An associative array of objects or classes containing methods used for validation
$_stopOnFailure : bool: Whether to apply last flag to generated rule(s).
$_useI18n : bool: Whether to use I18n functions for translating default error messages

Methods

__construct() : mixed: Constructor
__debugInfo() : array<string, mixed>: Get the printable version of this object.
add() : $this: Adds a new rule to a field's rule set. If second argument is an array then rules list for the field will be replaced with second argument and third argument will be ignored.
addDefaultProvider() : void: Associates an object to a name so it can be used as a default provider.
addNested() : $this: Adds a nested validator.
addNestedMany() : $this: Adds a nested validator.
allowEmpty() : $this: Allows a field to be empty. You can also pass array.
allowEmptyArray() : $this: Allows a field to be an empty array.
allowEmptyDate() : $this: Allows a field to be an empty date.
allowEmptyDateTime() : $this: Allows a field to be an empty date/time.
allowEmptyFile() : $this: Allows a field to be an empty file.
allowEmptyFor() : $this: Low-level method to indicate that a field can be empty.
allowEmptyString() : $this: Allows a field to be an empty string.
allowEmptyTime() : $this: Allows a field to be an empty time.
alphaNumeric() : $this: Add an alphanumeric rule to a field.
ascii() : $this: Add a validation rule to ensure a field contains only ascii bytes
asciiAlphaNumeric() : $this: Add an ascii-alphanumeric rule to a field.
boolean() : $this: Add a boolean validation rule to a field.
containsNonAlphaNumeric() : $this: Add a rule to check if a field contains non alpha numeric characters.
count() : int: Returns the number of fields having validation rules
creditCard() : $this: Add a credit card rule to a field.
date() : $this: Add a date format validation rule to a field.
dateTime() : $this: Add a date time format validation rule to a field.
decimal() : $this: Add a decimal validation rule to a field.
email() : $this: Add an email validation rule to a field.
equals() : $this: Add a equal to comparison rule to a field.
equalToField() : $this: Add a rule to compare one field is equal to another.
errors() : array<string|int, array<string|int, mixed>>: Validates and returns an array of failed fields and their error messages.
field() : ValidationSet: Returns a ValidationSet object containing all validation rules for a field, if passed a ValidationSet as second argument, it will replace any other rule set defined before
getDefaultProvider() : object|string|null: Returns the default provider stored under that name if it exists.
getDefaultProviders() : array<string|int, string>: Get the list of default providers.
getIterator() : Traversable<string, ValidationSet>: Returns an iterator for each of the fields to be validated
getNotEmptyMessage() : string|null: Gets the notEmpty message for a field
getProvider() : object|string|null: Returns the provider stored under that name if it exists.
getRequiredMessage() : string|null: Gets the required message for a field
greaterThan() : $this: Add a greater than comparison rule to a field.
greaterThanField() : $this: Add a rule to compare one field is greater than another.
greaterThanOrEqual() : $this: Add a greater than or equal to comparison rule to a field.
greaterThanOrEqualToField() : $this: Add a rule to compare one field is greater than or equal to another.
hasAtLeast() : $this: Add a validation rule to ensure that a field is an array containing at least the specified amount of elements
hasAtMost() : $this: Add a validation rule to ensure that a field is an array containing at most the specified amount of elements
hasField() : bool: Check whether a validator contains any rules for the given field.
hexColor() : $this: Add a validation rule to ensure a field is a 6 digits hex color value.
inList() : $this: Add a validation rule to ensure the field value is within an allowed list.
integer() : $this: Add a validation rule to ensure a field is an integer value.
ip() : $this: Add an IP validation rule to a field.
ipv4() : $this: Add an IPv4 validation rule to a field.
ipv6() : $this: Add an IPv6 validation rule to a field.
isArray() : $this: Add a validation rule to ensure that a field contains an array.
isEmptyAllowed() : bool: Returns whether a field can be left empty for a new or already existing record.
isPresenceRequired() : bool: Returns whether a field can be left out for a new or already existing record.
latitude() : $this: Add a validation rule to ensure the field is a latitude.
latLong() : $this: Add a validation rule to ensure the field is a lat/long tuple.
lengthBetween() : $this: Add an rule that ensures a string length is within a range.
lessThan() : $this: Add a less than comparison rule to a field.
lessThanField() : $this: Add a rule to compare one field is less than another.
lessThanOrEqual() : $this: Add a less than or equal comparison rule to a field.
lessThanOrEqualToField() : $this: Add a rule to compare one field is less than or equal to another.
localizedTime() : $this: Add a localized time, date or datetime format validation rule to a field.
longitude() : $this: Add a validation rule to ensure the field is a longitude.
maxLength() : $this: Add a string length validation rule to a field.
maxLengthBytes() : $this: Add a string length validation rule to a field.
minLength() : $this: Add a string length validation rule to a field.
minLengthBytes() : $this: Add a string length validation rule to a field.
multipleOptions() : $this: Add a validation rule for a multiple select. Comparison is case sensitive by default.
naturalNumber() : $this: Add a natural number validation rule to a field.
nonNegativeInteger() : $this: Add a validation rule to ensure a field is a non negative integer.
notAlphaNumeric() : $this: Add a non-alphanumeric rule to a field.
notAsciiAlphaNumeric() : $this: Add a non-ascii alphanumeric rule to a field.
notBlank() : $this: Add a notBlank rule to a field.
notEmpty() : $this: Sets a field to require a non-empty value. You can also pass array.
notEmptyArray() : $this: Require a field to be a non-empty array
notEmptyDate() : $this: Require a non-empty date value
notEmptyDateTime() : $this: Require a field to be a non empty date/time.
notEmptyFile() : $this: Require a field to be a not-empty file.
notEmptyString() : $this: Requires a field to not be an empty string.
notEmptyTime() : $this: Require a field to be a non-empty time.
notEquals() : $this: Add a not equal to comparison rule to a field.
notEqualToField() : $this: Add a rule to compare one field is not equal to another.
notSameAs() : $this: Add a rule to compare that two fields have different values.
numeric() : $this: Add a numeric value validation rule to a field.
offsetExists() : bool: Returns whether a rule set is defined for a field or not
offsetGet() : ValidationSet: Returns the rule set for a field
offsetSet() : void: Sets the rule set for a field
offsetUnset() : void: Unsets the rule set for a field
providers() : array<string|int, string>: Get the list of providers in this validator.
range() : $this: Add a validation rule to ensure a field is within a numeric range
regex() : $this: Returns whether a field matches against a regular expression.
remove() : $this: Removes a rule from the set by its name
requirePresence() : $this: Sets whether a field is required to be present in data array.
sameAs() : $this: Add a rule to compare two fields to each other.
scalar() : $this: Add a validation rule to ensure that a field contains a scalar.
setProvider() : $this: Associates an object to a name so it can be used as a provider. Providers are objects or class names that can contain methods used during validation of for deciding whether a validation rule can be applied. All validation methods, when called will receive the full list of providers stored in this validator.
setStopOnFailure() : $this: Whether to stop validation rule evaluation on the first failed rule.
time() : $this: Add a time format validation rule to a field.
uploadedFile() : $this: Add a validation rule to ensure the field is an uploaded file
url() : $this: Add a validation rule to ensure a field is a URL.
urlWithProtocol() : $this: Add a validation rule to ensure a field is a URL.
utf8() : $this: Add a validation rule to ensure a field contains only BMP utf8 bytes
utf8Extended() : $this: Add a validation rule to ensure a field contains only utf8 bytes.
uuid() : $this: Add a validation rule to ensure the field is a UUID
validate() : array<string|int, array<string|int, mixed>>: Validates and returns an array of failed fields and their error messages.
_canBeEmpty() : bool: Returns whether the field can be left blank according to `allowEmpty`
_checkPresence() : bool: Returns false if any validation for the passed rule set should be stopped due to the field missing in the data array
_convertValidatorToArray() : array<string|int, array<string|int, mixed>>: Converts validator to fieldName => $settings array
_fieldIsEmpty() : bool: Returns true if the field is empty in the passed data array
_processRules() : array<string, mixed>: Iterates over each rule in the validation set and collects the errors resulting from executing them
invertWhenClause() : callable|string|bool: Invert a when clause for creating notEmpty rules
isEmpty() : bool: Returns true if the field is empty in the passed data array

EMPTY_ALL

A combination of the all EMPTY_* flags


    public
        int
    EMPTY_ALL
    = self::EMPTY_STRING | self::EMPTY_ARRAY | self::EMPTY_FILE | self::EMPTY_DATE | self::EMPTY_TIME

EMPTY_ARRAY

A flag for allowEmptyFor()


    public
        int
    EMPTY_ARRAY
    = 2

When an empty array is given, it will be recognized as empty.

EMPTY_DATE

A flag for allowEmptyFor()


    public
        int
    EMPTY_DATE
    = 8

When an array is given, if it contains the year key, and only empty strings or null values, it will be recognized as empty.

EMPTY_FILE

A flag for allowEmptyFor()


    public
        int
    EMPTY_FILE
    = 4

When an array is given, if it has at least the name, type, tmp_name and error keys, and the value of error is equal to UPLOAD_ERR_NO_FILE, the value will be recognized as empty.

When an instance of \Psr\Http\Message\UploadedFileInterface is given the return value of it's getError() method must be equal to UPLOAD_ERR_NO_FILE.

EMPTY_NULL

A flag for allowEmptyFor()


    public
        int
    EMPTY_NULL
    = 0

When null is given, it will be recognized as empty.

EMPTY_STRING

A flag for allowEmptyFor()


    public
        int
    EMPTY_STRING
    = 1

When an empty string is given, it will be recognized as empty.

EMPTY_TIME

A flag for allowEmptyFor()


    public
        int
    EMPTY_TIME
    = 16

When an array is given, if it contains the hour key, and only empty strings or null values, it will be recognized as empty.

NESTED

Used to flag nested rules created with addNested() and addNestedMany()


    public
        string
    NESTED
    = '_nested'

WHEN_CREATE

By using 'create' you can make fields required when records are first created.


    public
        string
    WHEN_CREATE
    = 'create'

WHEN_UPDATE

By using 'update', you can make fields required when they are updated.


    public
        string
    WHEN_UPDATE
    = 'update'

$_allowEmptyFlags

Contains the flags which specify what is empty for each corresponding field.


    protected
        array<string, int>
    $_allowEmptyFlags
     = []

$_allowEmptyMessages

Contains the validation messages associated with checking the emptiness for each corresponding field.


    protected
        array<string, string>
    $_allowEmptyMessages
     = []

$_defaultProviders

An associative array of objects or classes used as a default provider list


    protected
    static    array<string, object|string>
    $_defaultProviders
     = []

$_fields

Holds the ValidationSet objects array


    protected
        array<string, ValidationSet>
    $_fields
     = []

$_presenceMessages

Contains the validation messages associated with checking the presence for each corresponding field.


    protected
        array<string, string>
    $_presenceMessages
     = []

$_providers

An associative array of objects or classes containing methods used for validation


    protected
        array<string, object|string>
    $_providers
     = []

$_stopOnFailure

Whether to apply last flag to generated rule(s).


    protected
        bool
    $_stopOnFailure
     = false

$_useI18n

Whether to use I18n functions for translating default error messages


    protected
        bool
    $_useI18n
     = false

__construct()

Constructor


    public
                    __construct() : mixed

__debugInfo()

Get the printable version of this object.


    public
                    __debugInfo() : array<string, mixed>

Return values

array<string, mixed>

add()

Adds a new rule to a field's rule set. If second argument is an array then rules list for the field will be replaced with second argument and third argument will be ignored.


    public
                    add(string $field, array<string|int, mixed>|string $name[, ValidationRule|array<string|int, mixed> $rule = [] ]) : $this

Example:

     $validator
         ->add('title', 'required', ['rule' => 'notBlank'])
         ->add('user_id', 'valid', ['rule' => 'numeric', 'message' => 'Invalid User'])

     $validator->add('password', [
         'size' => ['rule' => ['lengthBetween', 8, 20]],
         'hasSpecialCharacter' => ['rule' => 'validateSpecialchar', 'message' => 'not valid']
     ]);

Parameters

$field : string: The name of the field from which the rule will be added
$name : array<string|int, mixed>|string: The alias for a single rule or multiple rules array
$rule : ValidationRule|array<string|int, mixed> = []: the rule to add

Return values

$this

addDefaultProvider()

Associates an object to a name so it can be used as a default provider.


    public
            static        addDefaultProvider(string $name, object|string $object) : void

Parameters

$name : string: The name under which the provider should be set.
$object : object|string: Provider object or class name.

addNested()

Adds a nested validator.


    public
                    addNested(string $field, Validator $validator[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Nesting validators allows you to define validators for array types. For example, nested validators are ideal when you want to validate a sub-document, or complex array type.

This method assumes that the sub-document has a 1:1 relationship with the parent.

The providers of the parent validator will be synced into the nested validator, when errors are checked. This ensures that any validation rule providers connected in the parent will have the same values in the nested validator when rules are evaluated.

Parameters

$field : string: The root field for the nested validator.
$validator : Validator: The nested validator.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

addNestedMany()

Adds a nested validator.


    public
                    addNestedMany(string $field, Validator $validator[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Nesting validators allows you to define validators for array types. For example, nested validators are ideal when you want to validate many similar sub-documents or complex array types.

This method assumes that the sub-document has a 1:N relationship with the parent.

Parameters

$field : string: The root field for the nested validator.
$validator : Validator: The nested validator.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

allowEmpty()

Allows a field to be empty. You can also pass array.


    public
                    allowEmpty(array<string|int, mixed>|string $field[, callable|string|bool $when = true ][, string|null $message = null ]) : $this

Use , , , , , or instead.

Using an array will let you provide the following keys:

when individual when condition for field
'message' individual message for field

You can also set when and message for all passed fields, the individual setting takes precedence over group settings.

This is the opposite of notEmpty() which requires a field to not be empty. By using $mode equal to 'create' or 'update', you can allow fields to be empty when records are first created, or when they are updated.

Example:

// Email can be empty
$validator->allowEmpty('email');

// Email can be empty on create
$validator->allowEmpty('email', Validator::WHEN_CREATE);

// Email can be empty on update
$validator->allowEmpty('email', Validator::WHEN_UPDATE);

// Email and subject can be empty on update
$validator->allowEmpty(['email', 'subject'], Validator::WHEN_UPDATE;

// Email can be always empty, subject and content can be empty on update.
$validator->allowEmpty(
     [
         'email' => [
             'when' => true
         ],
         'content' => [
             'message' => 'Content cannot be empty'
         ],
         'subject'
     ],
     Validator::WHEN_UPDATE
);

It is possible to conditionally allow emptiness on a field by passing a callback as a second argument. The callback will receive the validation context array as argument:

$validator->allowEmpty('email', function ($context) {
 return !$context['newRecord'] || $context['data']['role'] === 'admin';
});

This method will correctly detect empty file uploads and date/time/datetime fields.

Because this and notEmpty() modify the same internal state, the last method called will take precedence.

Parameters

$field : array<string|int, mixed>|string: the name of the field or a list of fields
$when : callable|string|bool = true: Indicates when the field is allowed to be empty Valid values are true (always), 'create', 'update'. If a callable is passed then the field will allowed to be empty only when the callback returns true.
$message : string|null = null: The message to show if the field is not

Return values

$this

allowEmptyArray()

Allows a field to be an empty array.


    public
                    allowEmptyArray(string $field[, string|null $message = null ][, callable|string|bool $when = true ]) : $this

This method is equivalent to calling allowEmptyFor() with EMPTY_STRING + EMPTY_ARRAY flags.

Parameters

$field : string: The name of the field.
$message : string|null = null: The message to show if the field is not
$when : callable|string|bool = true: Indicates when the field is allowed to be empty Valid values are true, false, 'create', 'update'. If a callable is passed then the field will allowed to be empty only when the callback returns true.

Return values

$this

allowEmptyDate()

Allows a field to be an empty date.


    public
                    allowEmptyDate(string $field[, string|null $message = null ][, callable|string|bool $when = true ]) : $this

Empty date values are null, '', [] and arrays where all values are '' and the year key is present.

Parameters

$field : string: The name of the field.
$message : string|null = null: The message to show if the field is not
$when : callable|string|bool = true: Indicates when the field is allowed to be empty Valid values are true, false, 'create', 'update'. If a callable is passed then the field will allowed to be empty only when the callback returns true.

Return values

$this

allowEmptyDateTime()

Allows a field to be an empty date/time.


    public
                    allowEmptyDateTime(string $field[, string|null $message = null ][, callable|string|bool $when = true ]) : $this

Empty date values are null, '', [] and arrays where all values are '' and the year and hour keys are present.

This method is equivalent to calling allowEmptyFor() with EMPTY_STRING + EMPTY_DATE + EMPTY_TIME flags.

Parameters

$field : string: The name of the field.
$message : string|null = null: The message to show if the field is not
$when : callable|string|bool = true: Indicates when the field is allowed to be empty Valid values are true, false, 'create', 'update'. If a callable is passed then the field will allowed to be empty only when the callback returns false.

Return values

$this

allowEmptyFile()

Allows a field to be an empty file.


    public
                    allowEmptyFile(string $field[, string|null $message = null ][, callable|string|bool $when = true ]) : $this

This method is equivalent to calling allowEmptyFor() with EMPTY_FILE flag. File fields will not accept '', or [] as empty values. Only null and a file upload with error equal to UPLOAD_ERR_NO_FILE will be treated as empty.

Parameters

$field : string: The name of the field.
$message : string|null = null: The message to show if the field is not
$when : callable|string|bool = true: Indicates when the field is allowed to be empty Valid values are true, 'create', 'update'. If a callable is passed then the field will allowed to be empty only when the callback returns true.

Return values

$this

allowEmptyFor()

Low-level method to indicate that a field can be empty.


    public
                    allowEmptyFor(string $field[, int|null $flags = null ][, callable|string|bool $when = true ][, string|null $message = null ]) : $this

This method should generally not be used and instead you should use:

allowEmptyString()
allowEmptyArray()
allowEmptyFile()
allowEmptyDate()
allowEmptyDatetime()
allowEmptyTime()

Should be used as their APIs are simpler to operate and read.

You can also set flags, when and message for all passed fields, the individual setting takes precedence over group settings.

Example:

// Email can be empty
$validator->allowEmptyFor('email', Validator::EMPTY_STRING);

// Email can be empty on create
$validator->allowEmptyFor('email', Validator::EMPTY_STRING, Validator::WHEN_CREATE);

// Email can be empty on update
$validator->allowEmptyFor('email', Validator::EMPTY_STRING, Validator::WHEN_UPDATE);

It is possible to conditionally allow emptiness on a field by passing a callback as a second argument. The callback will receive the validation context array as argument:

$validator->allowEmpty('email', Validator::EMPTY_STRING, function ($context) {
  return !$context['newRecord'] || $context['data']['role'] === 'admin';
});

If you want to allow other kind of empty data on a field, you need to pass other flags:

$validator->allowEmptyFor('photo', Validator::EMPTY_FILE);
$validator->allowEmptyFor('published', Validator::EMPTY_STRING | Validator::EMPTY_DATE | Validator::EMPTY_TIME);
$validator->allowEmptyFor('items', Validator::EMPTY_STRING | Validator::EMPTY_ARRAY);

You can also use convenience wrappers of this method. The following calls are the same as above:

$validator->allowEmptyFile('photo');
$validator->allowEmptyDateTime('published');
$validator->allowEmptyArray('items');

Parameters

$field : string: The name of the field.
$flags : int|null = null: A bitmask of EMPTY_* flags which specify what is empty. If no flags/bitmask is provided only null will be allowed as empty value.
$when : callable|string|bool = true: Indicates when the field is allowed to be empty Valid values are true, false, 'create', 'update'. If a callable is passed then the field will allowed to be empty only when the callback returns true.
$message : string|null = null: The message to show if the field is not

Return values

$this

allowEmptyString()

Allows a field to be an empty string.


    public
                    allowEmptyString(string $field[, string|null $message = null ][, callable|string|bool $when = true ]) : $this

This method is equivalent to calling allowEmptyFor() with EMPTY_STRING flag.

Parameters

$field : string: The name of the field.
$message : string|null = null: The message to show if the field is not
$when : callable|string|bool = true: Indicates when the field is allowed to be empty Valid values are true, false, 'create', 'update'. If a callable is passed then the field will allowed to be empty only when the callback returns true.

Return values

$this

allowEmptyTime()

Allows a field to be an empty time.


    public
                    allowEmptyTime(string $field[, string|null $message = null ][, callable|string|bool $when = true ]) : $this

Empty date values are null, '', [] and arrays where all values are '' and the hour key is present.

This method is equivalent to calling allowEmptyFor() with EMPTY_STRING + EMPTY_TIME flags.

Parameters

$field : string: The name of the field.
$message : string|null = null: The message to show if the field is not
$when : callable|string|bool = true: Indicates when the field is allowed to be empty Valid values are true, false, 'create', 'update'. If a callable is passed then the field will allowed to be empty only when the callback returns true.

Return values

$this

alphaNumeric()

Add an alphanumeric rule to a field.


    public
                    alphaNumeric(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

ascii()

Add a validation rule to ensure a field contains only ascii bytes


    public
                    ascii(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

asciiAlphaNumeric()

Add an ascii-alphanumeric rule to a field.


    public
                    asciiAlphaNumeric(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

boolean()

Add a boolean validation rule to a field.


    public
                    boolean(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

containsNonAlphaNumeric()

Add a rule to check if a field contains non alpha numeric characters.


    public
                    containsNonAlphaNumeric(string $field[, int $limit = 1 ][, string|null $message = null ][, callable|string|null $when = null ]) : $this

Use instead. Will be removed in 5.0

Parameters

$field : string: The field you want to apply the rule to.
$limit : int = 1: The minimum number of non-alphanumeric fields required.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

count()

Returns the number of fields having validation rules


    public
                    count() : int

Return values

int

creditCard()

Add a credit card rule to a field.


    public
                    creditCard(string $field[, string $type = 'all' ][, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$type : string = 'all': The type of cards you want to allow. Defaults to 'all'. You can also supply an array of accepted card types. e.g ['mastercard', 'visa', 'amex']
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

date()

Add a date format validation rule to a field.


    public
                    date(string $field[, array<string|int, string> $formats = ['ymd'] ][, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$formats : array<string|int, string> = ['ymd']: A list of accepted date formats.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

dateTime()

Add a date time format validation rule to a field.


    public
                    dateTime(string $field[, array<string|int, string> $formats = ['ymd'] ][, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$formats : array<string|int, string> = ['ymd']: A list of accepted date formats.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

decimal()

Add a decimal validation rule to a field.


    public
                    decimal(string $field[, int|null $places = null ][, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$places : int|null = null: The number of decimal places to require.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

email()

Add an email validation rule to a field.


    public
                    email(string $field[, bool $checkMX = false ][, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$checkMX : bool = false: Whether to check the MX records.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

equals()

Add a equal to comparison rule to a field.


    public
                    equals(string $field, float|int $value[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$value : float|int: The value user data must be equal to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

equalToField()

Add a rule to compare one field is equal to another.


    public
                    equalToField(string $field, string $secondField[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$secondField : string: The field you want to compare against.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

errors()

Validates and returns an array of failed fields and their error messages.


    public
                    errors(array<string|int, mixed> $data[, bool $newRecord = true ]) : array<string|int, array<string|int, mixed>>

Renamed to .

Parameters

$data : array<string|int, mixed>: The data to be checked for errors
$newRecord : bool = true: whether the data to be validated is new or to be updated.

Return values

array<string|int, array<string|int, mixed>> —

Array of failed fields

field()

Returns a ValidationSet object containing all validation rules for a field, if passed a ValidationSet as second argument, it will replace any other rule set defined before


    public
                    field(string $name[, ValidationSet|null $set = null ]) : ValidationSet

Parameters

$name : string: [optional] The fieldname to fetch.
$set : ValidationSet|null = null: The set of rules for field

Return values

ValidationSet

getDefaultProvider()

Returns the default provider stored under that name if it exists.


    public
            static        getDefaultProvider(string $name) : object|string|null

Parameters

$name : string: The name under which the provider should be retrieved.

Return values

object|string|null

getDefaultProviders()

Get the list of default providers.


    public
            static        getDefaultProviders() : array<string|int, string>

Return values

array<string|int, string>

getIterator()

Returns an iterator for each of the fields to be validated


    public
                    getIterator() : Traversable<string, ValidationSet>

Return values

Traversable<string, ValidationSet>

getNotEmptyMessage()

Gets the notEmpty message for a field


    public
                    getNotEmptyMessage(string $field) : string|null

Parameters

$field : string: Field name

Return values

string|null

getProvider()

Returns the provider stored under that name if it exists.


    public
                    getProvider(string $name) : object|string|null

Parameters

$name : string: The name under which the provider should be set.

Return values

object|string|null

getRequiredMessage()

Gets the required message for a field


    public
                    getRequiredMessage(string $field) : string|null

Parameters

$field : string: Field name

Return values

string|null

greaterThan()

Add a greater than comparison rule to a field.


    public
                    greaterThan(string $field, float|int $value[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$value : float|int: The value user data must be greater than.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

greaterThanField()

Add a rule to compare one field is greater than another.


    public
                    greaterThanField(string $field, string $secondField[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$secondField : string: The field you want to compare against.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

greaterThanOrEqual()

Add a greater than or equal to comparison rule to a field.


    public
                    greaterThanOrEqual(string $field, float|int $value[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$value : float|int: The value user data must be greater than or equal to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

greaterThanOrEqualToField()

Add a rule to compare one field is greater than or equal to another.


    public
                    greaterThanOrEqualToField(string $field, string $secondField[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$secondField : string: The field you want to compare against.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

hasAtLeast()

Add a validation rule to ensure that a field is an array containing at least the specified amount of elements


    public
                    hasAtLeast(string $field, int $count[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$count : int: The number of elements the array should at least have
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

hasAtMost()

Add a validation rule to ensure that a field is an array containing at most the specified amount of elements


    public
                    hasAtMost(string $field, int $count[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$count : int: The number maximum amount of elements the field should have
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

hasField()

Check whether a validator contains any rules for the given field.


    public
                    hasField(string $name) : bool

Parameters

$name : string: The field name to check.

Return values

bool

hexColor()

Add a validation rule to ensure a field is a 6 digits hex color value.


    public
                    hexColor(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

inList()

Add a validation rule to ensure the field value is within an allowed list.


    public
                    inList(string $field, array<string|int, mixed> $list[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$list : array<string|int, mixed>: The list of valid options.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

integer()

Add a validation rule to ensure a field is an integer value.


    public
                    integer(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

ip()

Add an IP validation rule to a field.


    public
                    ip(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

This rule will accept both IPv4 and IPv6 addresses.

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

ipv4()

Add an IPv4 validation rule to a field.


    public
                    ipv4(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

ipv6()

Add an IPv6 validation rule to a field.


    public
                    ipv6(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

isArray()

Add a validation rule to ensure that a field contains an array.


    public
                    isArray(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

isEmptyAllowed()

Returns whether a field can be left empty for a new or already existing record.


    public
                    isEmptyAllowed(string $field, bool $newRecord) : bool

Parameters

$field : string: Field name.
$newRecord : bool: whether the data to be validated is new or to be updated.

Return values

bool

isPresenceRequired()

Returns whether a field can be left out for a new or already existing record.


    public
                    isPresenceRequired(string $field, bool $newRecord) : bool

Parameters

$field : string: Field name.
$newRecord : bool: Whether the data to be validated is new or to be updated.

Return values

bool

latitude()

Add a validation rule to ensure the field is a latitude.


    public
                    latitude(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

latLong()

Add a validation rule to ensure the field is a lat/long tuple.


    public
                    latLong(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

e.g. <lat>, <lng>

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

lengthBetween()

Add an rule that ensures a string length is within a range.


    public
                    lengthBetween(string $field, array<string|int, mixed> $range[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$range : array<string|int, mixed>: The inclusive minimum and maximum length you want permitted.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

lessThan()

Add a less than comparison rule to a field.


    public
                    lessThan(string $field, float|int $value[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$value : float|int: The value user data must be less than.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

lessThanField()

Add a rule to compare one field is less than another.


    public
                    lessThanField(string $field, string $secondField[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$secondField : string: The field you want to compare against.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

lessThanOrEqual()

Add a less than or equal comparison rule to a field.


    public
                    lessThanOrEqual(string $field, float|int $value[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$value : float|int: The value user data must be less than or equal to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

lessThanOrEqualToField()

Add a rule to compare one field is less than or equal to another.


    public
                    lessThanOrEqualToField(string $field, string $secondField[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$secondField : string: The field you want to compare against.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

localizedTime()

Add a localized time, date or datetime format validation rule to a field.


    public
                    localizedTime(string $field[, string $type = 'datetime' ][, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$type : string = 'datetime': Parser type, one out of 'date', 'time', and 'datetime'
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

longitude()

Add a validation rule to ensure the field is a longitude.


    public
                    longitude(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

maxLength()

Add a string length validation rule to a field.


    public
                    maxLength(string $field, int $max[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$max : int: The maximum length allowed.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

maxLengthBytes()

Add a string length validation rule to a field.


    public
                    maxLengthBytes(string $field, int $max[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$max : int: The maximum length allowed.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

minLength()

Add a string length validation rule to a field.


    public
                    minLength(string $field, int $min[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$min : int: The minimum length required.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

minLengthBytes()

Add a string length validation rule to a field.


    public
                    minLengthBytes(string $field, int $min[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$min : int: The minimum length required.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

multipleOptions()

Add a validation rule for a multiple select. Comparison is case sensitive by default.


    public
                    multipleOptions(string $field[, array<string, mixed> $options = [] ][, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$options : array<string, mixed> = []: The options for the validator. Includes the options defined in \Cake\Validation\Validation::multiple() and the caseInsensitive parameter.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

naturalNumber()

Add a natural number validation rule to a field.


    public
                    naturalNumber(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

nonNegativeInteger()

Add a validation rule to ensure a field is a non negative integer.


    public
                    nonNegativeInteger(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

notAlphaNumeric()

Add a non-alphanumeric rule to a field.


    public
                    notAlphaNumeric(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

notAsciiAlphaNumeric()

Add a non-ascii alphanumeric rule to a field.


    public
                    notAsciiAlphaNumeric(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

notBlank()

Add a notBlank rule to a field.


    public
                    notBlank(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

notEmpty()

Sets a field to require a non-empty value. You can also pass array.


    public
                    notEmpty(array<string|int, mixed>|string $field[, string|null $message = null ][, callable|string|bool $when = false ]) : $this

Use , , , , or instead.

Using an array will let you provide the following keys:

when individual when condition for field
message individual error message for field

You can also set when and message for all passed fields, the individual setting takes precedence over group settings.

This is the opposite of allowEmpty() which allows a field to be empty. By using $mode equal to 'create' or 'update', you can make fields required when records are first created, or when they are updated.

Example:

$message = 'This field cannot be empty';

// Email cannot be empty
$validator->notEmpty('email');

// Email can be empty on update, but not create
$validator->notEmpty('email', $message, 'create');

// Email can be empty on create, but required on update.
$validator->notEmpty('email', $message, Validator::WHEN_UPDATE);

// Email and title can be empty on create, but are required on update.
$validator->notEmpty(['email', 'title'], $message, Validator::WHEN_UPDATE);

// Email can be empty on create, title must always be not empty
$validator->notEmpty(
     [
         'email',
         'title' => [
             'when' => true,
             'message' => 'Title cannot be empty'
         ]
     ],
     $message,
     Validator::WHEN_UPDATE
);

It is possible to conditionally disallow emptiness on a field by passing a callback as the third argument. The callback will receive the validation context array as argument:

$validator->notEmpty('email', 'Email is required', function ($context) {
  return $context['newRecord'] && $context['data']['role'] !== 'admin';
});

Because this and allowEmpty() modify the same internal state, the last method called will take precedence.

Parameters

$field : array<string|int, mixed>|string: the name of the field or list of fields
$message : string|null = null: The message to show if the field is not
$when : callable|string|bool = false: Indicates when the field is not allowed to be empty. Valid values are true (always), 'create', 'update'. If a callable is passed then the field will allowed to be empty only when the callback returns false.

Return values

$this

notEmptyArray()

Require a field to be a non-empty array


    public
                    notEmptyArray(string $field[, string|null $message = null ][, callable|string|bool $when = false ]) : $this

Opposite to allowEmptyArray()

Parameters

$field : string: The name of the field.
$message : string|null = null: The message to show if the field is empty.
$when : callable|string|bool = false: Indicates when the field is not allowed to be empty. Valid values are false (never), 'create', 'update'. If a callable is passed then the field will be required to be not empty when the callback returns true.

Return values

$this

notEmptyDate()

Require a non-empty date value


    public
                    notEmptyDate(string $field[, string|null $message = null ][, callable|string|bool $when = false ]) : $this

Parameters

$field : string: The name of the field.
$message : string|null = null: The message to show if the field is empty.
$when : callable|string|bool = false: Indicates when the field is not allowed to be empty. Valid values are false (never), 'create', 'update'. If a callable is passed then the field will be required to be not empty when the callback returns true.

Return values

$this

notEmptyDateTime()

Require a field to be a non empty date/time.


    public
                    notEmptyDateTime(string $field[, string|null $message = null ][, callable|string|bool $when = false ]) : $this

Opposite to allowEmptyDateTime

Parameters

$field : string: The name of the field.
$message : string|null = null: The message to show if the field is empty.
$when : callable|string|bool = false: Indicates when the field is not allowed to be empty. Valid values are false (never), 'create', 'update'. If a callable is passed then the field will be required to be not empty when the callback returns true.

Return values

$this

notEmptyFile()

Require a field to be a not-empty file.


    public
                    notEmptyFile(string $field[, string|null $message = null ][, callable|string|bool $when = false ]) : $this

Opposite to allowEmptyFile()

Parameters

$field : string: The name of the field.
$message : string|null = null: The message to show if the field is empty.
$when : callable|string|bool = false: Indicates when the field is not allowed to be empty. Valid values are false (never), 'create', 'update'. If a callable is passed then the field will be required to be not empty when the callback returns true.

Return values

$this

notEmptyString()

Requires a field to not be an empty string.


    public
                    notEmptyString(string $field[, string|null $message = null ][, callable|string|bool $when = false ]) : $this

Opposite to allowEmptyString()

Parameters

$field : string: The name of the field.
$message : string|null = null: The message to show if the field is empty.
$when : callable|string|bool = false: Indicates when the field is not allowed to be empty. Valid values are false (never), 'create', 'update'. If a callable is passed then the field will be required to be not empty when the callback returns true.

Return values

$this

notEmptyTime()

Require a field to be a non-empty time.


    public
                    notEmptyTime(string $field[, string|null $message = null ][, callable|string|bool $when = false ]) : $this

Opposite to allowEmptyTime()

Parameters

$field : string: The name of the field.
$message : string|null = null: The message to show if the field is empty.
$when : callable|string|bool = false: Indicates when the field is not allowed to be empty. Valid values are false (never), 'create', 'update'. If a callable is passed then the field will be required to be not empty when the callback returns true.

Return values

$this

notEquals()

Add a not equal to comparison rule to a field.


    public
                    notEquals(string $field, float|int $value[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$value : float|int: The value user data must be not be equal to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

notEqualToField()

Add a rule to compare one field is not equal to another.


    public
                    notEqualToField(string $field, string $secondField[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$secondField : string: The field you want to compare against.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

notSameAs()

Add a rule to compare that two fields have different values.


    public
                    notSameAs(string $field, string $secondField[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$secondField : string: The field you want to compare against.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

numeric()

Add a numeric value validation rule to a field.


    public
                    numeric(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

offsetExists()

Returns whether a rule set is defined for a field or not


    public
                    offsetExists(string $field) : bool

Parameters

$field : string: name of the field to check

Return values

bool

offsetGet()

Returns the rule set for a field


    public
                    offsetGet(string|int $field) : ValidationSet

Parameters

$field : string|int: name of the field to check

Return values

ValidationSet

offsetSet()

Sets the rule set for a field


    public
                    offsetSet(string $field, ValidationSet|array<string|int, mixed> $rules) : void

Parameters

$field : string: name of the field to set
$rules : ValidationSet|array<string|int, mixed>: set of rules to apply to field

offsetUnset()

Unsets the rule set for a field


    public
                    offsetUnset(string $field) : void

Parameters

$field : string: name of the field to unset

providers()

Get the list of providers in this validator.


    public
                    providers() : array<string|int, string>

Return values

array<string|int, string>

range()

Add a validation rule to ensure a field is within a numeric range


    public
                    range(string $field, array<string|int, mixed> $range[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$range : array<string|int, mixed>: The inclusive upper and lower bounds of the valid range.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

regex()

Returns whether a field matches against a regular expression.


    public
                    regex(string $field, string $regex[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: Field name.
$regex : string: Regular expression.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

remove()

Removes a rule from the set by its name


    public
                    remove(string $field[, string|null $rule = null ]) : $this

Example:

     $validator
         ->remove('title', 'required')
         ->remove('user_id')

Parameters

$field : string: The name of the field from which the rule will be removed
$rule : string|null = null: the name of the rule to be removed

Return values

$this

requirePresence()

Sets whether a field is required to be present in data array.


    public
                    requirePresence(array<string|int, mixed>|string $field[, callable|string|bool $mode = true ][, string|null $message = null ]) : $this

You can also pass array. Using an array will let you provide the following keys:

mode individual mode for field
message individual error message for field

You can also set mode and message for all passed fields, the individual setting takes precedence over group settings.

Parameters

$field : array<string|int, mixed>|string: the name of the field or list of fields.
$mode : callable|string|bool = true: Valid values are true, false, 'create', 'update'. If a callable is passed then the field will be required only when the callback returns true.
$message : string|null = null: The message to show if the field presence validation fails.

Return values

$this

sameAs()

Add a rule to compare two fields to each other.


    public
                    sameAs(string $field, string $secondField[, string|null $message = null ][, callable|string|null $when = null ]) : $this

If both fields have the exact same value the rule will pass.

Parameters

$field : string: The field you want to apply the rule to.
$secondField : string: The field you want to compare against.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

scalar()

Add a validation rule to ensure that a field contains a scalar.


    public
                    scalar(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

setProvider()

Associates an object to a name so it can be used as a provider. Providers are objects or class names that can contain methods used during validation of for deciding whether a validation rule can be applied. All validation methods, when called will receive the full list of providers stored in this validator.


    public
                    setProvider(string $name, object|string $object) : $this

Parameters

$name : string: The name under which the provider should be set.
$object : object|string: Provider object or class name.

Return values

$this

setStopOnFailure()

Whether to stop validation rule evaluation on the first failed rule.


    public
                    setStopOnFailure([bool $stopOnFailure = true ]) : $this

When enabled the first failing rule per field will cause validation to stop. When disabled all rules will be run even if there are failures.

Parameters

$stopOnFailure : bool = true: If to apply last flag.

Return values

$this

time()

Add a time format validation rule to a field.


    public
                    time(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

uploadedFile()

Add a validation rule to ensure the field is an uploaded file


    public
                    uploadedFile(string $field, array<string, mixed> $options[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$options : array<string, mixed>: An array of options.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

url()

Add a validation rule to ensure a field is a URL.


    public
                    url(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

This validator does not require a protocol.

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

urlWithProtocol()

Add a validation rule to ensure a field is a URL.


    public
                    urlWithProtocol(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

This validator requires the URL to have a protocol.

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

utf8()

Add a validation rule to ensure a field contains only BMP utf8 bytes


    public
                    utf8(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

utf8Extended()

Add a validation rule to ensure a field contains only utf8 bytes.


    public
                    utf8Extended(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

This rule will accept 3 and 4 byte UTF8 sequences, which are necessary for emoji.

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

uuid()

Add a validation rule to ensure the field is a UUID


    public
                    uuid(string $field[, string|null $message = null ][, callable|string|null $when = null ]) : $this

Parameters

$field : string: The field you want to apply the rule to.
$message : string|null = null: The error message when the rule fails.
$when : callable|string|null = null: Either 'create' or 'update' or a callable that returns true when the validation rule should be applied.

Return values

$this

validate()

Validates and returns an array of failed fields and their error messages.


    public
                    validate(array<string|int, mixed> $data[, bool $newRecord = true ]) : array<string|int, array<string|int, mixed>>

Parameters

$data : array<string|int, mixed>: The data to be checked for errors
$newRecord : bool = true: whether the data to be validated is new or to be updated.

Return values

array<string|int, array<string|int, mixed>> —

Array of failed fields

_canBeEmpty()

Returns whether the field can be left blank according to `allowEmpty`


    protected
                    _canBeEmpty(ValidationSet $field, array<string, mixed> $context) : bool

Parameters

$field : ValidationSet: the set of rules for a field
$context : array<string, mixed>: a key value list of data containing the validation context.

Return values

bool

_checkPresence()

Returns false if any validation for the passed rule set should be stopped due to the field missing in the data array


    protected
                    _checkPresence(ValidationSet $field, array<string, mixed> $context) : bool

Parameters

$field : ValidationSet: The set of rules for a field.
$context : array<string, mixed>: A key value list of data containing the validation context.

Return values

bool

_convertValidatorToArray()

Converts validator to fieldName => $settings array


    protected
                    _convertValidatorToArray(string|int $fieldName[, array<string, mixed> $defaults = [] ][, array<string|int, mixed>|string $settings = [] ]) : array<string|int, array<string|int, mixed>>

Parameters

$fieldName : string|int: name of field
$defaults : array<string, mixed> = []: default settings
$settings : array<string|int, mixed>|string = []: settings from data

Return values

array<string|int, array<string|int, mixed>>

_fieldIsEmpty()

Returns true if the field is empty in the passed data array


    protected
                    _fieldIsEmpty(mixed $data) : bool

Use instead

Parameters

$data : mixed: Value to check against.

Return values

bool

_processRules()

Iterates over each rule in the validation set and collects the errors resulting from executing them


    protected
                    _processRules(string $field, ValidationSet $rules, array<string|int, mixed> $data, bool $newRecord) : array<string, mixed>

Parameters

$field : string: The name of the field that is being processed
$rules : ValidationSet: the list of rules for a field
$data : array<string|int, mixed>: the full data passed to the validator
$newRecord : bool: whether is it a new record or an existing one

Return values

array<string, mixed>

invertWhenClause()

Invert a when clause for creating notEmpty rules


    protected
                    invertWhenClause(callable|string|bool $when) : callable|string|bool

Parameters

$when : callable|string|bool: Indicates when the field is not allowed to be empty. Valid values are true (always), 'create', 'update'. If a callable is passed then the field will allowed to be empty only when the callback returns false.

Return values

callable|string|bool

isEmpty()

Returns true if the field is empty in the passed data array


    protected
                    isEmpty(mixed $data, int $flags) : bool

Parameters

$data : mixed: Value to check against.
$flags : int: A bitmask of EMPTY_* flags which specify what is empty

Return values

bool

Validator in package Application implements ArrayAccess, IteratorAggregate, Countable

Tags

Table of Contents

Interfaces

Constants

Properties

Methods

Constants

EMPTY_ALL

EMPTY_ARRAY

EMPTY_DATE

EMPTY_FILE

EMPTY_NULL

EMPTY_STRING

EMPTY_TIME

NESTED

WHEN_CREATE

WHEN_UPDATE

Properties

$_allowEmptyFlags

$_allowEmptyMessages

$_defaultProviders

Tags

$_fields

$_presenceMessages

$_providers

Tags

$_stopOnFailure

$_useI18n

Methods

__construct()

__debugInfo()

Return values

add()

Example:

Parameters

Tags

Return values

addDefaultProvider()

Parameters

Tags

addNested()

Parameters

Return values

addNestedMany()

Parameters

Return values

allowEmpty()

Example:

Parameters

Return values

allowEmptyArray()

Parameters

Tags

Return values

allowEmptyDate()

Parameters

Tags

Return values

allowEmptyDateTime()

Parameters

Tags

Return values

allowEmptyFile()

Parameters

Tags

Return values

allowEmptyFor()

Example:

Parameters

Tags

Return values

allowEmptyString()

Parameters

Tags

Return values

allowEmptyTime()

Parameters

Tags

Return values

Validator
in package

Application

implements ArrayAccess, IteratorAggregate, Countable