From ecdee057de42b0fa7a3b6766432353424de9e1a9 Mon Sep 17 00:00:00 2001
From: Vincent Langlet <vincentlanglet@hotmail.fr>
Date: Sun, 21 Sep 2025 21:35:15 +0200
Subject: [PATCH] Dynamic DOM return type

---
 stubs/dom.stub                           | 21 +++++++++++++++++++++
 tests/PHPStan/Analyser/nsrt/bug-9200.php | 16 ++++++++++++++++
 2 files changed, 37 insertions(+)
 create mode 100644 tests/PHPStan/Analyser/nsrt/bug-9200.php

diff --git a/stubs/dom.stub b/stubs/dom.stub
index 5f32a4763c..ffc8aff417 100644
--- a/stubs/dom.stub
+++ b/stubs/dom.stub
@@ -41,6 +41,27 @@ class DOMNode
 	 */
 	public function hasAttributes() {}
 
+	/**
+	 * @template TNode of DOMNode
+	 * @param TNode $node
+	 * @return __benevolent<TNode|false>
+	 */
+	public function insertBefore(DOMNode $node, ?DOMNode $child = null) {}
+
+	/**
+	 * @template TNode of DOMNode
+	 * @param TNode $node
+	 * @return __benevolent<TNode|false>
+	 */
+	public function removeChild(DOMNode $node) {}
+
+	/**
+	 * @template TNode of DOMNode
+	 * @param TNode $node
+	 * @return __benevolent<TNode|false>
+	 */
+	public function appendChild(DOMNode $node) {}
+
 }
 
 class DOMElement extends DOMNode
diff --git a/tests/PHPStan/Analyser/nsrt/bug-9200.php b/tests/PHPStan/Analyser/nsrt/bug-9200.php
new file mode 100644
index 0000000000..9ad50e5b83
--- /dev/null
+++ b/tests/PHPStan/Analyser/nsrt/bug-9200.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace Bug9200;
+
+use function PHPStan\Testing\assertType;
+
+function test(\DOMElement $element, \DOMNode $node): void
+{
+	assertType('(DOMElement|false)', $node->appendChild($element));
+	assertType('(DOMNode|false)', $element->appendChild($node));
+	assertType('(DOMElement|false)', $node->removeChild($element));
+	assertType('(DOMNode|false)', $element->removeChild($node));
+	assertType('(DOMElement|false)', $node->insertBefore($element, $node));
+	assertType('(DOMNode|false)', $node->insertBefore($node, $element));
+	assertType('(DOMNode|false)', $element->insertBefore($node, $node));
+}