[Caching] Add CacheMetaExtensionInterface for custom cache invalidation (#7933)

* [Caching] Add CacheMetaExtensionInterface for custom cache invalidation

Same mechanism as PHPStan's ResultCacheMetaExtension — extensions implement getKey() and getHash() to provide additional metadata that is folded into the file cache key. When any extension's hash changes, all cached files are reprocessed.

* Add e2e test for CacheMetaExtensionInterface cache invalidation

Proves the extension actually invalidates cache by using a conditional
rule that only triggers when an external file changes value.

Author: ruudk

.github/workflows/e2e_with_cache.yaml

@@ -52,3 +52,25 @@ jobs:
             # this tests that a 2nd run with cache and "--dry-run" gives same results, see https://github.com/rectorphp/rector-src/pull/3614#issuecomment-1507742338
             -   run: php ../e2eTestRunnerWithCache.php
                 working-directory: ${{ matrix.directory }}
+
+    cache_meta_extension:
+        runs-on: ubuntu-latest
+        timeout-minutes: 3
+
+        name: End to end test - e2e/cache-meta-extension
+
+        steps:
+            -   uses: actions/checkout@v4
+
+            -   uses: shivammathur/setup-php@v2
+                with:
+                    php-version: '8.3'
+                    coverage: none
+
+            -   run: composer install --ansi
+
+            -   run: composer install --ansi
+                working-directory: e2e/cache-meta-extension
+
+            -   run: php e2eTestRunnerCacheInvalidation.php
+                working-directory: e2e/cache-meta-extension

e2e/cache-meta-extension/.gitignore

@@ -0,0 +1 @@
+/vendor

e2e/cache-meta-extension/composer.json

@@ -0,0 +1,12 @@
+{
+    "require": {
+        "php": "^8.1"
+    },
+    "autoload": {
+        "psr-4": {
+            "App\\": "src/"
+        }
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true
+}

e2e/cache-meta-extension/e2eTestRunnerCacheInvalidation.php

@@ -0,0 +1,66 @@
+#!/usr/bin/env php
+<?php
+
+// Tests that CacheMetaExtensionInterface invalidates cache when the hash changes.
+//
+// Step 1: Run Rector with enabled.txt=false and --clear-cache → no changes, cache populated
+// Step 2: Change enabled.txt to true → cache invalidated → rule triggers → changes reported
+
+use Rector\Console\Formatter\ColorConsoleDiffFormatter;
+use Rector\Console\Style\SymfonyStyleFactory;
+use Rector\Differ\DefaultDiffer;
+use Rector\Util\Reflection\PrivatesAccessor;
+use Symfony\Component\Console\Command\Command;
+
+$projectRoot = __DIR__ .'/..';
+$rectorBin = $projectRoot . '/../bin/rector';
+$autoloadFile = $projectRoot . '/../vendor/autoload.php';
+
+require_once __DIR__ . '/../../vendor/autoload.php';
+
+$symfonyStyleFactory = new SymfonyStyleFactory(new PrivatesAccessor());
+$symfonyStyle = $symfonyStyleFactory->create();
+
+$e2eCommand = 'php '. $rectorBin .' process --dry-run --no-ansi -a '. $autoloadFile;
+
+// Step 1: enabled=false, clear cache → no changes
+file_put_contents(__DIR__ . '/enabled.txt', "false\n");
+
+$output = [];
+exec($e2eCommand . ' --clear-cache', $output, $exitCode);
+$outputString = trim(implode("\n", $output));
+
+if (! str_contains($outputString, '[OK] Rector is done!')) {
+    $symfonyStyle->error('Step 1 failed: Expected no changes with enabled=false');
+    $symfonyStyle->writeln($outputString);
+    exit(Command::FAILURE);
+}
+
+$symfonyStyle->success('Step 1 passed: No changes with enabled=false');
+
+// Step 2: enabled=true, no --clear-cache → cache meta invalidated → rule triggers
+file_put_contents(__DIR__ . '/enabled.txt', "true\n");
+
+$output = [];
+exec($e2eCommand, $output, $exitCode);
+$outputString = trim(implode("\n", $output));
+$outputString = str_replace(__DIR__, '.', $outputString);
+
+$expectedOutput = trim((string) file_get_contents(__DIR__ . '/expected-output.diff'));
+
+// Restore enabled.txt
+file_put_contents(__DIR__ . '/enabled.txt', "false\n");
+
+if ($outputString === $expectedOutput) {
+    $symfonyStyle->success('Step 2 passed: Cache invalidated, rule triggered');
+    exit(Command::SUCCESS);
+}
+
+$symfonyStyle->error('Step 2 failed: Expected cache invalidation to trigger the rule');
+
+$defaultDiffer = new DefaultDiffer();
+$colorConsoleDiffFormatter = new ColorConsoleDiffFormatter();
+$diff = $colorConsoleDiffFormatter->format($defaultDiffer->diff($outputString, $expectedOutput));
+$symfonyStyle->writeln($diff);
+
+exit(Command::FAILURE);

e2e/cache-meta-extension/enabled.txt

@@ -0,0 +1 @@
+false

e2e/cache-meta-extension/expected-output.diff

@@ -0,0 +1,21 @@
+1 file with changes
+===================
+
+1) src/DeadConstructor.php:2
+
+    ---------- begin diff ----------
+@@ @@
+
+ final class DeadConstructor
+ {
+-    public function __construct()
+-    {
+-    }
+ }
+    ----------- end diff -----------
+
+Applied rules:
+ * ConditionalEmptyConstructorRector
+
+
+ [OK] 1 file would have been changed (dry-run) by Rector

e2e/cache-meta-extension/rector.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+use App\ConditionalEmptyConstructorRector;
+use App\EnabledFlagCacheMetaExtension;
+use Rector\Caching\ValueObject\Storage\FileCacheStorage;
+use Rector\Config\RectorConfig;
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->cacheClass(FileCacheStorage::class);
+
+    $rectorConfig->paths([
+        __DIR__ . '/src/DeadConstructor.php',
+    ]);
+
+    $rectorConfig->rule(ConditionalEmptyConstructorRector::class);
+    $rectorConfig->cacheMetaExtension(EnabledFlagCacheMetaExtension::class);
+};

