CakePHP ORM

When to use

• The user needs to declare relationships (hasMany, belongsTo, belongsToMany) or eager-load related records.
• The user wants to compose a select, filter, order, or aggregate query with the CakePHP query builder.
• The user needs to read or write records using CakePHP Table objects and Entity objects.

When NOT to use

• Do not use this skill for Eloquent, Doctrine, or raw PDO; the Table/Entity/query-builder API is CakePHP specific.
• Do not force the ORM query builder onto a bulk DDL or vendor-specific statement that the builder cannot express; use a parameterized raw statement via the connection instead.

Core guidance

• Eager-load associations with contain to avoid N+1 queries — When you will access related records in a loop, eager-load them with contain() in the same query rather than lazy-accessing associations per row.
• Build conditions with the array/expression API, never string interpolation — Pass conditions to where() as an array (['status' => $value]) or via query expressions, so values are bound as parameters; never interpolate user input into a condition string.

Quick recipe

1. Fetch the Table with $this->fetchTable('Articles') (or the locator) and start a query with $table->find(). (verify: find() returns a Query object for the Articles table)
2. Add where(['status' => $status]) with array conditions (parameters are bound) and contain(['Authors', 'Comments']) to eager-load associations. (verify: The generated SQL binds the status value and joins/loads the associations)
3. Materialize the query with ->all() (or iterate it), then read entities and their contained associations without further queries. (verify: Iterating the result issues no additional per-row queries)

Best practices

• Control which fields can be set from request data via the entity's $_accessible map, and pass an explicit fields/accessibleFields option to newEntity() or patchEntity() for sensitive columns
• Put reusable query fragments in custom finder methods (findActive, findPublished) on the Table and chain them with find('active'), instead of repeating where() clauses across controllers
• For list or report queries that do not need full entities, restrict columns with select([...]) and consider ->enableHydration(false) to get plain arrays

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Lazy association access triggers N+1 queries — Accessing $row->association inside a loop without contain() runs one extra query per row. Fix: Add the association to contain() in the original query so related rows load in a batched query.
2. patchEntity silently drops fields not marked accessible — Fields absent from the entity's $_accessible map are silently ignored by newEntity()/patchEntity(), so an expected column is never saved. Fix: Add the intended field to $_accessible (or pass it via accessibleFields) while keeping sensitive columns locked down.
3. A Query object is lazy and executes only on iteration — A query returned by find() is not run until it is iterated, counted, or turned into a result with all()/toArray()/first(). Fix: Materialize the query explicitly with ->all(), ->toArray(), ->first(), or by iterating it once you have finished building.

Version notes

• CakePHP 5 splits SelectQuery and tightens types — CakePHP 5 introduces dedicated SelectQuery/InsertQuery/UpdateQuery/DeleteQuery classes and requires PHP 8.1+, so type against those interfaces rather than the single CakePHP 4 Query class.

Security

• Never interpolate untrusted input into queries — Route all user-supplied values through the builder's parameter binding — array conditions, IdentifierExpression for column names, and validated allow-lists for order() directions — and never concatenate request data into SQL fragments.

Testing

• Activation and decision behavior are verified in eval/scenarios/cakephp/orm.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/validation, php/typed-properties