feat: separate version bonding for PHP requirement and deprecations

Kenneth-Sills · Kenneth-Sills · commit 5d2cf969ee14 · 2026-02-16T00:07:02.000-05:00
This will allow us to implement eager deprecation resolution for
PHP version ranges.

Test cases have been added to make sure the feature works
correctly, but also that no rules in the PHP upgrade pipeline
are misconfigured in an obvious way.
diff --git a/src/Config/RectorConfig.php b/src/Config/RectorConfig.php
@@ -325,6 +325,11 @@ public function treatClassesAsFinal(bool $treatClassesAsFinal = true): void
         SimpleParameterProvider::setParameter(Option::TREAT_CLASSES_AS_FINAL, $treatClassesAsFinal);
     }
 
+    public function eagerlyResolveDeprecations(bool $eagerlyResolveDeprecations = true): void
+    {
+        SimpleParameterProvider::setParameter(Option::EAGERLY_RESOLVE_DEPRECATIONS, $eagerlyResolveDeprecations);
+    }
+
     /**
      * @param string[] $extensions
      */
diff --git a/src/Configuration/Option.php b/src/Configuration/Option.php
@@ -229,6 +229,12 @@ final class Option
      */
     public const string TREAT_CLASSES_AS_FINAL = 'treat_classes_as_final';
 
+    /**
+     * @internal Use @see \Rector\Config\RectorConfig::eagerlyResolveDeprecations() method
+     * @var string
+     */
+    public const string EAGERLY_RESOLVE_DEPRECATIONS = 'eagerly_resolve_deprecations';
+
     /**
      * @internal To report composer based loaded sets
      * @see \Rector\Configuration\RectorConfigBuilder::withComposerBased()
diff --git a/src/Configuration/RectorConfigBuilder.php b/src/Configuration/RectorConfigBuilder.php
@@ -157,6 +157,8 @@ final class RectorConfigBuilder
 
     private ?bool $isTreatClassesAsFinal = null;
 
+    private ?bool $isEagerlyResolvedDeprecations = null;
+
     /**
      * @var RegisteredService[]
      */
@@ -381,6 +383,10 @@ public function __invoke(RectorConfig $rectorConfig): void
             $rectorConfig->treatClassesAsFinal($this->isTreatClassesAsFinal);
         }
 
+        if ($this->isEagerlyResolvedDeprecations !== null) {
+            $rectorConfig->eagerlyResolveDeprecations($this->isEagerlyResolvedDeprecations);
+        }
+
         if ($this->reportingRealPath !== null) {
             $rectorConfig->reportingRealPath($this->reportingRealPath);
         }
@@ -1215,6 +1221,12 @@ public function withTreatClassesAsFinal(bool $isTreatClassesAsFinal = true): sel
         return $this;
     }
 
+    public function withEagerlyResolvedDeprecations(bool $isEagerlyResolvedDeprecations = true): self
+    {
+        $this->isEagerlyResolvedDeprecations = $isEagerlyResolvedDeprecations;
+        return $this;
+    }
+
     public function registerService(string $className, ?string $alias = null, ?string $tag = null): self
     {
         // BC layer since 2.2.9
diff --git a/src/Testing/PHPUnit/AbstractRectorTestCase.php b/src/Testing/PHPUnit/AbstractRectorTestCase.php
@@ -63,6 +63,8 @@ public static function tearDownAfterClass(): void
         SimpleParameterProvider::setParameter(Option::NEW_LINE_ON_FLUENT_CALL, false);
 
         SimpleParameterProvider::setParameter(Option::TREAT_CLASSES_AS_FINAL, false);
+
+        SimpleParameterProvider::setParameter(Option::EAGERLY_RESOLVE_DEPRECATIONS, false);
     }
 
     protected function setUp(): void
@@ -182,8 +184,8 @@ protected function doTestFileExpectingWarningAboutRuleApplied(
         $testClass = static::class;
         $this->assertSame(
             PHP_EOL . 'WARNING: On fixture file "' . $fixtureName . '" for test "' . $testClass . '"' . PHP_EOL .
-            'File not changed but some Rector rules applied:' . PHP_EOL .
-            ' * ' . $expectedRuleApplied . PHP_EOL,
+                'File not changed but some Rector rules applied:' . PHP_EOL .
+                ' * ' . $expectedRuleApplied . PHP_EOL,
             $content
         );
     }
