From 3a7a899c8c9c2d4d97d1001cb7f57c8f42a7245a Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Wed, 2 Sep 2026 14:50:14 +0200
Subject: [PATCH] [TypeDeclarationDocblocks] Turn bare "@return array" with
 empty "return []" into "mixed[]" instead of "array{}"

Claude-Session: https://claude.ai/code/session_011MyFdoaYnfDEvdM9o3kiyq
---
 .../Fixture/bare_array_empty_to_mixed.php.inc | 33 +++++++++++++++++++
 ...turnArrayFromDirectArrayInstanceRector.php | 23 +++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/bare_array_empty_to_mixed.php.inc

diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/bare_array_empty_to_mixed.php.inc b/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/bare_array_empty_to_mixed.php.inc
new file mode 100644
index 00000000000..eef23ef5eb6
--- /dev/null
+++ b/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/bare_array_empty_to_mixed.php.inc
@@ -0,0 +1,33 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\DocblockReturnArrayFromDirectArrayInstanceRector\Fixture;
+
+class BareArrayEmptyToMixed
+{
+    /**
+     * @return array
+     */
+    public function getRefreshTokenKeys()
+    {
+        return [];
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\DocblockReturnArrayFromDirectArrayInstanceRector\Fixture;
+
+class BareArrayEmptyToMixed
+{
+    /**
+     * @return mixed[]
+     */
+    public function getRefreshTokenKeys()
+    {
+        return [];
+    }
+}
+
+?>
diff --git a/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php b/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php
index 14d48b3151f..8bc465ac692 100644
--- a/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php
+++ b/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php
@@ -11,10 +11,12 @@
 use PhpParser\Node\Stmt\Return_;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
 use PHPStan\PhpDocParser\Ast\Type\ArrayTypeNode;
+use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
 use PHPStan\Type\Constant\ConstantArrayType;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
 use Rector\BetterPhpDocParser\PhpDocManipulator\PhpDocTypeChanger;
+use Rector\BetterPhpDocParser\ValueObject\Type\SpacingAwareArrayTypeNode;
 use Rector\Rector\AbstractRector;
 use Rector\TypeDeclarationDocblocks\NodeFinder\ReturnNodeFinder;
 use Rector\TypeDeclarationDocblocks\TagNodeAnalyzer\UsefulArrayTagNodeAnalyzer;
@@ -114,6 +116,17 @@ public function refactor(Node $node): ?Node
             return null;
         }
 
+        // bare "@return array" with "return []" -> "mixed[]", better than "array{}"
+        if ($soleReturn->expr->items === [] && $this->hasBareArrayReturnTag($phpDocInfo)) {
+            $this->phpDocTypeChanger->changeReturnTypeNode(
+                $node,
+                $phpDocInfo,
+                new SpacingAwareArrayTypeNode(new IdentifierTypeNode('mixed'))
+            );
+
+            return $node;
+        }
+
         // resolve simple type
         $returnedType = $this->getType($soleReturn->expr);
         if (! $returnedType instanceof ConstantArrayType) {
@@ -147,4 +160,14 @@ private function shouldSkipReturnMixedAndEmptyArray(PhpDocInfo $phpDocInfo, Arra
         // better than array{}
         return $returnTagValueNode->type instanceof ArrayTypeNode;
     }
+
+    private function hasBareArrayReturnTag(PhpDocInfo $phpDocInfo): bool
+    {
+        $returnTagValueNode = $phpDocInfo->getReturnTagValue();
+        if (! $returnTagValueNode instanceof ReturnTagValueNode) {
+            return false;
+        }
+
+        return $returnTagValueNode->type instanceof IdentifierTypeNode && $returnTagValueNode->type->name === 'array';
+    }
 }