From f5e98464dcd29dcc64fb13445b5cc3ed3d199365 Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Thu, 20 Aug 2026 17:24:25 +0100
Subject: [PATCH] [TypeDeclarationDocblocks] Skip
 ClassMethodArrayDocblockParamFromLocalCallsRector on methods overriding
 parent/interface (#9835)

---
 .../Fixture/skip_interface_wider_param.php.inc | 18 ++++++++++++++++++
 .../Source/SomeSearchInterface.php             | 11 +++++++++++
 ...dArrayDocblockParamFromLocalCallsRector.php |  9 ++++++++-
 3 files changed, 37 insertions(+), 1 deletion(-)
 create mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/Class_/ClassMethodArrayDocblockParamFromLocalCallsRector/Fixture/skip_interface_wider_param.php.inc
 create mode 100644 rules-tests/TypeDeclarationDocblocks/Rector/Class_/ClassMethodArrayDocblockParamFromLocalCallsRector/Source/SomeSearchInterface.php

diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/Class_/ClassMethodArrayDocblockParamFromLocalCallsRector/Fixture/skip_interface_wider_param.php.inc b/rules-tests/TypeDeclarationDocblocks/Rector/Class_/ClassMethodArrayDocblockParamFromLocalCallsRector/Fixture/skip_interface_wider_param.php.inc
new file mode 100644
index 00000000000..27fb67d6a78
--- /dev/null
+++ b/rules-tests/TypeDeclarationDocblocks/Rector/Class_/ClassMethodArrayDocblockParamFromLocalCallsRector/Fixture/skip_interface_wider_param.php.inc
@@ -0,0 +1,18 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Class_\ClassMethodArrayDocblockParamFromLocalCallsRector\Fixture;
+
+use Rector\Tests\TypeDeclarationDocblocks\Rector\Class_\ClassMethodArrayDocblockParamFromLocalCallsRector\Source\SomeSearchInterface;
+
+final class SkipInterfaceWiderParam implements SomeSearchInterface
+{
+    public function findOneMatching(array $criteria): ?object
+    {
+        return null;
+    }
+
+    public function go(string $id): ?object
+    {
+        return $this->findOneMatching(['id' => $id]);
+    }
+}
diff --git a/rules-tests/TypeDeclarationDocblocks/Rector/Class_/ClassMethodArrayDocblockParamFromLocalCallsRector/Source/SomeSearchInterface.php b/rules-tests/TypeDeclarationDocblocks/Rector/Class_/ClassMethodArrayDocblockParamFromLocalCallsRector/Source/SomeSearchInterface.php
new file mode 100644
index 00000000000..4a4802c65ca
--- /dev/null
+++ b/rules-tests/TypeDeclarationDocblocks/Rector/Class_/ClassMethodArrayDocblockParamFromLocalCallsRector/Source/SomeSearchInterface.php
@@ -0,0 +1,11 @@
+<?php
+
+namespace Rector\Tests\TypeDeclarationDocblocks\Rector\Class_\ClassMethodArrayDocblockParamFromLocalCallsRector\Source;
+
+interface SomeSearchInterface
+{
+    /**
+     * @param array{alias?: string, id?: string} $criteria
+     */
+    public function findOneMatching(array $criteria): ?object;
+}
diff --git a/rules/TypeDeclarationDocblocks/Rector/Class_/ClassMethodArrayDocblockParamFromLocalCallsRector.php b/rules/TypeDeclarationDocblocks/Rector/Class_/ClassMethodArrayDocblockParamFromLocalCallsRector.php
index 5757210532b..3c3dd427ae7 100644
--- a/rules/TypeDeclarationDocblocks/Rector/Class_/ClassMethodArrayDocblockParamFromLocalCallsRector.php
+++ b/rules/TypeDeclarationDocblocks/Rector/Class_/ClassMethodArrayDocblockParamFromLocalCallsRector.php
@@ -11,6 +11,7 @@
 use PHPStan\Type\Type;
 use PHPStan\Type\TypeCombinator;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
+use Rector\NodeManipulator\ClassMethodManipulator;
 use Rector\PhpParser\NodeFinder\LocalMethodCallFinder;
 use Rector\Rector\AbstractRector;
 use Rector\TypeDeclaration\NodeAnalyzer\CallTypesResolver;
@@ -29,7 +30,8 @@ public function __construct(
         private readonly CallTypesResolver $callTypesResolver,
         private readonly LocalMethodCallFinder $localMethodCallFinder,
         private readonly UsefulArrayTagNodeAnalyzer $usefulArrayTagNodeAnalyzer,
-        private readonly NodeDocblockTypeDecorator $nodeDocblockTypeDecorator
+        private readonly NodeDocblockTypeDecorator $nodeDocblockTypeDecorator,
+        private readonly ClassMethodManipulator $classMethodManipulator
     ) {
     }
 
@@ -89,6 +91,11 @@ public function refactor(Node $node): ?Node
                 continue;
             }
 
+            // parent/interface method may declare a wider @param contract; local calls are narrower, so skip to keep LSP
+            if ($this->classMethodManipulator->hasParentMethodOrInterfaceMethod($node, $this->getName($classMethod))) {
+                continue;
+            }
+
             $classMethodPhpDocInfo = $this->phpDocInfoFactory->createFromNodeOrEmpty($classMethod);
 
             $methodCalls = $this->localMethodCallFinder->match($node, $classMethod);