rectorphp/rector · error · ShouldNotHappenException

"%s" is deprecated, as data provider docblock typing is not

Error message

"%s" is deprecated, as data provider docblock typing is not relevant to code quality

What it means

Rector\TypeDeclarationDocblocks\Rector\Class_\AddReturnArrayDocblockFromDataProviderParamRector is deprecated: refactor() throws Rector\Exception\ShouldNotHappenException on the first Class_ node. The rule generated @return array<...> docblocks for PHPUnit data-provider methods based on the test method parameters, but data-provider typing has no bearing on production code quality, so the automation was dropped.

Source

Thrown at rules/TypeDeclarationDocblocks/Rector/Class_/AddReturnArrayDocblockFromDataProviderParamRector.php:70

     */
    public function provideNames(): array
    {
        return ['John', 'Jane'];
    }
}
CODE_SAMPLE
)]);
    }
    public function getNodeTypes(): array
    {
        return [Class_::class];
    }
    /**
     * @param Class_ $node
     */
    public function refactor(Node $node): ?Node
    {
        throw new ShouldNotHappenException(sprintf('"%s" is deprecated, as data provider docblock typing is not relevant to code quality', self::class));
    }
}

View on GitHub (pinned to 408fcb0ff1)

Solutions

Remove AddReturnArrayDocblockFromDataProviderParamRector from rector.php.
Optionally document a provider's yielded shape manually where it aids reading the test.
Enforce provider conventions in test style guides, not via code generation.

Example fix

// before (rector.php)
->withRules([AddReturnArrayDocblockFromDataProviderParamRector::class])

// after (rector.php) - rule removed; no replacement needed

Defensive patterns

Strategy: validation

Validate before calling

use Rector\TypeDeclarationDocblocks\Rector\Class_\AddReturnArrayDocblockFromDataProviderParamRector;

$rules = [/* your list */ AddReturnArrayDocblockFromDataProviderParamRector::class];
if (in_array(AddReturnArrayDocblockFromDataProviderParamRector::class, $rules, true)) {
    throw new InvalidArgumentException('Rule deprecated; data-provider typing is not a code-quality concern');
}

Try / catch

try {
    exit($rectorApplication->run());
} catch (\Rector\Exception\ShouldNotHappenException $e) {
    if (str_contains($e->getMessage(), 'AddReturnArrayDocblockFromDataProviderParamRector')) {
        fwrite(STDERR, 'Remove the rule; provider return typing added churn without quality gain.' . PHP_EOL);
        exit(1);
    }
    throw $e;
}

Prevention

Keep test-related rector rules to structural ones (renames, dead-code), not docbook typing.
Note this rule matches Class_ nodes - it fails on the first scanned class, usually a test case.
Sweep configs for 'FromDataProvider' rule names after rector upgrades; the whole family is deprecated.

When it happens

Trigger: The rule remains in a TypeDeclarationDocblocks rule list and rector visits any class; refactor() throws on the first Class_ node, typically the first test case scanned.

Common situations: 'Type everything' rector configs that also covered tests; CI failing on the first test class after a rector upgrade; monorepo configs reusing an old rule list across packages.

Related errors

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