controller-cleanup · diff
git:20261005.042befb to git:20261005.2187271
15 added, 12 removed. Audit A to A.
---
name: controller-cleanup
description: Refactor fat controllers into lean ones by extracting business logic to services, handlers, and invokable commands
capabilities: [read, search]
tags: [architecture]
# projected by `bun run build` — do not edit by hand
allowed-tools:
- Read
- Glob
- Grep
---
# Controller Cleanup (Symfony)
## Use when
- - Refining architecture/workflows/context handling in Symfony projects.
- - Planning and executing medium/complex changes safely.
+ - A controller action holds business logic, queries, or more than a handful of lines.
+ - Input parsing, validation, authorization and persistence are mixed in one action.
+ - A console command does the real work itself instead of delegating it.
## Default workflow
- 1. Establish current boundaries, constraints, and coupling points.
- 2. Propose smallest coherent architectural adjustment.
- 3. Execute in checkpoints with validation at each stage.
- 4. Summarize tradeoffs and follow-up backlog.
+ 1. List what the action does: input, validation, authorization, business logic, persistence, side effects.
+ 2. Cover the current HTTP behavior with a functional test before moving anything.
+ 3. Map input to a DTO with `#[MapRequestPayload]` or `#[MapQueryString]` and let the validator reject it.
+ 4. Move business logic into a service or a command handler, authorization into a voter, side effects into events or messages.
+ 5. Leave the action to resolve, authorize, delegate and respond, in five to ten lines.
## Guardrails
- - Use existing project patterns by default.
- - Avoid broad refactors without explicit need.
- - Keep decision log clear and auditable.
+ - Type-hint services as arguments or constructor parameters; never pull them from the container.
+ - Keep the HTTP behavior identical: same status codes, same payloads.
+ - Do not move the logic into a "manager" that is the old controller under a new name.
+ - Write console entry points as invokable `#[AsCommand]` classes (Symfony 7.3+) that delegate to the same services.
## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.
## Output contract
- - Architecture/workflow changes.
- - Checkpoint validation outcomes.
- - Residual risks and next steps.
+ - Lean actions that delegate.
+ - The extracted DTOs, services, voters or handlers, one responsibility each.
+ - Functional tests showing the HTTP behavior is unchanged.
## References
- `reference.md`