Laravel idioms
Write code the way the Laravel framework, its docs and well-maintained packages (laravel.io, Spatie) write it. Match the project's existing conventions and Laravel version first; these rules decide everything the project hasn't already decided.
With Laravel Boost: load this skill and laravel-best-practices. Boost's rule files also cover security, migrations, the HTTP client, error handling and mail. This skill adds the concrete rules below, the Laravel 13 / Filament 5 / Pest 5 API specifics, and the mandatory "Before you finish" checklist. Where the two differ on a specific API or pattern, follow this skill; verify version-sensitive APIs with Boost's search-docs when it is available.
Audit or refactor-report request? ("evaluate this codebase", "suggest refactors", "audit this app") → follow references/audit-mode.md. It ends in a self-contained HTML report built from assets/audit-report-template.html.
0. Check the version, then commit to its style
Read laravel/framework in composer.lock. The 11+ skeleton has no Http/Kernel.php, Console/Kernel.php, Exceptions/Handler.php, RouteServiceProvider, AuthServiceProvider or EventServiceProvider, and no routes/api.php until php artisan install:api. On Laravel 13, every new model, job and command uses attributes (#[Fillable], #[Hidden], #[Scope], #[ObservedBy], #[Tries], #[Signature] + #[Description]), and you use them in every new file, not only some. On older versions, or where existing code uses properties, keep properties. An upgraded app may still keep schedules in app/Console/Kernel.php or a provider: add new entries where the existing ones live.
1. Controllers orchestrate; they don't compute
A controller action authorizes, hands validated input to one collaborator, and returns a response. Limit: about 10 lines per action, one query or one call, and no private query/formatting helpers. When an action needs several queries, aggregation, row mapping or formatting, move that into a class named after what it produces, and have it reuse the model's scopes.
// bad: 60+ lines of joins, sums and formatting in __invoke plus private helpers
// good
public function __invoke(StatsRequest $request, BuildTeamStats $stats): JsonResponse
{
return response()->json($stats($request->user()->team, $request->filters()));
}
Plain CRUD needs no extra class: $request->user()->posts()->create($request->validated()) is the whole store action. Domain rules that belong to one model (syncing its tags, computing its totals) go in a model method, not in a private controller helper. Use resource routes with CRUD names (destroy, not delete); a non-CRUD endpoint gets its own invokable controller. Type-hint models for route binding ({post:slug}).
2. Validate every input, including query strings
Every request that reads input gets a FormRequest: store, update, and index/report endpoints that take filters, sort keys or per_page. An unvalidated ?status=bogus that silently returns nothing is a bug.
// bad
->when($request->filled('status'), fn ($q) => $q->where('status', $request->string('status')))
// good: IndexPostRequest
public function rules(): array
{
return [
'status' => ['sometimes', Rule::enum(PostStatus::class)],
'per_page' => ['sometimes', 'integer', 'between:1,100'],
];
}
- Persist only
validated() / safe()->only([...]), never all().
- Optional filters are
nullable as well as sometimes: an empty ?status= arrives as null, and a bare 'string' rule turns "no filter" into a 422.
- Use array rules with rule objects (
Rule::unique(...)->ignore(...), Rule::enum, Password::defaults()) and built-in rules (after_or_equal:from, size:2) before writing closures.
- Checks that need the database or another model go in
after(), and they stop at the first failure so the client gets one clear message per request.
- Normalise input in
prepareForValidation(). Add typed accessors (filters(), coupon()) that read validated(). Memoise lookups with once(fn () => ...), not hand-written $resolved flags.
- Omit
authorize() when it would just return true.
- Input that names a column or a direction (
?sort=, ?dir=, a filter key) passes an allow-list (Rule::in([...]) or a match); columns are never bound, so anything else is a 500 or lets a client sort by a hidden column. Never put request data in whereRaw/selectRaw/orderByRaw/DB::raw; bind it with ?. A user's LIKE search escapes % and _ with an explicit ESCAPE character, in one scope (whereLike doesn't escape, and a backslash matches nothing on SQLite). exists/unique on tenant data carry the owner: Rule::exists('folders', 'id')->where('team_id', $this->user()->team_id).
- Test optional input with
filled() or !== null, never truthiness: ->when($term, ...) skips a search for 0. Details: references/security.md.
3. Authorization: policies, one mechanism per controller
// bad
abort_unless($post->user_id === auth()->id(), 403);
// good: App\Policies\PostPolicy is auto-discovered
public function update(User $user, Post $post): bool
{
return $post->user()->is($user);
}
Choose one mechanism per controller and use it for every action: Gate::authorize('update', $post) in each action, route ->can('update', 'post'), or the FormRequest's authorize(). Don't mix them. When an action takes a FormRequest, authorize on the route or in the request's authorize(): Gate::authorize() in the action runs after validation, so a non-owner sending a bad body gets 422 instead of 403. The 11+ base Controller is empty, so $this->authorize() / $this->middleware() don't exist; don't re-add the traits. Don't register policies manually.
3b. API routes: guards and error responses
// bad: the default guest redirect calls route('login'). A client that sends no `Accept: application/json`
// (curl, a server-to-server script) gets a 500 in any app without a `login` route, and getJson() tests never see it
// good: bootstrap/app.php
->withMiddleware(function (Middleware $middleware): void {
$middleware->redirectGuestsTo(fn (Request $request) => $request->is('api/*') ? null : route('login'));
})
- JSON endpoints live in
routes/api.php (install:api; it adds the api/ prefix and no session, cookies or CSRF), never in routes/web.php and never with the web group. A token API uses auth:sanctum; a bare auth is the session guard. On a public route that personalises for logged-in callers, read $request->user('sanctum').
- 401 = not authenticated, 403 = authenticated but not allowed (policy), 404 = not found or another user's record you don't reveal (scope the query, or
Response::denyAsNotFound()), 422 = invalid input. Let the framework render them: never catch (Exception $e) { return response()->json(['error' => $e->getMessage()]) }. With debug off, a 404 still names the model class (No query results for model [App\Models\Order]). Only when the app must not reveal internals, render NotFoundHttpException on api/* with a plain message.
- Token abilities go on the route, so a token without the scope gets 403 before validation or a lookup runs: alias Sanctum's middleware in
bootstrap/app.php ($middleware->alias(['abilities' => CheckAbilities::class])), run it before route-model binding ($middleware->prependToPriorityList(SubstituteBindings::class, CheckAbilities::class), or a missing id answers 404 and someone else's 403), and use ->middleware('abilities:orders:write'). Ownership stays in a policy or a query scoped to the user. Don't move tokenCan() into a policy or controller: they run after the FormRequest has already answered 422. throttle:api needs a RateLimiter::for('api', ...); a login or token endpoint gets its own limiter keyed by email + IP.
3c. Inbound webhooks
- A provider's signed delivery goes in
routes/api.php (no session, cookies or CSRF), without auth or throttle. A fresh 13 skeleton has none: add the file and api: to withRouting() by hand (install:api also installs Sanctum). Not web plus a CSRF exclusion: web starts a session on every delivery, and a FormRequest there answers a bad payload with a 302.
- Verify in middleware before anything parses the body:
hash_equals(hash_hmac('sha256', $request->getContent(), $secret), (string) $request->header(...)), failing closed (401) on a missing header or an empty configured secret. Never sign re-encoded JSON.
- Answer 2xx fast and queue the work. Dedupe on the delivery id with a unique index (
createOrFirst() + wasRecentlyCreated), not the cache, and answer a duplicate with the same 2xx; a claimed row still unprocessed when the delivery repeats is dispatched again. Unknown types get their 2xx before any payload rule runs: validate only what every delivery carries (its id and type) up front, and a known type's fields where you process it. A rejected delivery is retried for as long as the provider retries, so never reject on a stricter rule than the provider's contract. State from a delivery is applied only if newer, in one statement (where(fn ($q) => $q->whereNull('remote_updated_at')->orWhere('remote_updated_at', '<', $at))->update([...])). A naturally idempotent single write may run inline. Tests post the exact signed bytes with $this->call() (postJson() re-encodes). Details: references/webhooks.md.
4. One source of truth for query rules
A filter rule is written once, as a composable scope, and every query reuses it: counts, sums and joins alike. Never write a second copy of the same where logic in a DB::table() query.
#[Scope] // 12.4+; scopeCreatedBetween() before that
protected function createdBetween(Builder $query, ?CarbonInterface $from, ?CarbonInterface $to): void
{
$query->when($from, fn ($q, $from) => $q->where('created_at', '>=', $from))
->when($to, fn ($q, $to) => $q->where('created_at', '<=', $to));
}
$count = Post::query()->createdBetween($from, $to)->published()->count();
$comments = Comment::query()->whereHas('post', fn ($q) => $q->createdBetween($from, $to)->published());
Use Model::query(), not DB::table(), when a model exists. Let SQL do aggregation (sum, count, exists, value, groupBy, withCount/withSum), not ->get()->sum(). Join only the tables a query actually reads. Iterate big tables with lazyById() / chunkById().
5. Models
#[Fillable(['title', 'body', 'status'])] // L13; the owner FK and derived columns stay out
#[ObservedBy(PostObserver::class)]
class Post extends Model
{
protected function casts(): array
{
return ['status' => PostStatus::class, 'meta' => AsArrayObject::class, 'published_at' => 'datetime'];
}
protected function title(): Attribute
{
return Attribute::make(set: fn (string $v) => trim($v));
}
public function user(): BelongsTo { return $this->belongsTo(User::class); }
}
- Use backed enums for every fixed set of states, never class constants. Compare cases (
=== PostStatus::Published), validate with Rule::enum, and set defaults with ->default(PostStatus::Draft->value) in migrations.
- Write through relationships:
$user->posts()->create(), ->associate(), whereBelongsTo, whereRelation. Add the inverse hasMany to the parent model when you need it.
- Derived fields (slug, published_at) go in model events or an observer, so they apply on every Eloquent write. Mass writes skip model events:
where()->update()/delete(), insert, upsert, builder increment, DB::table(). Where an observer must run (audit rows, cache busting), loop with lazyById() and save each model, or do the observer's work in the same method.
- Columns holding tokens or secrets go in
#[Hidden] (13; $hidden before). A token you only verify is stored as hash('sha256', $plain) and compared with hash_equals; encrypted casts are for secrets you must read back, and can't be queried.
- No N+1: eager load what loops and resources touch (
with('author:id,name')), use whenLoaded() in resources, and enable Model::shouldBeStrict(! $this->app->isProduction()).
5b. Migrations and schema
- Foreign keys start from
foreignId()/foreignIdFor(). Modifiers go before constrained(): ->nullable()->constrained()->nullOnDelete(). Pick ON DELETE on purpose: cascadeOnDelete() for owned children (line items, pivots), nullOnDelete() on a nullable column for references that must outlive the parent, the default restrict for records that must block a delete.
- Every invariant of the form "one X per Y" (one redemption per user and coupon, one row per SKU) is a unique index, and validation is only a friendly pre-check. Columns in that index are
NOT NULL, because NULLs never collide.
- Index the columns a hot query filters and sorts on, equality columns first, then the range or sort column:
->index(['customer_id', 'status', 'created_at']) for where customer_id = ? and status = ? order by created_at.
- On a table that already has production rows and running code, change the schema in steps: add the column nullable, backfill it, and switch the reads, then tighten or drop the old column in a later release. Never rename or drop a column in the same deploy as the code that stops using it. On a big MySQL table, give each DDL step its own migration (MySQL runs DDL outside transactions, so a half-applied migration can't simply re-run), create a composite index that leads with the foreign key column before adding the foreign key (MySQL then reuses it instead of building its own), and make
down() undo every step. A new table or a pre-launch app needs none of this.
- Backfills don't use Eloquent models (their later changes break old migrations, and they fire events and touch
updated_at). Use DB::table()->chunkById() or a set-based UPDATE, in a re-runnable command when the table is big. ->change() restates every attribute you keep (nullable, default, unsigned). Never edit a migration that has run anywhere shared: add a new one.
6. Collections, and no hidden state
// bad
$names = []; foreach ($users as $u) { if ($u->active) { $names[] = $u->name; } }
// good
$names = $users->filter->active->pluck('name')->values();
[$active, $idle] = $users->partition(fn (User $u) => $u->isActive());
A closure inside map/each/mapWithKeys never captures &$var. If a step needs a running total, use a plain foreach with a named accumulator, or reduce. Call ->values() after filter/reject/unique before JSON. Format money with Number::currency($major, in: 'EUR') (major units, display only), not number_format.
Money and dates. Money is integer minor units or a decimal string, never a float: no (int) ($price * 100) (19.99 → 1998). The minor-unit exponent depends on the currency (JPY 0, most 2, KWD 3), so never hard-code / 100 when several currencies are in play. Round once, at a stated point (per line or on the total), and split a total by largest remainder so the parts add back up. Validate money input with decimal:0,N, N the currency's exponent (numeric accepts 1e2), convert the string with integer maths on its digits (for a signed amount, convert the absolute value and re-apply the sign) (if you call Brick\Math directly, require brick/math in composer.json; it is only a transitive dependency), and cast minor-unit columns 'integer'. Store UTC; parse a user's input in their zone, then ->utc(). A user's "today" on a datetime column is [local midnight, next local midnight) converted to UTC, never whereDate() with UTC today(). addMonth() overflows (Jan 31 → Mar 3): $start->toImmutable()->addMonthsNoOverflow($n) from the original date, not chained from the last result (on a mutable Carbon the call moves $start itself). Never mutate a date you didn't create (->copy(), toImmutable()); switching the app default with Date::use() is a project decision, not part of a feature. Details: references/dates-and-money.md.
Pipelines replace loops; they are not a mandate to rewrite array_* calls. Never add a temp variable and @var, or silence the error (@phpstan-ignore, assert(), a cast), just to make a pipeline fit a declared type.
// bad: the temp exists only to carry a @var
/** @var list<string> $enabled */
$enabled = collect($this->languages($account))->filter(fn (array $l): bool => $l['enabled'] ?? false)->keys()->all();
return $enabled;
// good
return array_keys(array_filter($this->languages($account), fn (array $l): bool => $l['enabled'] ?? false));
The framework types ->all() as array<TKey, TValue> and ->keys()->all()/->values()->all() as array<int, T>, never list<T>. Where a method returns or a property holds list<…>, a single step stays array_map(...) / array_keys(array_filter(...)) / array_values(array_filter(...)), and a real multi-step pipeline (or the loop it replaces) returns array_values(collect($x)->...->all()). Widen the type to array<int, T> only when no caller relies on a list.
A strict in_array(..., true) dedupe becomes ->uniqueStrict(), never ->unique(), which compares loosely ('0'/'00' collapse). Leave array_unique() on strings as it is.
7. Queued jobs
implements ShouldQueue + one use Queueable; (Illuminate\Foundation\Queue\Queueable). Options as attributes on 13 (#[Tries(5), Backoff([10, 60, 300]), Timeout(120)]), never both attribute and property. Pass models to the constructor (#[WithoutRelations], and #[DeleteWhenMissingModels] when the row can be deleted before the job runs), services to handle(). dispatch(...)->afterResponse() is not queueing: it runs in the web process with no retries.
handle() is idempotent: a job can run twice (timeout, crash, queue:retry). Guard on persisted state, key writes on a natural key (updateOrCreate, unique index, idempotency key upstream; an accumulating write such as adding points needs a claimed row, because updateOrCreate would add twice), and do the externally visible effect last. The code that dispatches it is idempotent too: a state change that queues work (markAsPaid()) claims the transition with a conditional update (where('status', 'pending')->update(...) returns 1) and dispatches only when it won. SerializesModels re-fetches by id without global scopes, so a soft-deleted model comes back: check trashed()/status.
- Nothing to do or already done →
return. Something failed → let it throw (Http::timeout(10)->throw()), or $this->fail($e) when retrying can't help. Never catch, log and return, or store "failed" and return: no retry, no failed_jobs, no alert.
// bad
try { $client->createShipment($this->order); } catch (RequestException $e) { Log::error($e->getMessage()); return; }
// good: already done → return; failure → throws → backoff → retry → failed()
if ($this->order->shipment()->exists()) { return; }
$this->order->shipment()->create(['reference' => $client->createShipment($this->order)]);
- Default is one attempt, and every
release() (including the RateLimited/WithoutOverlapping middleware) uses one. Size #[Tries] or retryUntil() above the releases, add #[MaxExceptions], and always set #[Backoff] (default 0 retries in a tight loop).
- Built-in job middleware, not hand-rolled throttles in
handle(): RateLimited + a named RateLimiter::for(), (new WithoutOverlapping($id))->releaseAfter(30)->expireAfter(180) (defaults: release at once, lock never expires), (new ThrottlesExceptions(10, 300))->report() (it swallows the exception otherwise). An upstream 429 → $this->release() for its Retry-After (capped), not a throw that spends MaxExceptions.
- A job that tracks status on a row sets
processing with a timestamp and defines failed(?Throwable $e) (it runs on a fresh instance) that marks the row failed. A killed worker never calls failed(), so schedule a recovery for rows stuck past N minutes.
- Timeouts nest: HTTP client timeout <
#[Timeout] < retry_after (default 90; on SQS the queue's visibility timeout) < Supervisor stopwaitsecs / container stop grace. Restart workers on every deploy (queue:restart / horizon:terminate); process config, drivers, containers and monitoring are in references/queues-and-workers.md.
- Inside a transaction:
->afterCommit() on the dispatch; queued listeners and notifications implement ShouldQueueAfterCommit (ShouldHandleEventsAfterCommit only affects sync listeners and observers). Chains and batches have no afterCommit(): dispatch them after the transaction returns.
ShouldBeUnique always has uniqueId() and a #[UniqueFor] between the job's worst total run (every try plus backoff) and its schedule interval: an hourly job whose runs take up to 45 minutes gets #[UniqueFor(3300)], because a lock as long as the interval, orphaned by a killed worker, silently skips the next run. Raise retry_after on a dedicated connection for long jobs, not the shared one. Retries must end before any claim or lock around the job expires (retryUntil() inside a 15-minute claim), and a long job that times out shouldn't be retried behind the next scheduled copy (#[FailOnTimeout]). A batch runs on one queue (set it on the batch); then() runs only if every job succeeded, so with allowFailures() do completion work in finally() and check hasFailures(). Only a failure stops a chain: delete() and Skip let the next job run.
- Mail and notifications:
Mail::to($users) sends one message with every address in To, so loop and send one mailable per recipient. A ShouldQueue mailable or notification returns once it is queued, so a "sent" flag set next to it means "queued". The database channel needs make:notifications-table.
7b. Scheduler
// bad: lock outlives a killed run by 24 h, runs on every server, and only guards the dispatch
Schedule::call(fn () => Report::sendDaily())->dailyAt('02:30')->withoutOverlapping();
Schedule::job(new SyncStock)->everyFiveMinutes()->withoutOverlapping();
// good (routes/console.php)
Schedule::command(SendDailyReport::class)->dailyAt('07:00')->timezone('Europe/Copenhagen')
->onOneServer()->withoutOverlapping(30)->pingOnFailure(config('services.alerts.url'));
Schedule::job(new SyncStock)->everyFiveMinutes()->onOneServer(); // SyncStock: ShouldQueue, ShouldBeUnique, uniqueId(), #[UniqueFor]
- Three different overlap guards: the scheduler's
withoutOverlapping($minutes) (default 1440, so always pass an expiry just above the worst run), the job middleware's expireAfter($seconds) (default never), and Cache::lock(). On Schedule::job() the scheduler's guard covers only the dispatch.
- Several servers or containers run the scheduler →
onOneServer(), with the lock store chosen by environment (SCHEDULE_CACHE_STORE=redis or CACHE_STORE=redis in production). Never hardcode redis in code or as an env() default: tests and local runs have no Redis, and the array store tests the same locks. Closures need ->name() before withoutOverlapping()/onOneServer(). One server → neither.
- When the task or app names a business timezone other than the app's (never invent one), every time-of-day entry (
dailyAt, weeklyOn, nightly cleanups) runs in it: ->timezone() on each, or 'schedule_timezone' in config/app.php, at a local hour outside the DST change (03:00 or later in EU zones), never a UTC time picked to dodge it. Scheduled output is discarded unless you send it somewhere (->appendOutputTo(storage_path('logs/x.log'))) or the command logs it. Alert with onFailure()/pingOnFailure(), not thenPing()/after() (they fire on any exit). On Schedule::job() hooks mean "dispatched", so completion handling lives in the job.
- A dispatcher selects work by persisted state (
whereNull('synced_at')), never by a time window (missed ticks are never replayed), and claims rows (stamp a column) or dispatches unique jobs, so the next tick doesn't re-dispatch rows still in flight. Long work is a queued job or a command, never a long closure.
7c. Console commands
// bad: work in the constructor, `return;` on an error exits 0, chunk() skips rows it deletes
// good
#[Signature('carts:prune {--days=30} {--dry-run} {--force}')]
#[Description('Delete abandoned carts older than --days')]
class PruneAbandonedCarts extends Command
{
use ConfirmableTrait;
public function handle(): int
{
if (! $this->confirmToProceed()) { // asks only in production; --force skips; no TTY → cancelled
return self::FAILURE;
}
$deleted = 0;
foreach (Cart::query()->abandonedFor((int) $this->option('days'))->lazyById() as $cart) {
$cart->delete();
$deleted++;
}
$this->info("Deleted {$deleted} carts.");
return self::SUCCESS;
}
}
- Any failure exits non-zero:
return self::FAILURE or $this->fail('...'), including "some rows failed" (report($e) each, count, then FAILURE). Never a bare return; or a bool on an error path: cron, ECS and onFailure() only see the exit code. No work in the constructor (every artisan call builds every command); inject services into handle().
- Only commands that people run by hand against production data get
ConfirmableTrait + {--force} and a --dry-run that reports and changes nothing. A cleanup only the scheduler runs needs neither (scheduling it with --force is the smell), and read-only commands never do. Every prompted value is also an argument or option (cron has no TTY). Laravel Prompts' confirm() defaults to true, so pass default: false before anything destructive.
- Loops that update or delete the rows they filter on use
lazyById()/chunkById(), never chunk() (offset pages skip rows). A command that must never run twice at once implements Isolatable or gets withoutOverlapping() in the schedule. Isolatable locks before handle(), so the lock also covers a --dry-run and an open confirmation prompt: a command people preview by hand takes a Cache::lock() around the deleting part instead.
7d. Files and uploads
- Validate every upload with a type allow-list and a size cap:
File::types(['pdf', 'png', 'jpg'])->max('5mb'), or ['file', 'mimes:csv,txt', 'max:5120']. mimes checks the type sniffed from the content, so a CSV can sniff as text/plain (a header-only, single-column or semicolon file): always allow txt next to csv. Never pick a parser or a stored name from getClientOriginalExtension()/getClientOriginalName().
- Store with
$file->store('documents', 'local') (a random hashName()), naming the private disk every time you store, check or serve the file (the skeleton's local is storage/app/private; the default disk can be changed by config). Keep the client's name in a column if you need it. The public disk is only for files every anonymous visitor may read. Serve a private file from an authorized route with Storage::disk('local')->download($path, $name), or a link that expires (URL::temporarySignedRoute(..., now()->addMinutes(10), ...) behind the signed middleware, or Storage::temporaryUrl()): a plain signedRoute() never expires. Check exists() on the same disk first, because download() on a missing file is a 500.
- Rows from files and payloads are hostile. Strip a UTF-8 BOM from the first line, then find columns by name, with headers trimmed and lower-cased. When fields never contain line breaks (most feeds), read line by line and parse each with
str_getcsv(), so line numbers stay physical and one stray quote breaks one row, not the rest of the file. Skip blank and whitespace-only lines, check the column count before array_combine, and check each row with a few explicit tests whose message names the column and value (a Validator per row is heavy for a big file and its messages are generic), reporting the file's line number. Import the good rows unless the brief says all-or-nothing. Read with a stream (fopen/SplFileObject/Storage::readStream()), close the handle in finally, and store the file before queueing its processing (a job gets the path, never the UploadedFile).
8. Caching
// bad: race, and no TTL means forever
if (! Cache::has('stats:users')) { Cache::put('stats:users', User::count()); }
// good
$count = Cache::remember("team:{$team->id}:stats:users", now()->addMinutes(5), fn () => $team->users()->count());
- Always pass a TTL.
remember() re-runs a closure that returns null, so cache a sentinel. Cache::flexible($key, [300, 3600], ...) for hot values that may be briefly stale.
- Keys are namespaced (
domain:entity:id:variant), include every input and the tenant/user id, and get a :v2 segment when the payload shape changes.
- Cache arrays or ids, not models (
serializable_classes => false). Invalidate with forget() from an observer (ShouldHandleEventsAfterCommit), never Cache::flush(). tags() throws on the default database store.
- Atomic:
add() for once-per-window guards, add(key, 0, ttl) + increment() for counters. Locks always get seconds and release in finally (or pass a closure). Rate limiters are named RateLimiter::for() keyed by user id or IP.
- Memoize repeated reads per request with
Cache::memo(); tests use the array store plus travel(), never a mocked remember.
8b. Races: let the database decide
Applies to contended counters, caps, "one per user" rows and state changes with side effects. A plain CRUD write needs none of it.
// bad: two requests both see a free seat (and no booking) and both book; each sends a confirmation
if ($workshop->booked < $workshop->capacity && ! $workshop->bookings()->whereBelongsTo($user)->exists()) { /* create, increment, mail */ }
// good: lock the parent row first, then decide; a unique index on (workshop_id, user_id) backs the "once" rule
$booking = DB::transaction(function () use ($workshop, $user) {
$workshop = Workshop::whereKey($workshop->id)->lockForUpdate()->firstOrFail();
$booking = $workshop->bookings()->firstOrNew(['user_id' => $user->id]);
if ($booking->exists) {
return $booking; // the repeat request gets the same booking, 200
}
throw_if($workshop->booked >= $workshop->capacity, new WorkshopFull); // rendered as a 409
$booking->save();
$workshop->increment('booked');
return $booking;
}, 3);
if ($booking->wasRecentlyCreated) { BookingConfirmed::dispatch($booking); } // only the request that created it
- Decide from the database's answer:
createOrFirst() + wasRecentlyCreated (needs the unique index, and only the key columns as its first argument), insertOrIgnore() === 1, or where('status', 'paid')->update(['status' => 'shipped']) === 1. Never exists()/if ($model->status ...) then write, never read a counter or state and save it back ($model->count++; $model->save(), refresh() is not a lock), and never send, charge or dispatch before the claim succeeded. firstOrCreate without a unique index is check-then-insert, and the unique validation rule is only a pre-check.
- A limit on a single row lives in the
UPDATE's WHERE (->where('stock', '>=', $qty)->decrement('stock', $qty) returns 0 or 1). When the decision also inserts a child row, lock the parent first as above: inserting the child first takes a shared foreign-key lock on the parent, and two requests then deadlock on the parent's UPDATE. After $model->increment(), the model holds the loaded value + n, not the database's value, so never branch on it.
lockForUpdate() holds only inside DB::transaction(): re-read the row with the lock there, then decide. Use the closure form, not beginTransaction(), so an early return can't leave it open. DB::transaction($fn, 3) re-runs the whole closure after a deadlock, so the closure holds no HTTP calls, mail or dispatches (afterCommit()). SQLite compiles locks to nothing, so a passing SQLite test proves nothing about a lock: also test the outcome with the competing write injected (§13).
8c. Outbound HTTP
// bad: 30 s default timeout per attempt, retries a 404 or 422 too, and reads the body of a 500
$rates = Http::retry(3)->get(config('services.carrier.url').'/rates', ['postcode' => $postcode])->json('rates');
// good: one class per integration, settings in config/services.php
public function rates(string $postcode): array
{
return Http::baseUrl(config('services.carrier.base_url'))->withToken(config('services.carrier.key'))
->timeout(2)->connectTimeout(1) // per attempt: attempts × timeout + sleeps must fit the caller's budget
->retry(3, 200, fn (?Throwable $e) => $e instanceof ConnectionException
|| ($e instanceof RequestException && ($e->response->serverError() || $e->response->tooManyRequests())))
->get('/v2/rates', ['postcode' => $postcode]) // after the last attempt, retry() throws by itself
->json('rates');
}
- The client never throws on 4xx/5xx by itself:
->throw() or check ->failed() before reading a body. retry($times) counts attempts, not retries, and by default retries every failure, so always pass when; after the last attempt it throws RequestException (or ConnectionException, which has no response). Catch them only where you have a fallback or a mapping (404 → 422, fallback rate). report() only what a person must act on (a rejected key, a changed contract), not the transient failures the fallback already handles, and give expected domain exceptions (UnknownPostcode) ShouldntReport.
- Retry a POST that creates something only with an idempotency key the partner honours. Never call HTTP inside
DB::transaction(): commit first, or dispatch a queued job with afterCommit() for slow or optional calls.
- Tests, when the app makes HTTP calls:
Http::preventStrayRequests() once for the whole suite (tests/Pest.php or the base TestCase), not in each test file or in an app that calls nothing, a fake for every host (the first matching stub wins), Http::sequence() or Http::failedConnection() for failures, Http::assertSentCount() to prove what was retried, and Sleep::fake() so retry sleeps don't slow the suite.
9. Blade
- Views only render: queries, eager loading (
with, withCount) and paginate()->withQueryString() happen in the controller. Shared data goes through a view composer.
- Layouts and reusable markup are components. Anonymous components declare
@props and put $attributes->merge()/->class() on the root element. Pass PHP values with a colon (:$user).
- Forms:
@csrf on every non-GET form, method="POST" + @method('PUT'), old('title', $post->title), @error, @checked/@selected, route('posts.edit', $post). After a POST, redirect with a flash (to_route(...)->with('status', ...)), never return view().
{{ }} always; {!! !!} only for HTML you sanitised. PHP → JS via @js() / Js::from(). @class([...]) instead of @if inside class="". @can, not inline ownership checks.
9b. Livewire
- Every public property is browser-writable and every public method and
#[On] listener is an endpoint. Hold the model as a typed property (public Article $article, tamper-proof) or #[Locked] an id; never lock a wire:model field. Authorize inside every action, not only in mount() (a policy check, or a lookup through the user's own relation: one of them, not both), and keep helpers protected. Class components under App\Livewire resolve by name (articles.edit is App\Livewire\Articles\Edit): never register them with Livewire::component().
$this->validate() (or $this->form->validate()) before every write, persisting what it returns. Query in #[Computed] methods with eager loading, never Eloquent collections in public properties (they lose their eager loads on the next request). Tests use Livewire::test('articles.edit', [...]) (single-file and class components alike) and count queries on a later ->set()/->call() too, at 5 and 25 rows. Details: references/livewire.md.
9c. Inertia
- Every prop and shared prop is public JSON in the page. Pass arrays (
->only(...), ->through(fn ...)), never models, loaded relations or bare paginators. A resource class only when an API shares it (a JsonResource prop arrives wrapped in data; never JsonResource::withoutWrapping() to unwrap a page prop). Share 'auth' => ['user' => fn () => $request->user()?->only('id', 'name', 'email')], not the model.
- Only closures,
Inertia::optional() and Inertia::defer() are lazy: a query written as a plain value runs on every visit and partial reload. Validation fails with the normal redirect and errors prop, never a 422 JSON. Tests: assertInertia() with component($name, false) when page files are absent, writes sent with X-Inertia. Details: references/inertia.md.
10. Filament (v4/v5)
Check filament/filament in composer.lock, scaffold with make:filament-resource X --generate, and use the v4/v5 API, not v3:
// bad (v3)
use Filament\Forms\Form; use Filament\Tables\Actions\EditAction; use Filament\Forms\Components\Section;
public static function form(Form $form): Form { return $form->schema([...]); }
->actions([EditAction::make()])->bulkActions([...])
// good
use Filament\Schemas\Schema; use Filament\Actions\EditAction; use Filament\Schemas\Components\Section;
public static function form(Schema $schema): Schema { return CustomerForm::configure($schema); } // ->components([...])
->recordActions([EditAction::make()])->toolbarActions([BulkActionGroup::make([DeleteBulkAction::make()])])
- Resource folder per model with
Schemas/ and Tables/ classes; action modals use ->schema(), pages getHeaderActions(), widget properties are non-static.
- Enums implement
HasLabel/HasColor/HasIcon; columns use dot notation and formatters, belongs-to fields ->relationship().
- Policies cover built-in pages and actions only: custom
Actions get ->authorize()/->visible(), inline-edit columns ->disabled(). Scope data in getEloquentQuery(), and User implements FilamentUser.
- Test as Livewire components:
fillForm()->call('create')->assertHasNoFormErrors(), callAction(TestAction::make('x')->table($record)), assertCanSeeTableRecords.
11. Skeleton, config, helpers, style
- Put middleware, exception rendering and
shouldRenderJsonWhen in bootstrap/app.php, schedules in routes/console.php, and providers in bootstrap/providers.php. Listeners are auto-discovered under Application::configure() (a handle*/__invoke method whose first parameter has a class type; handle(object $event) is skipped), so don't also register them. Call env() only in config/*.php.
- Helpers:
Arr::wrap, data_get, str()->slug(), filled(), abort_unless, throw_if, ?->, once(), Number::*.
- Style (Pint laravel preset): guard clauses, no
else, match over switch, native types everywhere, docblocks only for generics or array shapes, constructor promotion, a blank line before return, and typed return types on every controller action.
11b. Errors and logging
- Log an exception as the object:
report($e), or Log::warning('...', ['exception' => $e]) for a chosen level. Never getMessage() alone (no trace), and report and continue, or rethrow, never both. catch (Throwable) only at a boundary that reports (a per-item loop, a job's tail); catch (\Exception) misses TypeError.
- Expected outcomes don't page anyone:
ShouldntReport on your own exceptions, $exceptions->dontReport() for vendor ones, $exceptions->level() for "seen but not a bug", and $exceptions->throttle() matching only the noisy class (default => null). A secret posted to a web form that can fail validation goes in `$exception
…(truncated)
1---2name: laravel-idioms3description: Use for any work in a Laravel codebase, whether reviewing, planning, building, refactoring, debugging, speeding up or testing PHP code in a project with an artisan file or laravel/framework in composer.json, even when the user never says "Laravel". Load it before planning a change or answering a question about the code, not only before editing. Also use it to audit a Laravel codebase, judge its health, find code smells or write a refactor report. Concrete rules for Laravel 11-13 on controllers, Form Requests, policies, collections, Eloquent and N+1, migrations, API auth and errors, webhooks, security, uploads, races, outbound HTTP, events and mail, queues, scheduler, Artisan commands, caching, Blade, Livewire, Inertia, Filament 5, error reporting and logging, dates and money, Pest and PHPUnit tests, plus a mandatory "Before you finish" checklist. Not for PHP projects that aren't Laravel. Complements Laravel Boost's laravel-best-practices skill, so load both when both are installed.4metadata:5 source: https://skillmd.com/skills/alfhen/laravel-idioms6---78# Laravel idioms910Write code the way the Laravel framework, its docs and well-maintained packages (laravel.io, Spatie) write it. Match the project's existing conventions and Laravel version first; these rules decide everything the project hasn't already decided.1112**With Laravel Boost:** load this skill *and* `laravel-best-practices`. Boost's rule files also cover security, migrations, the HTTP client, error handling and mail. This skill adds the concrete rules below, the Laravel 13 / Filament 5 / Pest 5 API specifics, and the mandatory "Before you finish" checklist. Where the two differ on a specific API or pattern, follow this skill; verify version-sensitive APIs with Boost's `search-docs` when it is available.1314**Audit or refactor-report request?** ("evaluate this codebase", "suggest refactors", "audit this app") → follow `references/audit-mode.md`. It ends in a self-contained HTML report built from `assets/audit-report-template.html`.1516## 0. Check the version, then commit to its style1718Read `laravel/framework` in `composer.lock`. The 11+ skeleton has no `Http/Kernel.php`, `Console/Kernel.php`, `Exceptions/Handler.php`, `RouteServiceProvider`, `AuthServiceProvider` or `EventServiceProvider`, and no `routes/api.php` until `php artisan install:api`. On **Laravel 13**, every new model, job and command uses attributes (`#[Fillable]`, `#[Hidden]`, `#[Scope]`, `#[ObservedBy]`, `#[Tries]`, `#[Signature]` + `#[Description]`), and you use them in every new file, not only some. On older versions, or where existing code uses properties, keep properties. An upgraded app may still keep schedules in `app/Console/Kernel.php` or a provider: add new entries where the existing ones live.1920## 1. Controllers orchestrate; they don't compute2122A controller action authorizes, hands validated input to one collaborator, and returns a response. **Limit: about 10 lines per action, one query or one call, and no `private` query/formatting helpers.** When an action needs several queries, aggregation, row mapping or formatting, move that into a class named after what it produces, and have it reuse the model's scopes.23```php24// bad: 60+ lines of joins, sums and formatting in __invoke plus private helpers25// good26public function __invoke(StatsRequest $request, BuildTeamStats $stats): JsonResponse27{28 return response()->json($stats($request->user()->team, $request->filters()));29}30```31Plain CRUD needs no extra class: `$request->user()->posts()->create($request->validated())` is the whole store action. Domain rules that belong to one model (syncing its tags, computing its totals) go in a model method, not in a private controller helper. Use resource routes with CRUD names (`destroy`, not `delete`); a non-CRUD endpoint gets its own invokable controller. Type-hint models for route binding (`{post:slug}`).3233## 2. Validate every input, including query strings3435Every request that reads input gets a FormRequest: store, update, **and** index/report endpoints that take filters, sort keys or `per_page`. An unvalidated `?status=bogus` that silently returns nothing is a bug.36```php37// bad38->when($request->filled('status'), fn ($q) => $q->where('status', $request->string('status')))39// good: IndexPostRequest40public function rules(): array41{42 return [43 'status' => ['sometimes', Rule::enum(PostStatus::class)],44 'per_page' => ['sometimes', 'integer', 'between:1,100'],45 ];46}47```48- Persist only `validated()` / `safe()->only([...])`, never `all()`.49- Optional filters are `nullable` as well as `sometimes`: an empty `?status=` arrives as `null`, and a bare `'string'` rule turns "no filter" into a 422.50- Use array rules with rule objects (`Rule::unique(...)->ignore(...)`, `Rule::enum`, `Password::defaults()`) and built-in rules (`after_or_equal:from`, `size:2`) before writing closures.51- Checks that need the database or another model go in `after()`, and they stop at the first failure so the client gets one clear message per request.52- Normalise input in `prepareForValidation()`. Add typed accessors (`filters()`, `coupon()`) that read `validated()`. Memoise lookups with `once(fn () => ...)`, not hand-written `$resolved` flags.53- Omit `authorize()` when it would just `return true`.54- Input that names a column or a direction (`?sort=`, `?dir=`, a filter key) passes an allow-list (`Rule::in([...])` or a `match`); columns are never bound, so anything else is a 500 or lets a client sort by a hidden column. Never put request data in `whereRaw`/`selectRaw`/`orderByRaw`/`DB::raw`; bind it with `?`. A user's LIKE search escapes `%` and `_` with an explicit `ESCAPE` character, in one scope (`whereLike` doesn't escape, and a backslash matches nothing on SQLite). `exists`/`unique` on tenant data carry the owner: `Rule::exists('folders', 'id')->where('team_id', $this->user()->team_id)`.55- Test optional input with `filled()` or `!== null`, never truthiness: `->when($term, ...)` skips a search for `0`. Details: `references/security.md`.5657## 3. Authorization: policies, one mechanism per controller5859```php60// bad61abort_unless($post->user_id === auth()->id(), 403);62// good: App\Policies\PostPolicy is auto-discovered63public function update(User $user, Post $post): bool64{65 return $post->user()->is($user);66}67```68Choose one mechanism per controller and use it for every action: `Gate::authorize('update', $post)` in each action, route `->can('update', 'post')`, or the FormRequest's `authorize()`. Don't mix them. When an action takes a FormRequest, authorize on the route or in the request's `authorize()`: `Gate::authorize()` in the action runs after validation, so a non-owner sending a bad body gets 422 instead of 403. The 11+ base `Controller` is empty, so `$this->authorize()` / `$this->middleware()` don't exist; don't re-add the traits. Don't register policies manually.6970## 3b. API routes: guards and error responses7172```php73// bad: the default guest redirect calls route('login'). A client that sends no `Accept: application/json`74// (curl, a server-to-server script) gets a 500 in any app without a `login` route, and getJson() tests never see it75// good: bootstrap/app.php76->withMiddleware(function (Middleware $middleware): void {77 $middleware->redirectGuestsTo(fn (Request $request) => $request->is('api/*') ? null : route('login'));78})79```80- JSON endpoints live in `routes/api.php` (`install:api`; it adds the `api/` prefix and no session, cookies or CSRF), never in `routes/web.php` and never with the `web` group. A token API uses `auth:sanctum`; a bare `auth` is the session guard. On a public route that personalises for logged-in callers, read `$request->user('sanctum')`.81- 401 = not authenticated, 403 = authenticated but not allowed (policy), 404 = not found *or* another user's record you don't reveal (scope the query, or `Response::denyAsNotFound()`), 422 = invalid input. Let the framework render them: never `catch (Exception $e) { return response()->json(['error' => $e->getMessage()]) }`. With debug off, a 404 still names the model class (`No query results for model [App\Models\Order]`). Only when the app must not reveal internals, render `NotFoundHttpException` on `api/*` with a plain message.82- Token abilities go on the route, so a token without the scope gets 403 before validation or a lookup runs: alias Sanctum's middleware in `bootstrap/app.php` (`$middleware->alias(['abilities' => CheckAbilities::class])`), run it before route-model binding (`$middleware->prependToPriorityList(SubstituteBindings::class, CheckAbilities::class)`, or a missing id answers 404 and someone else's 403), and use `->middleware('abilities:orders:write')`. Ownership stays in a policy or a query scoped to the user. Don't move `tokenCan()` into a policy or controller: they run after the FormRequest has already answered 422. `throttle:api` needs a `RateLimiter::for('api', ...)`; a login or token endpoint gets its own limiter keyed by email + IP.8384## 3c. Inbound webhooks8586- A provider's signed delivery goes in `routes/api.php` (no session, cookies or CSRF), without `auth` or `throttle`. A fresh 13 skeleton has none: add the file and `api:` to `withRouting()` by hand (`install:api` also installs Sanctum). Not `web` plus a CSRF exclusion: `web` starts a session on every delivery, and a FormRequest there answers a bad payload with a 302.87- Verify in middleware before anything parses the body: `hash_equals(hash_hmac('sha256', $request->getContent(), $secret), (string) $request->header(...))`, failing closed (401) on a missing header or an empty configured secret. Never sign re-encoded JSON.88- Answer 2xx fast and queue the work. Dedupe on the delivery id with a unique index (`createOrFirst()` + `wasRecentlyCreated`), not the cache, and answer a duplicate with the same 2xx; a claimed row still unprocessed when the delivery repeats is dispatched again. Unknown types get their 2xx before any payload rule runs: validate only what every delivery carries (its id and type) up front, and a known type's fields where you process it. A rejected delivery is retried for as long as the provider retries, so never reject on a stricter rule than the provider's contract. State from a delivery is applied only if newer, in one statement (`where(fn ($q) => $q->whereNull('remote_updated_at')->orWhere('remote_updated_at', '<', $at))->update([...])`). A naturally idempotent single write may run inline. Tests post the exact signed bytes with `$this->call()` (`postJson()` re-encodes). Details: `references/webhooks.md`.8990## 4. One source of truth for query rules9192A filter rule is written once, as a composable scope, and every query reuses it: counts, sums and joins alike. Never write a second copy of the same `where` logic in a `DB::table()` query.93```php94#[Scope] // 12.4+; scopeCreatedBetween() before that95protected function createdBetween(Builder $query, ?CarbonInterface $from, ?CarbonInterface $to): void96{97 $query->when($from, fn ($q, $from) => $q->where('created_at', '>=', $from))98 ->when($to, fn ($q, $to) => $q->where('created_at', '<=', $to));99}100101$count = Post::query()->createdBetween($from, $to)->published()->count();102$comments = Comment::query()->whereHas('post', fn ($q) => $q->createdBetween($from, $to)->published());103```104Use `Model::query()`, not `DB::table()`, when a model exists. Let SQL do aggregation (`sum`, `count`, `exists`, `value`, `groupBy`, `withCount/withSum`), not `->get()->sum()`. Join only the tables a query actually reads. Iterate big tables with `lazyById()` / `chunkById()`.105106## 5. Models107108```php109#[Fillable(['title', 'body', 'status'])] // L13; the owner FK and derived columns stay out110#[ObservedBy(PostObserver::class)]111class Post extends Model112{113 protected function casts(): array114 {115 return ['status' => PostStatus::class, 'meta' => AsArrayObject::class, 'published_at' => 'datetime'];116 }117118 protected function title(): Attribute119 {120 return Attribute::make(set: fn (string $v) => trim($v));121 }122123 public function user(): BelongsTo { return $this->belongsTo(User::class); }124}125```126- Use backed enums for every fixed set of states, never class constants. Compare cases (`=== PostStatus::Published`), validate with `Rule::enum`, and set defaults with `->default(PostStatus::Draft->value)` in migrations.127- Write through relationships: `$user->posts()->create()`, `->associate()`, `whereBelongsTo`, `whereRelation`. Add the inverse `hasMany` to the parent model when you need it.128- Derived fields (slug, published_at) go in model events or an observer, so they apply on every Eloquent write. Mass writes skip model events: `where()->update()/delete()`, `insert`, `upsert`, builder `increment`, `DB::table()`. Where an observer must run (audit rows, cache busting), loop with `lazyById()` and save each model, or do the observer's work in the same method.129- Columns holding tokens or secrets go in `#[Hidden]` (13; `$hidden` before). A token you only verify is stored as `hash('sha256', $plain)` and compared with `hash_equals`; `encrypted` casts are for secrets you must read back, and can't be queried.130- No N+1: eager load what loops and resources touch (`with('author:id,name')`), use `whenLoaded()` in resources, and enable `Model::shouldBeStrict(! $this->app->isProduction())`.131132## 5b. Migrations and schema133134- Foreign keys start from `foreignId()`/`foreignIdFor()`. Modifiers go before `constrained()`: `->nullable()->constrained()->nullOnDelete()`. Pick `ON DELETE` on purpose: `cascadeOnDelete()` for owned children (line items, pivots), `nullOnDelete()` on a nullable column for references that must outlive the parent, the default restrict for records that must block a delete.135- Every invariant of the form "one X per Y" (one redemption per user and coupon, one row per SKU) is a unique index, and validation is only a friendly pre-check. Columns in that index are `NOT NULL`, because NULLs never collide.136- Index the columns a hot query filters and sorts on, equality columns first, then the range or sort column: `->index(['customer_id', 'status', 'created_at'])` for `where customer_id = ? and status = ? order by created_at`.137- On a table that already has production rows and running code, change the schema in steps: add the column nullable, backfill it, and switch the reads, then tighten or drop the old column in a later release. Never rename or drop a column in the same deploy as the code that stops using it. On a big MySQL table, give each DDL step its own migration (MySQL runs DDL outside transactions, so a half-applied migration can't simply re-run), create a composite index that leads with the foreign key column before adding the foreign key (MySQL then reuses it instead of building its own), and make `down()` undo every step. A new table or a pre-launch app needs none of this.138- Backfills don't use Eloquent models (their later changes break old migrations, and they fire events and touch `updated_at`). Use `DB::table()->chunkById()` or a set-based `UPDATE`, in a re-runnable command when the table is big. `->change()` restates every attribute you keep (nullable, default, unsigned). Never edit a migration that has run anywhere shared: add a new one.139140## 6. Collections, and no hidden state141142```php143// bad144$names = []; foreach ($users as $u) { if ($u->active) { $names[] = $u->name; } }145// good146$names = $users->filter->active->pluck('name')->values();147[$active, $idle] = $users->partition(fn (User $u) => $u->isActive());148```149A closure inside `map`/`each`/`mapWithKeys` never captures `&$var`. If a step needs a running total, use a plain `foreach` with a named accumulator, or `reduce`. Call `->values()` after `filter/reject/unique` before JSON. Format money with `Number::currency($major, in: 'EUR')` (major units, display only), not `number_format`.150151**Money and dates.** Money is integer minor units or a decimal string, never a float: no `(int) ($price * 100)` (19.99 → 1998). The minor-unit exponent depends on the currency (JPY 0, most 2, KWD 3), so never hard-code `/ 100` when several currencies are in play. Round once, at a stated point (per line or on the total), and split a total by largest remainder so the parts add back up. Validate money input with `decimal:0,N`, N the currency's exponent (`numeric` accepts `1e2`), convert the string with integer maths on its digits (for a signed amount, convert the absolute value and re-apply the sign) (if you call `Brick\Math` directly, require `brick/math` in `composer.json`; it is only a transitive dependency), and cast minor-unit columns `'integer'`. Store UTC; parse a user's input in their zone, then `->utc()`. A user's "today" on a datetime column is `[local midnight, next local midnight)` converted to UTC, never `whereDate()` with UTC `today()`. `addMonth()` overflows (Jan 31 → Mar 3): `$start->toImmutable()->addMonthsNoOverflow($n)` from the original date, not chained from the last result (on a mutable `Carbon` the call moves `$start` itself). Never mutate a date you didn't create (`->copy()`, `toImmutable()`); switching the app default with `Date::use()` is a project decision, not part of a feature. Details: `references/dates-and-money.md`.152153Pipelines replace loops; they are not a mandate to rewrite `array_*` calls. Never add a temp variable and `@var`, or silence the error (`@phpstan-ignore`, `assert()`, a cast), just to make a pipeline fit a declared type.154```php155// bad: the temp exists only to carry a @var156/** @var list<string> $enabled */157$enabled = collect($this->languages($account))->filter(fn (array $l): bool => $l['enabled'] ?? false)->keys()->all();158159return $enabled;160// good161return array_keys(array_filter($this->languages($account), fn (array $l): bool => $l['enabled'] ?? false));162```163The framework types `->all()` as `array<TKey, TValue>` and `->keys()->all()`/`->values()->all()` as `array<int, T>`, never `list<T>`. Where a method returns or a property holds `list<…>`, a single step stays `array_map(...)` / `array_keys(array_filter(...))` / `array_values(array_filter(...))`, and a real multi-step pipeline (or the loop it replaces) returns `array_values(collect($x)->...->all())`. Widen the type to `array<int, T>` only when no caller relies on a list.164165A strict `in_array(..., true)` dedupe becomes `->uniqueStrict()`, never `->unique()`, which compares loosely (`'0'`/`'00'` collapse). Leave `array_unique()` on strings as it is.166167## 7. Queued jobs168169- `implements ShouldQueue` + one `use Queueable;` (`Illuminate\Foundation\Queue\Queueable`). Options as attributes on 13 (`#[Tries(5), Backoff([10, 60, 300]), Timeout(120)]`), never both attribute and property. Pass models to the constructor (`#[WithoutRelations]`, and `#[DeleteWhenMissingModels]` when the row can be deleted before the job runs), services to `handle()`. `dispatch(...)->afterResponse()` is not queueing: it runs in the web process with no retries.170- `handle()` is idempotent: a job can run twice (timeout, crash, `queue:retry`). Guard on persisted state, key writes on a natural key (`updateOrCreate`, unique index, idempotency key upstream; an accumulating write such as adding points needs a claimed row, because `updateOrCreate` would add twice), and do the externally visible effect last. The code that dispatches it is idempotent too: a state change that queues work (`markAsPaid()`) claims the transition with a conditional update (`where('status', 'pending')->update(...)` returns 1) and dispatches only when it won. `SerializesModels` re-fetches by id *without global scopes*, so a soft-deleted model comes back: check `trashed()`/status.171- Nothing to do or already done → `return`. Something failed → let it throw (`Http::timeout(10)->throw()`), or `$this->fail($e)` when retrying can't help. Never catch, log and return, or store "failed" and return: no retry, no `failed_jobs`, no alert.172```php173// bad174try { $client->createShipment($this->order); } catch (RequestException $e) { Log::error($e->getMessage()); return; }175// good: already done → return; failure → throws → backoff → retry → failed()176if ($this->order->shipment()->exists()) { return; }177$this->order->shipment()->create(['reference' => $client->createShipment($this->order)]);178```179- Default is one attempt, and every `release()` (including the `RateLimited`/`WithoutOverlapping` middleware) uses one. Size `#[Tries]` or `retryUntil()` above the releases, add `#[MaxExceptions]`, and always set `#[Backoff]` (default 0 retries in a tight loop).180- Built-in job middleware, not hand-rolled throttles in `handle()`: `RateLimited` + a named `RateLimiter::for()`, `(new WithoutOverlapping($id))->releaseAfter(30)->expireAfter(180)` (defaults: release at once, lock never expires), `(new ThrottlesExceptions(10, 300))->report()` (it swallows the exception otherwise). An upstream 429 → `$this->release()` for its `Retry-After` (capped), not a throw that spends `MaxExceptions`.181- A job that tracks status on a row sets `processing` with a timestamp and defines `failed(?Throwable $e)` (it runs on a fresh instance) that marks the row failed. A killed worker never calls `failed()`, so schedule a recovery for rows stuck past N minutes.182- Timeouts nest: HTTP client timeout < `#[Timeout]` < `retry_after` (default 90; on SQS the queue's visibility timeout) < Supervisor `stopwaitsecs` / container stop grace. Restart workers on every deploy (`queue:restart` / `horizon:terminate`); process config, drivers, containers and monitoring are in `references/queues-and-workers.md`.183- Inside a transaction: `->afterCommit()` on the dispatch; queued listeners and notifications implement `ShouldQueueAfterCommit` (`ShouldHandleEventsAfterCommit` only affects *sync* listeners and observers). Chains and batches have no `afterCommit()`: dispatch them after the transaction returns.184- `ShouldBeUnique` always has `uniqueId()` and a `#[UniqueFor]` between the job's worst total run (every try plus backoff) and its schedule interval: an hourly job whose runs take up to 45 minutes gets `#[UniqueFor(3300)]`, because a lock as long as the interval, orphaned by a killed worker, silently skips the next run. Raise `retry_after` on a dedicated connection for long jobs, not the shared one. Retries must end before any claim or lock around the job expires (`retryUntil()` inside a 15-minute claim), and a long job that times out shouldn't be retried behind the next scheduled copy (`#[FailOnTimeout]`). A batch runs on one queue (set it on the batch); `then()` runs only if every job succeeded, so with `allowFailures()` do completion work in `finally()` and check `hasFailures()`. Only a failure stops a chain: `delete()` and `Skip` let the next job run.185- Mail and notifications: `Mail::to($users)` sends one message with every address in `To`, so loop and send one mailable per recipient. A `ShouldQueue` mailable or notification returns once it is queued, so a "sent" flag set next to it means "queued". The `database` channel needs `make:notifications-table`.186187## 7b. Scheduler188189```php190// bad: lock outlives a killed run by 24 h, runs on every server, and only guards the dispatch191Schedule::call(fn () => Report::sendDaily())->dailyAt('02:30')->withoutOverlapping();192Schedule::job(new SyncStock)->everyFiveMinutes()->withoutOverlapping();193// good (routes/console.php)194Schedule::command(SendDailyReport::class)->dailyAt('07:00')->timezone('Europe/Copenhagen')195 ->onOneServer()->withoutOverlapping(30)->pingOnFailure(config('services.alerts.url'));196Schedule::job(new SyncStock)->everyFiveMinutes()->onOneServer(); // SyncStock: ShouldQueue, ShouldBeUnique, uniqueId(), #[UniqueFor]197```198- Three different overlap guards: the scheduler's `withoutOverlapping($minutes)` (default 1440, so always pass an expiry just above the worst run), the job middleware's `expireAfter($seconds)` (default never), and `Cache::lock()`. On `Schedule::job()` the scheduler's guard covers only the dispatch.199- Several servers or containers run the scheduler → `onOneServer()`, with the lock store chosen by environment (`SCHEDULE_CACHE_STORE=redis` or `CACHE_STORE=redis` in production). Never hardcode `redis` in code or as an `env()` default: tests and local runs have no Redis, and the `array` store tests the same locks. Closures need `->name()` before `withoutOverlapping()`/`onOneServer()`. One server → neither.200- When the task or app names a business timezone other than the app's (never invent one), every time-of-day entry (`dailyAt`, `weeklyOn`, nightly cleanups) runs in it: `->timezone()` on each, or `'schedule_timezone'` in `config/app.php`, at a local hour outside the DST change (03:00 or later in EU zones), never a UTC time picked to dodge it. Scheduled output is discarded unless you send it somewhere (`->appendOutputTo(storage_path('logs/x.log'))`) or the command logs it. Alert with `onFailure()`/`pingOnFailure()`, not `thenPing()`/`after()` (they fire on any exit). On `Schedule::job()` hooks mean "dispatched", so completion handling lives in the job.201- A dispatcher selects work by persisted state (`whereNull('synced_at')`), never by a time window (missed ticks are never replayed), and claims rows (stamp a column) or dispatches unique jobs, so the next tick doesn't re-dispatch rows still in flight. Long work is a queued job or a command, never a long closure.202203## 7c. Console commands204205```php206// bad: work in the constructor, `return;` on an error exits 0, chunk() skips rows it deletes207// good208#[Signature('carts:prune {--days=30} {--dry-run} {--force}')]209#[Description('Delete abandoned carts older than --days')]210class PruneAbandonedCarts extends Command211{212 use ConfirmableTrait;213214 public function handle(): int215 {216 if (! $this->confirmToProceed()) { // asks only in production; --force skips; no TTY → cancelled217 return self::FAILURE;218 }219220 $deleted = 0;221 foreach (Cart::query()->abandonedFor((int) $this->option('days'))->lazyById() as $cart) {222 $cart->delete();223 $deleted++;224 }225226 $this->info("Deleted {$deleted} carts.");227228 return self::SUCCESS;229 }230}231```232- Any failure exits non-zero: `return self::FAILURE` or `$this->fail('...')`, including "some rows failed" (`report($e)` each, count, then FAILURE). Never a bare `return;` or a bool on an error path: cron, ECS and `onFailure()` only see the exit code. No work in the constructor (every `artisan` call builds every command); inject services into `handle()`.233- Only commands that people run by hand against production data get `ConfirmableTrait` + `{--force}` and a `--dry-run` that reports and changes nothing. A cleanup only the scheduler runs needs neither (scheduling it with `--force` is the smell), and read-only commands never do. Every prompted value is also an argument or option (cron has no TTY). Laravel Prompts' `confirm()` defaults to **true**, so pass `default: false` before anything destructive.234- Loops that update or delete the rows they filter on use `lazyById()`/`chunkById()`, never `chunk()` (offset pages skip rows). A command that must never run twice at once implements `Isolatable` or gets `withoutOverlapping()` in the schedule. `Isolatable` locks before `handle()`, so the lock also covers a `--dry-run` and an open confirmation prompt: a command people preview by hand takes a `Cache::lock()` around the deleting part instead.235236## 7d. Files and uploads237238- Validate every upload with a type allow-list and a size cap: `File::types(['pdf', 'png', 'jpg'])->max('5mb')`, or `['file', 'mimes:csv,txt', 'max:5120']`. `mimes` checks the type sniffed from the content, so a CSV can sniff as `text/plain` (a header-only, single-column or semicolon file): always allow `txt` next to `csv`. Never pick a parser or a stored name from `getClientOriginalExtension()`/`getClientOriginalName()`.239- Store with `$file->store('documents', 'local')` (a random `hashName()`), naming the private disk every time you store, check or serve the file (the skeleton's `local` is `storage/app/private`; the default disk can be changed by config). Keep the client's name in a column if you need it. The `public` disk is only for files every anonymous visitor may read. Serve a private file from an authorized route with `Storage::disk('local')->download($path, $name)`, or a link that expires (`URL::temporarySignedRoute(..., now()->addMinutes(10), ...)` behind the `signed` middleware, or `Storage::temporaryUrl()`): a plain `signedRoute()` never expires. Check `exists()` on the same disk first, because `download()` on a missing file is a 500.240- Rows from files and payloads are hostile. Strip a UTF-8 BOM from the first line, then find columns by name, with headers trimmed and lower-cased. When fields never contain line breaks (most feeds), read line by line and parse each with `str_getcsv()`, so line numbers stay physical and one stray quote breaks one row, not the rest of the file. Skip blank and whitespace-only lines, check the column count before `array_combine`, and check each row with a few explicit tests whose message names the column and value (a `Validator` per row is heavy for a big file and its messages are generic), reporting the file's line number. Import the good rows unless the brief says all-or-nothing. Read with a stream (`fopen`/`SplFileObject`/`Storage::readStream()`), close the handle in `finally`, and store the file before queueing its processing (a job gets the path, never the `UploadedFile`).241242## 8. Caching243244```php245// bad: race, and no TTL means forever246if (! Cache::has('stats:users')) { Cache::put('stats:users', User::count()); }247// good248$count = Cache::remember("team:{$team->id}:stats:users", now()->addMinutes(5), fn () => $team->users()->count());249```250- Always pass a TTL. `remember()` re-runs a closure that returns `null`, so cache a sentinel. `Cache::flexible($key, [300, 3600], ...)` for hot values that may be briefly stale.251- Keys are namespaced (`domain:entity:id:variant`), include every input and the tenant/user id, and get a `:v2` segment when the payload shape changes.252- Cache arrays or ids, not models (`serializable_classes => false`). Invalidate with `forget()` from an observer (`ShouldHandleEventsAfterCommit`), never `Cache::flush()`. `tags()` throws on the default `database` store.253- Atomic: `add()` for once-per-window guards, `add(key, 0, ttl)` + `increment()` for counters. Locks always get seconds and release in `finally` (or pass a closure). Rate limiters are named `RateLimiter::for()` keyed by user id or IP.254- Memoize repeated reads per request with `Cache::memo()`; tests use the array store plus `travel()`, never a mocked `remember`.255256## 8b. Races: let the database decide257258Applies to contended counters, caps, "one per user" rows and state changes with side effects. A plain CRUD write needs none of it.259```php260// bad: two requests both see a free seat (and no booking) and both book; each sends a confirmation261if ($workshop->booked < $workshop->capacity && ! $workshop->bookings()->whereBelongsTo($user)->exists()) { /* create, increment, mail */ }262// good: lock the parent row first, then decide; a unique index on (workshop_id, user_id) backs the "once" rule263$booking = DB::transaction(function () use ($workshop, $user) {264 $workshop = Workshop::whereKey($workshop->id)->lockForUpdate()->firstOrFail();265 $booking = $workshop->bookings()->firstOrNew(['user_id' => $user->id]);266 if ($booking->exists) {267 return $booking; // the repeat request gets the same booking, 200268 }269 throw_if($workshop->booked >= $workshop->capacity, new WorkshopFull); // rendered as a 409270 $booking->save();271 $workshop->increment('booked');272273 return $booking;274}, 3);275if ($booking->wasRecentlyCreated) { BookingConfirmed::dispatch($booking); } // only the request that created it276```277- Decide from the database's answer: `createOrFirst()` + `wasRecentlyCreated` (needs the unique index, and only the key columns as its first argument), `insertOrIgnore() === 1`, or `where('status', 'paid')->update(['status' => 'shipped']) === 1`. Never `exists()`/`if ($model->status ...)` then write, never read a counter or state and save it back (`$model->count++; $model->save()`, `refresh()` is not a lock), and never send, charge or dispatch before the claim succeeded. `firstOrCreate` without a unique index is check-then-insert, and the `unique` validation rule is only a pre-check.278- A limit on a single row lives in the `UPDATE`'s `WHERE` (`->where('stock', '>=', $qty)->decrement('stock', $qty)` returns 0 or 1). When the decision also inserts a child row, lock the parent first as above: inserting the child first takes a shared foreign-key lock on the parent, and two requests then deadlock on the parent's `UPDATE`. After `$model->increment()`, the model holds the loaded value + n, not the database's value, so never branch on it.279- `lockForUpdate()` holds only inside `DB::transaction()`: re-read the row with the lock there, then decide. Use the closure form, not `beginTransaction()`, so an early return can't leave it open. `DB::transaction($fn, 3)` re-runs the whole closure after a deadlock, so the closure holds no HTTP calls, mail or dispatches (`afterCommit()`). SQLite compiles locks to nothing, so a passing SQLite test proves nothing about a lock: also test the outcome with the competing write injected (§13).280281## 8c. Outbound HTTP282283```php284// bad: 30 s default timeout per attempt, retries a 404 or 422 too, and reads the body of a 500285$rates = Http::retry(3)->get(config('services.carrier.url').'/rates', ['postcode' => $postcode])->json('rates');286// good: one class per integration, settings in config/services.php287public function rates(string $postcode): array288{289 return Http::baseUrl(config('services.carrier.base_url'))->withToken(config('services.carrier.key'))290 ->timeout(2)->connectTimeout(1) // per attempt: attempts × timeout + sleeps must fit the caller's budget291 ->retry(3, 200, fn (?Throwable $e) => $e instanceof ConnectionException292 || ($e instanceof RequestException && ($e->response->serverError() || $e->response->tooManyRequests())))293 ->get('/v2/rates', ['postcode' => $postcode]) // after the last attempt, retry() throws by itself294 ->json('rates');295}296```297- The client never throws on 4xx/5xx by itself: `->throw()` or check `->failed()` before reading a body. `retry($times)` counts attempts, not retries, and by default retries every failure, so always pass `when`; after the last attempt it throws `RequestException` (or `ConnectionException`, which has no response). Catch them only where you have a fallback or a mapping (404 → 422, fallback rate). `report()` only what a person must act on (a rejected key, a changed contract), not the transient failures the fallback already handles, and give expected domain exceptions (`UnknownPostcode`) `ShouldntReport`.298- Retry a POST that creates something only with an idempotency key the partner honours. Never call HTTP inside `DB::transaction()`: commit first, or dispatch a queued job with `afterCommit()` for slow or optional calls.299- Tests, when the app makes HTTP calls: `Http::preventStrayRequests()` once for the whole suite (`tests/Pest.php` or the base `TestCase`), not in each test file or in an app that calls nothing, a fake for every host (the first matching stub wins), `Http::sequence()` or `Http::failedConnection()` for failures, `Http::assertSentCount()` to prove what was retried, and `Sleep::fake()` so retry sleeps don't slow the suite.300301## 9. Blade302303- Views only render: queries, eager loading (`with`, `withCount`) and `paginate()->withQueryString()` happen in the controller. Shared data goes through a view composer.304- Layouts and reusable markup are components. Anonymous components declare `@props` and put `$attributes->merge()`/`->class()` on the root element. Pass PHP values with a colon (`:$user`).305- Forms: `@csrf` on every non-GET form, `method="POST"` + `@method('PUT')`, `old('title', $post->title)`, `@error`, `@checked`/`@selected`, `route('posts.edit', $post)`. After a POST, redirect with a flash (`to_route(...)->with('status', ...)`), never `return view()`.306- `{{ }}` always; `{!! !!}` only for HTML you sanitised. PHP → JS via `@js()` / `Js::from()`. `@class([...])` instead of `@if` inside `class=""`. `@can`, not inline ownership checks.307308## 9b. Livewire309310- Every public property is browser-writable and every public method and `#[On]` listener is an endpoint. Hold the model as a typed property (`public Article $article`, tamper-proof) or `#[Locked]` an id; never lock a `wire:model` field. Authorize inside every action, not only in `mount()` (a policy check, or a lookup through the user's own relation: one of them, not both), and keep helpers `protected`. Class components under `App\Livewire` resolve by name (`articles.edit` is `App\Livewire\Articles\Edit`): never register them with `Livewire::component()`.311- `$this->validate()` (or `$this->form->validate()`) before every write, persisting what it returns. Query in `#[Computed]` methods with eager loading, never Eloquent collections in public properties (they lose their eager loads on the next request). Tests use `Livewire::test('articles.edit', [...])` (single-file and class components alike) and count queries on a later `->set()`/`->call()` too, at 5 and 25 rows. Details: `references/livewire.md`.312313## 9c. Inertia314315- Every prop and shared prop is public JSON in the page. Pass arrays (`->only(...)`, `->through(fn ...)`), never models, loaded relations or bare paginators. A resource class only when an API shares it (a `JsonResource` prop arrives wrapped in `data`; never `JsonResource::withoutWrapping()` to unwrap a page prop). Share `'auth' => ['user' => fn () => $request->user()?->only('id', 'name', 'email')]`, not the model.316- Only closures, `Inertia::optional()` and `Inertia::defer()` are lazy: a query written as a plain value runs on every visit and partial reload. Validation fails with the normal redirect and `errors` prop, never a 422 JSON. Tests: `assertInertia()` with `component($name, false)` when page files are absent, writes sent with `X-Inertia`. Details: `references/inertia.md`.317318## 10. Filament (v4/v5)319320Check `filament/filament` in `composer.lock`, scaffold with `make:filament-resource X --generate`, and use the v4/v5 API, not v3:321```php322// bad (v3)323use Filament\Forms\Form; use Filament\Tables\Actions\EditAction; use Filament\Forms\Components\Section;324public static function form(Form $form): Form { return $form->schema([...]); }325->actions([EditAction::make()])->bulkActions([...])326// good327use Filament\Schemas\Schema; use Filament\Actions\EditAction; use Filament\Schemas\Components\Section;328public static function form(Schema $schema): Schema { return CustomerForm::configure($schema); } // ->components([...])329->recordActions([EditAction::make()])->toolbarActions([BulkActionGroup::make([DeleteBulkAction::make()])])330```331- Resource folder per model with `Schemas/` and `Tables/` classes; action modals use `->schema()`, pages `getHeaderActions()`, widget properties are non-static.332- Enums implement `HasLabel`/`HasColor`/`HasIcon`; columns use dot notation and formatters, belongs-to fields `->relationship()`.333- Policies cover built-in pages and actions only: custom `Action`s get `->authorize()`/`->visible()`, inline-edit columns `->disabled()`. Scope data in `getEloquentQuery()`, and `User implements FilamentUser`.334- Test as Livewire components: `fillForm()->call('create')->assertHasNoFormErrors()`, `callAction(TestAction::make('x')->table($record))`, `assertCanSeeTableRecords`.335336## 11. Skeleton, config, helpers, style337338- Put middleware, exception rendering and `shouldRenderJsonWhen` in `bootstrap/app.php`, schedules in `routes/console.php`, and providers in `bootstrap/providers.php`. Listeners are auto-discovered under `Application::configure()` (a `handle*`/`__invoke` method whose first parameter has a class type; `handle(object $event)` is skipped), so don't also register them. Call `env()` only in `config/*.php`.339- Helpers: `Arr::wrap`, `data_get`, `str()->slug()`, `filled()`, `abort_unless`, `throw_if`, `?->`, `once()`, `Number::*`.340- Style (Pint laravel preset): guard clauses, no `else`, `match` over `switch`, native types everywhere, docblocks only for generics or array shapes, constructor promotion, a blank line before `return`, and typed return types on every controller action.341342## 11b. Errors and logging343344- Log an exception as the object: `report($e)`, or `Log::warning('...', ['exception' => $e])` for a chosen level. Never `getMessage()` alone (no trace), and report and continue, or rethrow, never both. `catch (Throwable)` only at a boundary that reports (a per-item loop, a job's tail); `catch (\Exception)` misses `TypeError`.345- Expected outcomes don't page anyone: `ShouldntReport` on your own exceptions, `$exceptions->dontReport()` for vendor ones, `$exceptions->level()` for "seen but not a bug", and `$exceptions->throttle()` matching only the noisy class (`default => null`). A secret posted to a `web` form that can fail validation goes in `$exception346347…(truncated)