Class RulesChecker

ORM flavoured rules checker.

Adds ORM related features to the RulesChecker class.

Namespace: Cake\ORM
See: \Cake\Datasource\RulesChecker

Constants

string

CREATE ¶
```
'create'
```
Indicates that the checking rules to apply are those used for creating entities
string

DELETE ¶
```
'delete'
```
Indicates that the checking rules to apply are those used for deleting entities
string

UPDATE ¶
```
'update'
```
Indicates that the checking rules to apply are those used for updating entities

Property Summary

$_createRules protected

arrayCake\Datasource\RuleInvoker>

The list of rules to check during create operations
$_deleteRules protected

arrayCake\Datasource\RuleInvoker>

The list of rules to check during delete operations
$_options protected

array

List of options to pass to every callable rule
$_rules protected

arrayCake\Datasource\RuleInvoker>

The list of rules to be checked on both create and update operations
$_updateRules protected

arrayCake\Datasource\RuleInvoker>

The list of rules to check during update operations
$_useI18n protected

bool

Whether to use I18n functions for translating default error messages

Method Summary

__construct() public

Constructor. Takes the options to be passed to all rules.
_addError() protected

Utility method for decorating any callable so that if it returns false, the correct property in the entity is marked as invalid.
_addLinkConstraintRule() protected

Adds a link constraint rule.
_checkRules() protected

Used by top level functions checkDelete, checkCreate and checkUpdate, this function iterates an array containing the rules to be checked and checks them all.
add() public

Adds a rule that will be applied to the entity both on create and update operations.
addCreate() public

Adds a rule that will be applied to the entity on create operations.
addDelete() public

Adds a rule that will be applied to the entity on delete operations.
addUpdate() public

Adds a rule that will be applied to the entity on update operations.
check() public

Runs each of the rules by passing the provided entity and returns true if all of them pass. The rules to be applied are depended on the $mode parameter which can only be RulesChecker::CREATE, RulesChecker::UPDATE or RulesChecker::DELETE
checkCreate() public

Runs each of the rules by passing the provided entity and returns true if all of them pass. The rules selected will be only those specified to be run on 'create'
checkDelete() public

Runs each of the rules by passing the provided entity and returns true if all of them pass. The rules selected will be only those specified to be run on 'delete'
checkName() protected

Checks that a rule with the same name doesn't already exist
checkUpdate() public

Runs each of the rules by passing the provided entity and returns true if all of them pass. The rules selected will be only those specified to be run on 'update'
existsIn() public

Returns a callable that can be used as a rule for checking that the values extracted from the entity to check exist as the primary key in another table.
isLinkedTo() public

Validates whether links to the given association exist.
isNotLinkedTo() public

Validates whether links to the given association do not exist.
isUnique() public

Returns a callable that can be used as a rule for checking the uniqueness of a value in the table.
remove() public

Removes a rule from the set.
removeCreate() public

Removes a rule from the create set.
removeDelete() public

Removes a rule from the delete set.
removeUpdate() public

Removes a rule from the update set.
validCount() public

Validates the count of associated records.

Method Detail

__construct() ¶ public

__construct(array<string, mixed> $options = [])

Constructor. Takes the options to be passed to all rules.

Parameters

array<string, mixed> $options optional: The options to pass to every rule

_addError() ¶ protected

_addError(callable $rule, array|string|null $name = null, array<string, mixed> $options = []): Cake\Datasource\RuleInvoker

Utility method for decorating any callable so that if it returns false, the correct property in the entity is marked as invalid.

Parameters

callable $rule: The rule to decorate
array|string|null $name optional: The alias for a rule or an array of options
array<string, mixed> $options optional: The options containing the error message and field.

Returns

Cake\Datasource\RuleInvoker

_addLinkConstraintRule() ¶ protected

_addLinkConstraintRule(Cake\ORM\Association|string $association, string|null $errorField, string|null $message, string $linkStatus, string $ruleName): Cake\Datasource\RuleInvoker

Adds a link constraint rule.

Parameters

