[VersionBonding] Cap polyfill rules by explicitly picked withPhpSets() version

When a PHP version is explicitly picked, e.g. withPhpSets(php82: true),
the SetList::PHP_POLYFILLS set is still loaded. A rule bound to a higher
polyfill package, e.g. AddOverrideAttributeToOverriddenMethodsRector with
symfony/polyfill-php83, was then active regardless of the picked version.

The explicitly picked version is an intended ceiling, so polyfilled rules
above it are now skipped.

Author: TomasVotruba

src/Configuration/Option.php

@@ -45,6 +45,14 @@ final class Option
      */
     public const string POLYFILL_PACKAGES = 'polyfill_packages';
 
+    /**
+     * PHP version explicitly picked in withPhpSets(), e.g. withPhpSets(php82: true).
+     * Polyfilled rules above this version are skipped, as the version is an intended ceiling.
+     *
+     * @internal
+     */
+    public const string POLYFILL_CEILING_PHP_VERSION = 'polyfill_ceiling_php_version';
+
     /**
      * @internal Use @see \Rector\Config\RectorConfig::importNames() instead
      * @var string

src/Configuration/RectorConfigBuilder.php

@@ -191,6 +191,8 @@ final class RectorConfigBuilder
 
     private ?bool $isWithPhpLevelUsed = null;
 
+    private ?int $pickedPhpSetsVersion = null;
+
     /**
      * @var array<class-string<SetProviderInterface>,bool>
      */
@@ -221,6 +223,13 @@ public function __invoke(RectorConfig $rectorConfig): void
             $this->sets[] = SetList::PHP_POLYFILLS;
         }
 
+        if ($this->pickedPhpSetsVersion !== null) {
+            SimpleParameterProvider::setParameter(
+                Option::POLYFILL_CEILING_PHP_VERSION,
+                $this->pickedPhpSetsVersion
+            );
+        }
+
         // merge sets together
         $this->sets = array_merge($this->sets, $this->groupLoadedSets);
 
@@ -601,6 +610,9 @@ public function withPhpSets(
             return $this->addPhpLevelSets(ComposerJsonPhpVersionResolver::resolveFromCwdOrFail());
         }
 
+        // explicitly picked version is a ceiling, even for polyfilled rules
+        $this->pickedPhpSetsVersion = $pickedPhpVersions[0];
+
         return $this->addPhpLevelSets($pickedPhpVersions[0]);
     }
 

src/VersionBonding/PhpVersionedFilter.php

@@ -4,6 +4,8 @@
 
 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;
