[DowngradePhp81] Add AddReturnTypeWillChangeAttributeRector (#372)

- PHP 8.1 added provisional return types to built-in interfaces (ArrayAccess, Countable, Iterator, IteratorAggregate, Stringable), triggering deprecation notices on implementations without matching return types.
- This rule automatically adds #[\ReturnTypeWillChange] to affected methods, suppressing those notices for codebases that need to remain compatible with older PHP versions and cannot yet add the required return types.

Fixes: rectorphp/rector#9515

Author: jquiaios

config/set/downgrade-php81.php

@@ -9,6 +9,7 @@
 use Rector\Config\RectorConfig;
 use Rector\ValueObject\PhpVersion;
 use Rector\DowngradePhp81\Rector\ClassConst\DowngradeFinalizePublicClassConstantRector;
+use Rector\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector;
 use Rector\DowngradePhp81\Rector\FuncCall\DowngradeArrayIsListRector;
 use Rector\DowngradePhp81\Rector\FuncCall\DowngradeFirstClassCallableSyntaxRector;
 use Rector\DowngradePhp81\Rector\FunctionLike\DowngradeNeverTypeDeclarationRector;
@@ -25,6 +26,7 @@
     $rectorConfig->phpVersion(PhpVersion::PHP_80);
 
     $rectorConfig->rules([
+        AddReturnTypeWillChangeAttributeRector::class,
         DowngradeFinalizePublicClassConstantRector::class,
         DowngradeFirstClassCallableSyntaxRector::class,
         DowngradeNeverTypeDeclarationRector::class,

rules-tests/DowngradePhp81/Rector/ClassMethod/AddReturnTypeWillChangeAttributeRector/AddReturnTypeWillChangeAttributeRectorTest.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector;
+
+use Iterator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Rector\Testing\PHPUnit\AbstractRectorTestCase;
+
+final class AddReturnTypeWillChangeAttributeRectorTest extends AbstractRectorTestCase
+{
+    #[DataProvider('provideData')]
+    public function test(string $filePath): void
+    {
+        $this->doTestFile($filePath);
+    }
+
+    public static function provideData(): Iterator
+    {
+        return self::yieldFilesFromDirectory(__DIR__ . '/Fixture');
+    }
+
+    public function provideConfigFilePath(): string
+    {
+        return __DIR__ . '/config/configured_rule.php';
+    }
+}

rules-tests/DowngradePhp81/Rector/ClassMethod/AddReturnTypeWillChangeAttributeRector/Fixture/array_access.php.inc

@@ -0,0 +1,53 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector\Fixture;
+
+class ArrayAccessClass implements \ArrayAccess
+{
+    public function offsetGet($offset)
+    {
+    }
+
+    public function offsetExists($offset)
+    {
+    }
+
+    public function offsetSet($offset, $value)
+    {
+    }
+
+    public function offsetUnset($offset)
+    {
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector\Fixture;
+
+class ArrayAccessClass implements \ArrayAccess
+{
+    #[\ReturnTypeWillChange]
+    public function offsetGet($offset)
+    {
+    }
+
+    #[\ReturnTypeWillChange]
+    public function offsetExists($offset)
+    {
+    }
+
+    #[\ReturnTypeWillChange]
+    public function offsetSet($offset, $value)
+    {
+    }
+
+    #[\ReturnTypeWillChange]
+    public function offsetUnset($offset)
+    {
+    }
+}
+
+?>

rules-tests/DowngradePhp81/Rector/ClassMethod/AddReturnTypeWillChangeAttributeRector/Fixture/countable.php.inc

@@ -0,0 +1,26 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector\Fixture;
+
+class SomeCountable implements \Countable
+{
+    public function count()
+    {
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector\Fixture;
+
+class SomeCountable implements \Countable
+{
+    #[\ReturnTypeWillChange]
+    public function count()
+    {
+    }
+}
+
+?>

rules-tests/DowngradePhp81/Rector/ClassMethod/AddReturnTypeWillChangeAttributeRector/Fixture/iterator.php.inc

@@ -0,0 +1,62 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector\Fixture;
+
+class SomeIterator implements \Iterator
+{
+    public function current()
+    {
+    }
+
+    public function key()
+    {
+    }
+
+    public function next()
+    {
+    }
+
+    public function rewind()
+    {
+    }
+
+    public function valid()
+    {
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector\Fixture;
+
+class SomeIterator implements \Iterator
+{
+    #[\ReturnTypeWillChange]
+    public function current()
+    {
+    }
+
+    #[\ReturnTypeWillChange]
+    public function key()
+    {
+    }
+
+    #[\ReturnTypeWillChange]
+    public function next()
+    {
+    }
+
+    #[\ReturnTypeWillChange]
+    public function rewind()
+    {
+    }
+
+    #[\ReturnTypeWillChange]
+    public function valid()
+    {
+    }
+}
+
+?>

rules-tests/DowngradePhp81/Rector/ClassMethod/AddReturnTypeWillChangeAttributeRector/Fixture/iterator_aggregate.php.inc

@@ -0,0 +1,26 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector\Fixture;
+
+class SomeIteratorAggregate implements \IteratorAggregate
+{
+    public function getIterator()
+    {
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector\Fixture;
+
+class SomeIteratorAggregate implements \IteratorAggregate
+{
+    #[\ReturnTypeWillChange]
+    public function getIterator()
+    {
+    }
+}
+
+?>

rules-tests/DowngradePhp81/Rector/ClassMethod/AddReturnTypeWillChangeAttributeRector/Fixture/skip_attribute_already_present.php.inc

@@ -0,0 +1,26 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector\Fixture;
+
+class ArrayAccessAlreadyAttributed implements \ArrayAccess
+{
+    #[\ReturnTypeWillChange]
+    public function offsetGet($offset)
+    {
+    }
+
+    #[\ReturnTypeWillChange]
+    public function offsetExists($offset)
+    {
+    }
+
+    #[\ReturnTypeWillChange]
+    public function offsetSet($offset, $value)
+    {
+    }
+
+    #[\ReturnTypeWillChange]
+    public function offsetUnset($offset)
+    {
+    }
+}

rules-tests/DowngradePhp81/Rector/ClassMethod/AddReturnTypeWillChangeAttributeRector/Fixture/skip_has_return_type.php.inc

@@ -0,0 +1,22 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector\Fixture;
+
+class ArrayAccessWithReturnType implements \ArrayAccess
+{
+    public function offsetGet($offset): mixed
+    {
+    }
+
+    public function offsetExists($offset): bool
+    {
+    }
+
+    public function offsetSet($offset, $value): void
+    {
+    }
+
+    public function offsetUnset($offset): void
+    {
+    }
+}

rules-tests/DowngradePhp81/Rector/ClassMethod/AddReturnTypeWillChangeAttributeRector/Fixture/stringable.php.inc

@@ -0,0 +1,26 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector\Fixture;
+
+class SomeStringable implements \Stringable
+{
+    public function __toString()
+    {
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector\Fixture;
+
+class SomeStringable implements \Stringable
+{
+    #[\ReturnTypeWillChange]
+    public function __toString()
+    {
+    }
+}
+
+?>

rules-tests/DowngradePhp81/Rector/ClassMethod/AddReturnTypeWillChangeAttributeRector/config/configured_rule.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\Config\RectorConfig;
+use Rector\DowngradePhp81\Rector\ClassMethod\AddReturnTypeWillChangeAttributeRector;
+
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->rule(AddReturnTypeWillChangeAttributeRector::class);
+};