Track file dependencies for global constant fetches by SanderMuller · Pull Request #6023 · phpstan/phpstan-src

SanderMuller · 2026-07-08T12:16:39Z

DependencyResolver recorded file dependencies for class constants, functions, methods and properties, but not for global/namespaced constant fetches (Node\Expr\ConstFetch). On top of that, global constant declarations were not exported nodes. The result cache re-analyses a changed file's dependents only when the changed file's exported nodes change, so a file that reads a global constant was never re-analysed when that constant changed, leaving a stale result.

This fixes both halves:

Record a dependency on the file declaring a fetched global constant (ConstFetch in DependencyResolver), guarding the ubiquitous true/false/null literals so the common path stays a couple of string comparisons.
Export global constant declarations (name + value) as RootExportedNodes, like class constants already are, so renaming or changing a constant re-analyses the files that use it.

Two ways to hit the stale result, both fixed and covered by the result-cache-constants e2e test:

editing a global constant's declaration; the files reading it are re-analysed on the next run;
bumping a Composer package that declares the constant; with package-granular cache invalidation the reading file is now among the re-seeded files.

Performance

The ConstFetch branch runs for every constant fetch, so it is guarded. Measured over a cold, single-process analysis:

corpus	level	`ConstFetch` nodes	skipped (`true`/`false`/`null`)	`getConstant()` calls	added time
phpstan-src	8	10,151	9,928	223	4.9 ms
a doctrine/symfony app	5	12,279	11,348	930	16.5 ms
laravel/laravel	5	8,151	7,676	474	9.6 ms

Added time is under 0.02% of analysis CPU, and that figure is an upper bound (it includes the measurement probes). The exported-node part runs only for global const declarations, which are rare.

Reproducing the staleness

// a.php
<?php declare(strict_types = 1);
namespace App;
const MODE = 1;

// b.php
<?php declare(strict_types = 1);
namespace App;
function f(): int { return MODE; }

vendor/bin/phpstan analyse a.php b.php   # no errors; cache warm
# change a.php to: const MODE = 'x';
vendor/bin/phpstan analyse a.php b.php   # before: stale, still no error

Before this change the second run keeps b.php cached and reports nothing; a cold run reports that f() returns string. With the change the second run re-analyses b.php and matches the cold run.

DependencyResolver recorded dependencies for class constants, functions, methods and properties, but not for global/namespaced constant fetches (Node\Expr\ConstFetch). A file that used only a global constant declared elsewhere therefore recorded no dependency on it, so changing the constant did not re-analyse the consumer from the result cache, leaving a stale result (also surfaced by package-granular cache invalidation when the declaring package is bumped). Resolve the constant and record its declaring file, guarding the ubiquitous true/false/null literals so the common path stays cheap. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The dependency edge added in the previous commit records that a file reads a global constant, but the result cache only re-analyses a changed file's dependents when that file's exported nodes change, and global constant declarations were not exported nodes. So editing a global constant still left the reading files with stale cached results. Export global constant declarations (name + value) like class constants already are, so renaming or changing a constant re-analyses the files that use it. Covered by a result-cache e2e test. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

phpstan-bot · 2026-07-08T13:42:18Z

This pull request has been marked as ready for review.

The e2e test in the previous commit exercises the full result-cache flow, so the AnalyserTest case that asserted the raw dependency edge is redundant. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

staabm · 2026-07-10T18:08:02Z

+ namespace ResultCacheE2EConstants;
+
+-const SOME_MODE = 1;
+const RENAMED_MODE = 1;


Do we have the same problem when a const is declared using define()?

Good question, and yes, define() has the same problem. This PR doesn't fix it. Repro:

// define.php define('SOME_DEFINED_MODE', 1);

// consumer.php namespace App; function usesDefinedMode(): int { return SOME_DEFINED_MODE; }

Analyse (cache warm), change the define() value to 'str', analyse again: no error (stale). A cold run correctly reports usesDefinedMode() should return int but returns string.