Cake\ORM\Association|string $association: The association to check for links.
string|null $errorField: The name of the property to use for setting possible errors. When absent, the name is inferred from $association.
string|null $message: The error message to show in case the rule does not pass.
string $linkStatus: The ink status required for the check to pass.
string $ruleName: The alias/name of the rule.

Returns

Cake\Datasource\RuleInvoker

Throws

InvalidArgumentException
In case the `$association` argument is of an invalid type.

_checkRules() ¶ protected

_checkRules(Cake\Datasource\EntityInterface $entity, array<string, mixed> $options = [], arrayCake\Datasource\RuleInvoker> $rules = []): bool

Used by top level functions checkDelete, checkCreate and checkUpdate, this function iterates an array containing the rules to be checked and checks them all.

Parameters

Cake\Datasource\EntityInterface $entity: The entity to check for validity.
array<string, mixed> $options optional: Extra options to pass to checker functions.
arrayCake\Datasource\RuleInvoker> $rules optional: The list of rules that must be checked.

Returns

bool

add() ¶ public

add(callable $rule, array|string|null $name = null, array<string, mixed> $options = []): $this

Adds a rule that will be applied to the entity both on create and update operations.

Options

The options array accept the following special keys:

errorField: The name of the entity field that will be marked as invalid if the rule does not pass.
message: The error message to set to errorField if the rule does not pass.

Parameters

callable $rule: A callable function or object that will return whether the entity is valid or not.
array|string|null $name optional: The alias for a rule, or an array of options.
array<string, mixed> $options optional: List of extra options to pass to the rule callable as second argument.

Returns

$this

Throws

Cake\Core\Exception\CakeException
If a rule with the same name already exists

addCreate() ¶ public

addCreate(callable $rule, array|string|null $name = null, array<string, mixed> $options = []): $this

Adds a rule that will be applied to the entity on create operations.

Options

The options array accept the following special keys:

errorField: The name of the entity field that will be marked as invalid if the rule does not pass.
message: The error message to set to errorField if the rule does not pass.

Parameters

callable $rule: A callable function or object that will return whether the entity is valid or not.
array|string|null $name optional: The alias for a rule or an array of options.
array<string, mixed> $options optional: List of extra options to pass to the rule callable as second argument.

Returns

$this

Throws

Cake\Core\Exception\CakeException
If a rule with the same name already exists

addDelete() ¶ public

addDelete(callable $rule, array|string|null $name = null, array<string, mixed> $options = []): $this

Adds a rule that will be applied to the entity on delete operations.

Options

The options array accept the following special keys:

errorField: The name of the entity field that will be marked as invalid if the rule does not pass.
message: The error message to set to errorField if the rule does not pass.

Parameters

callable $rule: A callable function or object that will return whether the entity is valid or not.
array|string|null $name optional: The alias for a rule, or an array of options.
array<string, mixed> $options optional: List of extra options to pass to the rule callable as second argument.

Returns

$this

Throws

Cake\Core\Exception\CakeException
If a rule with the same name already exists

addUpdate() ¶ public

addUpdate(callable $rule, array|string|null $name = null, array<string, mixed> $options = []): $this

Adds a rule that will be applied to the entity on update operations.

Options

The options array accept the following special keys:

errorField: The name of the entity field that will be marked as invalid if the rule does not pass.
message: The error message to set to errorField if the rule does not pass.

Parameters

callable $rule: A callable function or object that will return whether the entity is valid or not.
array|string|null $name optional: The alias for a rule, or an array of options.
array<string, mixed> $options optional: List of extra options to pass to the rule callable as second argument.

Returns

$this

Throws

Cake\Core\Exception\CakeException
If a rule with the same name already exists

check() ¶ public

check(Cake\Datasource\EntityInterface $entity, string $mode, array<string, mixed> $options = []): bool

Runs each of the rules by passing the provided entity and returns true if all of them pass. The rules to be applied are depended on the $mode parameter which can only be RulesChecker::CREATE, RulesChecker::UPDATE or RulesChecker::DELETE

Parameters

Cake\Datasource\EntityInterface $entity: The entity to check for validity.
string $mode: Either 'create, 'update' or 'delete'.
array<string, mixed> $options optional: Extra options to pass to checker functions.