diff --git a/src/VersionBonding/Contract/DeprecatedAtVersionInterface.php b/src/VersionBonding/Contract/DeprecatedAtVersionInterface.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\VersionBonding\Contract;
+
+use Rector\ValueObject\PhpVersion;
+
+/**
+ * Can be implemented by @see \Rector\Contract\Rector\RectorInterface
+ *
+ * Rules that resolve deprecations can expose the PHP version where the
+ * deprecation starts.
+ *
+ * Rules that do not meet this PHP version will be skipped when
+ * Option::EAGERLY_RESOLVE_DEPRECATIONS is false (default).
+ *
+ * @see \Rector\VersionBonding\Contract\MinPhpVersionInterface
+ */
+interface DeprecatedAtVersionInterface
+{
+    /**
+     * @return PhpVersion::*
+     */
+    public function provideDeprecatedAtVersion(): int;
+}
diff --git a/src/VersionBonding/Contract/MinPhpVersionInterface.php b/src/VersionBonding/Contract/MinPhpVersionInterface.php
@@ -10,6 +10,10 @@
  * Can be implemented by @see \Rector\Contract\Rector\RectorInterface
  *
  * Rules that do not meet this PHP version will be skipped.
+ *
+ * Rules that also implement @see Rector\VersionBonding\Contract\DeprecatedAtVersionInterface
+ * will prioritize the deprecation version over the minimum PHP version when
+ * Option::EAGERLY_RESOLVE_DEPRECATIONS is false (default).
  */
 interface MinPhpVersionInterface
 {
diff --git a/src/VersionBonding/PhpVersionedFilter.php b/src/VersionBonding/PhpVersionedFilter.php
@@ -4,9 +4,12 @@
 
 namespace Rector\VersionBonding;
 
+use Rector\Configuration\Option;
+use Rector\Configuration\Parameter\SimpleParameterProvider;
 use Rector\Contract\Rector\RectorInterface;
 use Rector\Php\PhpVersionProvider;
 use Rector\Php\PolyfillPackagesProvider;
+use Rector\VersionBonding\Contract\DeprecatedAtVersionInterface;
 use Rector\VersionBonding\Contract\MinPhpVersionInterface;
 use Rector\VersionBonding\Contract\RelatedPolyfillInterface;
 
@@ -28,6 +31,10 @@ public function __construct(
     public function filter(array $rectors): array
     {
         $minProjectPhpVersion = $this->phpVersionProvider->provide();
+        $isEagerlyResolveDeprecations = SimpleParameterProvider::provideBoolParameter(
+            Option::EAGERLY_RESOLVE_DEPRECATIONS,
+            false
+        );
 
         $activeRectors = [];
         foreach ($rectors as $rector) {
@@ -40,13 +47,27 @@ public function filter(array $rectors): array
                 }
             }
 
-            if (! $rector instanceof MinPhpVersionInterface) {
+            if (
+                ! $rector instanceof MinPhpVersionInterface
+                && ! $rector instanceof DeprecatedAtVersionInterface
+            ) {
                 $activeRectors[] = $rector;
                 continue;
             }
 
+            $deprecationVersion = $rector instanceof DeprecatedAtVersionInterface
+                ? $rector->provideDeprecatedAtVersion()
+                : null;
+            $minPhpVersion = $rector instanceof MinPhpVersionInterface
+                ? $rector->provideMinPhpVersion()
+                : null;
+
+            $requiredPhpVersion = (! $deprecationVersion || $isEagerlyResolveDeprecations)
+                ? $minPhpVersion
+                : $deprecationVersion;
+
             // does satisfy version? → include
-            if ($rector->provideMinPhpVersion() <= $minProjectPhpVersion) {
+            if ($requiredPhpVersion === null || $requiredPhpVersion <= $minProjectPhpVersion) {
                 $activeRectors[] = $rector;
             }
         }
diff --git a/tests/VersionBonding/Fixture/DeprecatedAtVersionRector.php b/tests/VersionBonding/Fixture/DeprecatedAtVersionRector.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\VersionBonding\Fixture;
+
+use PhpParser\Node;
+use Rector\Rector\AbstractRector;
+use Rector\VersionBonding\Contract\DeprecatedAtVersionInterface;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+final class DeprecatedAtVersionRector extends AbstractRector implements DeprecatedAtVersionInterface
+{
+    public function __construct(
+        private readonly int $deprecatedAtVersion,
+    ) {
+    }
+
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition('Test rector with deprecated-at PHP version', []);
+    }
+
+    public function getNodeTypes(): array
+    {
+        return [Node\Stmt\Class_::class];
+    }
+
+    public function refactor(Node $node): ?Node
+    {
+        return null;
+    }
+
+    public function provideDeprecatedAtVersion(): int
+    {
+        return $this->deprecatedAtVersion;
+    }
+}
diff --git a/tests/VersionBonding/Fixture/MinPhpVersionRector.php b/tests/VersionBonding/Fixture/MinPhpVersionRector.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\VersionBonding\Fixture;
+
+use PhpParser\Node;
+use Rector\Rector\AbstractRector;
+use Rector\VersionBonding\Contract\MinPhpVersionInterface;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+final class MinPhpVersionRector extends AbstractRector implements MinPhpVersionInterface
+{
+    public function __construct(
+        private readonly int $minPhpVersion,
+    ) {
+    }
+
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition('Test rector with minimum PHP version', []);
+    }
+
+    public function getNodeTypes(): array
+    {
+        return [Node\Stmt\Class_::class];
+    }
+
+    public function refactor(Node $node): ?Node
+    {
+        return null;
+    }
+
+    public function provideMinPhpVersion(): int
+    {
+        return $this->minPhpVersion;
+    }
+}
diff --git a/tests/VersionBonding/Fixture/MixedVersionBoundsRector.php b/tests/VersionBonding/Fixture/MixedVersionBoundsRector.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\VersionBonding\Fixture;
+
+use PhpParser\Node;
+use Rector\Rector\AbstractRector;
+use Rector\VersionBonding\Contract\DeprecatedAtVersionInterface;
+use Rector\VersionBonding\Contract\MinPhpVersionInterface;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+final class MixedVersionBoundsRector extends AbstractRector implements MinPhpVersionInterface, DeprecatedAtVersionInterface
+{
+    public function __construct(
+        private readonly int $minPhpVersion,
+        private readonly int $deprecatedAtVersion,
+    ) {}
+
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition('Test rector with deprecation-aware versions', []);
+    }
+
+    public function getNodeTypes(): array
+    {
+        return [Node\Stmt\Class_::class];
+    }
+
+    public function refactor(Node $node): ?Node
+    {
+        return null;
+    }
+
+    public function provideMinPhpVersion(): int
+    {
+        return $this->minPhpVersion;
+    }
+
+    public function provideDeprecatedAtVersion(): int
+    {
+        return $this->deprecatedAtVersion;
+    }
+}
diff --git a/tests/VersionBonding/PhpVersionBoundsInvariantTest.php b/tests/VersionBonding/PhpVersionBoundsInvariantTest.php
@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\VersionBonding;
+
+use Rector\Configuration\PhpLevelSetResolver;
+use Rector\Contract\Rector\RectorInterface;
+use Rector\Testing\PHPUnit\AbstractLazyTestCase;
+use Rector\ValueObject\PhpVersion;
+use Rector\VersionBonding\Contract\DeprecatedAtVersionInterface;
+use Rector\VersionBonding\Contract\MinPhpVersionInterface;
+
+final class PhpVersionBoundsInvariantTest extends AbstractLazyTestCase
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        // Keep this test isolated from shared container state between tests.
+        self::$rectorConfig = null;
+
+        $allPhpLevelSets = PhpLevelSetResolver::resolveFromPhpVersion(PhpVersion::PHP_10);
+        self::getContainer()->sets($allPhpLevelSets);
+    }
+
+    public function testMinPhpVersionIsNotHigherThanDeprecatedAtVersion(): void
+    {
+        /** @var list<MinPhpVersionInterface&DeprecatedAtVersionInterface> $dualVersionRectors */
+        $dualVersionRectors = array_filter(
+            [...self::getContainer()->tagged(RectorInterface::class)],
+            fn (RectorInterface $rector): bool => (
+                $rector instanceof MinPhpVersionInterface
+                && $rector instanceof DeprecatedAtVersionInterface
+            )
+        );
+
+        $violations = array_filter(array_map(
+            function (MinPhpVersionInterface&DeprecatedAtVersionInterface $rector): ?string {
+                $minimumPhpVersion = $rector->provideMinPhpVersion();
+                $deprecatedAtVersion = $rector->provideDeprecatedAtVersion();
+
+                if ($minimumPhpVersion <= $deprecatedAtVersion) {
+                    return null;
+                }
+
+                return sprintf(
+                    '%s has provideMinPhpVersion()=%d and provideDeprecatedAtVersion()=%d',
+                    $rector::class,
+                    $minimumPhpVersion,
+                    $deprecatedAtVersion
+                );
+            },
+            $dualVersionRectors
+        ));
+
+        $this->assertNotEmpty($dualVersionRectors, 'No dual-version rectors were inspected.');
+        $this->assertSame([], $violations, implode(PHP_EOL, $violations));
+    }
+}
diff --git a/tests/VersionBonding/PhpVersionedFilterTest.php b/tests/VersionBonding/PhpVersionedFilterTest.php

Original file line number	Diff line number	Diff line change
`@@ -10,6 +10,10 @@`
`10`	`10`	`* Can be implemented by @see \Rector\Contract\Rector\RectorInterface`
`11`	`11`	`*`
`12`	`12`	`* Rules that do not meet this PHP version will be skipped.`
	`13`	`+ *`
	`14`	`+ * Rules that also implement @see Rector\VersionBonding\Contract\DeprecatedAtVersionInterface`
	`15`	`+ * will prioritize the deprecation version over the minimum PHP version when`
	`16`	`+ * Option::EAGERLY_RESOLVE_DEPRECATIONS is false (default).`
`13`	`17`	`*/`
`14`	`18`	`interface MinPhpVersionInterface`
`15`	`19`	`{`