The reason is that a define() is a function call, not a declaration, so it produces no exported node. The result cache re-analyses a changed file's dependents only when the file's exported nodes change, so the value change isn't detected even though the reading file depends on the define()'s file.

Handling it means exporting define() calls that have literal arguments (name + value), reusing the ExportedConstantNode from this PR. WordPress-style code leans on define(), so it's probably worth doing. Happy to add it here, or as a follow-up once this lands. Which do you prefer?

Lets do it in a separate PR

Opened it as #6036 (stacked on this one, so I'll rebase to a clean diff once this lands).

staabm · 2026-07-11T05:25:23Z

+				$lowercasedConstantName !== 'true'
+				&& $lowercasedConstantName !== 'false'
+				&& $lowercasedConstantName !== 'null'


usually we use in_array for such case

Done, switched to in_array($constantName->toLowerString(), ['true', 'false', 'null'], true).

staabm · 2026-07-11T05:27:26Z

+
+	public function getMode(): int
+	{
+		return SOME_MODE;


I think we should have another test which shows, that changing a constants value (not the name), will trigger new errors - e.g.

/** * @return int<1, 3> */ public function getMode(): int { return SOME_MODE; }

when SOME_MODE define is changed to 5, it should start erroring

Added. The e2e now also changes SOME_MODE from 1 to 5 with a @return int<1, 3> consumer, and asserts it starts erroring on the warm run (should return int<1, 3> but returns 5), alongside the existing rename test.

Address review: replace the true/false/null comparison chain with in_array, and extend the result-cache e2e to also cover a constant value change (not just a rename) via an int<1, 3> return type that starts erroring when the constant becomes 5. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

staabm · 2026-07-11T12:21:59Z

Thank you

SanderMuller mentioned this pull request Jul 8, 2026

test: Update the PHPStan baseline infection/infection#3348

Open

staabm reviewed Jul 8, 2026

View reviewed changes

Comment thread src/Dependency/DependencyResolver.php

SanderMuller marked this pull request as draft July 8, 2026 13:06

SanderMuller marked this pull request as ready for review July 8, 2026 13:41

staabm reviewed Jul 9, 2026

View reviewed changes

Comment thread tests/PHPStan/Analyser/AnalyserTest.php Outdated

Drop the unit-level dependency test, covered by the e2e test

e26bb43

The e2e test in the previous commit exercises the full result-cache flow, so the AnalyserTest case that asserted the raw dependency edge is redundant. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

SanderMuller requested a review from staabm July 9, 2026 08:02

staabm reviewed Jul 10, 2026

View reviewed changes

staabm requested review from VincentLanglet and ondrejmirtes July 11, 2026 04:45

staabm approved these changes Jul 11, 2026

View reviewed changes

staabm reviewed Jul 11, 2026

View reviewed changes

VincentLanglet approved these changes Jul 11, 2026

View reviewed changes

SanderMuller mentioned this pull request Jul 11, 2026

Track define()'d constants as exported nodes #6036

Merged

staabm merged commit a6b87aa into phpstan:2.2.x Jul 11, 2026
676 checks passed

Navigation Menu

Uh oh!

Track file dependencies for global constant fetches - #6023

Track file dependencies for global constant fetches#6023
staabm merged 4 commits into
phpstan:2.2.xfrom
SanderMuller:const-dependency-tracking

SanderMuller commented Jul 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

phpstan-bot commented Jul 8, 2026

Uh oh!

Uh oh!

staabm Jul 10, 2026

Uh oh!

SanderMuller Jul 10, 2026

Uh oh!

staabm Jul 11, 2026

Uh oh!

SanderMuller Jul 11, 2026

Uh oh!

staabm Jul 11, 2026

Uh oh!

SanderMuller Jul 11, 2026

Uh oh!

staabm Jul 11, 2026

Uh oh!

SanderMuller Jul 11, 2026

Uh oh!

Uh oh!

staabm commented Jul 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

SanderMuller commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance

Reproducing the staleness

Uh oh!

Uh oh!

phpstan-bot commented Jul 8, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

staabm commented Jul 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

SanderMuller commented Jul 8, 2026 •

edited

Loading