/ia-php-laravel

name: ia-php-laravel
class: language
description: >-
  Modern PHP 8.4 and Laravel patterns: architecture, Eloquent, migrations, queues, testing.
  Use when working with Laravel, Eloquent, Blade, artisan, or building/testing a
  framework-based PHP app. Not for php-src internals, standalone PHP libraries, or
  general PHP language discussion.
paths: "**/*.php"

PHP & Laravel Development

Code Style

• `declare(strict_types=1)` in every file
• Happy path last -- guards and errors first, success at the end. Early returns, no `else`.
• Comments explain *why*, never *what*. Never comment tests. If code needs a "what" comment, rename or restructure.
• No single-letter variables -- `$exception` not `$e`, `$request` not `$r`
• `?string` not `string|null`. Always specify `void`. Import classnames, never inline FQN.
• Validation uses array notation `['required', 'email']` for easier custom rule classes
• PHPStan level 8+ (`phpstan analyse --level=8`); aim for 9 on new projects. `@phpstan-type` / `@phpstan-param` for generic collection types. The missing-iterable-value-type check lands at **level 6** (and every level above it), so any project at 8+ inherits it: use the generic form on every iterable -- `@return Collection<int, User>`, `@param array<int, MyObject>` -- and array-shape notation `array{first: SomeClass, second: SomeClass}` for fixed-key returns; a bare `Collection` or `array` will not clear it.

Modern PHP (8.4)

Use when applicable -- no explanatory comments for these in generated code:

• Readonly classes/properties for immutable data; constructor promotion with readonly
• Enums with methods and interfaces for domain constants
• Match expressions over switch
• First-class callable syntax `$fn = $obj->method(...)`
• Fibers for cooperative async when Swoole/ReactPHP not available
• DNF types `(Stringable&Countable)|null` for complex constraints
• Property hooks: `public string $name { get => strtoupper($this->name); set => trim($value); }`
• Asymmetric visibility: `public private(set) string $name` -- public read, private write
• `new` without parentheses in chains: `new MyService()->handle()`
• `array_find()`, `array_any()`, `array_all()` -- native array search/check without closures wrapping Collection

Laravel Architecture

• **Escalate structure only when it pays for itself.** Simple CRUD → a fat Eloquent model + Form Request is correct; do not add layers. Reach for an **Action class** when an operation crosses model boundaries or gains a 3rd caller. Extract a **non-Eloquent domain object** only when a business rule needs testing without booting the DB, or protects an invariant the model can't. Default down the ladder, not up -- an unused abstraction is a defect, not foresight.
• **Thin controllers** -- only validate, call service/action, return response. Domain behavior (scopes, accessors, relationships) lives in models; cross-cutting orchestration in service classes.
• **Never call `env()` outside `config/`.** Wherever `php artisan config:cache` has run (the deploy sequence requires it, so typically production), every `env()` call outside a config file returns `null` -- silently, with no error. Read through `config('services.github.token')` and put third-party credentials in `config/services.php` rather than inventing a new config file.
• **Service classes** for business logic with readonly DI: `__construct(private readonly PaymentService $payments)`
• **Action classes** (single-purpose invokable) for operations crossing service boundaries
• **Form Requests** for all validation -- never inline in controllers, never inside services. Add `toDto()` so services receive typed, pre-validated data; internal code trusts that input was validated at the boundary.
• Conditional validation: `Rule::requiredIf()`, `sometimes`, `exclude_if`
• **Events + Listeners** for side effects (notifications, logging, cache invalidation) -- not in services. Name events past-tense in business terms (`OrderPlaced`, not `OrderRecordUpdated`). Carry IDs and changed facts in the payload, **not the full Eloquent model** -- `SerializesModels` re-fetches by key when a queued listener runs, so a model passed in-memory goes stale (same desync class as the observer/stale-copy pitfall below).
• Feature folder organization over type-based past ~20 models

Production Resilience

• **Fail-fast config validation** in a service provider's `boot()`: missing API keys, invalid DSNs, misconfigured queues crash on startup, not on the first request that hits the code path.
• **Health endpoints**: `/health` (shallow, 200 if the process responds) and `/ready` (deep -- checks DB, Redis, critical services).

Routing

• Scoped route model binding to prevent cross-tenant access: `Route::scopeBindings()->group(fn() => ...)`
• `Route::model('conversation', AiConversation::class)` for custom binding resolution
• API resource routes: `Route::apiResource('posts', PostController::class)` -- index/store/show/update/destroy without create/edit

Migrations

• Anonymous class migrations; `snake_case` plural table names matching model convention
• Foreign keys: `$table->foreignId('user_id')->constrained()->cascadeOnDelete()`. Always index foreign keys and frequently filtered columns.
• Down method: rollback logic or `Schema::dropIfExists()` for new tables
• Separate schema and data migrations -- backfills in their own migration file, not mixed with DDL
• Renames/removals use expand-contract: add new column → backfill → switch reads → drop old (full pattern in `ia-postgresql` skill)
• Never edit a migration that has run in a shared environment -- write a new one
• **Set `public $withinTransaction = false;` for per-row commit/lock-release (resumable backfills) or statements Postgres rejects inside a transaction (`CREATE INDEX CONCURRENTLY`, `ALTER TYPE ... ADD VALUE`).** Otherwise inner `DB::transaction()` loops become savepoints, not independent commits ([pitfalls-deep.md](./references/pitfalls-deep.md)); no-op on MySQL