I don't think this has to be behind bleeding edge. It's not a BC break, it should work the same way as before. It's a good point that some people might be doing something to the structure of the current result cache format to achieve similar things this PR aims to achieve, but that's out of BC surface anyway, and the end result should be that they should have to be able delete their tooling altogether, if we do a good job.

As a bonus, more E2E result cache tests will test the new path.

Done, made it the default and dropped the featureToggle. Since the on-disk format changes I bumped CACHE_VERSION, so the first run after upgrading is a cold one and everything is relative from then on. And yes, every result cache e2e now exercises the relative path, on top of the dedicated fixture and the git worktree test.

(just see CI is failling now)

(just see CI is failling now)

Looking into it. Yesterday GitHub had an outage so couldn't properly follow-up on the CI

Would be nice if you ran it locally and grepped the new result cache whether there are still some absolute paths present or not.

Also the cache should be portable between Windows and Linux so the directory separators should always be /. PHPStan has FileHelper class for normalization.

Did both.

I ran self-analysis and grepped the generated result cache for the absolute project prefix: 0 occurrences. Analysed files, the dependency graph, and the meta (including composerInstalled install_path and the stub files) are all stored relative to the anchor. Paths with no shared prefix with the anchor, e.g. a tmpDir pointed outside the project tree, stay absolute by design, matching ccache's CCACHE_BASEDIR rule; in a normal project tmpDir is under the project and gets relativized too.

On separators, stored paths now always use /. The relative path helper already emits / for anything reachable from the anchor, so this only covered the no-shared-prefix edge, which on Windows would otherwise keep backslashes. On load the paths are absolutized back to the OS-native separator that FileFinder uses for the analysed-file keys, so a cache written on Windows re-absolutizes on Linux and vice versa. Namespace separators in class names are left as-is; only path values are normalised.

just noticed, that this PR has another nice side effect: result-cache size shrinks by ~5% in comparison to 2.2.x on my machine running on phpstan-src

➜  phpstan-src git:(pr/6190) ls -la tmp/resultCache.php                        
-rw-r--r--@ 1 staabm  staff  40814358 Aug  7 13:32 tmp/resultCache.php
➜  phpstan-src git:(2.2.x) ls -la tmp/resultCache.php
-rw-r--r--@ 1 staabm  staff  42653306 Aug  7 13:33 tmp/resultCache.php
``

Nice, that makes sense: every stored path drops the absolute prefix (on your checkout the /Users/staabm/.../phpstan-src/ part), and each path shows up many times in the cache, as the section keys, in the dependency lists, and in the error and linesToIgnore entries, so it adds up quickly.

It also scales with how deep the checkout lives: a CI path like /home/runner/work/<repo>/<repo>/ is longer than a local one, so the relative form saves even more there.

• PR description needs update
• what about failing CI tests?

Description updated.

On CI: the failures were a real one from me. Removing the unit test earlier orphaned a ResultCachePathTransformer method, self-analysis flagged it as unused, and that one error failed every make phpstan-based job (plain, with result cache, generate-baseline, mutation, turbo). Fixed in 9e1943f by dropping the unused method, and those jobs are green again.

The only red left is Other Tests (cd e2e/bug8778), which fails at the turbo-extension artifact download with digest-mismatch: error before the test runs. That is infra, not from this PR (the same artifact digest-mismatch shows up on other PRs too).

Dogfooding this on real projects turned up a blocker: the phar never reuses the result cache. This is not a portability problem, it misses in place, with nothing moved.

Minimal repro, a single clean file at level 5, no vendor and no extensions, second identical run:

# phar from this PR
Result cache not used because the metadata do not match: executedFilesHashes
# phar from 2.2.x
Result cache restored. 0 files will be reanalysed.

Two real projects behave the same way with --fail-without-result-cache on an identical rerun: both write a cache and then miss it, where the 2.2.x phar restores it. The cache file is consistently a bit smaller than the 2.2.x one, so relativization is working, it just is not reversible.

Root cause. getExecutedFileHashes() hashes cliAutoloadFile plus bootstrapFiles, and conf/config.neon ships four bootstrap files that live inside the phar (stubs/runtime/ReflectionUnionType.php, ReflectionAttribute.php, Attribute85.php, ReflectionIntersectionType.php). The stored keys differ like this:

2.2.x:     phar:///abs/path/phpstan.phar/stubs/runtime/Attribute85.php
this PR:   phpstan.phar/stubs/runtime/Attribute85.php

