A comprehensive, opinionated guide for building Laravel applications across all team projects. These rules are strict, must-follow standards — deviations require justification.
Build a single source of truth for how the team writes Laravel. The goal is to eliminate stylistic debates in PRs, ensure new developers onboard fast, and keep code shape consistent across projects so any team member can drop into any codebase.
Every Laravel project adopts this baseline:
spatie/laravel-data— used as DTO transport layer (typed::from()hydration). Validation attributes NOT used (validation lives in FormRequests).spatie/laravel-model-states— state machines for entities with non-trivial status flows
laravel/pint— formatter (Laravel preset)larastan/larastan— static analysis (level 5, ratchet up)rector/rector— automated refactoring (--dry-runin CI)barryvdh/laravel-ide-helper— IDE autocomplete (dev only)
pestphp/pest— test frameworkpestphp/pest-plugin-laravel— Laravel-specific helpers- Postgres (test database matches production engine)
- Laravel's built-in fakes (
Http::fake(),Event::fake(),Queue::fake(), etc.) - Custom
Fake*Service classes (intests/Fakes/) for vendor-SDK Services
- This is the content-first version of the guide.
- Final delivery format (Markdown repo / Notion / PDF) decided later.
Sections are ordered by technical priority, not numerically. Earlier sections influence later ones; the build order respects dependencies.
| Build order | # | Section | Status |
|---|---|---|---|
| 1 | 3 | Code style & static analysis | ✅ Locked |
| 2 | 4 | Architecture patterns | ✅ Locked |
| 3 | 9 | Testing strategy | ✅ Locked |
| 4 | 12 | Git workflow & code review | ✅ Locked |
| 5 | 5 | Database & Eloquent | ⏳ Pending |
| 6 | 11 | Security practices | ⏳ Pending |
| 7 | 7 | Authentication & authorization | ⏳ Pending |
| 8 | 10 | Logging, monitoring & error tracking | ⏳ Pending |
| 9 | 8 | Background jobs in production | ⏳ Pending |
| 10 | 13 | CI/CD pipeline | ⏳ Pending |
| 11 | 14 | Deployment & infrastructure | ⏳ Pending |
| 12 | 6 | API & frontend integration | ⏳ Pending |
| 13 | 15 | Performance & caching | ⏳ Pending |
| 14 | 1 | Local development environment | ⏳ Pending |
| 15 | 2 | Project scaffolding | ⏳ Pending |
| 16 | 16 | Documentation & onboarding | ⏳ Pending |
The architecture/ folder contains a deep reference for each architectural building block. Start with architecture/README.md.
A printable poster of the architecture is available at architecture-map.html.
For AI coding assistants, distilled directive-form versions of the standards live in .ai/skills/. Pointer files at the repo root forward each tool to those skills:
| Tool | File |
|---|---|
| Claude Code | CLAUDE.md |
| OpenCode + cross-tool standard | AGENTS.md |
| GitHub Copilot | .github/copilot-instructions.md |
| Cursor | .cursorrules |
The skills cover architecture (Section 4) and testing (Section 9) so far. More skills will be added as later sections are locked.
Locked: 4 sections (3, 4, 9, 12). Remaining: 12 sections.
Next up: Section 5 (Database & Eloquent).
- Locked rules are stated as imperatives ("Use X", "Never do Y").
- Rationale is included where it helps; omitted where the rule is obvious.
- Examples are language-generic when possible, Laravel-specific when needed. Not tied to any specific product or domain.
- Strictness: strict by default. Every "exception" must be documented at the call site with a comment.