phpstan-trace

phpstan-trace

Inspect the full type-inference chain of a variable at a PHP source location.

When to use

Invoke this skill before attempting to fix a PHPStan type error when any of these signals are present:

• The variable is touched in 2+ scopes (passed into a closure, callback, helper, or array map).
• A third-party extension is plausibly involved: larastan Eloquent magic attributes ($user->name, $model->created_at), webmozart/assert or beberlei/assert guards, doctrine collections, dynamic-return-type extensions (e.g. Model::query()).
• The enclosing method is longer than ~30 lines OR the file exceeds ~100 lines.
• The error involves generics, array{...} shapes, or template parameters that don't match what you expect from reading the signature.
• You already read the source and the inferred type at the error line still doesn't make sense.
• The error is Cannot access property X on string, ... expects Foo, Foo|null given, ... always evaluates to true/false, or a similar "where did this type come from?" message in any of the above contexts.

The CLI returns every event (parameter binding, assign, compound-op, narrowing, read) that shaped the variable from function entry up to the failing line — so you can see where the wrong type came in, instead of guessing.

When NOT to use

Skip the CLI and just read the source if all of these hold:

• The file is short (< 100 lines) AND the method is short (< 30 lines).
• The error message names a single line and the variable is assigned/parameter-bound in plain sight nearby.
• No third-party extension is shaping the type (vanilla PHP, no Eloquent magic, no assert library).
• The fix is obviously a missing ?? default, a missing null guard, or a typo in a property name.

Also skip for non-type errors: Call to undefined method, Class X not found, Access to undefined constant — these don't need a type-inference chain.

Rule of thumb: if you'd confidently write the fix in under 30 seconds from reading the source, skip the trace. If you'd be guessing, run it.