The transformer treats the phar:// URL as an ordinary filesystem path, so the scheme is dropped and what remains is relative to the directory holding the phar. Since the scheme is gone from the stored string, absolutizing on load cannot put it back, so the restored key can never equal the phar://... key the current run computes. executedFilesHashes therefore differs on every run and the cache is thrown away.

Why the tests here do not catch it. Run from bin/phpstan at the same commit, the cache is reused normally (Result cache restored. 0 files will be reanalysed.), because the bootstrap files are then plain filesystem paths. Only the phar is affected, which is also why CI was already pointing at it: the Compile PHAR run for this branch fails e2e/bug8778 with exactly metadata do not match: executedFilesHashes, and those two jobs pass on the other PRs I compared against.

Fix direction. Make the path transformer phar://-aware and leave phar-internal paths absolute. They belong to the tool rather than to the project, so their location has no bearing on cache portability, and rewriting them can only break the round trip.

I will look at the fix. Flagging it now because @staabm asked people on phpstan/phpstan#8599 to try this artifact, and as built it will look like the feature does nothing.

Fixed in 6dddb50. The phar reuses its result cache again, and I have to correct the fix direction I gave earlier.

I said the transformer should leave phar-internal paths absolute, because they belong to the tool and rewriting them "can only break the round trip". The first half is fine, the reasoning is not. Dropping the scheme is what breaks the round trip, not rewriting the path. So the fix splits the scheme off, relativizes only the filesystem path behind it, and restores the scheme verbatim:

before:   phar:///abs/project/vendor/bin/phpstan.phar/stubs/runtime/Attribute85.php
stored:   phar://phpstan.phar/stubs/runtime/Attribute85.php
restored: phar:///abs/project/vendor/bin/phpstan.phar/stubs/runtime/Attribute85.php

Leaving them absolute would have been the smaller change, and it does restore in-place reuse, but I measured it and it forfeits the actual goal: with the phar sitting in the project's vendor, its absolute path moves with the project, so executedFilesHashes still differed after a move and the cache was still discarded. Preserving the scheme gets both. Built a phar from the branch and checked all three cases:

Two other things worth noting.

Error no longer reimplements the rewriting. It had relativizePaths(RelativePathHelper) and absolutizePaths(FileHelper), which duplicated what the transformer does and would have needed the same scheme handling bolted on separately. It now has one transformPaths(callable) that the transformer calls with its own relativizePath()/absolutizePath(), so an error's paths and the cache's file-path keys cannot drift apart again. Both methods are new in this PR, so nothing released changes.

The gap was that nothing exercised a phar:// path outside the compiled-phar job. Added e2e/result-cache-phar-bootstrap, which builds a small phar, registers a bootstrap file inside it and asserts that no scheme-less key is stored and that an identical rerun reuses the cache. It runs against bin/phpstan, and both assertions fail without the fix, so this cannot regress silently in the source build any more.

Gates: full suite green (21300 tests), self-analysis clean, phpcs clean, and the new e2e verified in both directions. e2e/bug8778 in the Compile PHAR job should go green now too, since that was the same executedFilesHashes mismatch.

@staabm the artifact is worth retesting now - as built before this commit it genuinely did nothing for a phar install.

Retested on the two real projects that originally showed the miss, with a phar built from 6dddb503b. Both reuse the cache again, matching base:

Second identical run each time, --fail-without-result-cache, cold cache before run 1. Both projects analyse clean, so exit 1 cannot mask exit 2 here.

That only shows the regression is gone, though. To check the feature itself I installed the phar the way Composer does, at vendor/bin/phpstan.phar inside the project, warmed the cache, then copied the whole project (a real cp -R, not a symlink) to a different absolute path:

So on a real project a phar install now survives the move, which is the thing the PR is for. My earlier evidence for the moved case was a synthetic single-file project, and the phar-installed case was exactly where it was broken, so I did not want to leave that on inference.

One check worth mentioning because the version string is misleading: the phar I built reports 2.2.x-dev@bba3c00, which is not the branch head, so I verified the contents instead of the label — read src/Analyser/ResultCache/ResultCachePathTransformer.php out of the phar and confirmed splitScheme() is present (and Error::transformPaths()), both absent from the pre-fix phar.

I just tried this on a real-world project. Some paths are still absolute in the file. It's inside the collectedDataCallback for ConstantConditionInTraitCollector. This is a collector that carries Error|array<mixed> so it's not ideal and I understand it was left there. Maybe we could introduce a new interface extending Collector interface that would add a new method that would be able to transform paths for its collected data? I expect this problem to be quite rare but it should still be addressed.

