From f5e1714ae53cdc3b6005cd037912f7e25068550c Mon Sep 17 00:00:00 2001 From: Perry Rylance Date: Mon, 6 May 2024 06:40:58 +0100 Subject: [PATCH] 3.0.1 - Add support for directly casting documents, objects and elements to strings - Regenerate documentation, update docs link --- .github/workflows/ci.yml | 3 + README.md | 6 +- composer.json | 2 +- docs/classes/DOMDocumentBadInit.html | 304 +++++-- docs/classes/DOMDocumentTest.html | 182 +++- .../PerryRylance-DOMDocument-DOMElement.html | 790 ++++++++++++++++++ .../PerryRylance-DOMDocument-DOMObject.html | 281 +++++-- docs/classes/PerryRylance-DOMDocument.html | 306 +++++-- docs/files/src-domdocument-domelement.html | 12 + docs/files/tests-domdocumenttest.html | 49 -- docs/index.html | 49 -- docs/js/searchIndex.js | 119 ++- docs/namespaces/default.html | 49 -- docs/namespaces/perryrylance-domdocument.html | 2 + docs/packages/Application.html | 51 +- docs/reports/markers.html | 32 +- src/DOMDocument.php | 44 +- src/DOMDocument/DOMElement.php | 9 + src/DOMDocument/DOMObject.php | 9 + tests/DOMDocumentTest.php | 40 +- tests/formatted.html | 80 ++ 21 files changed, 1887 insertions(+), 532 deletions(-) create mode 100644 docs/classes/PerryRylance-DOMDocument-DOMElement.html create mode 100644 tests/formatted.html diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b4e6050..4893c4f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,6 +8,9 @@ jobs: steps: - uses: actions/checkout@v3 + - uses: nanasess/setup-php@v4 + with: + php-version: '8.2' - name: Run PHPUnit tests run: | composer install diff --git a/README.md b/README.md index 5022f77..af39fa6 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Instantiate DOMDocument and enjoy the jQuery-like functions now at your disposal As of version 2.0.0, this library does not add jQuery-like methods to DOMElement, in order to avoid future collisions with the HTML living standard spec. Rather, these jQuery-like methods are implemented on `DOMObject` in the same manner jQuery objects work. ## Documentation -Read the libraries [documentation](http://perryrylance.com/docs/DOMDocument). +Read the libraries [documentation](https://perryrylance.github.io/DOMDocument/). The requirements to generate documentation are as follows: @@ -31,7 +31,9 @@ As of 3.0.0, tests are run via Docker to facilitate cross PHP version testing. All tests can be run by running `tests.sh`. - +To run individual tests from your native CLI: + +`docker-compose run php82 php /app/vendor/bin/phpunit tests --filter=testCastToString` ## Migrating from 2.* to 3.* Version 2.* is not compatible with PHP 8.3, version 3.0.0 addresses this. diff --git a/composer.json b/composer.json index 9dfcc6e..7f41194 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "name": "perry-rylance/dom-document", - "version": "3.0.0", + "version": "3.0.1", "minimum-stability": "stable", "description": "An extension of PHP's DOMDocument library. This library implements many common jQuery functions, adds support for HTML5, CSS selectors, method chaining and performing operations on sets of matched results.", diff --git a/docs/classes/DOMDocumentBadInit.html b/docs/classes/DOMDocumentBadInit.html index 6d09fa7..c5b6255 100644 --- a/docs/classes/DOMDocumentBadInit.html +++ b/docs/classes/DOMDocumentBadInit.html @@ -132,10 +132,17 @@

+
+ OPTION_DISABLE_HTML_NS + +  = 2 +
+
+
OPTION_EVALUATE_PHP -  = "executePHP" +  = 1
@@ -174,6 +181,13 @@

Magic method for getting properties. Only "html" is supported presently.
+
+ __toString() + +  : string +
+
Returns the entire document as a string.
+
convertUTF8ToHTMLEntities() @@ -184,14 +198,14 @@

create() -  : mixed +  : DOMObject
-
+
Creates a HTML fragment from the supplied HTML source string
getDocumentElementSafe() -  : DOMElement +  : DOMElement
Function to safely get the document element. Some PHP builds do not implement documentElement, this function can be used to safely retrieve the document element in absense of this property.
@@ -212,10 +226,17 @@

loadHTML() -  : This +  : bool
Loads the supplied HTML string
+
+ loadHTMLFile() + +  : bool +
+
Loads the supplied HTML file
+
save() @@ -240,9 +261,9 @@

