Skip to main content
skill CX Codex

controller-cleanup — Claude Code skill: refactor Symfony controllers

The controller-cleanup skill extracts business logic from fat Symfony controllers into services, handlers and commands. Leaves actions lean, delegating and responding only.

MIT ★ 234 updated 2026-10-05

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dev-toolings/superpowers-symfony --skill controller-cleanup -a claude-code
Open on GitHub

What controller-cleanup does

The skill reads a controller, lists what it does — validation, authorization, logic, persistence — and moves each concern to its layer. Before refactoring, it writes a functional test to lock down HTTP behavior: same status codes, same payloads. Input is mapped to DTOs via #[MapRequestPayload] or #[MapQueryString], authorization moves to a voter, side effects to events or messages.

Services are injected as constructor or method arguments; pulling them from the container is forbidden. Logic does not move to a "manager" that is the old controller under a new name. Console commands are written as invokable #[AsCommand] classes (Symfony 7.3+) that delegate to the same services.

Output: an action in five to ten lines, extracted DTOs, services, voters or handlers with one responsibility each, tests confirming HTTP behavior stayed the same.

What it helps with

  • extract business logic from a controller into services and handlers
  • cover an action with a functional test before refactoring
  • map input to a DTO using #[MapRequestPayload]
  • move authorization to a voter, side effects to events
  • write a console command as an invokable #[AsCommand] class

Example prompts for the agent

  • Break down UserController::register into services for validation, user creation and email sending
  • Cover POST /orders with a functional test, then extract logic to CreateOrderHandler
  • Rewrite app:import-products as an invokable command that delegates to ProductImporter

How to install controller-cleanup

1Skills CLI (Vercel)

npx skills add dev-toolings/superpowers-symfony --skill controller-cleanup -a claude-code

2Manually: put the files in place

~/.claude/skills/controller-cleanup/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/controller-cleanup/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about controller-cleanup

How do I install controller-cleanup in Claude Code?

Run npx skills add dev-toolings/superpowers-symfony --skill controller-cleanup -a claude-code, the skill path is ~/.claude/skills/controller-cleanup/SKILL.md.

What does the controller-cleanup skill do?

It moves business logic, validation and authorization from Symfony controllers into services, DTOs, voters and handlers. The action stays short — delegation and response only.

How does controller-cleanup preserve HTTP behavior?

Before refactoring, the skill writes a functional test to lock down response codes and bodies. After moving logic, the test confirms nothing broke.

Source text

SKILL.md · MIT
---
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`

© dev-toolings · MIT · dev-toolings/superpowers-symfony

Similar skills

All skills for Backend and APIs →

From the same set51

The whole set →
config-env-parameters The config-env-parameters skill guides changes to Symfony environment variables, parameters, and secrets across environments. Use it when configuration needs a clear home and safe injection into the app. CX Codex +1 ★ 234repo stars doctrine-fixtures-foundry doctrine-fixtures-foundry teaches the agent to build Doctrine test data with Zenstruck Foundry v2 factories: named states, sequences and entity relations. Triggers when you write fixtures or migrate factories from Foundry v1. CX Codex +1 ★ 234repo stars doctrine-transactions doctrine-transactions guides Claude Code on managing Doctrine ORM 3 transactions, locking strategies, and flush boundaries in Symfony applications. Fits concurrent row edits and rollback recovery. CX Codex +1 ★ 234repo stars doctrine-batch-processing doctrine-batch-processing is a Claude Code skill for processing large Doctrine datasets in memory-conscious imports, exports, and backfills. CX Codex +1 ★ 234repo stars brainstorming brainstorming structures feature discovery for Symfony projects: clarifies unclear requirements, identifies framework components, and compares architecture designs. CX Codex +1 ★ 234repo stars runner-selection The runner-selection skill detects whether Symfony commands belong in Docker, DDEV, or the host environment. Use it when the right command prefix is unclear or containers may be stopped. CX Codex +1 ★ 234repo stars doctrine-events doctrine-events — a Claude skill for attaching side effects to Doctrine entity events in Symfony: timestamps, slugs, search index updates, notifications. CX Codex +1 ★ 234repo stars form-types-validation form-types-validation generates Symfony form types, configures DTO validation groups, handles HTTP 422 responses, and sets up multi-step flows. CX Codex +1 ★ 234repo stars

Project sponsors

Companies that keep this analytics open