Here's how it looks in the result cache:

      4 => 
      array (
        0 => 'PHPStan\\Rules\\Comparison\\StrictComparisonOfDifferentTypesRule',
        1 => 'Slevomat\\Enum\\Enum',
        2 => '$this === $that:52',
        3 => true,
        4 => 
        array (
          'message' => 'Strict comparison using === between $this(Slevomat\\Amazon\\AmazonApiVersion) and Slevomat\\Amazon\\AmazonApiVersion will always evaluate to true.',
          'file' => '/Users/ondrej/Development/slevomat/app/model/Enum/Enum.php (in context of class Slevomat\\Amazon\\AmazonApiVersion)',
          'line' => 52,
          'canBeIgnored' => true,
          'filePath' => '/Users/ondrej/Development/slevomat/app/model/Amazon/AmazonApiVersion.php',
          'traitFilePath' => '/Users/ondrej/Development/slevomat/app/model/Enum/Enum.php',
          'tip' => '• Because the type is coming from a PHPDoc, you can turn off this check by setting <fg=cyan>treatPhpDocTypesAsCertain: false</> in your <fg=cyan>%configurationFile%</>.
• Use match expression instead. PHPStan will report unhandled enum cases.',
          'nodeLine' => 52,
          'nodeType' => 'PhpParser\\Node\\Expr\\BinaryOp\\Identical',
          'identifier' => 'identical.alwaysTrue',
          'metadata' => 
          array (
          ),
          'fixedErrorDiffHash' => NULL,
          'fixedErrorDiffDiff' => NULL,
        ),
      ),

The same problem is visible even when analysing phpstan-src here. It's easy to grep for absolute path of the project's checkout.

Fixed in d229daf, along with a second bug the same code path was hiding.

Collected data

Implemented your suggestion: a CollectorWithPaths interface extending Collector, which the cache calls when saving and loading. Two things I decided while writing it, both easy to change if you disagree:

• The method is static. The cache only ever holds the collector's class name (CollectedData::getCollectorType()), never an instance, and ResultCachePathTransformer is constructed with new rather than through the container — so an instance method would have meant injecting Collectors\Registry and giving it a class-to-instance lookup it does not currently have. is_a($collectorType, CollectorWithPaths::class, true) needs neither, and third-party collectors get the hook for free.
• Two collectors needed it, not one. FunctionCallConstantConditionCollector carries the same Error|array<mixed> payload as ConstantConditionInTraitCollector, and its data was leaking absolute paths too — that one shows up on phpstan-src as RangeFunctionReturnTypeExtension.php under booleanNot.alwaysFalse. The shared Error/array handling sits in one small helper; each collector keeps its own precisely typed method.

On the Error|array<mixed> union you mentioned: the array form is what an Error becomes after crossing a parallel worker boundary, so the helper handles both — Error::decode() then transformPaths() then jsonSerialize(), reusing the existing round trip rather than hand-picking keys.

Analysing phpstan-src now leaves 0 occurrences of the checkout path in resultCache.php, down from 284.

The second bug: mangled class names in the compound file field

Grepping for the checkout path, as you suggested, also turned up something worse in code I had already written. Error::getFile() returns the compound path (in context of class X) string, and I was relativizing it as if the whole thing were a path — so the forward-slash normalisation that makes the cache portable between Windows and Linux was rewriting the backslashes in the class name too:

'file' => 'src/Type/JustNullableTypeTrait.php (in context of class PHPStan/Type/BooleanType)'

That is on every error reported in a trait, not just collected data, and it survives the round trip — so a warm run served a mangled class name in that field. The transformer already had compound-aware helpers (relativizeCompoundKey/absolutizeCompoundKey, used for linesToIgnore keys); Error's paths now go through them, and the class name stays PHPStan\Type\BooleanType.

Test

e2e/result-cache-relative-path now has a trait with a constant condition, so the in-trait collector actually fires there, and the assertion changed from "the analysed file is not stored under its absolute path" to "the checkout prefix appears nowhere in the cache file", printing the offenders when it does. Verified it fails without the fix (6 absolute paths) and passes with it.

Gates: full suite green (21300), self-analysis clean, phpcs clean, and the warm run still restores with 0 files reanalysed.

One thing I did not do: nothing checks that a new collector carrying paths remembers to implement the interface. A rule could require it when a collector's value type mentions Error, but that seemed like scope creep here — say the word if you want it.

Thank you!