/controller-cleanup

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

• 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. 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

• 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

• 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`