Plugin Laravel Laravel Package

Product Decisions This Supports

• Shift-Left Becomes a Configurable Product Surface: v3.17.0 introduces the first opt-in rules — UnregisteredRouteName and UnconfiguredFilesystemDisk — that turn string-keyed lookups (route('users.shwo'), Storage::disk('publik')) from runtime-only failures into CI failures. This is a policy decision, not just a tooling upgrade: teams can now choose to make a class of "typo → 500 in production" bugs unmergeable, and can stage that decision independently of the base plugin upgrade.
• Noise Reduction Is a Feature, Not a Fix: {relation}_count / {relation}_exists are now int|null unless withCount()/loadCount()/$withCount is proven on that model, and withMin/withMax/withSum/withAvg attributes take the related column's type. Previously these were typed as always-present ints, which produced RedundantCondition false positives that trained engineers to ignore Psalm output. Fewer spurious warnings directly increases the merge gate's credibility — a measurable adoption lever.
• Coverage of Real Laravel Codebase Shapes: Relation generics now infer through traits and relation methods that delegate to another relation (return $this->allRevisions()->where(...)), and $this is preserved as the declaring model for relation calls in non-final parent/child models. Trait-composed relations and shared base models are the norm in mature Laravel apps — this release moves those from MorphMany<Model, Model> to MorphMany<PaymentSlip, Member>, which is the difference between a typed domain layer and an untyped one.
• Conditional Query Logic Is Now Checked: when()/unless() callback parameters are typed from the condition value (truthy for when(), falsy for unless(), closure return type for Closure conditions). This is where conditional filter builders, admin search screens, and report generators live — previously a callback taking string where the condition produced int went completely unverified.
• Collection Pipelines Narrow Correctly: Collection::filter(callable) now narrows like where(callable), and is_subclass_of(), is_a(), is_scalar(), is_iterable(), is_resource(), and null checks are recognized in both. Domain code that filters heterogeneous collections now yields Countable&Stringable or class-string<Job> instead of the widened input type — better autocomplete, better refactor safety, better analysis of downstream calls.
• Friction Removal in Bulk Relation Assignment: BelongsToMany::sync() / syncWithoutDetaching() / syncWithPivotValues() and the Laravel 13 *OrFail() variants now accept any Collection, not just the exact generic shape. $user->roles()->sync($roles->pluck('id')) no longer trips InvalidArgument / ImplicitToStringCast. This was a common pain point in role/permission and tagging features where teams had been writing suppressions.
• Dynamic Instantiation Is No Longer a Dead End: Model is now @psalm-consistent-constructor, so new $class() on a class-string<Model> stops being UnsafeInstantiation — unblocking factory patterns, generic repository/registry code, and polymorphic instantiation helpers. The tradeoff is honest: models overriding __construct incompatibly are now reported, because Eloquent's own new static($attributes) already breaks on them.
• Reliability of the Gate Itself: Two fixes target the worst failure mode — analysis that silently doesn't happen. Analysis-time type checks no longer autoload analyzed classes (which previously crashed the run or silently disabled the plugin on a vendor load-time deprecation), and first-class callables ($request->input(...), Artisan::command(...), Job::dispatch(...)) no longer crash with zend.assertions=1. Combined with v3.16.6's silent-mixed fix, this continues the pattern of making a green build mean something.
• Build vs. Buy: Reinforces Buy, and strengthens the argument against in-house stubs. Traits-based relation inference, per-receiver scope/SoftDeletes resolution on shared custom builders, aggregate-attribute provenance tracking, and is_subclass_of-aware collection narrowing are all deep framework-and-analyzer integration work. An in-house stub set would need continuous re-derivation from Laravel internals to match this, and would never surface the silent-disable class of bug.
• Adoption Sequencing as a Roadmap Item: Because the new rules are opt-in (<findUnregisteredRouteNames>, <findUnconfiguredFilesystemDisks>, or <experimental value="true" />), rollout can be planned in phases: upgrade plugin → triage existing-codebase fallout → enable rules on a new-code path or with a baseline → promote to global. That is a product rollout plan, not a single dependency bump.

