CakePHP Controllers

When to use

• The user is adding or editing a CakePHP controller action that responds to a routed request.
• The user wants to share request-handling logic (auth, flash, pagination) across controllers via a component.
• The user needs to read request data (query, post, params) or build a response (redirect, JSON, status) in a CakePHP controller.

When NOT to use

• Do not put app-wide request concerns (CORS, HTTPS enforcement, body parsing) in a controller; handle them in PSR-15 middleware in the application stack.
• Do not use this skill for Symfony, Laravel, or Laminas controllers; the action, component, and ServerRequest API is CakePHP specific.

Core guidance

• Read request data through the ServerRequest accessors — Read input with $this->request->getData('field'), getQuery('key'), and getParam('id') rather than touching superglobals, and provide a default for optional values.
• Keep actions thin and delegate to Tables and services — Limit an action to reading input, calling a Table finder or service, setting view variables, and returning a response; push domain logic into the model layer.

Quick recipe

1. In the action, guard the method with $this->request->is('post'), then build an entity with patchEntity($entity, $this->request->getData()). (verify: The entity carries the submitted fields subject to accessibility rules)
2. Persist with $table->save($entity) and branch on the boolean result, reading $entity->getErrors() when it fails to surface validation messages. (verify: A valid entity saves; an invalid one exposes per-field errors)
3. On success, set a flash message and return $this->redirect(['action' => 'index']); on failure, set the entity as a view variable and let the action render the form. (verify: Success redirects with a flash; failure re-renders the form with errors)

Best practices

• Reach for a component when logic needs the request, response, or controller lifecycle (flash, auth, pagination); for pure domain logic, use a plain service class instead
• Turn request data into entities with newEntity()/patchEntity() and persist with save(), checking the entity's errors, rather than assigning request fields onto entities by hand
• Return the result of $this->redirect(...), $this->response->withType(...), or a rendered view from the action; never call exit/die or echo output directly

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. getData returns null for absent keys — $this->request->getData('missing') returns null when the key is absent, so passing it straight into strict logic causes type errors. Fix: Provide a default (getData('field', '')) or validate presence via marshalling before use.
2. Forgetting to return the redirect response — Calling $this->redirect(...) without returning it lets execution continue and the action still tries to render a view. Fix: Always return $this->redirect(...) (and return early) so no further action code runs.
3. Public helper methods become routable actions — Any public method on a controller is dispatchable as an action, so a public helper can be reached via a crafted URL. Fix: Make non-action helpers protected/private, or restrict routing so only intended actions are reachable.

Version notes

• CakePHP 5 requires PHP 8.1 and typed controller signatures — CakePHP 5 requires PHP 8.1+ and ships stricter types on the request/response objects and component APIs, so actions and component hooks should use the typed signatures rather than the looser CakePHP 4 forms.

Security

• Validate input and authorize the action at the boundary — In every action, read input through the request accessors, marshal it through the Table so validation and field accessibility apply, and confirm the current user is authorized before mutating or exposing data.

Testing

• Activation and decision behavior are verified in eval/scenarios/cakephp/controllers.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

Prerequisites: cakephp/orm
Related: cakephp/validation