shorthand() -  : mixed +  : callable
-
+
Returns a "shorthand" function which you can use in a jQuery-like manner to create fragemnts, eg $_ = $doc->shorthand(); $div = $_("<div>Example</div>);
onLoaded() @@ -251,13 +272,6 @@

Callback which fires after the HTML has been parsed and loaded, but before loadHTML returns. Useful for controlling the execution order for operations spread across an inheritance chain.
-
- assertNotEmpty() - -  : mixed -
-
-

@@ -269,6 +283,35 @@

+

+ OPTION_DISABLE_HTML_NS + +

+ + + + + + public + mixed + OPTION_DISABLE_HTML_NS + = 2 + + + +
+ +
+ + + +
+

OPTION_EVALUATE_PHP @@ -286,7 +329,7 @@

public mixed OPTION_EVALUATE_PHP - = "executePHP" + = 1 @@ -306,7 +349,7 @@

@@ -350,7 +393,7 @@

@@ -388,7 +431,7 @@

@@ -429,7 +472,7 @@

see
- DOMElement + DOMElement

for a list of supported methods

@@ -489,7 +532,7 @@

@@ -519,6 +562,41 @@

Return values
— +
+
+

+ __toString() + +

+ + +

Returns the entire document as a string.

+ + + public + __toString() : string + + + + + +
Return values
+ string + — +

The entire document rendered to a string

+
+ +
@@ -580,25 +658,26 @@

- +

Creates a HTML fragment from the supplied HTML source string

+ public - create(mixed $html) : mixed - -
+ create(string $html) : DOMObject +

Parameters
$html - : mixed + : string
-
+

The HTML source string

+
@@ -606,9 +685,11 @@
Parameters
Return values
- mixed + DOMObject — - +

The resulting element(s)

+
+
@@ -632,14 +713,14 @@

public - getDocumentElementSafe() : DOMElement + getDocumentElementSafe() : DOMElement

Return values
- DOMElement + DOMElement —

The document element for this document

@@ -659,7 +740,7 @@

@@ -706,7 +787,7 @@

@@ -714,14 +795,14 @@

public - load(mixed $filename[, array<string|int, mixed> $options = array() ]) : This + load(string $filename[, int $options = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS ]) : This

Parameters
$filename - : mixed + : string
@@ -729,10 +810,10 @@
Parameters
$options - : array<string|int, mixed> - = array()
+ : int + = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS
-

An array of options. Presently only DOMDocument::OPTION_EVALUATE_PHP is supported, this defaults to TRUE and will execute inline PHP

+

A bit field of options. Presently only DOMDocument::OPTION_EVALUATE_PHP is supported, this defaults to TRUE and will execute inline PHP

@@ -777,7 +858,7 @@

@@ -785,7 +866,7 @@

public - loadHTML(string $src[, array<string|int, mixed> $options = array() ]) : This + loadHTML(string $src[, int $options = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS ]) : bool

Parameters
@@ -801,10 +882,10 @@
Parameters
$options - : array<string|int, mixed> - = array()
+ : int + = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS
-

An array of options. Presently only DOMDocument::OPTION_EXECUTE_PHP is supported, this defaults to TRUE and will execute inline PHP

+

A bit field of options. Presently only DOMDocument::OPTION_EXECUTE_PHP is supported, this defaults to TRUE and will execute inline PHP

@@ -829,9 +910,81 @@
Return values
- This + bool — -

document, for method chaining

+

true

+
+ + +
+
+

+ loadHTMLFile() + +

+ + +

Loads the supplied HTML file

+ + + public + loadHTMLFile(string $filename[, int $options = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS ]) : bool + + +
Parameters
+
+
+ $filename + : string +
+
+

The file to parse

+
+ +
+
+ $options + : int + = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS
+
+

A bit field of options. Presently only DOMDocument::OPTION_EXECUTE_PHP is supported, this defaults to TRUE and will execute inline PHP

+
+ +
+
+ + +
+ Tags + +
+
+
+ see +
+
+ https://github.com/Masterminds/html5-php#options + +

for other options supported by the HTML5 parser

+
+ +
+
+ +
Return values
+ bool + — +

true

@@ -849,7 +1002,7 @@

@@ -919,7 +1072,7 @@

@@ -988,7 +1141,7 @@

@@ -1023,24 +1176,26 @@

- +

Returns a "shorthand" function which you can use in a jQuery-like manner to create fragemnts, eg $_ = $doc->shorthand(); $div = $_("<div>Example</div>);

+ public - shorthand() : mixed - -
+ shorthand() : callable +

Return values
- mixed + callable — - +

A convenience function which creates HTML fragments from a string

+
+
@@ -1075,39 +1230,6 @@
Return values
— -
-
-

- assertNotEmpty() - -

- - - - - private - assertNotEmpty() : mixed - -
- - - - -
Return values
- mixed - — - -
diff --git a/docs/classes/DOMDocumentTest.html b/docs/classes/DOMDocumentTest.html index 1ebf094..c29f744 100644 --- a/docs/classes/DOMDocumentTest.html +++ b/docs/classes/DOMDocumentTest.html @@ -144,6 +144,27 @@

 : mixed +
+ +
+ testCastDocumentToString() + +  : mixed +
+
+ +
+ testCastDomObjectToString() + +  : mixed +
+
+ +
+ testCastElementToString() + +  : mixed +
@@ -345,7 +366,7 @@

getDocument() -  : mixed +  : DOMDocument
@@ -375,7 +396,7 @@

@@ -408,7 +429,7 @@

@@ -422,6 +443,105 @@

+

Return values
+ mixed + — + + + +
+

+ testCastDocumentToString() + +

+ + + + + public + testCastDocumentToString() : mixed + +
+ + + + +
Return values
+ mixed + — + + +
+
+

+ testCastDomObjectToString() + +

+ + + + + public + testCastDomObjectToString() : mixed + +
+ + + + +
Return values
+ mixed + — + + +
+
+

+ testCastElementToString() + +

+ + + + + public + testCastElementToString() : mixed + +
+ + + +
Return values
mixed — @@ -441,7 +561,7 @@

@@ -474,7 +594,7 @@

@@ -507,7 +627,7 @@

@@ -540,7 +660,7 @@

@@ -573,7 +693,7 @@

@@ -606,7 +726,7 @@

@@ -639,7 +759,7 @@

@@ -672,7 +792,7 @@

@@ -705,7 +825,7 @@

@@ -738,7 +858,7 @@

@@ -771,7 +891,7 @@

@@ -804,7 +924,7 @@

@@ -837,7 +957,7 @@

@@ -870,7 +990,7 @@

@@ -903,7 +1023,7 @@

@@ -936,7 +1056,7 @@

@@ -969,7 +1089,7 @@

@@ -1002,7 +1122,7 @@

@@ -1035,7 +1155,7 @@

@@ -1068,7 +1188,7 @@

@@ -1134,7 +1254,7 @@

@@ -1167,7 +1287,7 @@

@@ -1200,7 +1320,7 @@

@@ -1266,7 +1386,7 @@

@@ -1299,7 +1419,7 @@

@@ -1332,7 +1452,7 @@

@@ -1372,7 +1492,7 @@

private - getDocument() : mixed + getDocument() : DOMDocument
@@ -1380,7 +1500,7 @@

Return values
- mixed + DOMDocument — diff --git a/docs/classes/PerryRylance-DOMDocument-DOMElement.html b/docs/classes/PerryRylance-DOMDocument-DOMElement.html new file mode 100644 index 0000000..3c0ef20 --- /dev/null +++ b/docs/classes/PerryRylance-DOMDocument-DOMElement.html @@ -0,0 +1,790 @@ + + + + + Documentation + + + + + + + + + + + + + + + + + + + + +
+

Documentation

+ + +
+ +
+ + +
+ +
+
+ + + + +
+ + +
+

+ DOMElement + + + extends DOMElement + + +
+ in package + +
+ + +

+ + + +

This class is used to represent elements, and implements many jQuery-like functions for the elements

+ + + + + + + + + +

+ Table of Contents + +

+ +
+
+ __construct() + +  : mixed +
+
Constructor for a DOMElement. This should not be called directly. Use the document's createElement method instead
+ +
+ __get() + +  : mixed +
+
Getter. The only supported property is html
+ +
+ __set() + +  : mixed +
+
+ +
+ __toString() + +  : string +
+
Returns this element as a HTML fragment string.
+ +
+ getBreadth() + +  : int +
+
Returns the breadth (sometimes called child index) of this node in regards to it's siblings
+ +
+ getDepth() + +  : int +
+
Returns the depth of this node in regards to it's ancestors
+ +
+ isBefore() + +  : bool +
+
Test if this element comes before the other element in the DOM tree
+ +
+ querySelector() + +  : DOMElement|null +
+
Equivalent of JavaScripts querySelector. This will return the first element matching the specified selector, or NULL when no elements match
+ +
+ querySelectorAll() + +  : DOMObject +
+
Equivalent of JavaScripts querySelectorAll, takes a CSS selector, and optionally an array of options.
+ +
+ implicitCastDomElement() + +  : DOMElement +
+
+ +
+ implicitCastParentNode() + +  : DOMElement +
+
+ +
+ + + + + + + +
+

+ Methods + +

+
+

+ __construct() + +

+ + +

Constructor for a DOMElement. This should not be called directly. Use the document's createElement method instead

+ + + public + __construct(string $qualifiedName) : mixed + + +
Parameters
+
+
+ $qualifiedName + : string +
+
+
+ +
+
+ + + +
Return values
+ mixed + — + + +
+
+

+ __get() + +

+ + +

Getter. The only supported property is html

+ + + public + __get(string $name) : mixed + + +
Parameters
+
+
+ $name + : string +
+
+

The name of the property to get

+
+ +
+
+ + + +
Return values
+ mixed + — + + +
+
+

+ __set() + +

+ + + + + public + __set(mixed $name, mixed $value) : mixed + +
+ +
Parameters
+
+
+ $name + : mixed +
+
+
+ +
+
+ $value + : mixed +
+
+
+ +
+
+ + + +
Return values
+ mixed + — + + +
+
+

+ __toString() + +

+ + +

Returns this element as a HTML fragment string.

+ + + public + __toString() : string + + + + + +
Return values
+ string + — +

Elements in this element rendered to a HTML string fragment

+
+ + +
+
+

+ getBreadth() + +

+ + +

Returns the breadth (sometimes called child index) of this node in regards to it's siblings

+ + + public + getBreadth() : int + + + + + +
Return values
+ int + — +

The index of this node

+
+ + +
+
+

+ getDepth() + +

+ + +

Returns the depth of this node in regards to it's ancestors

+ + + public + getDepth() : int + + + + + +
Return values
+ int + — +

The depth of this node

+
+ + +
+
+

+ isBefore() + +

+ + +

Test if this element comes before the other element in the DOM tree

+ + + public + isBefore(DOMElement $other) : bool + + +
Parameters
+
+
+ $other + : DOMElement +
+
+

The element to compare positions with

+
+ +
+
+ + + +
Return values
+ bool + — +

TRUE if this element comes before the other, FALSE if not

+
+ + +
+
+

+ querySelector() + +

+ + +

Equivalent of JavaScripts querySelector. This will return the first element matching the specified selector, or NULL when no elements match

+ + + public + querySelector(string $selector) : DOMElement|null + + +
Parameters
+
+
+ $selector + : string +
+
+

The CSS selector

+
+ +
+
+ + + +
Return values
+ DOMElement|null + — +

The element matching the selector, or NULL if none is found

+
+ + +
+
+

+ querySelectorAll() + +

+ + +

Equivalent of JavaScripts querySelectorAll, takes a CSS selector, and optionally an array of options.

+ + + public + querySelectorAll(string $selector[, array<string|int, mixed> $options = [] ]) : DOMObject + + +
Parameters
+
+
+ $selector + : string +
+
+

The CSS selector

+
+ +
+
+ $options + : array<string|int, mixed> + = []
+
+

An array of options. The only supported option is "sort" which is true by default. This can be set to false for improved performance, where that is desirable over ordered results.

+
+ +
+
+ + + +
Return values
+ DOMObject + — +

The result set matching the specified selector

+
+ + +
+
+

+ implicitCastDomElement() + +

+ + + + + private + static implicitCastDomElement(mixed $el) : DOMElement + +
+ +
Parameters
+
+
+ $el + : mixed +
+
+
+ +
+
+ + + +
Return values
+ DOMElement + — + + +
+
+

+ implicitCastParentNode() + +

+ + + + + private + implicitCastParentNode() : DOMElement + +
+ + + + +
Return values
+ DOMElement + — + + +
+
+ + + + +
+
+
+
+

Search results

+ +
+
+
    +
    +
    +
    +
    +
    + + +
    + + + + + + + + diff --git a/docs/classes/PerryRylance-DOMDocument-DOMObject.html b/docs/classes/PerryRylance-DOMDocument-DOMObject.html index 3ff2dfe..011f506 100644 --- a/docs/classes/PerryRylance-DOMDocument-DOMObject.html +++ b/docs/classes/PerryRylance-DOMDocument-DOMObject.html @@ -185,6 +185,13 @@

    +
    + __toString() + +  : string +
    +
    Returns this object as a HTML fragment string.
    +
    addClass() @@ -241,6 +248,13 @@

    Returns closest ancestors of this set which matches the given selector. Please note this will NOT work on the document element presently
    +
    + contains() + +  : mixed +
    +
    +
    contents() @@ -307,7 +321,7 @@

    first() -  : DOMElement|null +  : DOMElement|null
    Returns the first result in this set, or null if the set is empty
    @@ -353,6 +367,13 @@

    Checks if any element within this set matches the supplied selector
    +
    + isDocument() + +  : bool +
    +
    Checks if this object contains the document exclusively
    +
    key() @@ -363,7 +384,7 @@

    last() -  : DOMElement|null +  : DOMElement|null
    Returns the last result in this set, or null if the set is empty
    @@ -524,7 +545,7 @@

    wrapInner() -  : DOMElement +  : DOMElement
    Wraps the contents of this set with the specified element or set. This does not presently support a function as input, like it's jQuery counterpart. If this set only contains a single node and $template is a DOMElement, $template will be injected directly into the DOM. If this set contains multiple elements then the wrapper will be cloned. If $template is a DOMObject, only the first element will be used.
    @@ -635,7 +656,7 @@

    @@ -678,7 +699,7 @@

    see
    - DOMElement + DOMElement

    for a list of supported methods

    @@ -751,7 +772,7 @@

    @@ -781,6 +802,41 @@

    Return values
    — + +
    +

    + __toString() + +

    + + +

    Returns this object as a HTML fragment string.

    + + + public + __toString() : string + + + + + +
    Return values
    + string + — +

    Elements in this object rendered to a HTML string fragment

    +
    + +
    @@ -842,7 +898,7 @@

    @@ -850,14 +906,14 @@

    public - after(DOMElement|DOMObject|array<string|int, mixed>|string $arg) : DOMObject + after(DOMElement|DOMObject|array<string|int, mixed>|string $arg) : DOMObject

    Parameters
    $arg - : DOMElement|DOMObject|array<string|int, mixed>|string + : DOMElement|DOMObject|array<string|int, mixed>|string

    The element(s) or text to insert

    @@ -915,7 +971,7 @@

    @@ -923,14 +979,14 @@

    public - append(DOMElement|DOMObject|array<string|int, mixed>|string $subject) : DOMObject + append(DOMElement|DOMObject|array<string|int, mixed>|string $subject) : DOMObject

    Parameters
    $subject - : DOMElement|DOMObject|array<string|int, mixed>|string + : DOMElement|DOMObject|array<string|int, mixed>|string

    The content to insert, can be an element, an array or result set of elements, or a string

    @@ -988,7 +1044,7 @@

    @@ -1109,7 +1165,7 @@

    @@ -1117,14 +1173,14 @@

    public - before(DOMElement|DOMObject|array<string|int, mixed>|string $arg) : DOMObject + before(DOMElement|DOMObject|array<string|int, mixed>|string $arg) : DOMObject

    Parameters
    $arg - : DOMElement|DOMObject|array<string|int, mixed>|string + : DOMElement|DOMObject|array<string|int, mixed>|string

    The element(s) or text to insert

    @@ -1182,7 +1238,7 @@

    @@ -1229,7 +1285,7 @@

    @@ -1264,7 +1320,7 @@

    @@ -1313,6 +1369,58 @@

    Return values
    +
    +
    +

    + contains() + +

    + + + + + public + static contains(DOMElement $container, DOMDocument $contained) : mixed + +
    + +
    Parameters
    +
    +
    + $container + : DOMElement +
    +
    +
    + +
    +
    + $contained + : DOMDocument +
    +
    +
    + +
    +
    + + + +
    Return values
    + mixed + — + +
    @@ -1362,7 +1470,7 @@

    @@ -1395,7 +1503,7 @@

    @@ -1466,7 +1574,7 @@

    @@ -1499,7 +1607,7 @@

    @@ -1601,7 +1709,7 @@

    @@ -1636,7 +1744,7 @@

    @@ -1699,7 +1807,7 @@

    @@ -1762,7 +1870,7 @@

    @@ -1809,7 +1917,7 @@

    @@ -1817,7 +1925,7 @@

    public - first() : DOMElement|null + first() : DOMElement|null @@ -1839,7 +1947,7 @@

    Return values
    - DOMElement|null + DOMElement|null —

    The first element in the set, or null if the set is empty

    @@ -1859,7 +1967,7 @@

    @@ -1906,7 +2014,7 @@

    @@ -1953,7 +2061,7 @@

    @@ -1988,7 +2096,7 @@

    @@ -2035,7 +2143,7 @@

    @@ -2079,7 +2187,7 @@

    @@ -2112,6 +2220,41 @@

    Return values
    +
    +
    +

    + isDocument() + +

    + + +

    Checks if this object contains the document exclusively

    + + + public + isDocument() : bool + + + + + +
    Return values
    + bool + — +

    TRUE if this set contains the document exclusively

    +
    + +
    @@ -2159,7 +2302,7 @@

    @@ -2167,7 +2310,7 @@

    public - last() : DOMElement|null + last() : DOMElement|null @@ -2189,7 +2332,7 @@

    Return values
    - DOMElement|null + DOMElement|null —

    The last element in the set, or null if the set is empty

    @@ -2209,7 +2352,7 @@

    @@ -2253,7 +2396,7 @@

    @@ -2297,7 +2440,7 @@

    @@ -2341,7 +2484,7 @@

    @@ -2393,7 +2536,7 @@

    @@ -2437,7 +2580,7 @@

    @@ -2484,7 +2627,7 @@

    @@ -2492,14 +2635,14 @@

    public - prepend(DOMElement|DOMObject|array<string|int, mixed>|string $subject) : DOMObject + prepend(DOMElement|DOMObject|array<string|int, mixed>|string $subject) : DOMObject

    Parameters
    $subject - : DOMElement|DOMObject|array<string|int, mixed>|string + : DOMElement|DOMObject|array<string|int, mixed>|string

    The content to insert, can be an element, an array or result set of elements, or a string

    @@ -2557,7 +2700,7 @@

    @@ -2604,7 +2747,7 @@

    @@ -2659,7 +2802,7 @@

    @@ -2694,7 +2837,7 @@

    @@ -2739,7 +2882,7 @@

    @@ -2786,7 +2929,7 @@

    @@ -2857,7 +3000,7 @@

    @@ -2890,7 +3033,7 @@

    @@ -2923,7 +3066,7 @@

    @@ -2958,7 +3101,7 @@

    @@ -3004,7 +3147,7 @@

    @@ -3051,7 +3194,7 @@

    @@ -3084,7 +3227,7 @@

    @@ -3131,7 +3274,7 @@

    @@ -3164,7 +3307,7 @@

    @@ -3210,7 +3353,7 @@

    @@ -3218,7 +3361,7 @@

    public - wrapInner(mixed $template) : DOMElement + wrapInner(mixed $template) : DOMElement

    Parameters
    @@ -3236,7 +3379,7 @@
    Parameters
    Return values
    - DOMElement + DOMElement —

    This element, for method chaining

    diff --git a/docs/classes/PerryRylance-DOMDocument.html b/docs/classes/PerryRylance-DOMDocument.html index 97a319c..2c82253 100644 --- a/docs/classes/PerryRylance-DOMDocument.html +++ b/docs/classes/PerryRylance-DOMDocument.html @@ -148,10 +148,17 @@

    +
    + OPTION_DISABLE_HTML_NS + +  = 2 +
    +
    +
    OPTION_EVALUATE_PHP -  = "executePHP" +  = 1
    @@ -190,6 +197,13 @@

    Magic method for getting properties. Only "html" is supported presently.
    +
    + __toString() + +  : string +
    +
    Returns the entire document as a string.
    +
    convertUTF8ToHTMLEntities() @@ -200,14 +214,14 @@

    create() -  : mixed +  : DOMObject
    -
    +
    Creates a HTML fragment from the supplied HTML source string
    getDocumentElementSafe() -  : DOMElement +  : DOMElement
    Function to safely get the document element. Some PHP builds do not implement documentElement, this function can be used to safely retrieve the document element in absense of this property.
    @@ -228,10 +242,17 @@

    loadHTML() -  : This +  : bool
    Loads the supplied HTML string
    +
    + loadHTMLFile() + +  : bool +
    +
    Loads the supplied HTML file
    +
    save() @@ -256,9 +277,9 @@

    shorthand() -  : mixed +  : callable
    -
    +
    Returns a "shorthand" function which you can use in a jQuery-like manner to create fragemnts, eg $_ = $doc->shorthand(); $div = $_("<div>Example</div>);
    onLoaded() @@ -267,13 +288,6 @@

    Callback which fires after the HTML has been parsed and loaded, but before loadHTML returns. Useful for controlling the execution order for operations spread across an inheritance chain.
    -
    - assertNotEmpty() - -  : mixed -
    -
    -

    @@ -285,6 +299,35 @@

    +

    + OPTION_DISABLE_HTML_NS + +

    + + + + + + public + mixed + OPTION_DISABLE_HTML_NS + = 2 + + + +
    + +
    + + + +
    +

    OPTION_EVALUATE_PHP @@ -302,7 +345,7 @@

    public mixed OPTION_EVALUATE_PHP - = "executePHP" + = 1 @@ -322,7 +365,7 @@

    @@ -366,7 +409,7 @@

    @@ -404,7 +447,7 @@

    @@ -445,7 +488,7 @@

    see
    - DOMElement + DOMElement

    for a list of supported methods

    @@ -472,7 +515,7 @@

    @@ -524,7 +567,7 @@

    @@ -554,6 +597,41 @@

    Return values
    — +
    +
    +

    + __toString() + +

    + + +

    Returns the entire document as a string.

    + + + public + __toString() : string + + + + + +
    Return values
    + string + — +

    The entire document rendered to a string

    +
    + +
    @@ -615,25 +693,26 @@

    - +

    Creates a HTML fragment from the supplied HTML source string

    + public - create(mixed $html) : mixed - -
    + create(string $html) : DOMObject +

    Parameters
    $html - : mixed + : string
    -
    +

    The HTML source string

    +
    @@ -641,9 +720,11 @@
    Parameters
    Return values
    - mixed + DOMObject — - +

    The resulting element(s)

    +
    +
    @@ -667,14 +748,14 @@

    public - getDocumentElementSafe() : DOMElement + getDocumentElementSafe() : DOMElement

    Return values
    - DOMElement + DOMElement —

    The document element for this document

    @@ -694,7 +775,7 @@

    @@ -741,7 +822,7 @@

    @@ -749,14 +830,14 @@

    public - load(mixed $filename[, array<string|int, mixed> $options = array() ]) : This + load(string $filename[, int $options = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS ]) : This

    Parameters
    $filename - : mixed + : string
    @@ -764,10 +845,10 @@
    Parameters
    $options - : array<string|int, mixed> - = array()
    + : int + = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS
    -

    An array of options. Presently only DOMDocument::OPTION_EVALUATE_PHP is supported, this defaults to TRUE and will execute inline PHP

    +

    A bit field of options. Presently only DOMDocument::OPTION_EVALUATE_PHP is supported, this defaults to TRUE and will execute inline PHP

    @@ -812,7 +893,7 @@

    @@ -820,7 +901,7 @@

    public - loadHTML(string $src[, array<string|int, mixed> $options = array() ]) : This + loadHTML(string $src[, int $options = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS ]) : bool

    Parameters
    @@ -836,10 +917,10 @@
    Parameters
    $options - : array<string|int, mixed> - = array()
    + : int + = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS
    -

    An array of options. Presently only DOMDocument::OPTION_EXECUTE_PHP is supported, this defaults to TRUE and will execute inline PHP

    +

    A bit field of options. Presently only DOMDocument::OPTION_EXECUTE_PHP is supported, this defaults to TRUE and will execute inline PHP

    @@ -864,9 +945,81 @@
    Return values
    - This + bool — -

    document, for method chaining

    +

    true

    +
    + + +
    +
    +

    + loadHTMLFile() + +

    + + +

    Loads the supplied HTML file

    + + + public + loadHTMLFile(string $filename[, int $options = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS ]) : bool + + +
    Parameters
    +
    +
    + $filename + : string +
    +
    +

    The file to parse

    +
    + +
    +
    + $options + : int + = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS
    +
    +

    A bit field of options. Presently only DOMDocument::OPTION_EXECUTE_PHP is supported, this defaults to TRUE and will execute inline PHP

    +
    + +
    +
    + + +
    + Tags + +
    +
    +
    + see +
    +
    + https://github.com/Masterminds/html5-php#options + +

    for other options supported by the HTML5 parser

    +
    + +
    +
    + +
    Return values
    + bool + — +

    true

    @@ -884,7 +1037,7 @@

    @@ -954,7 +1107,7 @@

    @@ -1023,7 +1176,7 @@

    @@ -1058,24 +1211,26 @@

    - +

    Returns a "shorthand" function which you can use in a jQuery-like manner to create fragemnts, eg $_ = $doc->shorthand(); $div = $_("<div>Example</div>);

    + public - shorthand() : mixed - -
    + shorthand() : callable +

    Return values
    - mixed + callable — - +

    A convenience function which creates HTML fragments from a string

    +
    +
    -
    -

    - assertNotEmpty() - -

    - - - - - private - assertNotEmpty() : mixed - -
    - - - - -
    Return values
    - mixed - — - -
    diff --git a/docs/files/src-domdocument-domelement.html b/docs/files/src-domdocument-domelement.html index 060ba20..534e27c 100644 --- a/docs/files/src-domdocument-domelement.html +++ b/docs/files/src-domdocument-domelement.html @@ -102,6 +102,18 @@

    DOMElement.php

    +

    + Interfaces, Classes, Traits and Enums + +

    + +
    + +
    DOMElement
    +
    This class is used to represent elements, and implements many jQuery-like functions for the elements
    + + +
    diff --git a/docs/files/tests-domdocumenttest.html b/docs/files/tests-domdocumenttest.html index 4dafb5d..b076249 100644 --- a/docs/files/tests-domdocumenttest.html +++ b/docs/files/tests-domdocumenttest.html @@ -118,59 +118,10 @@

    -

    - Table of Contents - -

    - -
    -
    - DEBUG - -  = true -
    -
    - -
    -
    -

    - Constants - -

    -
    -

    - DEBUG - -

    - - - - - - public - mixed - DEBUG - = true - - - -
    - -
    - - - -
    -
    diff --git a/docs/index.html b/docs/index.html index ef296b8..c6309c1 100644 --- a/docs/index.html +++ b/docs/index.html @@ -125,57 +125,8 @@

    -

    - Table of Contents - -

    - -
    -
    - DEBUG - -  = true -
    -
    - -
    - - -
    -

    - Constants - -

    -
    -

    - DEBUG - -

    - - - - public - mixed - DEBUG - = true - - - -
    - -
    - - - -
    -
    diff --git a/docs/js/searchIndex.js b/docs/js/searchIndex.js index 1ce2ec5..a82c2b4 100644 --- a/docs/js/searchIndex.js +++ b/docs/js/searchIndex.js @@ -1,6 +1,66 @@ Search.appendIndex( [ { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMElement", + "name": "DOMElement", + "summary": "This\u0020class\u0020is\u0020used\u0020to\u0020represent\u0020elements,\u0020and\u0020implements\u0020many\u0020jQuery\u002Dlike\u0020functions\u0020for\u0020the\u0020elements", + "url": "classes/PerryRylance-DOMDocument-DOMElement.html" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMElement\u003A\u003A__construct\u0028\u0029", + "name": "__construct", + "summary": "Constructor\u0020for\u0020a\u0020DOMElement.\u0020This\u0020should\u0020not\u0020be\u0020called\u0020directly.\u0020Use\u0020the\u0020document\u0027s\u0020createElement\u0020method\u0020instead", + "url": "classes/PerryRylance-DOMDocument-DOMElement.html#method___construct" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMElement\u003A\u003AimplicitCastParentNode\u0028\u0029", + "name": "implicitCastParentNode", + "summary": "", + "url": "classes/PerryRylance-DOMDocument-DOMElement.html#method_implicitCastParentNode" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMElement\u003A\u003AimplicitCastDomElement\u0028\u0029", + "name": "implicitCastDomElement", + "summary": "", + "url": "classes/PerryRylance-DOMDocument-DOMElement.html#method_implicitCastDomElement" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMElement\u003A\u003AisBefore\u0028\u0029", + "name": "isBefore", + "summary": "Test\u0020if\u0020this\u0020element\u0020comes\u0020before\u0020the\u0020other\u0020element\u0020in\u0020the\u0020DOM\u0020tree", + "url": "classes/PerryRylance-DOMDocument-DOMElement.html#method_isBefore" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMElement\u003A\u003AgetBreadth\u0028\u0029", + "name": "getBreadth", + "summary": "Returns\u0020the\u0020breadth\u0020\u0028sometimes\u0020called\u0020child\u0020index\u0029\u0020of\u0020this\u0020node\u0020in\u0020regards\u0020to\u0020it\u0027s\u0020siblings", + "url": "classes/PerryRylance-DOMDocument-DOMElement.html#method_getBreadth" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMElement\u003A\u003AgetDepth\u0028\u0029", + "name": "getDepth", + "summary": "Returns\u0020the\u0020depth\u0020of\u0020this\u0020node\u0020in\u0020regards\u0020to\u0020it\u0027s\u0020ancestors", + "url": "classes/PerryRylance-DOMDocument-DOMElement.html#method_getDepth" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMElement\u003A\u003A__get\u0028\u0029", + "name": "__get", + "summary": "Getter.\u0020The\u0020only\u0020supported\u0020property\u0020is\u0020html", + "url": "classes/PerryRylance-DOMDocument-DOMElement.html#method___get" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMElement\u003A\u003A__set\u0028\u0029", + "name": "__set", + "summary": "", + "url": "classes/PerryRylance-DOMDocument-DOMElement.html#method___set" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMElement\u003A\u003AquerySelectorAll\u0028\u0029", + "name": "querySelectorAll", + "summary": "Equivalent\u0020of\u0020JavaScripts\u0020querySelectorAll,\u0020takes\u0020a\u0020CSS\u0020selector,\u0020and\u0020optionally\u0020an\u0020array\u0020of\u0020options.", + "url": "classes/PerryRylance-DOMDocument-DOMElement.html#method_querySelectorAll" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMElement\u003A\u003AquerySelector\u0028\u0029", + "name": "querySelector", + "summary": "Equivalent\u0020of\u0020JavaScripts\u0020querySelector.\u0020This\u0020will\u0020return\u0020the\u0020first\u0020element\u0020matching\u0020the\u0020specified\u0020selector,\u0020or\u0020NULL\u0020when\u0020no\u0020elements\u0020match", + "url": "classes/PerryRylance-DOMDocument-DOMElement.html#method_querySelector" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMElement\u003A\u003A__toString\u0028\u0029", + "name": "__toString", + "summary": "Returns\u0020this\u0020element\u0020as\u0020a\u0020HTML\u0020fragment\u0020string.", + "url": "classes/PerryRylance-DOMDocument-DOMElement.html#method___toString" + }, { "fqsen": "\\PerryRylance\\DOMDocument\\DOMObject", "name": "DOMObject", "summary": "This\u0020class\u0020is\u0020used\u0020to\u0020represent\u0020a\u0020results\u0020set\u0020of\u0020matched\u0020elements,\u0020in\u0020much\u0020the\u0020same\u0020way\u0020as\u0020a\u0020jQuery\u0020array\u0020works.\u0020Any\u0020methods\u0020supported\u0020by\u0020DOMElement\u0020can\u0020be\u0020called\u0020on\u0020a\u0020DOMObject\u0020list.", @@ -15,6 +75,11 @@ Search.appendIndex( "name": "implicitOwnerDocumentCast", "summary": "", "url": "classes/PerryRylance-DOMDocument-DOMObject.html#method_implicitOwnerDocumentCast" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMObject\u003A\u003Acontains\u0028\u0029", + "name": "contains", + "summary": "", + "url": "classes/PerryRylance-DOMDocument-DOMObject.html#method_contains" }, { "fqsen": "\\PerryRylance\\DOMDocument\\DOMObject\u003A\u003AtoArray\u0028\u0029", "name": "toArray", @@ -120,6 +185,11 @@ Search.appendIndex( "name": "is", "summary": "Checks\u0020if\u0020any\u0020element\u0020within\u0020this\u0020set\u0020matches\u0020the\u0020supplied\u0020selector", "url": "classes/PerryRylance-DOMDocument-DOMObject.html#method_is" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMObject\u003A\u003AisDocument\u0028\u0029", + "name": "isDocument", + "summary": "Checks\u0020if\u0020this\u0020object\u0020contains\u0020the\u0020document\u0020exclusively", + "url": "classes/PerryRylance-DOMDocument-DOMObject.html#method_isDocument" }, { "fqsen": "\\PerryRylance\\DOMDocument\\DOMObject\u003A\u003Aduplicate\u0028\u0029", "name": "duplicate", @@ -270,6 +340,11 @@ Search.appendIndex( "name": "import", "summary": "Imports\u0020the\u0020supplied\u0020subject\u0020and\u0020appends\u0020it\u0020to\u0020this\u0020set.\u0020Noop\u0020when\u0020this\u0020set\u0020is\u0020empty.", "url": "classes/PerryRylance-DOMDocument-DOMObject.html#method_import" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\\DOMObject\u003A\u003A__toString\u0028\u0029", + "name": "__toString", + "summary": "Returns\u0020this\u0020object\u0020as\u0020a\u0020HTML\u0020fragment\u0020string.", + "url": "classes/PerryRylance-DOMDocument-DOMObject.html#method___toString" }, { "fqsen": "\\PerryRylance\\DOMDocument\\DOMObject\u003A\u003A\u0024index", "name": "index", @@ -308,13 +383,18 @@ Search.appendIndex( }, { "fqsen": "\\PerryRylance\\DOMDocument\u003A\u003Ashorthand\u0028\u0029", "name": "shorthand", - "summary": "", + "summary": "Returns\u0020a\u0020\u0022shorthand\u0022\u0020function\u0020which\u0020you\u0020can\u0020use\u0020in\u0020a\u0020jQuery\u002Dlike\u0020manner\u0020to\u0020create\u0020fragemnts,\u0020eg\u0020\u0024_\u0020\u003D\u0020\u0024doc\u002D\u003Eshorthand\u0028\u0029\u003B\u0020\u0024div\u0020\u003D\u0020\u0024_\u0028\u0022\u003Cdiv\u003EExample\u003C\/div\u003E\u0029\u003B", "url": "classes/PerryRylance-DOMDocument.html#method_shorthand" }, { "fqsen": "\\PerryRylance\\DOMDocument\u003A\u003AloadHTML\u0028\u0029", "name": "loadHTML", "summary": "Loads\u0020the\u0020supplied\u0020HTML\u0020string", "url": "classes/PerryRylance-DOMDocument.html#method_loadHTML" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\u003A\u003AloadHTMLFile\u0028\u0029", + "name": "loadHTMLFile", + "summary": "Loads\u0020the\u0020supplied\u0020HTML\u0020file", + "url": "classes/PerryRylance-DOMDocument.html#method_loadHTMLFile" }, { "fqsen": "\\PerryRylance\\DOMDocument\u003A\u003AonLoaded\u0028\u0029", "name": "onLoaded", @@ -350,21 +430,26 @@ Search.appendIndex( "name": "import", "summary": "This\u0020function\u0020will\u0020import\u0020the\u0020specified\u0020content\u0020to\u0020be\u0020used\u0020inside\u0020this\u0020document.", "url": "classes/PerryRylance-DOMDocument.html#method_import" - }, { - "fqsen": "\\PerryRylance\\DOMDocument\u003A\u003AassertNotEmpty\u0028\u0029", - "name": "assertNotEmpty", - "summary": "", - "url": "classes/PerryRylance-DOMDocument.html#method_assertNotEmpty" }, { "fqsen": "\\PerryRylance\\DOMDocument\u003A\u003Acreate\u0028\u0029", "name": "create", - "summary": "", + "summary": "Creates\u0020a\u0020HTML\u0020fragment\u0020from\u0020the\u0020supplied\u0020HTML\u0020source\u0020string", "url": "classes/PerryRylance-DOMDocument.html#method_create" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\u003A\u003A__toString\u0028\u0029", + "name": "__toString", + "summary": "Returns\u0020the\u0020entire\u0020document\u0020as\u0020a\u0020string.", + "url": "classes/PerryRylance-DOMDocument.html#method___toString" }, { "fqsen": "\\PerryRylance\\DOMDocument\u003A\u003AOPTION_EVALUATE_PHP", "name": "OPTION_EVALUATE_PHP", "summary": "", "url": "classes/PerryRylance-DOMDocument.html#constant_OPTION_EVALUATE_PHP" + }, { + "fqsen": "\\PerryRylance\\DOMDocument\u003A\u003AOPTION_DISABLE_HTML_NS", + "name": "OPTION_DISABLE_HTML_NS", + "summary": "", + "url": "classes/PerryRylance-DOMDocument.html#constant_OPTION_DISABLE_HTML_NS" }, { "fqsen": "\\PerryRylance\\DOMDocument\u003A\u003AUNDEFINED", "name": "UNDEFINED", @@ -375,11 +460,6 @@ Search.appendIndex( "name": "constructorCalled", "summary": "", "url": "classes/PerryRylance-DOMDocument.html#property_constructorCalled" - }, { - "fqsen": "\\DEBUG", - "name": "DEBUG", - "summary": "", - "url": "namespaces/default.html#constant_DEBUG" }, { "fqsen": "\\DOMDocumentBadInit", "name": "DOMDocumentBadInit", @@ -550,6 +630,21 @@ Search.appendIndex( "name": "testOutputNotEmpty", "summary": "", "url": "classes/DOMDocumentTest.html#method_testOutputNotEmpty" + }, { + "fqsen": "\\DOMDocumentTest\u003A\u003AtestCastDocumentToString\u0028\u0029", + "name": "testCastDocumentToString", + "summary": "", + "url": "classes/DOMDocumentTest.html#method_testCastDocumentToString" + }, { + "fqsen": "\\DOMDocumentTest\u003A\u003AtestCastDomObjectToString\u0028\u0029", + "name": "testCastDomObjectToString", + "summary": "", + "url": "classes/DOMDocumentTest.html#method_testCastDomObjectToString" + }, { + "fqsen": "\\DOMDocumentTest\u003A\u003AtestCastElementToString\u0028\u0029", + "name": "testCastElementToString", + "summary": "", + "url": "classes/DOMDocumentTest.html#method_testCastElementToString" }, { "fqsen": "\\", "name": "\\", diff --git a/docs/namespaces/default.html b/docs/namespaces/default.html index 4854698..51ad9e4 100644 --- a/docs/namespaces/default.html +++ b/docs/namespaces/default.html @@ -120,57 +120,8 @@

    -

    - Table of Contents - -

    - -
    -
    - DEBUG - -  = true -
    -
    - -
    -
    -

    - Constants - -

    -
    -

    - DEBUG - -

    - - - - - - public - mixed - DEBUG - = true - - - -
    - -
    - - - -
    -
    diff --git a/docs/namespaces/perryrylance-domdocument.html b/docs/namespaces/perryrylance-domdocument.html index a991945..fca1857 100644 --- a/docs/namespaces/perryrylance-domdocument.html +++ b/docs/namespaces/perryrylance-domdocument.html @@ -104,6 +104,8 @@

    +
    DOMElement
    +
    This class is used to represent elements, and implements many jQuery-like functions for the elements
    DOMObject
    This class is used to represent a results set of matched elements, in much the same way as a jQuery array works. Any methods supported by DOMElement can be called on a DOMObject list.
    diff --git a/docs/packages/Application.html b/docs/packages/Application.html index 23b1255..07104fe 100644 --- a/docs/packages/Application.html +++ b/docs/packages/Application.html @@ -103,6 +103,8 @@

    +
    DOMElement
    +
    This class is used to represent elements, and implements many jQuery-like functions for the elements
    DOMObject
    This class is used to represent a results set of matched elements, in much the same way as a jQuery array works. Any methods supported by DOMElement can be called on a DOMObject list.
    DOMDocument
    @@ -116,57 +118,8 @@

    -

    - Table of Contents - -

    - -
    -
    - DEBUG - -  = true -
    -
    - -
    -
    -

    - Constants - -

    -
    -

    - DEBUG - -

    - - - - - - public - mixed - DEBUG - = true - - - -
    - -
    - - - -
    -
    diff --git a/docs/reports/markers.html b/docs/reports/markers.html index 5b0104d..41d0263 100644 --- a/docs/reports/markers.html +++ b/docs/reports/markers.html @@ -101,10 +101,6 @@

    Table of Contents

    src/DOMDocument/DOMObject.php 6 - - - src/DOMDocument.php - 1 @@ -126,48 +122,30 @@

    DOMObject.php

    TODO - 54 + 65 Test that this returns by value and not by reference. External code should NOT manipulate this set TODO - 72 + 83 We've made a special exception for querySelectorAll here so that "is" can work and so that the "closest" test passes. "is" uses the parent of the subject element and performs a query selector all / find with the selector passed to "is". If the element calling "is" matches itself in the results from it's parents query selector all, then "is" returns true. The first expression here stops the exception from being raised and allows this to continue working. This should be removed when querySelectorAll is removed. TODO - 354 + 375 Is it sensible to return query results here? How will this handle non-element nodes? TODO - 235 + 246 Review this, it should return a results set, should it be any empty array on an empty set? I expect so TODO - 248 + 259 Review this, it should return a results set, should it be any empty array on an empty set? I expect so - - -

    DOMDocument.php

    - - - - - - - - - - - - - - -
    TypeLineDescription
    TODO18Change at some point to match up, find as a constant for now
    diff --git a/src/DOMDocument.php b/src/DOMDocument.php index f452aef..11e2548 100644 --- a/src/DOMDocument.php +++ b/src/DOMDocument.php @@ -146,7 +146,11 @@ public function __call($name, $arguments) throw new \Exception("No such method $name"); } - public function shorthand() + /** + * Returns a "shorthand" function which you can use in a jQuery-like manner to create fragemnts, eg $_ = $doc->shorthand(); $div = $_("
    Example
    ); + * @return callable A convenience function which creates HTML fragments from a string + */ + public function shorthand(): callable { return function($subject) { return new DOMObject($subject); @@ -197,6 +201,18 @@ public function loadHTML(string $src, int $options = DOMDocument::OPTION_EVALUAT return true; } + /** + * Loads the supplied HTML file + * @param string $filename The file to parse + * @param int $options A bit field of options. Presently only DOMDocument::OPTION_EXECUTE_PHP is supported, this defaults to TRUE and will execute inline PHP + * @see https://github.com/Masterminds/html5-php#options for other options supported by the HTML5 parser + * @return bool true + */ + public function loadHTMLFile(string $filename, int $options = DOMDocument::OPTION_EVALUATE_PHP | DOMDocument::OPTION_DISABLE_HTML_NS): bool + { + return $this->loadHTML($filename, $options); + } + /** * Callback which fires after the HTML has been parsed and loaded, but before loadHTML returns. Useful for controlling the execution order for operations spread across an inheritance chain. * @return null @@ -232,7 +248,7 @@ public function load(string $filename, int $options = DOMDocument::OPTION_EVALUA * @param array $options An array of options to pass to the HTML5 parser * @see https://github.com/Masterminds/html5-php#options for other options supported by the HTML5 parser */ - public function saveHTML($element=null, $options=array()): string|false + public function saveHTML($element=null, $options=array()): string | false { if($element == null) $element = $this; @@ -286,7 +302,7 @@ public function getDocumentElementSafe() * This function saves only the inside of the element of this document. This is useful when you want to import a HTML document into another, but you don't want to end up with nested elements. This is equivalent to using the "html" property. * @return string The HTML string */ - public function saveInnerBody() + public function saveInnerBody(): string { $body = null; $result = ''; @@ -334,13 +350,12 @@ public function import($subject) return $results; } - private function assertNotEmpty() - { - if(empty($this->getDocumentElementSafe())) - throw new \Exception('Document is empty'); - } - - public function create($html) + /** + * Creates a HTML fragment from the supplied HTML source string + * @param string $html The HTML source string + * @return DOMObject The resulting element(s) + */ + public function create(string $html): DOMObject { $div = $this->createElement("div"); $set = new DOMObject($div); @@ -355,4 +370,13 @@ public function create($html) return new DOMObject($arr); } + + /** + * Returns the entire document as a string. + * @return string The entire document rendered to a string + */ + public function __toString() + { + return $this->saveHTML(); + } } diff --git a/src/DOMDocument/DOMElement.php b/src/DOMDocument/DOMElement.php index 99ff40c..fcfae0f 100644 --- a/src/DOMDocument/DOMElement.php +++ b/src/DOMDocument/DOMElement.php @@ -176,6 +176,15 @@ public function querySelector($selector) return $results[0]; } + + /** + * Returns this element as a HTML fragment string. + * @return string Elements in this element rendered to a HTML string fragment + */ + public function __toString() + { + return $this->html; + } /** * @ignore diff --git a/src/DOMDocument/DOMObject.php b/src/DOMDocument/DOMObject.php index 116a9c9..def5d67 100644 --- a/src/DOMDocument/DOMObject.php +++ b/src/DOMDocument/DOMObject.php @@ -1314,6 +1314,15 @@ public function import($subject) return $this; } + + /** + * Returns this object as a HTML fragment string. + * @return string Elements in this object rendered to a HTML string fragment + */ + public function __toString() + { + return $this->html; + } } class_alias(DOMObject::class, '\PerryRylance\DOMDocument\DOMQueryResults'); \ No newline at end of file diff --git a/tests/DOMDocumentTest.php b/tests/DOMDocumentTest.php index c8f9c4b..0a174fe 100644 --- a/tests/DOMDocumentTest.php +++ b/tests/DOMDocumentTest.php @@ -13,7 +13,7 @@ public function __construct() final class DOMDocumentTest extends TestCase { - private function getDocument() + private function getDocument(): DOMDocument { $document = new DOMDocument(); $document->load(__DIR__ . "/sample.html"); @@ -447,4 +447,42 @@ public function testOutputNotEmpty() $this->assertNotEmpty($document->html); } + + public function testCastDocumentToString() + { + // NB: The renderer has different ideas about whitespace and self closing elements so I've baked in the formatted document for use here. + $file = __DIR__ . "/formatted.html"; + $source = file_get_contents($file); + + $document = $this->getDocument(); + $string = (string)$document; + + $this->assertStringEqualsStringIgnoringLineEndings($source, $string); + } + + public function testCastDomObjectToString() + { + $source = str_repeat("
    Testing...
    ", 3); + + $document = new DOMDocument(); + $document->loadHTML("$source"); + + $divs = $document->find('div'); + $string = (string)$divs; + + $this->assertStringEqualsStringIgnoringLineEndings($source, $string); + } + + public function testCastElementToString() + { + $source = '
    Test
    '; + + $document = new DOMDocument(); + $document->loadHTML($source); + + $div = $document->find("#test")[0]; + $string = (string)$div; + + $this->assertEquals($source, $string); + } } diff --git a/tests/formatted.html b/tests/formatted.html new file mode 100644 index 0000000..2f6a92f --- /dev/null +++ b/tests/formatted.html @@ -0,0 +1,80 @@ + + + + PerryRylance\DOMDocument Test + + + + + + + + +
    +
    +
    +
    + + +
    + + The content of the document...... + + + +
    This should be removed
    + +
      +
    • +
    + +
    +
    + + + + +
    +
    + + + +
    +
    + +
    + Should only match span +
    + +
    +
      +
    • This test failed
      • +
    • This test failed
      • +
    • This test failed
      • +
    +
    + + Visit my blog + + + +