Feature Request

Document the following caching subjects:

• How to override the cache class.
• That Rector detects it's running in CI and changes the default disk cache to memory cache.
• Whether caching during CI is actually advisable.

When running in a GitHub Actions CI workflow on PR push, Rector doesn't write in the designated cache directory. Locally it does.

GitHub Actions workflow YAML:

      - name: Rector Cache
        uses: actions/cache@v3
        with:
          path: ./var/cache/rector
          key: ${{ runner.os }}-rector-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-rector-

      - name: Rector Dry Run
        run: php vendor/bin/rector process --dry-run --config=rector.php

In rector.php:

return static function (RectorConfig $rectorConfig): void {
    // ...

    // We need a cache that works locally as well as on GitHub Actions runners.
    $rectorConfig->cacheDirectory('./var/cache/rector');

    // ...
};

When running Rector:

vendor/bin/rector --dry-run --config=rector.php

Locally, a directory is generated in the app's directory under ./var/cache/rector/ (0a, 0b, 0c, ...), but on the action runner it isn't. The "Post Rector Cache" action complains:

Warning: Path Validation Error: Path(s) specified in the action for caching do(es) not exist, hence no cache is being saved.

Obviously, because the cache directory isn't generated.

Cause

The culprit is detecting that we're running CI and overriding the default disk cache to memory cache:

Fix

The fix is to explicitly and unconditionally restore the filesystem cache:

// We need a cache that works locally as well as on GitHub Actions runners.
$rectorConfig->cacheDirectory('./var/cache/rector');
$rectorConfig->cacheClass(FileCacheStorage::class);

It would have saved me some time if this were documented somewhere. Is it, and if not, can it?