rectorphp/rector · error · ShouldNotHappenException

Provide only PHP file, ready for Dependency Injection. "%s"

Error message

Provide only PHP file, ready for Dependency Injection. "%s" given

What it means

FileHashComputer::compute() builds the cache key for the resolved Rector config file and asserts that file has a .php extension, since modern Rector configuration must be plain PHP. When ChangedFilesDetector::setFirstResolvedConfigFileInfo() passes a config path whose extension is not php, ensureIsPhp() throws ShouldNotHappenException. It is Rector telling you the file you pointed it at cannot be a Rector config.

Source

Thrown at src/Caching/Config/FileHashComputer.php:26

use Rector\Exception\ShouldNotHappenException;
/**
 * Inspired by https://github.com/symplify/easy-coding-standard/blob/e598ab54686e416788f28fcfe007fd08e0f371d9/packages/changed-files-detector/src/FileHashComputer.php
 */
final class FileHashComputer
{
    public function compute(string $filePath): string
    {
        $this->ensureIsPhp($filePath);
        $parametersHash = SimpleParameterProvider::hash();
        return sha1($filePath . $parametersHash . VersionResolver::PACKAGE_VERSION);
    }
    private function ensureIsPhp(string $filePath): void
    {
        $fileExtension = pathinfo($filePath, \PATHINFO_EXTENSION);
        if ($fileExtension === 'php') {
            return;
        }
        throw new ShouldNotHappenException(sprintf(
            // getRealPath() cannot be used, as it breaks in phar
            'Provide only PHP file, ready for Dependency Injection. "%s" given',
            $filePath
        ));
    }
}

View on GitHub (pinned to 408fcb0ff1)

Solutions

Convert the config to a PHP file named rector.php (or keep the .php extension, e.g. rector.dist.php)
Pass a .php config explicitly: vendor/bin/rector process src --config rector.php
Remove leftover YAML configs and update CI scripts/docs that reference them

Example fix

# before: legacy yaml config
vendor/bin/rector process src --config rector.yml

# after: php config
vendor/bin/rector process src --config rector.php

Defensive patterns

Strategy: validation

Validate before calling

// before running rector with an explicit config
$configFile = getenv('RECTOR_CONFIG') ?: 'rector.php';
if (pathinfo($configFile, PATHINFO_EXTENSION) !== 'php' || ! is_file($configFile)) {
    fwrite(STDERR, "Config must be an existing PHP file: {$configFile}\n");
    exit(1);
}

Type guard

function isPhpConfigFile(string $path): bool
{
    return pathinfo($path, PATHINFO_EXTENSION) === 'php' && is_file($path);
}

Prevention

Keep the config named rector.php; if you need variants use .php suffixes (rector.ci.php)
Purge references to rector.yml from CI scripts and documentation during upgrades
When passing --config, lint the value in wrapper scripts before invoking rector

When it happens

Trigger: Running rector --config rector.yaml / rector.yml (legacy YAML config from Rector <=0.8), --config rector.dist, or a config file with any non-php extension; also a custom filename like rector-config.txt passed via --config.

Common situations: Projects migrating from old Rector versions that used YAML config; CI scripts still passing the ancient --config=rector.yml flag; config files renamed with a .dist or environment suffix.

Related errors

AI-assisted analysis of rectorphp/rector@408fcb0ff1 (2026-08-21). Data as JSON: /api/errors/d58df7e6223a9f69. Report an issue: GitHub.