Returns

bool

Throws

InvalidArgumentException
if an invalid mode is passed.

checkCreate() ¶ public

checkCreate(Cake\Datasource\EntityInterface $entity, array<string, mixed> $options = []): bool

Runs each of the rules by passing the provided entity and returns true if all of them pass. The rules selected will be only those specified to be run on 'create'

Parameters

Cake\Datasource\EntityInterface $entity: The entity to check for validity.
array<string, mixed> $options optional: Extra options to pass to checker functions.

Returns

bool

checkDelete() ¶ public

checkDelete(Cake\Datasource\EntityInterface $entity, array<string, mixed> $options = []): bool

Runs each of the rules by passing the provided entity and returns true if all of them pass. The rules selected will be only those specified to be run on 'delete'

Parameters

Cake\Datasource\EntityInterface $entity: The entity to check for validity.
array<string, mixed> $options optional: Extra options to pass to checker functions.

Returns

bool

checkName() ¶ protected

checkName(string $name, arrayCake\Datasource\RuleInvoker> $rules): void

Checks that a rule with the same name doesn't already exist

Parameters

string $name: The name to check
arrayCake\Datasource\RuleInvoker> $rules: The rules array to check

Returns

void

Throws

Cake\Core\Exception\CakeException

checkUpdate() ¶ public

checkUpdate(Cake\Datasource\EntityInterface $entity, array<string, mixed> $options = []): bool

Runs each of the rules by passing the provided entity and returns true if all of them pass. The rules selected will be only those specified to be run on 'update'

Parameters

Cake\Datasource\EntityInterface $entity: The entity to check for validity.
array<string, mixed> $options optional: Extra options to pass to checker functions.

Returns

bool

existsIn() ¶ public

existsIn(list<string>|string $field, Cake\ORM\TableCake\ORM\Association|string $table, array<string, mixed>|string|null $message = null): Cake\Datasource\RuleInvoker

Returns a callable that can be used as a rule for checking that the values extracted from the entity to check exist as the primary key in another table.

This is useful for enforcing foreign key integrity checks.

Example:

$rules->add($rules->existsIn('author_id', 'Authors', 'Invalid Author'));

$rules->add($rules->existsIn('site_id', new SitesTable(), 'Invalid Site'));

Available $options are error 'message' and 'allowNullableNulls' flag. 'message' sets a custom error message. Set 'allowNullableNulls' to true to accept composite foreign keys where one or more nullable columns are null.

Parameters

list<string>|string $field: The field or list of fields to check for existence by primary key lookup in the other table.
Cake\ORM\TableCake\ORM\Association|string $table: The table name where the fields existence will be checked.
array<string, mixed>|string|null $message optional: The error message to show in case the rule does not pass. Can also be an array of options. When an array, the 'message' key can be used to provide a message.

Returns

Cake\Datasource\RuleInvoker

isLinkedTo() ¶ public

isLinkedTo(Cake\ORM\Association|string $association, string|null $field = null, string|null $message = null): Cake\Datasource\RuleInvoker

Validates whether links to the given association exist.

Example:

$rules->addUpdate($rules->isLinkedTo('Articles', 'article'));

On a Comments table that has a belongsTo Articles association, this check would ensure that comments can only be edited as long as they are associated to an existing article.

Parameters

Cake\ORM\Association|string $association: The association to check for links.
string|null $field optional: The name of the association property. When supplied, this is the name used to set possible errors. When absent, the name is inferred from $association.
string|null $message optional: The error message to show in case the rule does not pass.

Returns

Cake\Datasource\RuleInvoker

isNotLinkedTo() ¶ public

isNotLinkedTo(Cake\ORM\Association|string $association, string|null $field = null, string|null $message = null): Cake\Datasource\RuleInvoker

Validates whether links to the given association do not exist.

Example:

$rules->addDelete($rules->isNotLinkedTo('Comments', 'comments'));

On a Articles table that has a hasMany Comments association, this check would ensure that articles can only be deleted when no associated comments exist.

Parameters

Cake\ORM\Association|string $association: The association to check for links.
string|null $field optional: The name of the association property. When supplied, this is the name used to set possible errors. When absent, the name is inferred from $association.
string|null $message optional: The error message to show in case the rule does not pass.

