From e6ccc2ba3390b4088debed88f85f46587d466d74 Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Fri, 12 Sep 2025 14:07:29 +0200
Subject: [PATCH] [type-declaration-docblocks] add nesting support to
 DocblockReturnArrayFromDirectArrayInstanceRector

---
 .../Fixture/single-nested-level.php.inc       | 38 +++++++++++++++++++
 ...turnArrayFromDirectArrayInstanceRector.php | 28 +++++++++++---
 2 files changed, 60 insertions(+), 6 deletions(-)
 create mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/single-nested-level.php.inc

diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/single-nested-level.php.inc b/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/single-nested-level.php.inc
new file mode 100644
index 00000000000..2fa60947429
--- /dev/null
+++ b/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/single-nested-level.php.inc
@@ -0,0 +1,38 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\DocblockReturnArrayFromDirectArrayInstanceRector\Fixture;
+
+final class SingleNestedLevel
+{
+    public function getNames($value): array
+    {
+        return [
+            'key' => [
+                'subkey' => $value
+            ],
+        ];
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\DocblockReturnArrayFromDirectArrayInstanceRector\Fixture;
+
+final class SingleNestedLevel
+{
+    /**
+     * @return array<string, array<string, mixed>>
+     */
+    public function getNames($value): array
+    {
+        return [
+            'key' => [
+                'subkey' => $value
+            ],
+        ];
+    }
+}
+
+?>
diff --git a/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php b/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php
index a9b42199b82..937599308d6 100644
--- a/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php
+++ b/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php
@@ -113,10 +113,7 @@ public function refactor(Node $node): ?Node
             return null;
         }
 
-        $genericKeyType = $this->constantToGenericType($returnedType->getKeyType());
-        $genericItemType = $this->constantToGenericType($returnedType->getItemType());
-
-        $genericTypeNode = $this->createArrayGenericTypeNode($genericKeyType, $genericItemType);
+        $genericTypeNode = $this->createGenericArrayTypeFromConstantArrayType($returnedType);
 
         $returnTagValueNode = new ReturnTagValueNode($genericTypeNode, '');
         $phpDocInfo->addTagValueNode($returnTagValueNode);
@@ -151,10 +148,29 @@ private function constantToGenericType(Type $type): Type
         return new MixedType();
     }
 
-    private function createArrayGenericTypeNode(Type $keyType, Type $itemType): GenericTypeNode
+    private function createGenericArrayTypeFromConstantArrayType(ConstantArrayType $constantArrayType): GenericTypeNode
+    {
+        $genericKeyType = $this->constantToGenericType($constantArrayType->getKeyType());
+
+        $itemType = $constantArrayType->getItemType();
+        if ($itemType instanceof ConstantArrayType) {
+            $genericItemType = $this->createGenericArrayTypeFromConstantArrayType($itemType);
+        } else {
+            $genericItemType = $this->constantToGenericType($itemType);
+        }
+
+        return $this->createArrayGenericTypeNode($genericKeyType, $genericItemType);
+    }
+
+    private function createArrayGenericTypeNode(Type $keyType, Type|GenericTypeNode $itemType): GenericTypeNode
     {
         $keyDocTypeNode = $this->staticTypeMapper->mapPHPStanTypeToPHPStanPhpDocTypeNode($keyType);
-        $itemDocTypeNode = $this->staticTypeMapper->mapPHPStanTypeToPHPStanPhpDocTypeNode($itemType);
+
+        if ($itemType instanceof Type) {
+            $itemDocTypeNode = $this->staticTypeMapper->mapPHPStanTypeToPHPStanPhpDocTypeNode($itemType);
+        } else {
+            $itemDocTypeNode = $itemType;
+        }
 
         return new GenericTypeNode(new IdentifierTypeNode('array'), [$keyDocTypeNode, $itemDocTypeNode]);
     }