From e48b8e4e4060fb32838c44a262f736158697cb00 Mon Sep 17 00:00:00 2001 From: Dustin Wilson Date: Mon, 3 Jan 2022 10:49:07 -0600 Subject: [PATCH] More documentation --- README.md | 174 +++++++++++++++++++++++++++++++----------- lib/XPathEvaluate.php | 4 +- 2 files changed, 132 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 975a718..7a71653 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,10 @@ partial class Document { ?string $charset = null ); + public function registerXPathFunctions( + string|array|null $restrict = null + ): void; + public function serialize( ?Node $node = null, array $config = [] @@ -40,6 +44,64 @@ Creates a new `MensBeam\HTML\DOM\Document` object. * `source`: A string representing an HTML document to be parsed. * `charset`: Character set to be used as the encoding for the document. If a document is parsed its default is 'windows-1251', otherwise 'UTF-8'. +##### Examples ##### + +- Creating a new document: + + ```php + use MensBeam\HTML\DOM; + + $d = new Document(); + ``` + +- Creating a new document from a string: + + ```php + use MensBeam\HTML\DOM; + + $d = new Document('Ook

Ook!

'); + ``` + + or: + + ```php + use MensBeam\HTML\DOM; + + $d = new Document(); + $d->load('Ook

Ook!

'); + ``` + +#### MensBeam\HTML\DOM\Document::registerXPathFunctions #### + +Register PHP functions as XPath functions. Works like `\DOMXPath::registerPhpFunctions` except that the php namespace does not need to be registered. + +* `restrict`: Use this parameter to only allow certain functions to be called from XPath. This parameter can be either a string (a function name), an array of function names, or null to allow everything. + +##### Example ##### + +```php +use MensBeam\HTML\DOM; + +$d = new Document('

Ook

Eek?

Ook?

'); +// Register PHP functions (no restrictions) +$d->registerXPathFunctions(); +// Call substr function on classes +$result = $d->evaluate('//*[php:functionString("substr", @class, 0, 8) = "subtitle"]'); + +echo "Found " . count($result) . " nodes with classes starting with 'subtitle':\n"; +foreach ($result as $node) { + echo "$node\n"; +} +``` + +Output: + +``` +Found 2 nodes with classes starting with 'subtitle': +

Eek?

+

Ook?

+``` + #### MensBeam\HTML\DOM\Document::serialize #### Converts a node to a string. @@ -52,6 +114,56 @@ Converts a node to a string. - `indentWithSpaces` (`bool|null`): Whether to use spaces or tabs to indent. This is `true` by default and has no effect unless `reformatWhitespace` is `true` - `reformatWhitespace` (`bool|null`): Whether to reformat whitespace (pretty-print) or not. This is `false` by default +##### Examples ##### + +- Serializing a document: + + ```php + use MensBeam\HTML\DOM; + + $d = new Document(''); + echo $d->serialize(); + ``` + + or: + + ```php + use MensBeam\HTML\DOM; + + $d = new Document(''); + echo $d; + ``` + + Output: + + ```html + + ``` + +- Serializing a document (pretty printing): + + ```php + use MensBeam\HTML\DOM; + + $d = new Document('

Ook!

Ook, eek? Ooooook. Ook.'); + echo $d->serialize($d, [ 'reformatWhitespace' => true ]); + ``` + + Output: + + ```html + + + + + +

Ook!

+ +

Ook, eek? Ooooook. Ook.

+ + + ``` + ### MensBeam\HTML\DOM\Node ### ```php @@ -98,59 +210,31 @@ Applies the callback filter while walking down the DOM tree and yields nodes mat - `Node::WALK_STOP`: Stop the walker. * `includeReferenceNode`: Include `$this` when walking down the tree. -### Examples ### - -- Creating a new document: - - ```php - use MensBeam\HTML\DOM; - - $d = new Document(); - ``` - -- Creating a new document from a string: - - ```php - use MensBeam\HTML\DOM; - - $d = new Document('Ook

Ook!

'); - ``` - - or: +### MensBeam\HTML\DOM\XPathEvaluator ### - ```php - use MensBeam\HTML\DOM; +```php +namespace MensBeam\HTML\DOM; - $d = new Document(); - $d->load('Ook

Ook!

'); - ``` +partial class XPathEvaluator { + public function registerXPathFunctions(Document $document, string|array|null $restrict = null): void; +} +``` -- Serializing a document: +#### MensBeam\HTML\DOM\XPathEvaluator::registerXPathFunctions #### - ```php - use MensBeam\HTML\DOM; +Register PHP functions as XPath functions. Works like `\DOMXPath::registerPhpFunctions` except that the php namespace does not need to be registered. - $d = new Document(''); - echo $d->serialize(); - ``` +* `document`: The document to register the functions on. +* `restrict`: Use this parameter to only allow certain functions to be called from XPath. This parameter can be either a string (a function name), an array of function names, or null to allow everything. - or: +### MensBeam\HTML\DOM\XPathResult ### - ```php - use MensBeam\HTML\DOM; +`MensBeam\HTML\DOM\XPathResult` implements `\ArrayAccess`, `\Countable`, and `\Iterator` and will allow for accessing as if it is an array when the result type is `MensBeam\HTML\DOM\XPathResult::ORDERED_NODE_ITERATOR_TYPE`, `MensBeam\HTML\DOM\XPathResult::UNORDERED_NODE_ITERATOR_TYPE`, `MensBeam\HTML\DOM\XPathResult::ORDERED_NODE_SNAPSHOT_TYPE`, or `MensBeam\HTML\DOM\XPathResult::UNORDERED_NODE_SNAPSHOT_TYPE`. - $d = new Document(''); - echo $d; - ``` - -- Serializing a document (pretty printing): - - ```php - use MensBeam\HTML\DOM; - - $d = new Document(''); - echo $d->serialize($d, [ 'reformatWhitespace' => true ]); - ``` +```php +partial class XPathResult implements \ArrayAccess, \Countable, \Iterator { +} +``` ## Limitations & Differences from Specification ## diff --git a/lib/XPathEvaluate.php b/lib/XPathEvaluate.php index 749ce19..103be6f 100644 --- a/lib/XPathEvaluate.php +++ b/lib/XPathEvaluate.php @@ -140,6 +140,8 @@ trait XPathEvaluate { } protected function xpathRegisterPhpFunctions(Document $document, string|array|null $restrict = null): void { - Reflection::getProtectedProperty($document, 'innerNode')->xpath->registerPhpFunctions($restrict); + $xpath = Reflection::getProtectedProperty($document, 'innerNode')->xpath; + $xpath->registerNamespace('php', 'http://php.net/xpath'); + $xpath->registerPhpFunctions($restrict); } } \ No newline at end of file