[DowngradePhp80] Do not change correct Union array docblock to mixed[…

…] on DowngradeUnionTypeDeclarationRector (#2555)

* [DowngradePhp80] Do not change correct Union array docblock on DowngradeUnionTypeDeclarationRector

* Fixed 🎉

* ensure @return tag exists

* fix

* final touch: check both on param and return

* clean up

* updated failign test case

* move sub type check to PhpDocTypeChanger

* Fixed 🎉

* cs

* final touch: variable cleanup

* final touch: variable cleanup

packages/BetterPhpDocParser/PhpDocParser/PhpDocFromTypeDeclarationDecorator.php

@@ -15,6 +15,7 @@
 use PhpParser\Node\Stmt\ClassMethod;
 use PhpParser\Node\Stmt\Function_;
 use PhpParser\Node\Stmt\Interface_;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
 use PHPStan\Type\ObjectType;
 use PHPStan\Type\Type;
 use PHPStan\Type\UnionType;
@@ -68,8 +69,13 @@ public function decorate(ClassMethod | Function_ | Closure | ArrowFunction $func
             return;
         }
 
-        $type = $this->staticTypeMapper->mapPhpParserNodePHPStanType($functionLike->returnType);
         $phpDocInfo = $this->phpDocInfoFactory->createFromNodeOrEmpty($functionLike);
+
+        $returnTagValueNode = $phpDocInfo->getReturnTagValue();
+        $type = $returnTagValueNode instanceof ReturnTagValueNode
+            ? $this->staticTypeMapper->mapPHPStanPhpDocTypeToPHPStanType($returnTagValueNode, $functionLike->returnType)
+            : $this->staticTypeMapper->mapPhpParserNodePHPStanType($functionLike->returnType);
+
         $this->phpDocTypeChanger->changeReturnType($phpDocInfo, $type);
 
         $functionLike->returnType = null;

rules-tests/DowngradePhp80/Rector/FunctionLike/DowngradeUnionTypeDeclarationRector/Fixture/do_not_change_correct_union_array_docblock_on_param.php.inc

@@ -0,0 +1,51 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp80\Rector\FunctionLike\DowngradeUnionTypeDeclarationRector\Fixture;
+
+use PhpParser\Node;
+use PhpParser\Node\Stmt;
+
+final class DoNotChangeCorrectUnionArrayDocblockOnParam
+{
+    /**
+     * @param int|string[]
+     */
+    public function run(int|array $data)
+    {
+    }
+
+    /**
+     * @param Node|null|Stmt[]
+     */
+    public function run2(Node|null|array $data)
+    {
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\DowngradePhp80\Rector\FunctionLike\DowngradeUnionTypeDeclarationRector\Fixture;
+
+use PhpParser\Node;
+use PhpParser\Node\Stmt;
+
+final class DoNotChangeCorrectUnionArrayDocblockOnParam
+{
+    /**
+     * @param int|string[]
+     */
+    public function run($data)
+    {
+    }
+
+    /**
+     * @param Node|null|Stmt[]
+     */
+    public function run2($data)
+    {
+    }
+}
+
+?>

rules-tests/DowngradePhp80/Rector/FunctionLike/DowngradeUnionTypeDeclarationRector/Fixture/do_not_change_correct_union_array_docblock_on_return.php.inc

@@ -0,0 +1,51 @@
+<?php
+
+namespace Rector\Tests\DowngradePhp80\Rector\FunctionLike\DowngradeUnionTypeDeclarationRector\Fixture;
+
+use PhpParser\Node;
+use PhpParser\Node\Stmt;
+
+final class DoNotChangeCorrectUnionArrayDocblockOnReturn
+{
+    /**
+     * @return int|string[]
+     */
+    public function run(): int|array
+    {
+    }
+
+    /**
+     * @return Node|null|Stmt[]
+     */
+    public function run2(): Node|null|array
+    {
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\DowngradePhp80\Rector\FunctionLike\DowngradeUnionTypeDeclarationRector\Fixture;
+
+use PhpParser\Node;
+use PhpParser\Node\Stmt;
+
+final class DoNotChangeCorrectUnionArrayDocblockOnReturn
+{
+    /**
+     * @return int|string[]
+     */
+    public function run()
+    {
+    }
+
+    /**
+     * @return Node|null|Stmt[]
+     */
+    public function run2()
+    {
+    }
+}
+
+?>