[doc-en] master: Document Dom\Element::getElementsByClassName(), Dom\Element::insertAdjacentHTML() and the Date __wakeup() deprecation (#6034)

Author: Louis-Arnaud (lacatoire) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-11-05T08:56:41+01:00 Commit: https://github.com/php/doc-en/commit/aef95033d4ca8869ae7e5dcc557a0531604a2769 Raw diff: https://github.com/php/doc-en/commit/aef95033d4ca8869ae7e5dcc557a0531604a2769.diff Document Dom\Element::getElementsByClassName(), Dom\Element::insertAdjacentHTML() and the Date __wakeup() deprecation (#6034) Changed paths: A reference/dom/dom/element/getelementsbyclassname.xml A reference/dom/dom/element/insertadjacenthtml.xml M reference/datetime/versions.xml M reference/dom/dom/dom-adjacentposition.xml M reference/dom/dom/dom-element.xml M reference/dom/dom/parentnode/queryselectorall.xml Diff: diff --git a/reference/datetime/versions.xml b/reference/datetime/versions.xml index a5c4eb28ab41..b07a6815762c 100644 --- a/reference/datetime/versions.xml +++ b/reference/datetime/versions.xml @@ -70,7 +70,7 @@ <function name="datetimezone" from="PHP 5 &gt;= 5.2.0, PHP 7, PHP 8"/> <function name="datetimezone::__construct" from="PHP 5 &gt;= 5.2.0, PHP 7, PHP 8"/> - <function name="datetimezone::__wakeup" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8"/> + <function name="datetimezone::__wakeup" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8" deprecated="PHP 8.5.0"/> <function name="datetimezone::__set_state" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8"/> <function name="datetimezone::getlocation" from="PHP 5 &gt;= 5.3.0, PHP 7, PHP 8"/> <function name="datetimezone::getname" from="PHP 5 &gt;= 5.2.0, PHP 7, PHP 8"/> @@ -86,7 +86,7 @@ <function name="dateperiod" from="PHP 5 &gt;= 5.3.0, PHP 7, PHP 8"/> <function name="dateperiod::__construct" from="PHP 5 &gt;= 5.3.0, PHP 7, PHP 8"/> - <function name="dateperiod::__wakeup" from="PHP 5 &gt;= 5.3.27, PHP 7, PHP 8"/> + <function name="dateperiod::__wakeup" from="PHP 5 &gt;= 5.3.27, PHP 7, PHP 8" deprecated="PHP 8.5.0"/> <function name="dateperiod::__set_state" from="PHP 5 &gt;= 5.3.27, PHP 7, PHP 8"/> <function name="dateperiod::createfromiso8601string" from="PHP 8 &gt;= 8.3.0"/> <function name="dateperiod::getstartdate" from="PHP 5 &gt;= 5.6.5, PHP 7, PHP 8"/> diff --git a/reference/dom/dom/dom-adjacentposition.xml b/reference/dom/dom/dom-adjacentposition.xml index a59237b8bb2e..44e5341cfdee 100644 --- a/reference/dom/dom/dom-adjacentposition.xml +++ b/reference/dom/dom/dom-adjacentposition.xml @@ -9,8 +9,9 @@ <simpara> The <enumname>AdjacentPosition</enumname> enum is used to specify where, relative to the context element, insertion should be performed - using <methodname>Dom\Element::insertAdjacentElement</methodname> - or <methodname>Dom\Element::insertAdjacentText</methodname>. + using <methodname>Dom\Element::insertAdjacentElement</methodname>, + <methodname>Dom\Element::insertAdjacentText</methodname> + or <methodname>Dom\Element::insertAdjacentHTML</methodname>. </simpara> </section> diff --git a/reference/dom/dom/dom-element.xml b/reference/dom/dom/dom-element.xml index 8038cf02d277..255a78c75a57 100644 --- a/reference/dom/dom/dom-element.xml +++ b/reference/dom/dom/dom-element.xml @@ -145,8 +145,7 @@ <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;']]))"/> <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo> - <classsynopsisinfo role="comment">Not documented yet</classsynopsisinfo> - <!--<xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dom-element')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Dom\\Element'])"/>--> + <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dom-element')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Dom\\Element'])"/> <classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo> <classsynopsisinfo role="comment">Not documented yet</classsynopsisinfo> @@ -277,6 +276,6 @@ </partintro> -<!-- &reference.dom.dom.entities.element; --> +&reference.dom.dom.entities.element; </reference> diff --git a/reference/dom/dom/element/getelementsbyclassname.xml b/reference/dom/dom/element/getelementsbyclassname.xml new file mode 100644 index 000000000000..754d19cbe06d --- /dev/null +++ b/reference/dom/dom/element/getelementsbyclassname.xml @@ -0,0 +1,125 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="dom-element.getelementsbyclassname" xmlns="http://docbook.org/ns/docbook"> + <refnamediv> + <refname>Dom\Element::getElementsByClassName</refname> + <refpurpose>Returns a collection of descendant elements that have the given classes</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Dom\\Element"> + <modifier>public</modifier> <type>Dom\HTMLCollection</type><methodname>Dom\Element::getElementsByClassName</methodname> + <methodparam><type>string</type><parameter>classNames</parameter></methodparam> + </methodsynopsis> + <simpara> + Returns a <classname>Dom\HTMLCollection</classname> of the descendants of + this element, in document order, whose <literal>class</literal> attribute + contains all the classes given in <parameter>classNames</parameter>. + The element itself is never part of the collection. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>classNames</parameter></term> + <listitem> + <simpara> + One or more class names separated by ASCII whitespace. + An element only matches if it has every one of these classes, + in any order. + </simpara> + <simpara> + Class names are compared case-sensitively, unless the document is in + quirks mode, in which case the comparison is ASCII case-insensitive. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + Returns a <classname>Dom\HTMLCollection</classname> of the matching + elements. The collection is empty if no element matches, or if + <parameter>classNames</parameter> contains no class name, for example when + it is an empty string or only whitespace. + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>ValueError</exceptionname> if + <parameter>classNames</parameter> contains a null byte. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="dom-element.getelementsbyclassname.example.basic"> + <title><methodname>Dom\Element::getElementsByClassName</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$dom = Dom\HTMLDocument::createFromString( + '<!DOCTYPE html><body><div id="list">' + . '<p class="item new">One</p>' + . '<p class="item">Two</p>' + . '<p class="Item">Three</p>' + . '</div></body>', + LIBXML_NOERROR +); + +$list = $dom->getElementById('list'); + +foreach ($list->getElementsByClassName('new item') as $element) { + echo $element->textContent, "\n"; +} + +echo $list->getElementsByClassName('item')->length, "\n"; +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +One +2 +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><methodname>Dom\ParentNode::querySelectorAll</methodname></member> + <member><link linkend="dom-element.props.classlist">Dom\Element::$classList</link></member> + <member><classname>Dom\TokenList</classname></member> + </simplelist> + </refsect1> + +</refentry> +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/dom/dom/element/insertadjacenthtml.xml b/reference/dom/dom/element/insertadjacenthtml.xml new file mode 100644 index 000000000000..5d583e10b7c5 --- /dev/null +++ b/reference/dom/dom/element/insertadjacenthtml.xml @@ -0,0 +1,137 @@ +<?xml version="1.0" encoding="utf-8"?> +<refentry xml:id="dom-element.insertadjacenthtml" xmlns="http://docbook.org/ns/docbook"> + <refnamediv> + <refname>Dom\Element::insertAdjacentHTML</refname> + <refpurpose>Parses a string as HTML or XML and inserts the result at a given position</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis role="Dom\\Element"> + <modifier>public</modifier> <type>void</type><methodname>Dom\Element::insertAdjacentHTML</methodname> + <methodparam><type>Dom\AdjacentPosition</type><parameter>where</parameter></methodparam> + <methodparam><type>string</type><parameter>string</parameter></methodparam> + </methodsynopsis> + <simpara> + Parses <parameter>string</parameter> as a fragment and inserts the resulting + nodes at the position given by <parameter>where</parameter>, relative to + this element. The fragment is parsed as HTML in an HTML document, + and as XML in an XML document. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + <varlistentry> + <term><parameter>where</parameter></term> + <listitem> + <simpara> + A <enumname>Dom\AdjacentPosition</enumname> case that specifies where + the nodes are inserted relative to this element. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem> + <simpara> + The HTML or XML markup to parse. In an XML document it must be a + well-formed XML fragment. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + &return.void; + </simpara> + </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <simpara> + Throws a <exceptionname>DOMException</exceptionname> with code + <constant>Dom\NO_MODIFICATION_ALLOWED_ERR</constant> if + <parameter>where</parameter> is + <literal>Dom\AdjacentPosition::BeforeBegin</literal> or + <literal>Dom\AdjacentPosition::AfterEnd</literal> + and this element has no parent, or its parent is the document. + </simpara> + <simpara> + Throws a <exceptionname>DOMException</exceptionname> with code + <constant>Dom\SYNTAX_ERR</constant> if this element is in an XML document + and <parameter>string</parameter> is not a well-formed XML fragment. + </simpara> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="dom-element.insertadjacenthtml.example.basic"> + <title><methodname>Dom\Element::insertAdjacentHTML</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + +$dom = Dom\HTMLDocument::createFromString( + '<!DOCTYPE html><body><ul id="list"><li>Two</li></ul></body>', + LIBXML_NOERROR +); + +$list = $dom->getElementById('list'); + +$list->firstElementChild->insertAdjacentHTML( + Dom\AdjacentPosition::BeforeBegin, + '<li>One</li>' +); +$list->insertAdjacentHTML( + Dom\AdjacentPosition::BeforeEnd, + '<li>Three</li><li><b>Four</b></li>' +); + +echo $list->outerHTML, "\n"; +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +<ul id="list"><li>One</li><li>Two</li><li>Three</li><li><b>Four</b></li></ul> +]]> + </screen> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><classname>Dom\AdjacentPosition</classname></member> + <member><methodname>Dom\ParentNode::append</methodname></member> + <member><link linkend="dom-element.props.innerhtml">Dom\Element::$innerHTML</link></member> + <member><link linkend="dom-element.props.outerhtml">Dom\Element::$outerHTML</link></member> + </simplelist> + </refsect1> + +</refentry> +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +indent-tabs-mode:nil +sgml-parent-document:nil +sgml-default-dtd-file:"~/.phpdoc/manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vim600: syn=xml fen fdm=syntax fdl=2 si +vim: et tw=78 syn=sgml +vi: ts=1 sw=1 +--> diff --git a/reference/dom/dom/parentnode/queryselectorall.xml b/reference/dom/dom/parentnode/queryselectorall.xml index 1c2377eb8978..9524c0f1f02a 100644 --- a/reference/dom/dom/parentnode/queryselectorall.xml +++ b/reference/dom/dom/parentnode/queryselectorall.xml @@ -33,6 +33,7 @@ &reftitle.seealso; <simplelist> <member><methodname>Dom\ParentNode::querySelector</methodname></member> + <member><methodname>Dom\Element::getElementsByClassName</methodname></member> </simplelist> </refsect1>