From ecfc7413ef4e97715e0997af647d6daa23b92b67 Mon Sep 17 00:00:00 2001
From: Louis-Arnaud <la.catoire@gmail.com>
Date: Sun, 12 Jul 2026 12:21:07 +0200
Subject: [PATCH] Document the new Dom\ParentNode $children property (PHP 8.5)

Add the read-only $children property (Dom\HTMLCollection) to Dom\ParentNode
and its implementations Dom\Element, Dom\Document and Dom\DocumentFragment.
The property is defined once on Dom\ParentNode and referenced through a local
anchor in each implementing class, matching the other ParentNode properties.
---
 reference/dom/dom/dom-document.xml         | 11 +++++++++++
 reference/dom/dom/dom-documentfragment.xml | 11 +++++++++++
 reference/dom/dom/dom-element.xml          | 11 +++++++++++
 reference/dom/dom/dom-parentnode.xml       | 23 ++++++++++++++++++++++
 4 files changed, 56 insertions(+)

diff --git a/reference/dom/dom/dom-document.xml b/reference/dom/dom/dom-document.xml
index 0c472d5de5e4..1f1f7b1e1015 100644
--- a/reference/dom/dom/dom-document.xml
+++ b/reference/dom/dom/dom-document.xml
@@ -104,6 +104,12 @@
      <type>int</type>
      <varname linkend="dom-document.props.childelementcount">childElementCount</varname>
     </fieldsynopsis>
+    <fieldsynopsis>
+     <modifier>public</modifier>
+     <modifier>readonly</modifier>
+     <type>Dom\HTMLCollection</type>
+     <varname linkend="dom-document.props.children">children</varname>
+    </fieldsynopsis>
     <fieldsynopsis>
      <modifier>public</modifier>
      <type class="union"><type>Dom\HTMLElement</type><type>null</type></type>
@@ -210,6 +216,11 @@
       <xi:fallback/>
      </xi:include>
     </varlistentry>
+    <varlistentry xml:id="dom-document.props.children">
+     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('dom-parentnode.props.children')/*)">
+      <xi:fallback/>
+     </xi:include>
+    </varlistentry>
     <varlistentry xml:id="dom-document.props.body">
      <term><varname>body</varname></term>
      <listitem>
diff --git a/reference/dom/dom/dom-documentfragment.xml b/reference/dom/dom/dom-documentfragment.xml
index 1c5b8390a8e6..6b3b5c1dc2d5 100644
--- a/reference/dom/dom/dom-documentfragment.xml
+++ b/reference/dom/dom/dom-documentfragment.xml
@@ -60,6 +60,12 @@
      <type>int</type>
      <varname linkend="dom-documentfragment.props.childelementcount">childElementCount</varname>
     </fieldsynopsis>
+    <fieldsynopsis>
+     <modifier>public</modifier>
+     <modifier>readonly</modifier>
+     <type>Dom\HTMLCollection</type>
+     <varname linkend="dom-documentfragment.props.children">children</varname>
+    </fieldsynopsis>
 
     <classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dom-node')/db:partintro/db:section/db:classsynopsis/db:fieldsynopsis[preceding-sibling::db:classsynopsisinfo[1][@role='comment' and text()='&Properties;']]))">
@@ -98,6 +104,11 @@
       <xi:fallback/>
      </xi:include>
     </varlistentry>
+    <varlistentry xml:id="dom-documentfragment.props.children">
+     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('dom-parentnode.props.children')/*)">
+      <xi:fallback/>
+     </xi:include>
+    </varlistentry>
    </variablelist>
   </section>
 
diff --git a/reference/dom/dom/dom-element.xml b/reference/dom/dom/dom-element.xml
index 3df5455fb903..d3cd6aa54ac3 100644
--- a/reference/dom/dom/dom-element.xml
+++ b/reference/dom/dom/dom-element.xml
@@ -121,6 +121,12 @@
      <type class="union"><type>Dom\Element</type><type>null</type></type>
      <varname linkend="dom-element.props.nextelementsibling">nextElementSibling</varname>
     </fieldsynopsis>
+    <fieldsynopsis>
+     <modifier>public</modifier>
+     <modifier>readonly</modifier>
+     <type>Dom\HTMLCollection</type>
+     <varname linkend="dom-element.props.children">children</varname>
+    </fieldsynopsis>
     <fieldsynopsis>
      <modifier>public</modifier>
      <type>string</type>
@@ -231,6 +237,11 @@
       <xi:fallback/>
      </xi:include>
     </varlistentry>
+    <varlistentry xml:id="dom-element.props.children">
+     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('dom-parentnode.props.children')/*)">
+      <xi:fallback/>
+     </xi:include>
+    </varlistentry>
     <varlistentry xml:id="dom-element.props.innerhtml">
      <term><varname>innerHTML</varname></term>
      <listitem>
diff --git a/reference/dom/dom/dom-parentnode.xml b/reference/dom/dom/dom-parentnode.xml
index 2fb3a0dbe350..a5c48b75f04f 100644
--- a/reference/dom/dom/dom-parentnode.xml
+++ b/reference/dom/dom/dom-parentnode.xml
@@ -21,6 +21,14 @@
      <interfacename>Dom\ParentNode</interfacename>
     </oointerface>
 
+    <classsynopsisinfo role="comment">&Properties;</classsynopsisinfo>
+    <fieldsynopsis>
+     <modifier>public</modifier>
+     <modifier>readonly</modifier>
+     <type>Dom\HTMLCollection</type>
+     <varname linkend="dom-parentnode.props.children">children</varname>
+    </fieldsynopsis>
+
     <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dom-parentnode')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Dom\\ParentNode'])">
      <xi:fallback/>
@@ -29,6 +37,21 @@
 
   </section>
 
+  <section xml:id="dom-parentnode.props">
+   &reftitle.properties;
+   <variablelist>
+    <varlistentry xml:id="dom-parentnode.props.children">
+     <term><varname>children</varname></term>
+     <listitem>
+      <simpara>
+       A <classname>Dom\HTMLCollection</classname> containing all child
+       elements of this node. Available as of PHP 8.5.0.
+      </simpara>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </section>
+
  </partintro>
 
  &reference.dom.dom.entities.parentnode;