Started DOM documentation

3 years ago · 91b9615f8a
2 changed files with 75 additions and 10 deletions
--- a/README.md
+++ b/README.md
@ -1,4 +1,4 @@
-# HTML
+# HTML #

 Tools for parsing and printing HTML5 documents and fragments.

@ -17,7 +17,7 @@ $dom->loadHTML('<!DOCTYPE html><html lang="en" charset="utf-8"><head><title>Ook!
 ?>
 ```

-## Comparison with `masterminds/html5`
+## Comparison with `masterminds/html5` ##

 This library and [masterminds/html5](https://packagist.org/packages/masterminds/html5) serve similar purposes. Generally, we are more accurate, but they are much faster. The following table summarizes the main functional differences.

@ -46,3 +46,60 @@ This library and [masterminds/html5](https://packagist.org/packages/masterminds/
 † With HTML namespace disabled. With HTML namespace enabled it does not finish in a reasonable time due to a PHP bug.

 ‡ With parse errors suppressed. Reporting parse errors adds approximately 10% overhead.
+
+## Document Object Model ##
+
+This library works by parsing HTML strings into PHP's existing XML DOM. It, however, has to force the antiquated PHP DOM extension into working properly with modern HTML DOM by extending many of the node types. The documentation below follows PHP's doc style guide with the exception of inherited methods and properties not being listed. Therefore, only new constants, properties, and methods will be listed; in addition, extended methods which change outward behavior from their parent class will be listed.
+
+### MensBeam\\HTML\\Document ###
+
+```php
+MensBeam\HTML\Document extends \DOMDocument {
+
+    /* Constants */
+    public const NO_QUIRKS_MODE = 0;
+    public const QUIRKS_MODE = 1;
+    public const LIMITED_QUIRKS_MODE = 2;
+
+    /* Properties */
+    public string|null $documentEncoding = null;
+    public int $quirksMode = 0;
+
+    /* Methods */
+    public load ( string $filename , null $options = null , string|null $encodingOrContentType = null ) : bool
+    public loadHTML ( string $source , null $options = null , string|null $encodingOrContentType = null ) : bool
+    public loadHTMLFile ( string $filename , null $options = null , string|null $encodingOrContentType = null ) : bool
+    public loadXML ( string $source , null $options = null ) : false
+    public save ( string $filename , null $options = null ) : int|false
+    public saveXML ( DOMNode|null $node = null , null $options = null ) : false
+    public validate ( ) : true
+    public xinclude ( null $options = null ) : false
+
+}
+```
+
+#### Properties ####
+
+<dl>
+ <dt>documentEncoding</dt>
+ <dd>Encoding of the document, as specified when parsing or when determining encoding type.</dd>
+ <dt>quirksMode</dt>
+ <dd>Used when parsing. Can be not in quirks mode, quirks mode, or limited quirks mode. See the `MensBeam\HTML\Document` constants to see the valid values.</dd>
+</dl>
+
+The following properties inherited from `\DOMDocument` have no effect on `Mensbeam\HTML\Document`:
+
+* actualEncoding
+* config
+* encoding
+* formatOutput
+* preserveWhiteSpace
+* recover
+* resolveExternals
+* standalone
+* substituteEntities
+* validateOnParse
+* version
+* xmlEncoding
+* xmlStandalone
+* xmlVersion
--- a/lib/DOM/Document.php
+++ b/lib/DOM/Document.php
@ -14,10 +14,10 @@ class Document extends \DOMDocument {
    public const QUIRKS_MODE = 1;
    public const LIMITED_QUIRKS_MODE = 2;

-    public $quirksMode = self::NO_QUIRKS_MODE;
-    public $mangledElements = false;
-    public $mangledAttributes = false;
    public $documentEncoding = null;
+    public $mangledAttributes = false;
+    public $mangledElements = false;
+    public $quirksMode = self::NO_QUIRKS_MODE;

    // An array of all template elements created in the document
    // This exists because values of properties on derived DOM classes
@ -103,13 +103,13 @@ class Document extends \DOMDocument {
        }
    }

-    public function load($source, $options = null, ?string $encodingOrContentType = null): bool {
-        $data = Parser::fetchFile($source, $encodingOrContentType);
+    public function load($filename, $options = null, ?string $encodingOrContentType = null): bool {
+        $data = Parser::fetchFile($filename, $encodingOrContentType);
        if (!$data) {
            return false;
        }
        [$data, $encodingOrContentType] = $data;
-        Parser::parse($data, $this, $encodingOrContentType, null, (string) $source);
+        Parser::parse($data, $this, $encodingOrContentType, null, (string)$filename);
        return true;
    }

@ -119,7 +119,15 @@ class Document extends \DOMDocument {
        return true;
    }

-    public function save($filename, $options = 0): string {
+    public function loadHTMLFile($filename, $options = null, ?string $encodingOrContentType = null): bool {
+        return $this->load($filename, $options, $encodingOrContentType);
+    }
+
+    public function loadXML($source, $options = null): bool {
+        return false;
+    }
+
+    public function save($filename, $options = null) {
        return file_put_contents($filename, $this->serialize());
    }

@ -137,7 +145,7 @@ class Document extends \DOMDocument {
        return $this->save($filename);
    }

-    public function saveXML(?\DOMNode $node = null, $options = null) {
+    public function saveXML(?\DOMNode $node = null, $options = null): bool {
        return false;
    }