Skip to content

Track every class, function and constant lookup instead of re-analysing the files with errors - #7032

Merged
ondrejmirtes merged 8 commits into
2.3.xfrom
missing-class-value-dependencies
Nov 13, 2026
Merged

ondrejmirtes merged 8 commits into
2.3.xfrom
missing-class-value-dependencies

Conversation

@ondrejmirtes

@ondrejmirtes ondrejmirtes commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

Closes phpstan/phpstan#15211
Closes phpstan/phpstan#15453

The result cache no longer re-analyses all files with errors when a symbol appears or goes away. Each class, function and constant the reflection layer is asked for is recorded as a value dependency of whatever asked, whether it was found or missing. When a symbol appears or disappears, exactly the files that looked it up are re-analysed, including files that had no error but whose result depended on the symbol's absence: class_exists()/function_exists()/defined() narrowing, class names in strings, new \ReflectionFunction('...'), PHPDoc types like scalar that become a class, custom rules calling hasClass(), and rules on CollectedDataNode.

Commits

  1. Keep fully qualified names apart from names with a leading backslash in the name resolution memo. An existing order-dependent bug: '\strval' as a callable string and \strval() shared a memo key.
  2. Give a built-in class the same value whichever stub it was read from.
  3. Track every class, function and constant lookup instead of re-analysing the files with errors. The main change:
    • Adds FunctionResultCacheValueExtension and ConstantResultCacheValueExtension next to ClassResultCacheValueExtension, each found or missing.
    • An unqualified function or constant in a namespace records both the namespaced and the global lookup, so declaring App\strlen() re-analyses the files calling strlen() in App (#15453).
    • Symbols found by name make the file depend on the file declaring them, which covers removals.
    • Lookups are split like the existing analysis and declarations value dependents, the same split AnalysedFileDependencyCollector and AnalysedDeclarationDependencyCollector make for unmatched ignoreErrors entries. Lookups made while resolving a declaration the process remembers (ancestors, PHPDoc types, class constant initializers) are kept per declared class, function or file.
    • MemoizingReflectionProvider records a remembered answer again once per file, declaration and collected-data rule. The turbo extension answers from the memo only when the answer was recorded in the current context.
    • The sweep and the filesWithCollectedDataRuleErrors cache section, which existed only for it, are removed. The cache version is bumped.
  4. Remember which functions and constants a scanned file declares.
  5. Do not ask the reflection cache for functions the PhpStorm stubs do not have.
  6. Look a symbol up once in all directory locators. Commits 4 to 6 make the lookups of missing names, which the result cache repeats on restore, cheap.
  7. Track the files of the project's Composer autoload entries like scanned files. PSR-4, PSR-0, classmap and files entries outside vendor/, so a class appearing there is noticed.
  8. Look up again only the missing symbols a changed file may declare. No-op warm runs no longer look up every missing name.

Tests

  • e2e/result-cache-missing-classes and e2e/result-cache-symbol-lookups have 42 tests. Each one asserts the exact filesToAnalyseCount from result-cache-info --json and compares the warm run with a cold run.
  • Switching off each new hook in turn breaks at least one of them. On the code before this PR, 7 of the symbol-lookup tests are stale.
  • Several tests disprove suspected gaps: function names and constant namespaces in another case, inline-ignored errors, a function added to an untracked scanned file, a removed trait, a class moved to another file, define(), conditional declarations, a Composer package adding a class, parameter defaults and global type aliases.
  • Existing tests that asserted the re-analysis of unrelated files with errors now expect fewer files (result-cache-scanned-2, result-cache-scanned-exported-nodes), and the verbose messages no longer mention "the files with errors".

Measured on 9 replayed Laravel commits (about 1,700 files, level 6): warm runs re-analysed 1 to 19 files, or 322 for a commit adding a trait to Model, where the sweep re-analysed about 930. Each warm run matched its cold run. Restoring took about 1.8 s.

Known limitation, unchanged: a class_alias() in a file that a bootstrap file requires is not tracked. Only the files listed in bootstrapFiles are hashed.

Also checked: the whole unit suite with and without the turbo extension, smoke, method and signature parity, and byte-identical output with and without turbo on Laravel.

@ondrejmirtes
ondrejmirtes force-pushed the missing-class-value-dependencies branch 3 times, most recently from fcda131 to 852dbe5 Compare November 13, 2026 10:11
…in the name resolution memo

new FullyQualified('strval') and new Name('\strval') - the name of a callable
string - shared one key and resolve differently, so the answer for '\strval'
depended on which was asked first, and with it whether array_map('\strval', ...)
was reported, depending on the order the files were analysed in.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c5c8-8d5b-7459-a22c-beb8e7ba8a3b
ClassResultCacheValueExtension hashed the file of each class and ancestor.
For a built-in class that is the stub it was reflected from, which depends on
the source locator that reflected it first, so a value recorded in one run
could differ from the one the next run computed. A built-in class changes
only with PHP, its extensions or PHPStan, which invalidate the result cache
anyway.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c5c8-8d5b-7459-a22c-beb8e7ba8a3b
…ng the files with errors

Each class, function and constant the reflection layer is asked for is
recorded, found or not. When a symbol appears or goes away, exactly the
files whose result depends on it are re-analysed - also the ones without
an error, which the re-analysis of the files with errors never reached:
narrowing by class_exists(), a class name compared as a string, a rule
asking the reflection provider, an inline-ignored error.

- Not found: a value dependency on ClassResultCacheValueExtension,
  FunctionResultCacheValueExtension (keyed by the lowercased name) or
  ConstantResultCacheValueExtension (lowercased namespace, case-sensitive
  name), whose value is "missing" until the symbol is declared.
- Found: a dependency on the file declaring it, like on the files
  declaring the symbols the analysed code references.

An unqualified function or constant in a namespace looks up the namespaced
name before the global one, and both lookups are recorded, so declaring
App\strlen() re-analyses the files calling strlen() in App
(phpstan/phpstan#15453).

Lookups are split like the value dependents already are, and like
AnalysedFileDependencyCollector and AnalysedDeclarationDependencyCollector
split the dependencies of unmatched ignoreErrors entries. One made during
the analysis of a file is what is reported in that file depends on. One
made while resolving a declaration the process remembers - the ancestors
of a class, a PHPDoc type, the initializer of a class constant - is what
the declaration depends on: it is kept by the declared class, function or
file, and a file follows the declarations of the symbols it depends on and
every declaration of its own.

MemoizingReflectionProvider remembers its answers for the whole process,
so a remembered answer is recorded again once per file, declaration and
rule on collected data; the turbo extension answers from the memo only
when it was recorded in the current context. InitializerExprTypeResolver
gets ValueDependencyCollector injected for that. Rules on CollectedDataNode
keep the values of what they looked up with their reused result, computed
only when the result is kept.

With that, nothing re-analyses all the files with errors any more: not a
new or changed file declaring symbols, a deleted file, a changed scanned
file, a changed Composer package or extension version. The
filesWithCollectedDataRuleErrors section existed only for that, it is gone.

E2E tests in result-cache-missing-classes and result-cache-symbol-lookups
assert the re-analysed files with result-cache-info and compare the warm
result with a cold run, for symbols appearing, going away, shadowing
global functions and constants, in scanned files and for rules on
collected data. Tests that asserted the re-analysis of unrelated files
with errors now expect fewer files.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c5c8-8d5b-7459-a22c-beb8e7ba8a3b
The symbol scan lists more files than declare a function or a constant: a
method looks like a function to it, and define() may be called anywhere. A
function or constant that does not exist parsed those files on each lookup,
which the result cache now does on every run to check that it is still
missing. On wordpress-develop that was 1.8 seconds of each warm run.
…ot have

Like classes already: almost every function name reaching this locator is a userland one no
earlier locator found - also every namespaced name an unqualified call is looked up by first -
and the result cache asks for each missing function again on every run. Asking the cache means
hashing the key and stat()ing a file that can never exist.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c5c8-8d5b-7459-a22c-beb8e7ba8a3b
A project with many Composer packages has a directory locator for each classmap directory, and
a name none of them declares - which the result cache asks about for every missing class and
function on every run - was looked up in each of them. They are asked through one map of all
their symbols now, in the same order.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c5c8-8d5b-7459-a22c-beb8e7ba8a3b
…ed files

A class or function can appear in a file of the project's own autoload
entries - PSR-4, PSR-0, classmap and files, of autoload and autoload-dev,
and of packages from path repositories - without any analysed or scanned
file changing, and nothing noticed it. Those files are now scanned files:
a new one or a changed one is noticed and read for what it declares, and
its exported nodes decide which dependents are re-analysed. A changed file
of a package from a path repository is tracked file by file instead of
throwing the whole result cache away; the scanned-vendor e2e test records
its package as downloaded to keep covering a package from Packagist.

An entry containing the vendor directory, like a namespace mapped to the
project root, is walked without it and gives only PHP files, the project's
entries pointing into the vendor directory are left to their package, and
nothing under tmpDir counts as a scanned file - the result cache and the
container would otherwise change on every run.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c5c8-8d5b-7459-a22c-beb8e7ba8a3b
A class, function or constant a lookup did not find when the result cache
was written is looked up again only when a new or changed analysed or
scanned file declares that name, or when a Composer package or PHP
extension version changed. Before, every missing name was looked up on
every restore, which slowed down warm runs that changed nothing.

The restore works out what may have been declared, and the ResultCache
carries it to the finalizer, which checks the values a rule on collected
data depends on before reusing its errors.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1c5c8-8d5b-7459-a22c-beb8e7ba8a3b
@ondrejmirtes
ondrejmirtes force-pushed the missing-class-value-dependencies branch from 852dbe5 to a6e7dc4 Compare November 13, 2026 10:35
@ondrejmirtes
ondrejmirtes merged commit 2418876 into 2.3.x Nov 13, 2026
375 of 376 checks passed
@ondrejmirtes
ondrejmirtes deleted the missing-class-value-dependencies branch November 13, 2026 10:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Result cache keeps a stale result when a namespaced function shadows the global function a file falls back to Scanned cache vs large baseline

1 participant