@@ -28,10 +30,13 @@ public function __construct(
     public function filter(array $rectors): array
     {
         $minProjectPhpVersion = $this->phpVersionProvider->provide();
+        $ceilingPhpVersion = $this->resolveCeilingPhpVersion();
 
         $activeRectors = [];
         foreach ($rectors as $rector) {
-            if ($rector instanceof RelatedPolyfillInterface) {
+            // polyfill package can raise the rule above the project PHP version,
+            // but never above an explicitly picked withPhpSets() version
+            if ($rector instanceof RelatedPolyfillInterface && $ceilingPhpVersion === null) {
                 $polyfillPackageNames = $this->polyfillPackagesProvider->provide();
 
                 if (in_array($rector->providePolyfillPackage(), $polyfillPackageNames, true)) {
@@ -45,12 +50,30 @@ public function filter(array $rectors): array
                 continue;
             }
 
+            $maxPhpVersion = $rector instanceof RelatedPolyfillInterface && $ceilingPhpVersion !== null
+                ? $ceilingPhpVersion
+                : $minProjectPhpVersion;
+
             // does satisfy version? → include
-            if ($rector->provideMinPhpVersion() <= $minProjectPhpVersion) {
+            if ($rector->provideMinPhpVersion() <= $maxPhpVersion) {
                 $activeRectors[] = $rector;
             }
         }
 
         return $activeRectors;
     }
+
+    private function resolveCeilingPhpVersion(): ?int
+    {
+        if (! SimpleParameterProvider::hasParameter(Option::POLYFILL_CEILING_PHP_VERSION)) {
+            return null;
+        }
+
+        $ceilingPhpVersion = SimpleParameterProvider::provideIntParameter(Option::POLYFILL_CEILING_PHP_VERSION);
+        if ($ceilingPhpVersion <= 0) {
+            return null;
+        }
+
+        return $ceilingPhpVersion;
+    }
 }

tests/VersionBonding/Fixture/PolyfillPhp83Rector.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\VersionBonding\Fixture;
+
+use PhpParser\Node;
+use Rector\Rector\AbstractRector;
+use Rector\ValueObject\PhpVersion;
+use Rector\ValueObject\PolyfillPackage;
+use Rector\VersionBonding\Contract\MinPhpVersionInterface;
+use Rector\VersionBonding\Contract\RelatedPolyfillInterface;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+final class PolyfillPhp83Rector extends AbstractRector implements MinPhpVersionInterface, RelatedPolyfillInterface
+{
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition('Test rector bound to PHP 8.3 polyfill', []);
+    }
+
+    public function getNodeTypes(): array
+    {
+        return [Node\Stmt\Class_::class];
+    }
+
+    public function refactor(Node $node): ?Node
+    {
+        return null;
+    }
+
+    public function provideMinPhpVersion(): int
+    {
+        return PhpVersion::PHP_83;
+    }
+
+    public function providePolyfillPackage(): string
+    {
+        return PolyfillPackage::PHP_83;
+    }
+}

tests/VersionBonding/PhpVersionedFilterTest.php

@@ -5,9 +5,14 @@
 namespace Rector\Tests\VersionBonding;
 
 use PHPUnit\Framework\TestCase;
+use Rector\Configuration\Option;
+use Rector\Configuration\Parameter\SimpleParameterProvider;
 use Rector\Php\PhpVersionProvider;
 use Rector\Php\PolyfillPackagesProvider;
 use Rector\Tests\VersionBonding\Fixture\NoInterfaceRector;
+use Rector\Tests\VersionBonding\Fixture\PolyfillPhp83Rector;
+use Rector\ValueObject\PhpVersion;
+use Rector\ValueObject\PolyfillPackage;
 use Rector\VersionBonding\PhpVersionedFilter;
 
 final class PhpVersionedFilterTest extends TestCase
@@ -20,6 +25,14 @@ protected function setUp(): void
         $polyfillPackagesProvider = new PolyfillPackagesProvider();
 
         $this->phpVersionedFilter = new PhpVersionedFilter($phpVersionProvider, $polyfillPackagesProvider);
+
+        SimpleParameterProvider::setParameter(Option::POLYFILL_PACKAGES, [PolyfillPackage::PHP_83]);
+    }
+
+    protected function tearDown(): void
+    {
+        SimpleParameterProvider::setParameter(Option::POLYFILL_PACKAGES, []);
+        SimpleParameterProvider::setParameter(Option::POLYFILL_CEILING_PHP_VERSION, 0);
     }
 
     public function testRectorWithoutInterfaceIsIncluded(): void
@@ -30,4 +43,32 @@ public function testRectorWithoutInterfaceIsIncluded(): void
         $this->assertCount(1, $filtered);
         $this->assertSame($noInterfaceRector, $filtered[0]);
     }
+
+    public function testPolyfilledRectorIsIncluded(): void
+    {
+        $polyfillPhp83Rector = new PolyfillPhp83Rector();
+        $filtered = $this->phpVersionedFilter->filter([$polyfillPhp83Rector]);
+
+        $this->assertCount(1, $filtered);
+        $this->assertSame($polyfillPhp83Rector, $filtered[0]);
+    }
+
+    public function testPolyfilledRectorAbovePickedPhpSetsVersionIsSkipped(): void
+    {
+        SimpleParameterProvider::setParameter(Option::POLYFILL_CEILING_PHP_VERSION, PhpVersion::PHP_82);
+
+        $filtered = $this->phpVersionedFilter->filter([new PolyfillPhp83Rector()]);
+        $this->assertCount(0, $filtered);
+    }
+
+    public function testPolyfilledRectorBelowPickedPhpSetsVersionIsIncluded(): void
+    {
+        SimpleParameterProvider::setParameter(Option::POLYFILL_CEILING_PHP_VERSION, PhpVersion::PHP_83);
+
+        $polyfillPhp83Rector = new PolyfillPhp83Rector();
+        $filtered = $this->phpVersionedFilter->filter([$polyfillPhp83Rector]);
+
+        $this->assertCount(1, $filtered);
+        $this->assertSame($polyfillPhp83Rector, $filtered[0]);
+    }
 }