From 851dc9e26cfb6b7dce8a88e53eaac4d4be79aaf1 Mon Sep 17 00:00:00 2001 From: Niels Dossche <7771979+nielsdos@users.noreply.github.com> Date: Sun, 15 Dec 2024 14:55:16 +0100 Subject: [PATCH 1/3] Document Dom\HTMLDocument methods --- language-snippets.ent | 51 +++++++ reference/dom/constants.xml | 4 +- reference/dom/dom/dom-htmldocument.xml | 7 +- .../dom/dom/htmldocument/createempty.xml | 93 +++++++++++++ .../dom/dom/htmldocument/createfromfile.xml | 105 +++++++++++++++ .../dom/dom/htmldocument/createfromstring.xml | 126 ++++++++++++++++++ reference/dom/dom/htmldocument/savehtml.xml | 77 +++++++++++ .../dom/dom/htmldocument/savehtmlfile.xml | 81 +++++++++++ reference/dom/dom/htmldocument/savexml.xml | 84 ++++++++++++ .../dom/dom/htmldocument/savexmlfile.xml | 88 ++++++++++++ reference/dom/domdocument/savexml.xml | 8 +- reference/dom/versions.xml | 8 ++ 12 files changed, 719 insertions(+), 13 deletions(-) create mode 100644 reference/dom/dom/htmldocument/createempty.xml create mode 100644 reference/dom/dom/htmldocument/createfromfile.xml create mode 100644 reference/dom/dom/htmldocument/createfromstring.xml create mode 100644 reference/dom/dom/htmldocument/savehtml.xml create mode 100644 reference/dom/dom/htmldocument/savehtmlfile.xml create mode 100644 reference/dom/dom/htmldocument/savexml.xml create mode 100644 reference/dom/dom/htmldocument/savexmlfile.xml diff --git a/language-snippets.ent b/language-snippets.ent index 26bb4819a0ed..ce8e6c9623cc 100644 --- a/language-snippets.ent +++ b/language-snippets.ent @@ -1720,6 +1720,28 @@ it is inserted with (e.g.) DOMNo of the libxml option constants. '> + + It is also possible to pass Dom\HTML_NO_DEFAULT_NS + to disable the use of the HTML namespace and the template element. + This should only be used if the implications are properly understood. +'> + + + The encoding that the document was created in. + If not provided, it will automatically detect the used encoding. +'> + + + &reftitle.notes; + + + Whitespace in the html and head tags + is not considered significant and may lose formatting. + + +'> + registerNodeNS @@ -1731,6 +1753,14 @@ it is inserted with (e.g.) DOMNo '> + + Additional Options. + The LIBXML_NOEMPTYTAG + and LIBXML_NOXMLDECL options are supported. + Prior to PHP 8.3.0, only the LIBXML_NOEMPTYTAG + option is supported. +'> + DOM_HIERARCHY_REQUEST_ERR @@ -1763,6 +1793,27 @@ it is inserted with (e.g.) DOMNo '> + + + Throws a Dom\Exception with code + Dom\WRONG_DOCUMENT_ERR if node + is from another document. + +'> + + + + Throws a ValueError if + options contains an invalid option. + + + + + Throws a ValueError if + overrideEncoding is an unknown encoding. + +'> + DOMException with code DOM_HIERARCHY_REQUEST_ERR.'> diff --git a/reference/dom/constants.xml b/reference/dom/constants.xml index 15c5dd74e6d7..6e74b04eac90 100644 --- a/reference/dom/constants.xml +++ b/reference/dom/constants.xml @@ -251,9 +251,9 @@ - + - Dom\NO_DEFAULT_NS + Dom\HTML_NO_DEFAULT_NS (int) diff --git a/reference/dom/dom/dom-htmldocument.xml b/reference/dom/dom/dom-htmldocument.xml index ce9d564fdae4..5be58b4b3a5a 100644 --- a/reference/dom/dom/dom-htmldocument.xml +++ b/reference/dom/dom/dom-htmldocument.xml @@ -41,10 +41,9 @@ &Methods; - Not documented yet - + &InheritedMethods; Not documented yet @@ -64,6 +63,6 @@ - + &reference.dom.dom.entities.htmldocument; diff --git a/reference/dom/dom/htmldocument/createempty.xml b/reference/dom/dom/htmldocument/createempty.xml new file mode 100644 index 000000000000..8a6d06e3eb92 --- /dev/null +++ b/reference/dom/dom/htmldocument/createempty.xml @@ -0,0 +1,93 @@ + + + + Dom\HTMLDocument::createEmpty + Creates an empty HTML document + + + + &reftitle.description; + + public static Dom\HTMLDocumentDom\HTMLDocument::createEmpty + stringencoding"UTF-8" + + + Creates an empty HTML document without any elements. + + + + + &reftitle.parameters; + + + encoding + + + The character encoding of the document, used for serialization when + calling the save methods. + + + + + + + + &reftitle.returnvalues; + + An empty HTML document. + + + + + &reftitle.examples; + + <methodname>Dom\HTMLDocument::createEmpty</methodname> example + + Creates an empty document and serializes it. + + +saveHtml()); +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + Dom\HTMLDocument::createFromString + Dom\HTMLDocument::createFromFile + + + + + diff --git a/reference/dom/dom/htmldocument/createfromfile.xml b/reference/dom/dom/htmldocument/createfromfile.xml new file mode 100644 index 000000000000..a9823ef9b034 --- /dev/null +++ b/reference/dom/dom/htmldocument/createfromfile.xml @@ -0,0 +1,105 @@ + + + + Dom\HTMLDocument::createFromFile + Parses an HTML document from a file + + + + &reftitle.description; + + public static Dom\HTMLDocumentDom\HTMLDocument::createFromFile + stringpath + intoptions0 + stringnulloverrideEncoding&null; + + + Parses an HTML document from a file, + according to the living standard. + + + + + &reftitle.parameters; + + + path + + + The path to the file to parse. + + + + + options + + &dom.parameter.compliant.options; + + + + overrideEncoding + + &dom.parameter.compliant.encoding; + + + + + + + &reftitle.returnvalues; + + The parsed document as an Dom\HTMLDocument instance. + + + + + &reftitle.errors; + + + + Throws a ValueError if + path contains null bytes or contains + "%00". + + + &dom.errors.compliant.common; + + + Throws an Exception if + the file could not be opened. + + + + + + &dom.parser.compliant.note.whitespace; + + + &reftitle.seealso; + + Dom\HTMLDocument::createEmpty + Dom\HTMLDocument::createFromString + + + + + diff --git a/reference/dom/dom/htmldocument/createfromstring.xml b/reference/dom/dom/htmldocument/createfromstring.xml new file mode 100644 index 000000000000..45cc90370d31 --- /dev/null +++ b/reference/dom/dom/htmldocument/createfromstring.xml @@ -0,0 +1,126 @@ + + + + Dom\HTMLDocument::createFromString + Parses an HTML document from a string + + + + &reftitle.description; + + public static Dom\HTMLDocumentDom\HTMLDocument::createFromString + stringsource + intoptions0 + stringnulloverrideEncoding&null; + + + Parses an HTML document from a string, + according to the living standard. + + + + + &reftitle.parameters; + + + source + + + The string containing the HTML to parse. + + + + + options + + &dom.parameter.compliant.options; + + + + overrideEncoding + + &dom.parameter.compliant.encoding; + + + + + + + &reftitle.returnvalues; + + The parsed document as an Dom\HTMLDocument instance. + + + + + &reftitle.errors; + + &dom.errors.compliant.common; + + + + + &reftitle.examples; + + <methodname>Dom\HTMLDocument::createFromString</methodname> example + + Parses a sample document. + + + + + +

