Documentation additions, Document::body

docs/en/030_Document_Object_Model/010_Document/020_Document-C14N.md

@@ -1,13 +0,0 @@
----
-title: Document::C14N
----
-
-Document::C14N — **DISABLED**
-
-## Description ##
-
-```php
-public Document::C14N ( bool $exclusive = false , bool $withComments = false , array|null $xpath = null , array|null $nsPrefixes = null ) : false
-```
-
-This function has been disabled and will always return `false`. `\DOMDocument::C14N` is an extremely slow and inefficient method to serialize DOM and never should be used. Documented to show difference from [`\DOMDocument`](https://www.php.net/manual/en/class.domdocument.php).

docs/en/030_Document_Object_Model/010_Document/020_Document-C14NFile.md

@@ -1,13 +0,0 @@
----
-title: Document::C14NFile
----
-
-Document::C14NFile — **DISABLED**
-
-## Description ##
-
-```php
-public Document::C14NFile ( string $uri , bool $exclusive = false , bool $withComments = false , array|null $xpath = null , array|null $nsPrefixes = null ) : false
-```
-
-This function has been disabled and will always return `false`. `\DOMDocument::C14NFile` is an extremely slow and inefficient method to serialize DOM and never should be used. Documented to show difference from [`\DOMDocument`](https://www.php.net/manual/en/class.domdocument.php).

docs/en/030_Document_Object_Model/010_Document/index.md

@@ -11,7 +11,7 @@ Represents an entire HTML document; serves as the root of the document tree. Unl
 <div class="info"><p><strong>Info</strong> Only new methods and methods which make outward-facing changes from <a href="https://www.php.net/manual/en/class.domdocument.php">\DOMDocument</a> will be documented here, otherwise they will be linked back to PHP's documentation.</p></div>
 
 <pre><code class="php">MensBeam\HTML\Document extends <a href="https://www.php.net/manual/en/class.domdocument.php">\DOMDocument</a> {
-    use <a href="../Walk/index.html">Walk</a>;
+    use <a href="../Node/index.html">Node</a>, <a href="../Walk/index.html">Walk</a>;
 
     /* Constants */
     public const NO_QUIRKS_MODE = 0 ;
@@ -19,6 +19,7 @@ Represents an entire HTML document; serves as the root of the document tree. Unl
     public const LIMITED_QUIRKS_MODE = 2 ;
 
     /* Properties */
+    public Element|null <a href="#document-props-body">$body</a> = null ;
     public string|null <a href="#document-props-documentencoding">$documentEncoding</a> = null ;
     public int <a href="#document-props-quirksmode">$quirksMode</a> = 0 ;
 
@@ -47,22 +48,23 @@ Represents an entire HTML document; serves as the root of the document tree. Unl
     public string <a href="https://www.php.net/manual/en/class.domnode.php#domnode.props.textcontent">$textContent</a> ;
 
     /* Methods */
-    public <a href="Document_construct.html">__construct</a> ( )
-    public <a href="Document_createEntityReference.html">createEntityReference</a> ( string $name ) : false
-    public <a href="Document_C14N.html">C14N</a> ( bool $exclusive = false , bool $withComments = false , array|null $xpath = null , array|null $nsPrefixes = null ) : false
-    public <a href="Document_C14NFile.html">C14NFile</a> ( string $uri , bool $exclusive = false , bool $withComments = false , array|null $xpath = null , array|null $nsPrefixes = null ) : false
-    public <a href="Document_load.html">load</a> ( string $filename , null $options = null , string|null $encodingOrContentType = null ) : bool
-    public <a href="Document_loadHTML.html">loadHTML</a> ( string $source , null $options = null , string|null $encodingOrContentType = null ) : bool
-    public <a href="Document_loadHTMLFile.html">loadHTMLFile</a> ( string $filename , null $options = null , string|null $encodingOrContentType = null ) : bool
-    public <a href="Document_loadHTML.html">loadXML</a> ( string $source , null $options = null ) : false
-    public <a href="Document_save.html">save</a> ( string $filename , null $options = null ) : int|false
-    public <a href="Document_saveHTMLFile.html">saveHTMLFile</a> ( string $filename , null $options = null ) : int|false
-    public <a href="Document_saveXML.html">saveXML</a> ( <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|null $node = null , null $options = null ) : false
-    public <a href="Document_validate.html">validate</a> ( ) : true
-    public <a href="Document_xinclude.html">xinclude</a> ( null $options = null ) : false
+    public <a href="construct.html">__construct</a> ( )
+    public <a href="createEntityReference.html">createEntityReference</a> ( string $name ) : false
+    public <a href="load.html">load</a> ( string $filename , null $options = null , string|null $encodingOrContentType = null ) : bool
+    public <a href="loadHTML.html">loadHTML</a> ( string $source , null $options = null , string|null $encodingOrContentType = null ) : bool
+    public <a href="loadHTMLFile.html">loadHTMLFile</a> ( string $filename , null $options = null , string|null $encodingOrContentType = null ) : bool
+    public <a href="loadHTML.html">loadXML</a> ( string $source , null $options = null ) : false
+    public <a href="save.html">save</a> ( string $filename , null $options = null ) : int|false
+    public <a href="saveHTMLFile.html">saveHTMLFile</a> ( string $filename , null $options = null ) : int|false
+    public <a href="saveXML.html">saveXML</a> ( <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|null $node = null , null $options = null ) : false
+    public <a href="validate.html">validate</a> ( ) : true
+    public <a href="xinclude.html">xinclude</a> ( null $options = null ) : false
+
+    /* Magic Methods */
+    public __toString() : string
 
     /* Methods from <a href="../Walk/index.html">Walk</a> */
-    public <a href="../Walk/Walk_walk.html">walk</a> ( <a href="https://www.php.net/manual/en/class.closure.php">\Closure</a> $filter ) : <a href="https://www.php.net/manual/en/class.generator.php">\Generator</a>
+    public <a href="../Walk/walk.html">walk</a> ( <a href="https://www.php.net/manual/en/class.closure.php">\Closure</a> $filter ) : <a href="https://www.php.net/manual/en/class.generator.php">\Generator</a>
 
     /* Methods inherited from <a href="https://www.php.net/manual/en/class.domdocument.php">\DOMDocument</a> */
     public <a href="https://www.php.net/manual/en/domdocument.createattribute.php">createAttribute</a> ( string $localName ) : <a href="https://www.php.net/manual/en/class.domattr.php">\DOMAttr</a>|false
@@ -116,6 +118,9 @@ Represents an entire HTML document; serves as the root of the document tree. Unl
 ## Properties ##
 
 <dl>
+ <dt id="document-props-body"><var>body</var></dt>
+ <dd>Represents the <code>body</code> or <code>frameset</code> node of the current document, or <code>null</code> if no such element exists.</dd>
+
  <dt id="document-props-documentencoding"><var>documentEncoding</var></dt>
  <dd>Encoding of the document, as specified when parsing or when determining encoding type. Use this instead of <a href="https://php.net/manual/en/class.domdocument.php#domdocument.props.encoding"><code>\DOMDocument::encoding</code></a>.</dd>
 

docs/en/030_Document_Object_Model/Node/010_C14N.md

@@ -0,0 +1,13 @@
+---
+title: Node::C14N
+---
+
+Node::C14N — **DISABLED**
+
+## Description ##
+
+```php
+public Node::C14N ( bool $exclusive = false , bool $withComments = false , array|null $xpath = null , array|null $nsPrefixes = null ) : false
+```
+
+This function has been disabled and will always return `false`. `\DOMNode::C14N` is an extremely slow and inefficient method to serialize DOM and never should be used.

docs/en/030_Document_Object_Model/Node/010_C14NFile.md

@@ -0,0 +1,13 @@
+---
+title: Node::C14NFile
+---
+
+Document::C14NFile — **DISABLED**
+
+## Description ##
+
+```php
+public Node::C14NFile ( string $uri , bool $exclusive = false , bool $withComments = false , array|null $xpath = null , array|null $nsPrefixes = null ) : false
+```
+
+This function has been disabled and will always return `false`. `\DOMNode::C14NFile` is an extremely slow and inefficient method to serialize DOM and never should be used.

docs/en/030_Document_Object_Model/Node/010_appendChild.md

@@ -0,0 +1,47 @@
+---
+title: Node::appendChild
+---
+
+Node::appendChild — Adds new child at the end of the children
+
+## Description ##
+
+```php
+public Node::appendChild ( \DOMNode $node ) : \DOMNode|false
+```
+
+This function appends a child to an existing list of children or creates a new list of children. The child can be created with e.g. [`Document::createElement()`](https://www.php.net/manual/en/domdocument.createelement.php), [`Document::createTextNode()`](https://www.php.net/manual/en/domdocument.createtextnode.php) etc. or simply by using any other node.
+
+When using an existing node it will be moved.
+
+<div class="warning">
+ <p><strong>Warning</strong> Only the following element types may be appended to any node using <code>Node</code> and subject to hierarchy restrictions depending on the type of node being appended to:</p>
+
+ <ul>
+  <li><code>Comment</code></li>
+  <li><code>DocumentFragment</code></li>
+  <li><a href="https://www.php.net/manual/en/class.domdocumenttype.php"><code>\DOMDocumentType</code></a></li>
+  <li><code>Element</code></li>
+  <li><code>ProcessingInstruction</code></li>
+  <li><code>Text</code></li>
+ </ul>
+
+ <p>Note that <code>\DOMAttr</code> is missing from this list.</p>
+</div>
+
+## Examples ##
+
+**Example \#1 Adding a child to the body**
+
+```php
+<?php
+
+namespace MensBeam\HTML;
+
+$dom = new Document();
+$dom->loadHTML('<!DOCTYPE html><html><head><title>Ook!</title></head><body></body></html>');
+
+$node = $dom->createElement('br');
+$dom->body->appendChild($node);
+
+?>

docs/en/030_Document_Object_Model/Node/index.md

@@ -0,0 +1,16 @@
+# The Node trait #
+
+## Introduction ##
+
+Allows the extended PHP DOM classes to simulate inheriting from a theoretical extended [\DOMNode](https://www.php.net/manual/en/class.domnode.php).
+
+<pre><code class="php">trait MensBeam\HTML\Node {
+
+    public <a href="appendChild.html">appendChild</a> ( <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> $node ) : <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|false
+    public <a href="C14N.html">C14N</a> ( bool $exclusive = false , bool $withComments = false , null $xpath = null , null $nsPrefixes = null ) : false
+    public <a href="C14NFile.html">C14NFile</a> ( string $uri , bool $exclusive = false , bool $withComments = false , null $xpath = null , null $nsPrefixes = null ) : false
+    public <a href="Node_insertBefore.html">insertBefore</a> ( <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> $node , <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|null $child = null ) : <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|false
+    public <a href="Node_removeChild.html">removeChild</a> ( <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> $child ) : <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|false
+    public <a href="Node_replaceChild.html">replaceChild</a> ( <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> $node , <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a> $child ) : <a href="https://www.php.net/manual/en/class.domnode.php">\DOMNode</a>|false
+
+}</code></pre>

docs/en/030_Document_Object_Model/Walk/010_Walk-walk.md → docs/en/030_Document_Object_Model/Walk/010_walk.md

@@ -10,7 +10,7 @@ Walk::walk — Output generator for walking down the DOM tree
 public Walk::walk ( <a href="https://www.php.net/manual/en/class.closure.php">\Closure</a> $filter ) : <a href="https://www.php.net/manual/en/class.generator.php">\Generator</a>
 ```
 
-Creates a <a href="https://www.php.net/manual/en/class.generator.php">`\Generator`</a> object for walking down the DOM tree.
+Creates a [`\Generator`](https://www.php.net/manual/en/class.generator.php) object for walking down the DOM tree.
 
 ## Examples ##
 

docs/en/030_Document_Object_Model/Walk/index.md

@@ -2,10 +2,10 @@
 
 ## Introduction ##
 
-Allows nodes to walk down the DOM via a [`\Generator`](https://www.php.net/manual/en/class.generator.php).
+Allows the extended PHP DOM classes to walk down the DOM via a [`\Generator`](https://www.php.net/manual/en/class.generator.php). This is in lieu of recreating the awful [DOM TreeWalker API](https://developer.mozilla.org/en-US/docs/Web/API/Treewalker).
 
 <pre><code class="php">trait MensBeam\HTML\Walk {
 
-    public <a href="Walk_walk.html">walk</a> ( <a href="https://www.php.net/manual/en/class.closure.php">\Closure</a> $filter ) : <a href="https://www.php.net/manual/en/class.generator.php">\Generator</a>
+    public <a href="walk.html">walk</a> ( <a href="https://www.php.net/manual/en/class.closure.php">\Closure</a> $filter ) : <a href="https://www.php.net/manual/en/class.generator.php">\Generator</a>
 
 }</code></pre>

lib/DOM/Document.php

@@ -19,6 +19,8 @@ class Document extends \DOMDocument {
     public $mangledElements = false;
     public $quirksMode = self::NO_QUIRKS_MODE;
 
+    protected $_body = null;
+
     public function __construct() {
         parent::__construct();
 
@@ -151,6 +153,65 @@ class Document extends \DOMDocument {
         ElementMap::destroy($this);
     }
 
+    public function __get(string $prop) {
+        if ($prop === 'body') {
+            if ($this->documentElement === null || $this->documentElement->childNodes->length === 0) {
+                return null;
+            }
+
+            # The body element of a document is the first of the html element's children
+            # that is either a body element or a frameset element, or null if there is no
+            # such element.
+            $n = $this->documentElement->firstChild;
+            do {
+                if ($n instanceof Element && $n->namespaceURI === null && ($n->nodeName === 'body' || $n->nodeName === 'frameset')) {
+                    return $n;
+                }
+            } while ($n = $n->nextSibling);
+
+            return null;
+        }
+    }
+
+    public function __set(string $prop, $value) {
+        if ($prop === 'body') {
+            # On setting, the following algorithm must be run:
+            #
+            # 1. If the new value is not a body or frameset element, then throw a
+            # "HierarchyRequestError" DOMException.
+            if (!$value instanceof Element || $value->namespaceURI !== null) {
+                throw new DOMException(DOMException::HIERARCHY_REQUEST_ERROR);
+            }
+            if ($value->nodeName !== 'body' && $value->nodeName !== 'frameset') {
+                throw new DOMException(DOMException::HIERARCHY_REQUEST_ERROR);
+            }
+
+            if ($this->_body !== null) {
+                # 2. Otherwise, if the new value is the same as the body element, return.
+                if ($value->isSameNode($this->_body)) {
+                    return;
+                }
+
+                # 3. Otherwise, if the body element is not null, then replace the body element
+                # with the new value within the body element's parent and return.
+                $this->documentElement->replaceChild($value, $this->_body);
+                $this->_body = $value;
+                return;
+            }
+
+            # 4. Otherwise, if there is no document element, throw a "HierarchyRequestError"
+            # DOMException.
+            if ($this->documentElement === null) {
+                throw new DOMException(DOMException::HIERARCHY_REQUEST_ERROR);
+            }
+
+            # 5. Otherwise, the body element is null, but there's a document element. Append
+            # the new value to the document element.
+            $this->documentElement->appendChild($value);
+            $this->_body = $value;
+        }
+    }
+
     public function __toString() {
         return $this->serialize();
     }

lib/DOM/ElementMap.php

@@ -17,6 +17,7 @@ class ElementMap {
         foreach (self::$_storage as $k => $v) {
             if ($v->isSameNode($element)) {
                 unset(self::$_storage[$k]);
+                self::$_storage = array_values(self::$_storage);
                 return true;
             }
         }
@@ -25,11 +26,20 @@ class ElementMap {
     }
 
     public static function destroy(Document $document) {
+        $changed = false;
         foreach (self::$_storage as $k => $v) {
             if ($v->ownerDocument->isSameNode($document)) {
                 unset(self::$_storage[$k]);
+                $changed = true;
             }
         }
+
+        if ($changed) {
+            self::$_storage = array_values(self::$_storage);
+            return true;
+        }
+
+        return false;
     }
 
     public static function has(Element $element) {
@@ -45,6 +55,9 @@ class ElementMap {
     public static function set(Element $element) {
         if (!self::has($element)) {
             self::$_storage[] = $element;
+            return true;
         }
+
+        return false;
     }
 }

lib/DOM/traits/Node.php

@@ -9,6 +9,64 @@ namespace MensBeam\HTML;
 // Extensions to PHP's DOM cannot inherit from an extended Node parent, so a
 // trait is the next best thing...
 trait Node {
+    public function appendChild($node) {
+        $this->preInsertionValidity($node);
+
+        $result = parent::appendChild($node);
+        if ($result !== false && $result instanceof TemplateElement) {
+            if ($result instanceof TemplateElement) {
+                ElementMap::set($result);
+            }
+        }
+        return $result;
+    }
+
+    // Disable C14N
+    public function C14N($exclusive = null, $with_comments = null, ?array $xpath = null, ?array $ns_prefixes = null): bool {
+        return false;
+    }
+
+    // Disable C14NFile
+    public function C14NFile($uri, $exclusive = null, $with_comments = null, ?array $xpath = null, ?array $ns_prefixes = null): bool {
+        return false;
+    }
+
+    public function insertBefore($node, $child = null) {
+        $this->preInsertionValidity($node, $child);
+
+        $result = parent::insertBefore($node, $child);
+        if ($result !== false) {
+            if ($result instanceof TemplateElement) {
+                ElementMap::set($result);
+            }
+            if ($child instanceof TemplateElement) {
+                ElementMap::delete($child);
+            }
+        }
+        return $result;
+    }
+
+    public function removeChild($child) {
+        $result = parent::removeChild($child);
+        if ($result !== false && $result instanceof TemplateElement) {
+            ElementMap::delete($child);
+        }
+        return $result;
+    }
+
+    public function replaceChild($node, $child) {
+        $result = parent::replaceChild($node, $child);
+        if ($result !== false) {
+            if ($result instanceof TemplateElement) {
+                ElementMap::set($child);
+            }
+            if ($child instanceof TemplateElement) {
+                ElementMap::delete($child);
+            }
+        }
+        return $result;
+    }
+
     protected function preInsertionValidity(\DOMNode $node, ?\DOMNode $child = null) {
         // "parent" in the spec comments below is $this
 
@@ -134,60 +192,4 @@ trait Node {
             }
         }
     }
-
-    public function appendChild($node) {
-        $this->preInsertionValidity($node);
-
-        $result = parent::appendChild($node);
-        if ($result !== false && $result instanceof TemplateElement) {
-            ElementMap::set($result);
-        }
-        return $result;
-    }
-
-    // Disable C14N
-    public function C14N($exclusive = null, $with_comments = null, ?array $xpath = null, ?array $ns_prefixes = null): bool {
-        return false;
-    }
-
-    // Disable C14NFile
-    public function C14NFile($uri, $exclusive = null, $with_comments = null, ?array $xpath = null, ?array $ns_prefixes = null): bool {
-        return false;
-    }
-
-    public function insertBefore($node, $child = null) {
-        $this->preInsertionValidity($node, $child);
-
-        $result = parent::insertBefore($node, $child);
-        if ($result !== false) {
-            if ($result instanceof TemplateElement) {
-                ElementMap::set($result);
-            }
-            if ($child instanceof TemplateElement) {
-                ElementMap::delete($child);
-            }
-        }
-        return $result;
-    }
-
-    public function removeChild($child) {
-        $result = parent::removeChild($child);
-        if ($result !== false && $result instanceof TemplateElement) {
-            ElementMap::delete($child);
-        }
-        return $result;
-    }
-
-    public function replaceChild($node, $child) {
-        $result = parent::replaceChild($node, $child);
-        if ($result !== false) {
-            if ($result instanceof TemplateElement) {
-                ElementMap::set($child);
-            }
-            if ($child instanceof TemplateElement) {
-                ElementMap::delete($child);
-            }
-        }
-        return $result;
-    }
 }