Document Dom\HTMLDocument methods

php · Dec 15, 2024 · 851dc9e · 851dc9e
1 parent 7d2dd02
commit 851dc9e
Show file tree

Hide file tree

Showing 12 changed files with 719 additions and 13 deletions.
diff --git a/language-snippets.ent b/language-snippets.ent
@@ -1720,6 +1720,28 @@ it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNo
   of the <link linkend="libxml.constants">libxml option constants</link>.
 </para>'>
 
+<!ENTITY dom.parameter.compliant.options '&dom.parameter.options;
+ <simpara xmlns="http://docbook.org/ns/docbook">
+  It is also possible to pass <constant>Dom\HTML_NO_DEFAULT_NS</constant>
+  to disable the use of the HTML namespace and the template element.
+  This should only be used if the implications are properly understood.
+</simpara>'>
+
+<!ENTITY dom.parameter.compliant.encoding '<simpara xmlns="http://docbook.org/ns/docbook">
+ The encoding that the document was created in.
+ If not provided, it will automatically detect the used encoding.
+</simpara>'>
+
+<!ENTITY dom.parser.compliant.note.whitespace '<refsect1 role="notes" xmlns="http://docbook.org/ns/docbook">
+ &reftitle.notes;
+ <note>
+  <simpara>
+   Whitespace in the <literal>html</literal> and <literal>head</literal> tags
+   is not considered significant and may lose formatting.
+  </simpara>
+ </note>
+</refsect1>'>
+
 <!ENTITY dom.parameters.register_node_ns '<varlistentry xmlns="http://docbook.org/ns/docbook">
  <term><parameter>registerNodeNS</parameter></term>
  <listitem>
@@ -1731,6 +1753,14 @@ it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNo
  </listitem>
 </varlistentry>'>
 
+<!ENTITY dom.parameters.serialize.options '<para xmlns="http://docbook.org/ns/docbook">
+ Additional Options.
+ The <link linkend="libxml.constants">LIBXML_NOEMPTYTAG</link>
+ and <link linkend="libxml.constants">LIBXML_NOXMLDECL</link> options are supported.
+ Prior to PHP 8.3.0, only the <link linkend="libxml.constants">LIBXML_NOEMPTYTAG</link>
+ option is supported.
+</para>'>
+
 <!ENTITY dom.errors.hierarchy.parent '<varlistentry xmlns="http://docbook.org/ns/docbook">
  <term><constant>DOM_HIERARCHY_REQUEST_ERR</constant></term>
   <listitem>
@@ -1763,6 +1793,27 @@ it is inserted with (e.g.) <function xmlns="http://docbook.org/ns/docbook">DOMNo
  </listitem>
 </varlistentry>'>
 
+<!ENTITY dom.errors.compliant.wrong_document '<listitem xmlns="http://docbook.org/ns/docbook">
+ <simpara>
+  Throws a <exceptionname>Dom\Exception</exceptionname> with code
+  <constant>Dom\WRONG_DOCUMENT_ERR</constant> if <parameter>node</parameter>
+  is from another document.
+ </simpara>
+</listitem>'>
+
+<!ENTITY dom.errors.compliant.common '<listitem xmlns="http://docbook.org/ns/docbook">
+ <simpara>
+  Throws a <exceptionname>ValueError</exceptionname> if
+  <parameter>options</parameter> contains an invalid option.
+ </simpara>
+</listitem>
+<listitem>
+ <simpara>
+  Throws a <exceptionname>ValueError</exceptionname> if
+  <parameter>overrideEncoding</parameter> is an unknown encoding.
+ </simpara>
+</listitem>'>
+
 <!ENTITY dom.changelog.previous_hierarchy_exception 'Previously this threw a
  <classname xmlns="http://docbook.org/ns/docbook">DOMException</classname> with code
  <constant xmlns="http://docbook.org/ns/docbook">DOM_HIERARCHY_REQUEST_ERR</constant>.'>

diff --git a/reference/dom/constants.xml b/reference/dom/constants.xml
@@ -251,9 +251,9 @@
      </row>
     </thead>
     <tbody>
-     <row xml:id="constant.dom-no-default-ns">
+     <row xml:id="constant.dom-html-no-default-ns">
       <entry>
-       <constant>Dom\NO_DEFAULT_NS</constant>
+       <constant>Dom\HTML_NO_DEFAULT_NS</constant>
        (<type>int</type>)
       </entry>
       <entry>

