CakePHP Validation

When to use

• The user needs rules that depend on the database, such as uniqueness or foreign-key existence, checked before a save commits.
• The user wants a custom validation rule, a named validation set, or a rule that applies only under certain conditions.
• The user needs to validate the shape of submitted data (required, length, format) before it is persisted in CakePHP.

When NOT to use

• Do not model "may this user perform this action" as a validation rule; that is an authorization concern handled by policies, not the Validator.
• Do not use this skill for Symfony Validator, Laravel validation, or Respect/Validation; the Validator and RulesChecker API is CakePHP specific.

Core guidance

• Enforce uniqueness with isUnique in buildRules, not the Validator — Add $rules->add($rules->isUnique(['email'])) in buildRules() for uniqueness, rather than trying to check it in the shape Validator.
• Validate shape with a Validator, integrity with application rules — Put format and presence checks (required, email, length) in validationDefault() where they run during marshalling; put database-dependent checks (unique, exists) in buildRules() where they run at save time.

Quick recipe

1. In the Table's validationDefault(Validator $validator), chain rules like requirePresence('email'), notEmptyString('email'), and email('email'). (verify: Marshalling malformed data populates the entity's errors)
2. In buildRules(RulesChecker $rules), add $rules->add($rules->isUnique(['email'])) and any existsIn foreign-key checks, backed by matching database constraints. (verify: Saving a duplicate email fails with a rule error)
3. Marshal input with patchEntity(), call save(), and on a falsey result read $entity->getErrors() to display per-field messages. (verify: Valid data persists; invalid data returns messages and saves nothing)

Best practices

• Treat a falsey save() return (or a marshalled entity with getErrors()) as the signal that validation failed, and surface those messages instead of assuming success
• Define alternate validation methods (e.g
• Use requirePresence('field') to require the key to exist in the data, and notEmptyString('field') (or the typed notEmpty variant) to reject blank values; combine them when a field must be both present and non-empty

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Confusing requirePresence with notEmpty — Adding only requirePresence still lets an empty string through, and adding only notEmpty still lets a missing key through. Fix: Combine requirePresence and the appropriate notEmpty* rule when a field must be both present and filled.
2. Ignoring the save return value hides validation failures — Calling save() and ignoring its return lets a validation or rule failure pass silently, so nothing is persisted but the code continues. Fix: Branch on the boolean result (or use saveOrFail where an exception is appropriate) and read getErrors() on failure.
3. Uniqueness placed in the Validator never runs at save — A uniqueness check written into the shape Validator does not have database access at marshalling time and cannot reliably enforce uniqueness. Fix: Move uniqueness to buildRules() with isUnique, backed by a database unique index.

Version notes

• CakePHP 5 tightens Validator and rule signatures — CakePHP 5 (PHP 8.1+) uses stricter parameter and return types on the Validator and RulesChecker methods, so custom rules and validationDefault() overrides should adopt the typed signatures used in the 5.x API.

Security

• Always validate on the server; never trust client checks — Define the authoritative rules in the Table's Validator and RulesChecker and run them on every write path; treat client-side or JavaScript validation as UX only, and pair uniqueness rules with real database constraints.

Testing

• Activation and decision behavior are verified in eval/scenarios/cakephp/validation.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: cakephp/controllers, cakephp/orm, php/typed-properties