e2e/cache-meta-extension/src/ConditionalEmptyConstructorRector.php

@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use PhpParser\Node;
+use PhpParser\Node\Stmt\Class_;
+use PhpParser\Node\Stmt\ClassMethod;
+use Rector\Rector\AbstractRector;
+use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+/**
+ * Removes empty constructors only when enabled.txt contains "true".
+ * Used to test CacheMetaExtensionInterface e2e.
+ */
+final class ConditionalEmptyConstructorRector extends AbstractRector
+{
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition('Remove empty constructors conditionally', [
+            new CodeSample(
+                <<<'CODE_SAMPLE'
+class SomeClass
+{
+    public function __construct()
+    {
+    }
+}
+CODE_SAMPLE
+                ,
+                <<<'CODE_SAMPLE'
+class SomeClass
+{
+}
+CODE_SAMPLE
+            ),
+        ]);
+    }
+
+    /**
+     * @return array<class-string<Node>>
+     */
+    public function getNodeTypes(): array
+    {
+        return [Class_::class];
+    }
+
+    /**
+     * @param Class_ $node
+     */
+    public function refactor(Node $node): ?Class_
+    {
+        $enabled = trim((string) file_get_contents(__DIR__ . '/../enabled.txt'));
+
+        if ($enabled !== 'true') {
+            return null;
+        }
+
+        $hasChanged = false;
+
+        foreach ($node->stmts as $key => $stmt) {
+            if (! $stmt instanceof ClassMethod) {
+                continue;
+            }
+
+            if (! $this->isName($stmt, '__construct')) {
+                continue;
+            }
+
+            if ($stmt->stmts !== null && $stmt->stmts !== []) {
+                continue;
+            }
+
+            unset($node->stmts[$key]);
+            $hasChanged = true;
+        }
+
+        if ($hasChanged) {
+            return $node;
+        }
+
+        return null;
+    }
+}

e2e/cache-meta-extension/src/DeadConstructor.php

@@ -0,0 +1,8 @@
+<?php
+
+final class DeadConstructor
+{
+    public function __construct()
+    {
+    }
+}

e2e/cache-meta-extension/src/EnabledFlagCacheMetaExtension.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use Rector\Caching\Contract\CacheMetaExtensionInterface;
+
+final class EnabledFlagCacheMetaExtension implements CacheMetaExtensionInterface
+{
+    public function getKey(): string
+    {
+        return 'enabled-flag';
+    }
+
+    public function getHash(): string
+    {
+        return (string) file_get_contents(__DIR__ . '/../enabled.txt');
+    }
+}