diff --git a/reference/dom/dom/dom-htmldocument.xml b/reference/dom/dom/dom-htmldocument.xml
@@ -41,10 +41,9 @@
     </xi:include>
 
     <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-htmldocument')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Dom\\HTMLDocument'])">
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.dom-htmldocument')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Dom\\HTMLDocument'])">
      <xi:fallback/>
-    </xi:include>-->
+    </xi:include>
 
     <classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
     <classsynopsisinfo role="comment">Not documented yet</classsynopsisinfo>
@@ -64,6 +63,6 @@
 
  </partintro>
 
-<!-- &reference.dom.dom.entities.htmldocument; -->
+ &reference.dom.dom.entities.htmldocument;
 
 </reference>
diff --git a/reference/dom/dom/htmldocument/createempty.xml b/reference/dom/dom/htmldocument/createempty.xml
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xml:id="dom-htmldocument.createempty" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>Dom\HTMLDocument::createEmpty</refname>
+  <refpurpose>Creates an empty <acronym>HTML</acronym> document</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis role="Dom\\HTMLDocument">
+   <modifier>public</modifier> <modifier>static</modifier> <type>Dom\HTMLDocument</type><methodname>Dom\HTMLDocument::createEmpty</methodname>
+   <methodparam choice="opt"><type>string</type><parameter>encoding</parameter><initializer>"UTF-8"</initializer></methodparam>
+  </methodsynopsis>
+  <simpara>
+   Creates an empty <acronym>HTML</acronym> document without any elements.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>encoding</parameter></term>
+    <listitem>
+     <simpara>
+      The character encoding of the document, used for serialization when
+      calling the save methods.
+     </simpara>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <simpara>
+   An empty <acronym>HTML</acronym> document.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example xml:id="dom-htmldocument.createempty.example.basic">
+   <title><methodname>Dom\HTMLDocument::createEmpty</methodname> example</title>
+   <simpara>
+    Creates an empty document and serializes it.
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$dom = Dom\HTMLDocument::createEmpty();
+var_dump($dom->saveHtml());
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+string(0) ""
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Dom\HTMLDocument::createFromString</methodname></member>
+   <member><methodname>Dom\HTMLDocument::createFromFile</methodname></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/htmldocument/createfromfile.xml b/reference/dom/dom/htmldocument/createfromfile.xml
@@ -0,0 +1,105 @@
+<?xml version="1.0" encoding="utf-8"?>
+<refentry xml:id="dom-htmldocument.createfromfile" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>Dom\HTMLDocument::createFromFile</refname>
+  <refpurpose>Parses an <acronym>HTML</acronym> document from a file</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis role="Dom\\HTMLDocument">
+   <modifier>public</modifier> <modifier>static</modifier> <type>Dom\HTMLDocument</type><methodname>Dom\HTMLDocument::createFromFile</methodname>
+   <methodparam><type>string</type><parameter>path</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>0</initializer></methodparam>
+   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>overrideEncoding</parameter><initializer>&null;</initializer></methodparam>
+  </methodsynopsis>
+  <simpara>
+   Parses an <acronym>HTML</acronym> document from a file,
+   according to the living standard.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>path</parameter></term>
+    <listitem>
+     <simpara>
+      The path to the file to parse.
+     </simpara>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>options</parameter></term>
+    <listitem>
+     &dom.parameter.compliant.options;
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>overrideEncoding</parameter></term>
+    <listitem>
+     &dom.parameter.compliant.encoding;
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <simpara>
+   The parsed document as an <classname>Dom\HTMLDocument</classname> instance.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <itemizedlist>
+   <listitem>
+    <simpara>
+     Throws a <exceptionname>ValueError</exceptionname> if
+     <parameter>path</parameter> contains null bytes or contains
+     <literal>"%00"</literal>.
+    </simpara>
+   </listitem>
+   &dom.errors.compliant.common;
+   <listitem>
+    <simpara>
+     Throws an <exceptionname>Exception</exceptionname> if
+     the file could not be opened.
+    </simpara>
+   </listitem>
+  </itemizedlist>
+ </refsect1>
+
+ &dom.parser.compliant.note.whitespace;
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><methodname>Dom\HTMLDocument::createEmpty</methodname></member>
+   <member><methodname>Dom\HTMLDocument::createFromString</methodname></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
+-->