When to Consider This Package

Adopt if:

• You run Psalm in CI and want it to actually gate merges on Laravel code — events/listeners, HTTP client, pipelines, form requests, facades, mail, notifications, Eloquent relations, console commands, DB/schema introspection.
• You have Macroable-extended or facade-heavy code paths where methods previously resolved to mixed and were therefore unanalyzed.
• You want route-name and filesystem-disk typos caught at CI time rather than in staging or production. The two new opt-in rules are the highest-value-per-effort items in this release for most applications; each is a one-line config change.
• Your codebase uses relation methods defined in traits or delegating relation methods ($this->rel()->where(...)), or shares a custom builder across parent and child models — this release specifically corrects inference for all three.
• You use withCount / withExists / withMin / withMax / withSum / withAvg and were seeing RedundantCondition noise on the generated attributes.
• You use conditional query builders via when()/unless() with typed callbacks and want those parameter types verified.
• You bulk-assign relations with sync() / syncWithoutDetaching() / syncWithPivotValues() passing collections (role/permission, tagging, team-membership features).
• You instantiate models dynamically from class-string<Model> via a factory, registry, or repository pattern.
• You run analysis with zend.assertions=1 (common in dev/CI) and use first-class callable syntax anywhere — prior versions could crash outright.

Look elsewhere if:

• You use PHPStan or Larastan rather than Psalm — every change here is Psalm-plugin specific.
• Your app is pre-Laravel 11 (use psalm/[email protected]).
• You need runtime protection. These remain purely static-analysis changes; zero runtime effect, no new dependency, no infrastructure change.
• Your codebase has no macros, no facades, no dynamic dispatch, no trait-composed relations — the highest-value inference fixes wouldn't bite, though the two opt-in rules and the aggregate-attribute typing still would.

Caution:

• Upgrading the plugin may surface newly reported issues where mixed or over-narrow types previously masked them. v3.16.6 already warned of this; expect a second, smaller wave here — particularly from the {relation}_count nullability change, which will suppress some RedundantCondition while possibly surfacing PossiblyNullOperand-style issues at call sites that assumed non-null.
• Enabling the opt-in rules on a legacy codebase will likely produce a long tail of genuine hits (dead routes after refactors, disks renamed over time). Budget a burndown, not a single afternoon: scope the rules to new/changed code first, baseline the existing findings, then ratchet. Enabling <experimental value="true" /> switches on both rules at once plus other experimental behavior — prefer the individual flags if you want controlled rollout.
• sync() now accepting any Collection removes a validation signal; if your team was relying on that error to catch passing the wrong collection (e.g. models instead of IDs), that protection is gone — cover it with a test instead.
• Model as @psalm-consistent-constructor will now flag models that override __construct incompatibly. The plugin is right that Eloquent already breaks there, but the issue will appear as new noise on upgrade.

How to Pitch It (Stakeholders)

For Executives:

"This release moves our static analysis from 'catches some bugs' to 'catches a specific, expensive class of bugs at merge time.' Two new opt-in checks flag misspelled route names and unconfigured storage disks — both of which currently fail only when a user hits that code path, often in production. Beyond that, the analyzer now understands how our Eloquent relations and collections actually work, so it produces far fewer false alarms and far more real findings on the code most of our business logic lives in. It also fixes two cases where the tool could silently stop working. No runtime impact, no new cost, no infrastructure change. Rollout is phased and reversible: upgrade, triage, then switch the new checks on."

Key Outcomes:

• Typos in route names and storage disks become CI failures instead of production 500s — enabled per-project, so we control the blast radius.
• Fewer false positives on withCount/withSum attributes and bulk relation sync() calls, which directly increases how much engineers trust a red build.
• Deeper coverage of traits, shared base models, and custom builders — the structural patterns our largest applications actually use.
• The gate stops silently failing — fixes for a plugin-disabling autoload crash and a first-class-callable crash under zend.assertions=1.
• Zero runtime risk; a config flag and a composer update.

