From 3b409218c829f58ab8062102d947039fe906ca66 Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Mon, 18 May 2026 08:08:39 +0200
Subject: [PATCH] [TypeDeclarationDocblocks] Skip overridden methods in
 DocblockReturnArrayFromDirectArrayInstanceRector

Skip @return docblock generation when the ClassMethod overrides a
parent/interface method, to avoid conflicting with the existing
parent docblock contract.

Fixes rectorphp/rector#9599
---
 .../Fixture/skip_overridden_method.php.inc    | 38 +++++++++++++++++++
 ...turnArrayFromDirectArrayInstanceRector.php |  9 ++++-
 2 files changed, 46 insertions(+), 1 deletion(-)
 create mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/skip_overridden_method.php.inc

diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/skip_overridden_method.php.inc b/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/skip_overridden_method.php.inc
new file mode 100644
index 00000000000..c31fd206401
--- /dev/null
+++ b/rules-tests/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector/Fixture/skip_overridden_method.php.inc
@@ -0,0 +1,38 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\ClassMethod\DocblockReturnArrayFromDirectArrayInstanceRector\Fixture;
+
+interface SomeOverriddenInterface
+{
+    /**
+     * @return int[]
+     */
+    public function getCodes(): iterable;
+}
+
+abstract class SomeOverriddenBase
+{
+    /**
+     * @return string[]
+     */
+    abstract public function getMethods(): iterable;
+}
+
+final class SomeOverriddenChild extends SomeOverriddenBase implements SomeOverriddenInterface
+{
+    public function getCodes(): iterable
+    {
+        return [
+            200,
+            201,
+        ];
+    }
+
+    public function getMethods(): iterable
+    {
+        return [
+            'GET',
+            'POST',
+        ];
+    }
+}
diff --git a/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php b/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php
index 978acccb496..14d48b3151f 100644
--- a/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php
+++ b/rules/TypeDeclarationDocblocks/Rector/ClassMethod/DocblockReturnArrayFromDirectArrayInstanceRector.php
@@ -19,6 +19,7 @@
 use Rector\TypeDeclarationDocblocks\NodeFinder\ReturnNodeFinder;
 use Rector\TypeDeclarationDocblocks\TagNodeAnalyzer\UsefulArrayTagNodeAnalyzer;
 use Rector\TypeDeclarationDocblocks\TypeResolver\ConstantArrayTypeGeneralizer;
+use Rector\VendorLocker\ParentClassMethodTypeOverrideGuard;
 use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
 use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
 
@@ -32,7 +33,8 @@ public function __construct(
         private readonly PhpDocTypeChanger $phpDocTypeChanger,
         private readonly ConstantArrayTypeGeneralizer $constantArrayTypeGeneralizer,
         private readonly ReturnNodeFinder $returnNodeFinder,
-        private readonly UsefulArrayTagNodeAnalyzer $usefulArrayTagNodeAnalyzer
+        private readonly UsefulArrayTagNodeAnalyzer $usefulArrayTagNodeAnalyzer,
+        private readonly ParentClassMethodTypeOverrideGuard $parentClassMethodTypeOverrideGuard
     ) {
     }
 
@@ -88,6 +90,11 @@ public function refactor(Node $node): ?Node
             return null;
         }
 
+        // skip overridden methods to not conflict with parent/interface @return docblock
+        if ($node instanceof ClassMethod && $this->parentClassMethodTypeOverrideGuard->hasParentClassMethod($node)) {
+            return null;
+        }
+
         $phpDocInfo = $this->phpDocInfoFactory->createFromNodeOrEmpty($node);
 
         if ($this->usefulArrayTagNodeAnalyzer->isUsefulArrayTag($phpDocInfo->getReturnTagValue())) {