Returns

Cake\Datasource\RuleInvoker

isUnique() ¶ public

isUnique(list<string> $fields, array<string, mixed>|string|null $message = null): Cake\Datasource\RuleInvoker

Returns a callable that can be used as a rule for checking the uniqueness of a value in the table.

Example

$rules->add($rules->isUnique(['email'], 'The email should be unique'));

Options

allowMultipleNulls Allows any field to have multiple null values. Defaults to false.

Parameters

list<string> $fields: The list of fields to check for uniqueness.
array<string, mixed>|string|null $message optional: The error message to show in case the rule does not pass. Can also be an array of options. When an array, the 'message' key can be used to provide a message.

Returns

Cake\Datasource\RuleInvoker

remove() ¶ public

remove(string $name): $this

Removes a rule from the set.

Parameters

string $name: The name of the rule to remove.

Returns

$this

removeCreate() ¶ public

removeCreate(string $name): $this

Removes a rule from the create set.

Parameters

string $name: The name of the rule to remove.

Returns

$this

removeDelete() ¶ public

removeDelete(string $name): $this

Removes a rule from the delete set.

Parameters

string $name: The name of the rule to remove.

Returns

$this

removeUpdate() ¶ public

removeUpdate(string $name): $this

Removes a rule from the update set.

Parameters

string $name: The name of the rule to remove.

Returns

$this

validCount() ¶ public

validCount(string $field, int $count = 0, string $operator = '>', string|null $message = null): Cake\Datasource\RuleInvoker

Validates the count of associated records.

Parameters

string $field: The field to check the count on.
int $count optional: The expected count.
string $operator optional: The operator for the count comparison.
string|null $message optional: The error message to show in case the rule does not pass.

Returns

Cake\Datasource\RuleInvoker

Property Detail

`$_createRules` ¶ protected

The list of rules to check during create operations

Type

arrayCake\Datasource\RuleInvoker>

`$_deleteRules` ¶ protected

The list of rules to check during delete operations

Type

arrayCake\Datasource\RuleInvoker>

`$_options` ¶ protected

List of options to pass to every callable rule

Type

array

`$_rules` ¶ protected

The list of rules to be checked on both create and update operations

Type

arrayCake\Datasource\RuleInvoker>

`$_updateRules` ¶ protected

The list of rules to check during update operations

Type

arrayCake\Datasource\RuleInvoker>

`$_useI18n` ¶ protected

Whether to use I18n functions for translating default error messages

Type

bool

Namespaces

Class RulesChecker

Constants

Property Summary

Method Summary

__construct() public

_addError() protected

_addLinkConstraintRule() protected

_checkRules() protected

add() public

addCreate() public

addDelete() public

addUpdate() public

check() public

checkCreate() public

checkDelete() public

checkName() protected

checkUpdate() public

existsIn() public

isLinkedTo() public

isNotLinkedTo() public

isUnique() public

remove() public

removeCreate() public

removeDelete() public

removeUpdate() public

validCount() public

Method Detail

__construct() ¶ public

Parameters

_addError() ¶ protected

Parameters

Returns

_addLinkConstraintRule() ¶ protected

Parameters

Returns

Throws

See Also

_checkRules() ¶ protected

Parameters

Returns

add() ¶ public

Options

Parameters

Returns

Throws

addCreate() ¶ public

Options

Parameters

Returns

Throws

addDelete() ¶ public

Options

Parameters

Returns

Throws

addUpdate() ¶ public

Options

Parameters

Returns

Throws

check() ¶ public

Parameters

Returns

Throws

checkCreate() ¶ public

Parameters

Returns

checkDelete() ¶ public

Parameters

Returns

checkName() ¶ protected

Parameters

Returns

Throws

checkUpdate() ¶ public

Parameters

Returns

existsIn() ¶ public

Example:

`$_createRules` ¶ protected

`$_deleteRules` ¶ protected

`$_options` ¶ protected

`$_rules` ¶ protected

`$_updateRules` ¶ protected

`$_useI18n` ¶ protected