Code Convention

A reference of conventions for writing maintainable Laravel/PHP code (with React/TypeScript frontend). Apply these when authoring or modifying code — not as a post-hoc review checklist, but as the default shape of the code you produce.

How to use this skill

1. Skim the relevant section(s) for the code you're about to write (Architecture for new features, Database for migrations, Testing for tests, etc.).
2. Match your output to the patterns shown. When a project-specific convention conflicts with this skill (check CLAUDE.md, existing code in the area you're modifying), the project wins — these are sensible defaults, not absolute laws.
3. If you find yourself violating a rule, pause and justify why. Most violations are accidental; the few intentional ones usually have a good reason worth stating in a comment or PR description.

The "why" matters more than the rule. Each section explains the reasoning so you can apply judgment to edge cases rather than mechanically following text.

Architecture

Keep business logic out of controllers

Controllers handle HTTP — request parsing, response shaping, status codes. Business logic belongs in Actions (mutations) and Queries (reads). The reason: anything more than a trivial controller method is usually needed by other entry points too (API endpoints, mobile apps, console commands, queued jobs). Logic locked inside a controller method has to be duplicated or extracted later.