[Feature] Add ReturnAnnotationIncorrectNullableRector for fixing incorrect null type in @return

build/target-repository/docs/rector_rules_overview.md

@@ -1,4 +1,4 @@
-# 508 Rules Overview
+# 510 Rules Overview
 
 <br>
 
@@ -86,9 +86,9 @@
 
 - [Strict](#strict) (5)
 
-- [Transform](#transform) (35)
+- [Transform](#transform) (36)
 
-- [TypeDeclaration](#typedeclaration) (24)
+- [TypeDeclaration](#typedeclaration) (25)
 
 - [Visibility](#visibility) (3)
 
@@ -10195,6 +10195,43 @@ return static function (ContainerConfigurator $containerConfigurator): void {
 
 <br>
 
+### FileGetContentsAndJsonDecodeToStaticCallRector
+
+Merge 2 function calls to static call
+
+:wrench: **configure it!**
+
+- class: [`Rector\Transform\Rector\FunctionLike\FileGetContentsAndJsonDecodeToStaticCallRector`](../rules/Transform/Rector/FunctionLike/FileGetContentsAndJsonDecodeToStaticCallRector.php)
+
+```php
+use Rector\Transform\Rector\FunctionLike\FileGetContentsAndJsonDecodeToStaticCallRector;
+use Rector\Transform\ValueObject\StaticCallRecipe;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+
+return static function (ContainerConfigurator $containerConfigurator): void {
+    $services = $containerConfigurator->services();
+
+    $services->set(FileGetContentsAndJsonDecodeToStaticCallRector::class)
+        ->configure([new StaticCallRecipe('FileLoader', 'loadJson')]);
+};
+```
+
+↓
+
+```diff
+ final class SomeClass
+ {
+     public function load($filePath)
+     {
+-        $fileGetContents = file_get_contents($filePath);
+-        return json_decode($fileGetContents, true);
++        return FileLoader::loadJson($filePath);
+     }
+ }
+```
+
+<br>
+
 ### FuncCallToConstFetchRector
 
 Changes use of function calls to use constants
@@ -11702,6 +11739,28 @@ Add `@var` to properties that are missing it
 
 <br>
 
+### ReturnAnnotationIncorrectNullableRector
+
+Add or remove null type from `@return` phpdoc typehint based on php return type declaration
+
+- class: [`Rector\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector`](../rules/TypeDeclaration/Rector/ClassMethod/ReturnAnnotationIncorrectNullableRector.php)
+
+```diff
+ final class SomeClass
+ {
+     /**
+-     * @return \DateTime[]
++     * @return \DateTime[]|null
+      */
+     public function getDateTimes(): ?array
+     {
+         return $this->dateTimes;
+     }
+ }
+```
+
+<br>
+
 ### ReturnNeverTypeRector
 
 Add "never" return-type for methods that never return anything

rules-tests/TypeDeclaration/Rector/ClassMethod/ReturnAnnotationIncorrectNullableRector/Fixture/return-annotation-already-includes-null.php.inc

@@ -0,0 +1,14 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationAlreadyIncludesNull
+{
+    /**
+     * @return \DateTime[]|null
+     */
+    public function getDateTimes(): ?array
+    {
+        return $this->dateTimes;
+    }
+}

rules-tests/TypeDeclaration/Rector/ClassMethod/ReturnAnnotationIncorrectNullableRector/Fixture/return-annotation-complex.php.inc

@@ -0,0 +1,43 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationComplex
+{
+    /**
+     * @Serializer\VirtualProperty
+     * @Serializer\Type("array<DateTime>")
+     * @Assert\All({
+     *     @Assert\NotBlank,
+     *     @AppAssert\Country,
+     * })
+     * @return \DateTime[]
+     */
+    public function getDateTimes(): ?array
+    {
+        return $this->dateTimes;
+    }
+}
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationComplex
+{
+    /**
+     * @Serializer\VirtualProperty
+     * @Serializer\Type("array<DateTime>")
+     * @Assert\All({
+     *     @Assert\NotBlank,
+     *     @AppAssert\Country,
+     * })
+     * @return \DateTime[]|null
+     */
+    public function getDateTimes(): ?array
+    {
+        return $this->dateTimes;
+    }
+}
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/ReturnAnnotationIncorrectNullableRector/Fixture/return-annotation-incorrectly-includes-null-on-scalar.php.inc

@@ -0,0 +1,31 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationIncorrectlyIncludesNullOnScalar
+{
+    /**
+     * @return string|null
+     */
+    public function getDateTimes(): array
+    {
+        return $this->text;
+    }
+}
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationIncorrectlyIncludesNullOnScalar
+{
+    /**
+     * @return string
+     */
+    public function getDateTimes(): array
+    {
+        return $this->text;
+    }
+}
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/ReturnAnnotationIncorrectNullableRector/Fixture/return-annotation-incorrectly-includes-null.php.inc

@@ -0,0 +1,31 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationIncorrectlyIncludesNull
+{
+    /**
+     * @return \DateTime[]|null
+     */
+    public function getDateTimes(): array
+    {
+        return $this->dateTimes;
+    }
+}
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationIncorrectlyIncludesNull
+{
+    /**
+     * @return \DateTime[]
+     */
+    public function getDateTimes(): array
+    {
+        return $this->dateTimes;
+    }
+}
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/ReturnAnnotationIncorrectNullableRector/Fixture/return-annotation-is-missing-null-with-generic-syntax.php.inc

@@ -0,0 +1,37 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationIsMissingNullWithGenericSyntax
+{
+    /**
+     * Rector automatically transforms generic int-keyed simple arrays to the [] notation
+     * @see \Rector\PHPStanStaticTypeMapper\TypeMapper\ArrayTypeMapper::isIntegerKeyAndNonNestedArray
+     *
+     * @return array<int,\DateTime>
+     */
+    public function getDateTimes(): ?array
+    {
+        return $this->dateTimes;
+    }
+}
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationIsMissingNullWithGenericSyntax
+{
+    /**
+     * Rector automatically transforms generic int-keyed simple arrays to the [] notation
+     * @see \Rector\PHPStanStaticTypeMapper\TypeMapper\ArrayTypeMapper::isIntegerKeyAndNonNestedArray
+     *
+     * @return \DateTime[]|null
+     */
+    public function getDateTimes(): ?array
+    {
+        return $this->dateTimes;
+    }
+}
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/ReturnAnnotationIncorrectNullableRector/Fixture/return-annotation-is-missing-null-with-nested-generic-syntax.php.inc

@@ -0,0 +1,31 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationIsMissingNullWithNestedGenericSyntax
+{
+    /**
+     * @return array<int, array<string, \DateTime>>
+     */
+    public function getDateTimes(): ?array
+    {
+        return $this->dateTimes;
+    }
+}
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationIsMissingNullWithNestedGenericSyntax
+{
+    /**
+     * @return array<int, array<string, \DateTime>>|null
+     */
+    public function getDateTimes(): ?array
+    {
+        return $this->dateTimes;
+    }
+}
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/ReturnAnnotationIncorrectNullableRector/Fixture/return-annotation-is-missing-null.php.inc

@@ -0,0 +1,31 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationIsMissingNull
+{
+    /**
+     * @return \DateTime[]
+     */
+    public function getDateTimes(): ?array
+    {
+        return $this->dateTimes;
+    }
+}
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+final class ReturnAnnotationIsMissingNull
+{
+    /**
+     * @return \DateTime[]|null
+     */
+    public function getDateTimes(): ?array
+    {
+        return $this->dateTimes;
+    }
+}
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/ReturnAnnotationIncorrectNullableRector/Fixture/return-annotation-on-function-incorrectly-includes-null.php.inc

@@ -0,0 +1,27 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+/**
+ * @return \DateTime[]|null
+ */
+function getDateTimes(): array
+{
+    return [new \DateTime()];
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+/**
+ * @return \DateTime[]
+ */
+function getDateTimes(): array
+{
+    return [new \DateTime()];
+}
+
+?>

rules-tests/TypeDeclaration/Rector/ClassMethod/ReturnAnnotationIncorrectNullableRector/Fixture/return-annotation-on-function-is-missing-null.php.inc

@@ -0,0 +1,27 @@
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+/**
+ * @return \DateTime[]
+ */
+function getDateTimes(int $i): ?array
+{
+    return $i > 0 ? [new \DateTime()] : null;
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclaration\Rector\ClassMethod\ReturnAnnotationIncorrectNullableRector\Fixture;
+
+/**
+ * @return \DateTime[]|null
+ */
+function getDateTimes(int $i): ?array
+{
+    return $i > 0 ? [new \DateTime()] : null;
+}
+
+?>