For Engineering Teams:

*"v3.17.0 is mostly inference and reliability, plus our first two opt-in rules.

New opt-in checks (off by default):

• UnregisteredRouteName — validates route names in route(), to_route(), URL::route()/signedRoute()/temporarySignedRoute(), Redirect::route(), redirect()->route(), and url()->route() against the booted app's route table. Enable with <findUnregisteredRouteNames value="true" /> (or <experimental value="true" />).
• UnconfiguredFilesystemDisk — validates Storage::disk() names against filesystems.disks, with a closest-name suggestion. Enable with <findUnconfiguredFilesystemDisks value="true" />. Bonus: \Storage::disk() now narrows to FilesystemAdapter like the facade already did.

 return redirect()->route('users.shwo', $user);
+// UnregisteredRouteName: Route name 'users.shwo' is not registered

 Storage::disk('publik')->put($path, $contents);
+// UnconfiguredFilesystemDisk: Disk 'publik' is not configured in filesystems.disks, did you mean 'public'?

Sharper inference:

• when()/unless() callback params are typed from the condition: when() passes the truthy value, unless() the falsy one, a Closure condition passes its return type. Wrong-type callbacks are now InvalidArgument.
• Relation generics infer through traits and delegating relation methods (return $this->allRevisions()->where(...)) — MorphMany<Model, Model> becomes MorphMany<PaymentSlip, Member>.
• Collection::filter(callable) narrows like where(callable), and both recognize is_subclass_of(), is_a(), is_scalar(), is_iterable(), is_resource(), !is_null($x), $x !== null — yielding Countable&Stringable, class-string<Job>, etc.
• BelongsToMany::sync() / syncWithoutDetaching() / syncWithPivotValues() and the Laravel 13 *OrFail() variants accept any Collection; $user->roles()->sync($roles->pluck('id')) no longer errors.
• $this stays the declaring model for relation calls in non-final parent/child models — no more MoreSpecificReturnType / LessSpecificReturnStatement on return $this->rel()->where(...).
• Scopes and SoftDeletes methods resolve per receiver model on a custom builder shared between parent and child, instead of whichever model was scanned last.

Fixes:

• {relation}_count / {relation}_exists are int|null unless withCount()/withExists()/loadCount()/loadExists() is proven on that model (or in $withCount); withMin/withMax/withSum/withAvg typed from the related column. Expect some RedundantCondition warnings to disappear and a few null-safety issues to appear.
• Model is @psalm-consistent-constructor — new $class() on a class-string<Model> is no longer UnsafeInstantiation; a model overriding __construct incompatibly is now reported (Eloquent's own new static($attributes) already breaks on it).
• @psalm-mutation-free dropped from Request::input() (it lazily decodes JSON) — FormRequest overrides no longer flagged.
• Analysis-time type checks no longer autoload analyzed classes, which previously crashed the run or silently disabled the plugin when a vendor file raised a load-time deprecation.
• First-class callables ($request->input(...), Artisan::command(...), Job::dispatch(...)) no longer crash with zend.assertions=1.

Action:

1. composer update psalm/plugin-laravel, re-run analysis, triage the delta (don't suppress — the new findings are the point).
2. Enable <findUnregisteredRouteNames> first; it's the highest signal-to-noise check in this release. Baseline existing hits, then ratchet.
3. Enable <findUnconfiguredFilesystemDisks> next — usually a short list of renamed/legacy disks.
4. If your team was relying on sync()'s old strictness to catch passing the wrong collection, add a test; that check is intentionally gone."

Why Now?

• Low effort: one composer update, one triage pass, two optional config flags.
• High reward: converts typos that fail at runtime into merge-time failures, and removes false positives that were eroding trust in the gate.
• Keeps the gate honest: the autoload and zend.assertions fixes eliminate paths where analysis silently did nothing — the same class of problem v3.16.6 addressed for mixed types.
• Future-proof: better trait/relation/builder inference and Model constructor consistency align with Laravel 11–13's stricter typing as our applications grow more dynamic, not less.