laravel-expertlisted

> **AI-consumed reference.** Optimized for Claude to read during execution. > Human-readable explanation: see [docs/architecture/HIERARCHICAL_PLANNING.md](../../../docs/architecture/HIERARCHICAL_PLANNING.md) > or [docs/getting-started/](../../../docs/getting-started/) depending on topic. # Laravel Expert — Gotchas & Decisions Use Context7 for full Laravel docs. ## Key Decisions ```toon decisions[4]{choice,use_when}: Form Request vs inline,"Form Request for reusable validation. Inline for one-off simple checks" Service vs Action class,"Service for stateless business logic. Action (single __invoke) for discrete operations" Event/Listener vs direct,"Events for decoupling (notifications/logging). Direct for tightly coupled ops" Eloquent vs Query Builder,"Eloquent for domain models with relationships. Query Builder for reports/bulk ops" ``` ## Gotchas - N+1: always `with()` eager load. Use `preventLazyLoading()` in AppServiceProvider to catch in dev - `readonly` DTOs (PHP 8.2+): `readonly class UserData { public function __construct(public string $name) {} }` - `updateOrCreate` is NOT atomic — race condition possible. Use DB transaction for critical ops - `$model->save()` returns bool, not the model — don't chain. `Model::create()` returns the model - Mass assignment: `$fillable` whitelist or `$guarded = []` (never use `$guarded = []` with user input) - `firstOrFail()` throws `ModelNotFoundException` (404). `first()` returns null silently - Queue jobs: always implem