From ba0e85966b7a1ab3c298af7a45721339290635fd Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Wed, 2 Sep 2026 14:31:36 +0200
Subject: [PATCH] [TypeDeclarationDocblocks] Skip empty array return in
 DocblockReturnArrayFromDirectArrayInstanceRector

A @return array{} is the narrowest array type. When added to a method that
can be overridden, any child returning a filled array violates it. Empty
array{} docblocks carry no useful information, so skip them entirely.
---
 .../Fixture/return_empty.php.inc              | 30 -------------------
 .../Fixture/skip_return_empty.php.inc         | 11 +++++++
 ...turnArrayFromDirectArrayInstanceRector.php | 21 ++-----------
 3 files changed, 13 insertions(+), 49 deletions(-)
 delete mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/return_empty.php.inc
 create mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/skip_return_empty.php.inc

diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/return_empty.php.inc b/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/return_empty.php.inc
deleted file mode 100644
index 4beb2996db5..00000000000
--- a/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/return_empty.php.inc
+++ /dev/null
@@ -1,30 +0,0 @@
-<?php
-
-namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\DocblockReturnArrayFromDirectArrayInstanceRector\Fixture;
-
-class ReturnEmpty
-{
-    public function run(): array
-    {
-        return [];
-    }
-}
-
-?>
------
-<?php
-
-namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\DocblockReturnArrayFromDirectArrayInstanceRector\Fixture;
-
-class ReturnEmpty
-{
-    /**
-     * @return array{}
-     */
-    public function run(): array
-    {
-        return [];
-    }
-}
-
-?>
diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/skip_return_empty.php.inc b/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/skip_return_empty.php.inc
new file mode 100644
index 00000000000..8f37bb8e9ff
--- /dev/null
+++ b/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/skip_return_empty.php.inc
@@ -0,0 +1,11 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\DocblockReturnArrayFromDirectArrayInstanceRector\Fixture;
+
+class SkipReturnEmpty
+{
+    public function run(): array
+    {
+        return [];
+    }
+}
diff --git a/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php b/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php
index 14d48b3151f..5016bd502b7 100644
--- a/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php
+++ b/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php
@@ -9,10 +9,7 @@
 use PhpParser\Node\Stmt\ClassMethod;
 use PhpParser\Node\Stmt\Function_;
 use PhpParser\Node\Stmt\Return_;
-use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
-use PHPStan\PhpDocParser\Ast\Type\ArrayTypeNode;
 use PHPStan\Type\Constant\ConstantArrayType;
-use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
 use Rector\BetterPhpDocParser\PhpDocManipulator\PhpDocTypeChanger;
 use Rector\Rector\AbstractRector;
@@ -110,7 +107,8 @@ public function refactor(Node $node): ?Node
             return null;
         }
 
-        if ($this->shouldSkipReturnMixedAndEmptyArray($phpDocInfo, $soleReturn->expr)) {
+        // skip empty array; @return array{} is the narrowest array type and breaks any child override that returns a filled array
+        if ($soleReturn->expr->items === []) {
             return null;
         }
 
@@ -132,19 +130,4 @@ public function refactor(Node $node): ?Node
 
         return $node;
     }
-
-    private function shouldSkipReturnMixedAndEmptyArray(PhpDocInfo $phpDocInfo, Array_ $array): bool
-    {
-        if ($array->items !== []) {
-            return false;
-        }
-
-        $returnTagValueNode = $phpDocInfo->getReturnTagValue();
-        if (! $returnTagValueNode instanceof ReturnTagValueNode) {
-            return false;
-        }
-
-        // better than array{}
-        return $returnTagValueNode->type instanceof ArrayTypeNode;
-    }
 }