laravel-larastan
Use when configuring Larastan or reading its findings in a Laravel app: which of its rules are on by default and which to opt into, how model properties are inferred from migrations, how to type build
SKILL.mdskills/laravel-larastan/SKILL.md
GitHublaravel-larastan
Step 7 (gate) of the pipeline (WORKFLOW.md), and the typing side of step 6. skills/laravel-conventions §9
says that static analysis runs and that a baseline only shrinks; this block is the detail underneath:
the rule catalogue, the settings that change what the analyser can see, and the ways to feed it types.
Special status. New block, 🟡: never run on real work in house. Checked on 2026-10-20 against the Larastan
repository's own documentation, 3.x line (its default branch). Parameter names and defaults are version facts:
re-read docs/rules.md and
docs/custom-config-parameters.md of the pinned version before changing a setting (skills/source-freshness).
When
A phpstan.neon is created or edited, a Larastan error needs a decision (fix, type, ignore, baseline), or new
Eloquent code (a builder, a factory, a custom collection, an accessor) is written.
Steps
- Know what it is. An extension for PHPStan that boots the application's container to resolve types only knowable at runtime, so it executes some of your code at analysis time. The README at the 2026-10-20 reading: the 3.x line needs PHP 8.2+ and Laravel 11.15+ (its version table says 11.16+ for the line, an inconsistency inside the page: take the stricter); Laravel 9 to 11.16 stays on 2.x and older Laravel on 1.x. The operator installs it as a dev dependency and includes its extension file in the PHPStan config; this block installs nothing.
- Default rules are on for a reason; do not switch them off to make an error go away. Documented as on by
default at the reading:
Model::make()(usenew), collection calls that a database query could answer,env()outside the config directory (it returns null when config is cached),$appendsentries that are not computed properties, and the relation existence check on queries, eager loads and a model's default$with/$withCount(always on, no switch). The rule catalogue lists four more without stating a default or a parameter (dispatch argument types against the job constructor, uselessvalue()andwith()calls, a deferrable provider missingprovides()): treat them as present but check the installed version. - Opt into the rules that catch real production defects. Disabled by default at the reading, each behind a
named parameter: model property names in methods that take one (typos in
create([...])), unique jobs that do not declare a lock lifetime or an id for a parameterised job, unique jobs dispatched through batches or bulk, queued jobs holding a model in a public property without the model-serialising trait, batched jobs missing the batch trait, batchable jobs that never check cancellation, and a job dispatched inside a transaction without deferring to commit (skills/laravel-dispatch-after-commit). Enable them one at a time and fix or baseline the first run, deliberately. - Opt-in rules with a stated false-positive risk stay a choice. The catalogue itself warns that the
unused-views rule may report false positives; the missing-translations check cannot see translations stored in a
database, so it stays off there (the catalogue says so); the Octane compatibility check is for apps that
run on it; the implicit builder-call rule enforces
Model::query()->where()overModel::where(). Turn them on when the team decided, not as a default. - Help the analyser see the schema. It reads model properties from migrations (and squashed schema
dumps). Migrations in non-default places need
databaseMigrationsPath; conditional migration code is assumed to evaluate true; PostgreSQL schema dumps parse poorly with the default parser, so either use a parser the docs name (installing the second SQL parser package makes it switch automatically) or generate migrations it can read. Schema dumps have their own path option (squashedMigrationsPath, defaultdatabase/schema). By default only the declared return type of acasts()method is used; the method body is parsed for cast types only whenparseModelCastsMethodis on, at a speed cost. - Type the Eloquent extension points. A custom builder (the model uses the builder trait, declares the
builder class), a factory whose generic template is the model and which the model names, and a custom
collection with its generic type give the analyser what it needs (the builder and collection traits are
documented for Laravel 11+, older versions override the model methods); the docs say custom builders analyse
better than model scopes. An attribute accessor must be a protected method returning the attribute type
with its generic types (getter type first, setter argument second). Where a project forbids
scopes (
skills/laravel-no-fat-models), the builder is the typed alternative. - Choose the level and hold it. The sample config starts at level 5, and level 10 is the highest; raise it as the codebase allows, never lower it to pass. A raise is its own change.
- An ignore is a reviewed decision. Prefer fixing, then a PHPDoc type, then a narrow ignore with the
error identifier and a reason (
skills/code-baseline§8 point 13; own guidance, the documentation only shows the line and regex forms). Blanket line ignores and loose regexes hide the next real error of the same shape. The one documented error to ignore is a higher-order message on a plain support collection; anything else is investigated first. - A baseline freezes the past, not the future. Generate it once for a legacy codebase; the diff must not
add entries (
skills/laravel-verification). A memory-limit failure is fixed with the memory option, not by narrowing the analysed paths.
Output / checkpoint
Analysis passes at the project's level with no new baseline entry and no new ignore without a reason; each
enabled optional rule is named in the config with the decision that enabled it. Checked at gate (7).
Guardrails
No comments in the code produced. Do not edit the baseline to hide a finding the diff introduced. A rule turned off to make a build green is reported, not applied.
Origin
Rewritten from the Larastan repository documentation (larastan/larastan, MIT per repository metadata, 3.x
line, read 2026-10-20): the README (requirements, support matrix, config skeleton, memory limit, ignoring and
baseline), docs/rules.md (25 rules with defaults and parameters, every opt-in name in step 3 matched),
docs/custom-config-parameters.md, docs/features.md (builders, factories, collections, accessors) and
docs/errors-to-ignore.md. Not covered by the configuration page and therefore sourced to the rule catalogue
only: the Octane, unused-views, missing-translations and implicit-builder options. Independent verification 2026-10-21: 20 checked, 17 matched, 3 corrected (casts() body versus return type, the scale wording, the translations remark was documented), 0 unverified. Own guidance: the baseline
discipline of steps 7 to 9 beyond what the README shows, and the "diff must not add entries" rule. Mechanisms
only, rewritten in our words. Version-sensitive: rule names, parameter names and defaults.