[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.

Author: ruudk

src/Caching/Config/FileHashComputer.php

@@ -5,6 +5,7 @@
 namespace Rector\Caching\Config;
 
 use Rector\Application\VersionResolver;
+use Rector\Caching\Contract\CacheMetaExtensionInterface;
 use Rector\Configuration\Parameter\SimpleParameterProvider;
 use Rector\Exception\ShouldNotHappenException;
 
@@ -13,12 +14,31 @@
  */
 final class FileHashComputer
 {
+    /**
+     * @param CacheMetaExtensionInterface[] $cacheMetaExtensions
+     */
+    public function __construct(
+        private readonly array $cacheMetaExtensions = []
+    ) {
+    }
+
     public function compute(string $filePath): string
     {
         $this->ensureIsPhp($filePath);
 
         $parametersHash = SimpleParameterProvider::hash();
-        return sha1($filePath . $parametersHash . VersionResolver::PACKAGE_VERSION);
+        $extensionHash = $this->computeExtensionHash();
+        return sha1($filePath . $parametersHash . $extensionHash . VersionResolver::PACKAGE_VERSION);
+    }
+
+    private function computeExtensionHash(): string
+    {
+        $extensionHash = '';
+        foreach ($this->cacheMetaExtensions as $cacheMetaExtension) {
+            $extensionHash .= $cacheMetaExtension->getKey() . ':' . $cacheMetaExtension->getHash();
+        }
+
+        return $extensionHash;
     }
 
     private function ensureIsPhp(string $filePath): void

src/Caching/Contract/CacheMetaExtensionInterface.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Caching\Contract;
+
+/**
+ * Allows extensions to provide additional metadata for cache invalidation.
+ * When any extension's hash changes, all cached files are reprocessed.
+ *
+ * @api
+ */
+interface CacheMetaExtensionInterface
+{
+    /**
+     * Returns unique key for this cache meta entry.
+     * This describes the source of the metadata.
+     */
+    public function getKey(): string;
+
+    /**
+     * Returns hash of the cache meta entry.
+     * This represents the current state of the additional meta source.
+     */
+    public function getHash(): string;
+}

src/Config/RectorConfig.php

@@ -6,6 +6,7 @@
 
 use Illuminate\Container\Container;
 use Override;
+use Rector\Caching\Contract\CacheMetaExtensionInterface;
 use Rector\Caching\Contract\ValueObject\Storage\CacheStorageInterface;
 use Rector\Configuration\Option;
 use Rector\Configuration\Parameter\SimpleParameterProvider;
@@ -360,6 +361,17 @@ public function cacheClass(string $cacheClass): void
         SimpleParameterProvider::setParameter(Option::CACHE_CLASS, $cacheClass);
     }
 
+    /**
+     * @param class-string<CacheMetaExtensionInterface> $cacheMetaExtensionClass
+     */
+    public function cacheMetaExtension(string $cacheMetaExtensionClass): void
+    {
+        Assert::isAOf($cacheMetaExtensionClass, CacheMetaExtensionInterface::class);
+
+        $this->singleton($cacheMetaExtensionClass);
+        $this->tag($cacheMetaExtensionClass, CacheMetaExtensionInterface::class);
+    }
+
     /**
      * @see https://github.com/nikic/PHP-Parser/issues/723#issuecomment-712401963
      */

src/Configuration/RectorConfigBuilder.php

@@ -7,6 +7,7 @@
 use PhpParser\NodeVisitor;
 use Rector\Bridge\SetProviderCollector;
 use Rector\Bridge\SetRectorsResolver;
+use Rector\Caching\Contract\CacheMetaExtensionInterface;
 use Rector\Caching\Contract\ValueObject\Storage\CacheStorageInterface;
 use Rector\Composer\InstalledPackageResolver;
 use Rector\Config\Level\CodeQualityLevel;
@@ -91,6 +92,11 @@ final class RectorConfigBuilder
 
     private ?string $containerCacheDirectory = null;
 
+    /**
+     * @var array<class-string<CacheMetaExtensionInterface>>
+     */
+    private array $cacheMetaExtensions = [];
+
     private ?bool $parallel = null;
 
     private int $parallelTimeoutSeconds = 120;
@@ -316,6 +322,10 @@ public function __invoke(RectorConfig $rectorConfig): void
             $rectorConfig->containerCacheDirectory($this->containerCacheDirectory);
         }
 
+        foreach ($this->cacheMetaExtensions as $cacheMetaExtensionClass) {
+            $rectorConfig->cacheMetaExtension($cacheMetaExtensionClass);
+        }
+
         if ($this->importNames || $this->importDocBlockNames) {
             $rectorConfig->importNames($this->importNames, $this->importDocBlockNames);
             $rectorConfig->importShortClasses($this->importShortClasses);
@@ -880,6 +890,16 @@ public function withCache(
         return $this;
     }
 
+    /**
+     * @param class-string<CacheMetaExtensionInterface> $cacheMetaExtensionClass
+     */
+    public function withCacheMetaExtension(string $cacheMetaExtensionClass): self
+    {
+        $this->cacheMetaExtensions[] = $cacheMetaExtensionClass;
+
+        return $this;
+    }
+
     /**
      * @param class-string<ConfigurableRectorInterface> $rectorClass
      * @param mixed[] $configuration

src/DependencyInjection/LazyContainerFactory.php

@@ -36,6 +36,8 @@
 use Rector\BetterPhpDocParser\PhpDocParser\StaticDoctrineAnnotationParser\PlainValueParser;
 use Rector\Caching\Cache;
 use Rector\Caching\CacheFactory;
+use Rector\Caching\Config\FileHashComputer;
+use Rector\Caching\Contract\CacheMetaExtensionInterface;
 use Rector\ChangesReporting\Contract\Output\OutputFormatterInterface;
 use Rector\ChangesReporting\Output\ConsoleOutputFormatter;
 use Rector\ChangesReporting\Output\GitHubOutputFormatter;
@@ -482,6 +484,10 @@ static function (Container $container): DynamicSourceLocatorProvider {
             return $cacheFactory->create();
         });
 
+        $rectorConfig->when(FileHashComputer::class)
+            ->needs('$cacheMetaExtensions')
+            ->giveTagged(CacheMetaExtensionInterface::class);
+
         // tagged services
         $rectorConfig->when(BetterPhpDocParser::class)
             ->needs('$phpDocNodeDecorators')