[doc-en] master: Add examples to Dom\ParentNode and Dom\HTMLDocument methods (#6042)

Author: Tim Bond (cookieguru) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-11-09T10:10:57+01:00 Commit: https://github.com/php/doc-en/commit/1e4b8a2d480789857d79ab3ffce0d3d8f14cbd06 Raw diff: https://github.com/php/doc-en/commit/1e4b8a2d480789857d79ab3ffce0d3d8f14cbd06.diff Add examples to Dom\ParentNode and Dom\HTMLDocument methods (#6042) * Add examples to Dom\ParentNode methods Add examples for: * Dom\ParentNode::append * Dom\ParentNode::prepend * Dom\ParentNode::querySelector * Dom\ParentNode::querySelectorAll * Add examples to Dom\HTMLDocument methods Add examples for * Dom\HTMLDocument::createFromFile * Dom\HTMLDocument::saveHtml * Dom\HTMLDocument::saveHtmlFile * Dom\HTMLDocument::saveXml * Dom\HTMLDocument::saveXmlFile Changed paths: M reference/dom/dom/htmldocument/createfromfile.xml M reference/dom/dom/htmldocument/savehtml.xml M reference/dom/dom/htmldocument/savehtmlfile.xml M reference/dom/dom/htmldocument/savexml.xml M reference/dom/dom/htmldocument/savexmlfile.xml M reference/dom/dom/parentnode/append.xml M reference/dom/dom/parentnode/prepend.xml M reference/dom/dom/parentnode/queryselector.xml M reference/dom/dom/parentnode/queryselectorall.xml Diff: diff --git a/reference/dom/dom/htmldocument/createfromfile.xml b/reference/dom/dom/htmldocument/createfromfile.xml index a9823ef9b034..63da8cbaa7ea 100644 --- a/reference/dom/dom/htmldocument/createfromfile.xml +++ b/reference/dom/dom/htmldocument/createfromfile.xml @@ -72,7 +72,25 @@ </itemizedlist> </refsect1> - &dom.parser.compliant.note.whitespace; + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="dom-htmldocument.createfromfile.example.basic"> + <title><methodname>Dom\HTMLDocument::createFromFile</methodname> example</title> + <simpara> + Parses a document from a file. + </simpara> + <programlisting role="php" annotations="non-interactive"> +<![CDATA[ +<?php +$dom = Dom\HTMLDocument::createFromFile('/path/to/file.html'); +echo $dom->saveHtml(); +?> +]]> + </programlisting> + </example> + </refsect1> + +&dom.parser.compliant.note.whitespace; <refsect1 role="seealso"> &reftitle.seealso; diff --git a/reference/dom/dom/htmldocument/savehtml.xml b/reference/dom/dom/htmldocument/savehtml.xml index d5fa667b3078..44ad81e648d7 100644 --- a/reference/dom/dom/htmldocument/savehtml.xml +++ b/reference/dom/dom/htmldocument/savehtml.xml @@ -46,6 +46,30 @@ </itemizedlist> </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="dom-htmldocument.savehtml.example.basic"> + <title><methodname>Dom\HTMLDocument::saveHtml</methodname> example</title> + <simpara> + Serializes a document to an <acronym>HTML</acronym> string. + </simpara> + <programlisting role="php"> +<![CDATA[ +<?php +$dom = Dom\HTMLDocument::createFromString('<!DOCTYPE html><p>Hello, world!</p>'); +echo $dom->saveHtml(); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +<!DOCTYPE html><html><head></head><body><p>Hello, world!</p></body></html> +]]> + </screen> + </example> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <simplelist> diff --git a/reference/dom/dom/htmldocument/savehtmlfile.xml b/reference/dom/dom/htmldocument/savehtmlfile.xml index 1e452801e3cc..689d0b94b7f6 100644 --- a/reference/dom/dom/htmldocument/savehtmlfile.xml +++ b/reference/dom/dom/htmldocument/savehtmlfile.xml @@ -50,6 +50,33 @@ </itemizedlist> </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="dom-htmldocument.savehtmlfile.example.basic"> + <title><methodname>Dom\HTMLDocument::saveHtmlFile</methodname> example</title> + <simpara> + Serializes a document to an <acronym>HTML</acronym> file. + </simpara> + <programlisting role="php"> +<![CDATA[ +<?php +$dom = Dom\HTMLDocument::createFromString('<!DOCTYPE html><p>Hello, world!</p>'); +$bytes = $dom->saveHtmlFile('/path/to/output.html'); +echo "Saved $bytes bytes\n"; +var_dump($bytes); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +Saved 74 bytes +int(74) +]]> + </screen> + </example> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <simplelist> diff --git a/reference/dom/dom/htmldocument/savexml.xml b/reference/dom/dom/htmldocument/savexml.xml index 9cb09fcc61a3..a23bd156e576 100644 --- a/reference/dom/dom/htmldocument/savexml.xml +++ b/reference/dom/dom/htmldocument/savexml.xml @@ -53,6 +53,32 @@ </itemizedlist> </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="dom-htmldocument.savexml.example.basic"> + <title><methodname>Dom\HTMLDocument::saveXml</methodname> example</title> + <simpara> + Serializes a document to an <acronym>XML</acronym> string. + </simpara> + <programlisting role="php"> +<![CDATA[ +<?php +$dom = Dom\HTMLDocument::createFromString('<!DOCTYPE html><p>Hello, world!</p>'); +echo $dom->saveXml(); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +<?xml version="1.0" encoding="UTF-8" standalone="yes"?> +<!DOCTYPE html> +<html xmlns="http://www.w3.org/1999/xhtml"><head></head><body><p>Hello, world!</p></body></html> +]]> + </screen> + </example> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <simplelist> diff --git a/reference/dom/dom/htmldocument/savexmlfile.xml b/reference/dom/dom/htmldocument/savexmlfile.xml index 391629f4c9f5..cad38519e900 100644 --- a/reference/dom/dom/htmldocument/savexmlfile.xml +++ b/reference/dom/dom/htmldocument/savexmlfile.xml @@ -57,6 +57,33 @@ </itemizedlist> </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="dom-htmldocument.savexmlfile.example.basic"> + <title><methodname>Dom\HTMLDocument::saveXmlFile</methodname> example</title> + <simpara> + Serializes a document to an <acronym>XML</acronym> file. + </simpara> + <programlisting role="php"> +<![CDATA[ +<?php +$dom = Dom\HTMLDocument::createFromString('<!DOCTYPE html><p>Hello, world!</p>'); +$bytes = $dom->saveXmlFile('/path/to/output.xml'); +echo "Saved $bytes bytes\n"; +var_dump($bytes); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +Saved 168 bytes +int(168) +]]> + </screen> + </example> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <simplelist> diff --git a/reference/dom/dom/parentnode/append.xml b/reference/dom/dom/parentnode/append.xml index 25b84d54fd03..2a483e7ba144 100644 --- a/reference/dom/dom/parentnode/append.xml +++ b/reference/dom/dom/parentnode/append.xml @@ -18,6 +18,37 @@ <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('domparentnode.append')/db:refsect1[@role='returnvalues'])" /> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('domparentnode.append')/db:refsect1[@role='errors'])" /> + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="dom-parentnode.append.example.basic"> + <title><methodname>Dom\ParentNode::append</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$dom = Dom\HTMLDocument::createFromString( + '<!DOCTYPE html><body><ul id="list"><li>One</li></ul></body>', + LIBXML_NOERROR +); + +$list = $dom->getElementById('list'); + +$li = $dom->createElement('li'); +$li->textContent = 'Three'; +$list->append('Two', $li); + +echo $dom->saveHtml($list), "\n"; +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +<ul id="list"><li>One</li>Two<li>Three</li></ul> +]]> + </screen> + </example> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <simplelist> diff --git a/reference/dom/dom/parentnode/prepend.xml b/reference/dom/dom/parentnode/prepend.xml index 3c348de60d51..3949f5b7570b 100644 --- a/reference/dom/dom/parentnode/prepend.xml +++ b/reference/dom/dom/parentnode/prepend.xml @@ -18,6 +18,37 @@ <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('domparentnode.prepend')/db:refsect1[@role='returnvalues'])" /> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('domparentnode.prepend')/db:refsect1[@role='errors'])" /> + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="dom-parentnode.prepend.example.basic"> + <title><methodname>Dom\ParentNode::prepend</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$dom = Dom\HTMLDocument::createFromString( + '<!DOCTYPE html><body><ul id="list"><li>One</li></ul></body>', + LIBXML_NOERROR +); + +$list = $dom->getElementById('list'); + +$li = $dom->createElement('li'); +$li->textContent = 'Minus One'; +$list->prepend('Zero', $li); + +echo $dom->saveHtml($list), "\n"; +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +<ul id="list">Zero<li>Minus One</li><li>One</li></ul> +]]> + </screen> + </example> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <simplelist> diff --git a/reference/dom/dom/parentnode/queryselector.xml b/reference/dom/dom/parentnode/queryselector.xml index fb2f0115f1d9..9ba39881675a 100644 --- a/reference/dom/dom/parentnode/queryselector.xml +++ b/reference/dom/dom/parentnode/queryselector.xml @@ -48,6 +48,38 @@ </simpara> </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="dom-parentnode.queryselector.example.basic"> + <title><methodname>Dom\ParentNode::querySelector</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$dom = Dom\HTMLDocument::createFromString( + '<!DOCTYPE html><body><div id="container"><p class="item">First</p><p class="item">Second</p></div></body>', + LIBXML_NOERROR +); + +$container = $dom->getElementById('container'); + +$firstItem = $container->querySelector('.item'); +echo $firstItem->textContent, "\n"; + +echo $container->querySelector('p.item')->textContent, "\n"; + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +First +First +]]> + </screen> + </example> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <simplelist> diff --git a/reference/dom/dom/parentnode/queryselectorall.xml b/reference/dom/dom/parentnode/queryselectorall.xml index 9524c0f1f02a..c8f448b52c0f 100644 --- a/reference/dom/dom/parentnode/queryselectorall.xml +++ b/reference/dom/dom/parentnode/queryselectorall.xml @@ -29,6 +29,41 @@ <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('dom-parentnode.queryselector')/db:refsect1[@role='errors'])" /> + <refsect1 role="examples"> + &reftitle.examples; + <example xml:id="dom-parentnode.queryselectorall.example.basic"> + <title><methodname>Dom\ParentNode::querySelectorAll</methodname> example</title> + <programlisting role="php"> +<![CDATA[ +<?php +$dom = Dom\HTMLDocument::createFromString( + '<!DOCTYPE html><body><div id="container"><p class="item">First</p><p class="item">Second</p><p>Third</p></div></body>', + LIBXML_NOERROR +); + +$container = $dom->getElementById('container'); + +$items = $container->querySelectorAll('.item'); +foreach ($items as $item) { + echo $item->textContent, "\n"; +} + +echo $items->length, "\n"; + +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +First +Second +2 +]]> + </screen> + </example> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <simplelist>