[DeadCode] Skip static/$this union @return in RemoveUselessUnionReturnDocblockRector

rules-tests/DeadCode/Rector/ClassMethod/RemoveUselessUnionReturnDocblockRector/Fixture/skip_static_function.php.inc

@@ -0,0 +1,11 @@
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\ClassMethod\RemoveUselessUnionReturnDocblockRector\Fixture;
+
+/**
+ * @return static|null
+ */
+function skipStaticFunction(): ?SomeStaticInterface
+{
+    return null;
+}

rules-tests/DeadCode/Rector/ClassMethod/RemoveUselessUnionReturnDocblockRector/Fixture/skip_static_union.php.inc

@@ -0,0 +1,28 @@
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\ClassMethod\RemoveUselessUnionReturnDocblockRector\Fixture;
+
+interface SomeStaticInterface
+{
+}
+
+trait SkipStaticUnionTrait
+{
+    private $parent;
+
+    /**
+     * @return static|null
+     */
+    public function getParent(): ?SomeStaticInterface
+    {
+        return $this->parent;
+    }
+
+    /**
+     * @return $this|null
+     */
+    public function getThisParent(): ?SomeStaticInterface
+    {
+        return $this->parent;
+    }
+}

rules/DeadCode/Rector/ClassMethod/RemoveUselessUnionReturnDocblockRector.php

@@ -8,6 +8,8 @@
 use PhpParser\Node\Stmt\ClassMethod;
 use PhpParser\Node\Stmt\Function_;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
+use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
+use PHPStan\PhpDocParser\Ast\Type\ThisTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\UnionTypeNode;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfo;
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
@@ -104,6 +106,11 @@ public function refactor(Node $node): ?Node
             return null;
         }
 
+        // keep static/$this, they denote the runtime subclass the native type cannot express
+        if ($this->hasStaticOrThisType($returnTagValueNode->type)) {
+            return null;
+        }
+
         $nativeReturnType = $this->staticTypeMapper->mapPhpParserNodePHPStanType($node->returnType);
 
         // keep array-involving native type (array, ?array, union with array), the docblock may carry element types
@@ -131,4 +138,19 @@ public function provideMinPhpVersion(): int
     {
         return PhpVersionFeature::UNION_TYPES;
     }
+
+    private function hasStaticOrThisType(UnionTypeNode $unionTypeNode): bool
+    {
+        foreach ($unionTypeNode->types as $typeNode) {
+            if ($typeNode instanceof ThisTypeNode) {
+                return true;
+            }
+
+            if ($typeNode instanceof IdentifierTypeNode && $typeNode->name === 'static') {
+                return true;
+            }
+        }
+
+        return false;
+    }
 }