Hello, world!

+ + +HTML); +echo $dom->saveHtml(); +?> +]]> + + &example.outputs; + + +

Hello, world!

+ + +]]> + + + + + &dom.parser.compliant.note.whitespace; + + + &reftitle.seealso; + + Dom\HTMLDocument::createEmpty + Dom\HTMLDocument::createFromFile + + + + + diff --git a/reference/dom/dom/htmldocument/savehtml.xml b/reference/dom/dom/htmldocument/savehtml.xml new file mode 100644 index 000000000000..d5fa667b3078 --- /dev/null +++ b/reference/dom/dom/htmldocument/savehtml.xml @@ -0,0 +1,77 @@ + + + + Dom\HTMLDocument::saveHtml + Serializes the document as an HTML string + + + + &reftitle.description; + + public stringDom\HTMLDocument::saveHtml + Dom\Nodenullnode&null; + + + Serializes the document as an HTML string. + + + + + &reftitle.parameters; + + + node + + + The node to serialize. + If not provided, the entire document is serialized. + + + + + + + + &reftitle.returnvalues; + + The serialized HTML document string in the current + document encoding. + + + + + &reftitle.errors; + + &dom.errors.compliant.wrong_document; + + + + + &reftitle.seealso; + + Dom\HTMLDocument::saveHtmlFile + Dom\HTMLDocument::saveXml + + + + + diff --git a/reference/dom/dom/htmldocument/savehtmlfile.xml b/reference/dom/dom/htmldocument/savehtmlfile.xml new file mode 100644 index 000000000000..1e452801e3cc --- /dev/null +++ b/reference/dom/dom/htmldocument/savehtmlfile.xml @@ -0,0 +1,81 @@ + + + + Dom\HTMLDocument::saveHtmlFile + Serializes the document as an HTML file + + + + &reftitle.description; + + public intfalseDom\HTMLDocument::saveHtmlFile + stringfilename + + + Serializes the document as an HTML file. + + + + + &reftitle.parameters; + + + filename + + + The path to the file to save to. + + + + + + + + &reftitle.returnvalues; + + The number of bytes written on success, or &false; on failure. + + + + + &reftitle.errors; + + + + Throws a ValueError if + filename is an empty string or contains any + null bytes. + + + + + + + &reftitle.seealso; + + Dom\HTMLDocument::saveHtml + Dom\HTMLDocument::saveXmlFile + + + + + diff --git a/reference/dom/dom/htmldocument/savexml.xml b/reference/dom/dom/htmldocument/savexml.xml new file mode 100644 index 000000000000..bd87e7929147 --- /dev/null +++ b/reference/dom/dom/htmldocument/savexml.xml @@ -0,0 +1,84 @@ + + + + Dom\HTMLDocument::saveXml + Serializes the document as an XML string + + + + &reftitle.description; + + public stringfalseDom\HTMLDocument::saveXml + Dom\Nodenullnode&null; + intoptions0 + + + Serializes the document as an XML stirng. + + + + + &reftitle.parameters; + + + node + + + The node to serialize. + If not provided, the entire document is serialized. + + + + + options + + &dom.parameters.serialize.options; + + + + + + + &reftitle.returnvalues; + + The serialized XML document string in the current + document encoding, or &false; on failure. + + + + + &reftitle.errors; + + &dom.errors.compliant.wrong_document; + + + + + &reftitle.seealso; + + Dom\HTMLDocument::saveXmlFile + Dom\XMLDocument::saveHtml + + + + + diff --git a/reference/dom/dom/htmldocument/savexmlfile.xml b/reference/dom/dom/htmldocument/savexmlfile.xml new file mode 100644 index 000000000000..391629f4c9f5 --- /dev/null +++ b/reference/dom/dom/htmldocument/savexmlfile.xml @@ -0,0 +1,88 @@ + + + + Dom\HTMLDocument::saveXmlFile + Serializes the document as an XML file + + + + &reftitle.description; + + public intfalseDom\HTMLDocument::saveXmlFile + stringfilename + intoptions0 + + + Serializes the document as an XML file. + + + + + &reftitle.parameters; + + + filename + + + The path to the file to save to. + + + + + options + + &dom.parameters.serialize.options; + + + + + + + &reftitle.returnvalues; + + The number of bytes written on success, or &false; on failure. + + + + + &reftitle.errors; + + + + Throws a ValueError if + filename is an empty string or contains any + null bytes. + + + + + + + &reftitle.seealso; + + Dom\HTMLDocument::saveXml + Dom\HTMLDocument::saveHtmlFile + + + + + diff --git a/reference/dom/domdocument/savexml.xml b/reference/dom/domdocument/savexml.xml index 3b54b8cbbf87..b1751e937ddc 100644 --- a/reference/dom/domdocument/savexml.xml +++ b/reference/dom/domdocument/savexml.xml @@ -36,13 +36,7 @@ options - - Additional Options. - The LIBXML_NOEMPTYTAG - and LIBXML_NOXMLDECL options are supported. - Prior to PHP 8.3.0, only the LIBXML_NOEMPTYTAG - option is supported. - + &dom.parameters.serialize.options; diff --git a/reference/dom/versions.xml b/reference/dom/versions.xml index 514f4b0e865f..154b12547470 100644 --- a/reference/dom/versions.xml +++ b/reference/dom/versions.xml @@ -248,6 +248,14 @@ + + + + + + + + From ace936aa13746cb902d03824a80fb3f5ee06b000 Mon Sep 17 00:00:00 2001 From: Niels Dossche <7771979+nielsdos@users.noreply.github.com> Date: Sun, 15 Dec 2024 15:33:50 +0100 Subject: [PATCH 2/3] ws --- reference/dom/dom/htmldocument/createfromstring.xml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/dom/dom/htmldocument/createfromstring.xml b/reference/dom/dom/htmldocument/createfromstring.xml index 45cc90370d31..c7dc4f8f3d51 100644 --- a/reference/dom/dom/htmldocument/createfromstring.xml +++ b/reference/dom/dom/htmldocument/createfromstring.xml @@ -72,9 +72,9 @@ $dom = Dom\HTMLDocument::createFromString(<<<'HTML' - -

Hello, world!

- + +

Hello, world!

+ HTML); echo $dom->saveHtml(); @@ -85,8 +85,8 @@ echo $dom->saveHtml(); -

Hello, world!

- +

Hello, world!

+ ]]> From 7d10c77ce0e09a9bb98dde0c2807f6f375662cae Mon Sep 17 00:00:00 2001 From: Niels Dossche <7771979+nielsdos@users.noreply.github.com> Date: Sun, 15 Dec 2024 15:34:20 +0100 Subject: [PATCH 3/3] name --- language-snippets.ent | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/language-snippets.ent b/language-snippets.ent index ce8e6c9623cc..15c95939c4dd 100644 --- a/language-snippets.ent +++ b/language-snippets.ent @@ -1795,7 +1795,7 @@ it is inserted with (e.g.) DOMNo - Throws a Dom\Exception with code + Throws a Dom\DOMException with code Dom\WRONG_DOCUMENT_ERR if node is from another document.