Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/scotteh/php-dom-wrapper

Simple DOM wrapper library to manipulate and traverse HTML documents similar to jQuery
https://github.com/scotteh/php-dom-wrapper
autoloader composer dom dom-wrapper-library html manipulation parser php php-dom-wrapper traversal traverse-html-documents
Last synced: about 10 hours ago
JSON representation
Simple DOM wrapper library to manipulate and traverse HTML documents similar to jQuery
Host: GitHub
URL: https://github.com/scotteh/php-dom-wrapper
Owner: scotteh
License: bsd-3-clause
Created: 2015-05-05T13:14:31.000Z (over 9 years ago)
Default Branch: master
Last Pushed: 2024-02-22T13:04:38.000Z (10 months ago)
Last Synced: 2024-05-18T07:02:41.758Z (7 months ago)
Topics: autoloader, composer, dom, dom-wrapper-library, html, manipulation, parser, php, php-dom-wrapper, traversal, traverse-html-documents
Language: PHP
Homepage:
Size: 206 KB
Stars: 137
Watchers: 10
Forks: 33
Open Issues: 4
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

README

        # PHP DOM Wrapper

## Intro

PHP DOM Wrapper is a simple DOM wrapper library to manipulate and traverse HTML documents. Based around jQuery's manipulation and traversal methods, largely mimicking the behaviour of it's jQuery counterparts.

## Author

 - Andrew Scott ([email protected])

## Requirements

 - PHP 8.0 or later

 - PSR-4 compatible autoloader

## Install

Install with [Composer](https://getcomposer.org/doc/).

```

composer require scotteh/php-dom-wrapper

```

## Autoloading

This library requires an autoloader, if you aren't already using one you can include [Composers autoloader](https://getcomposer.org/doc/01-basic-usage.md#autoloading).

``` php

require 'vendor/autoload.php';

```

## Methods

### Manipulation

| Method | jQuery Equivalent *(if different)* |

|--------|------------------------------|

| [addClass()](#addClass)    |

| [follow()](#follow)       | *after()* |

| [appendWith()](#appendWith)      | *append()* |

| [appendTo()](#appendTo)    |

| [attr()](#attr)        |

| [clone()](#clone)       |

| [destroy()](#destroy)      | *remove()* |

| [detach()](#detach)      |

| [empty()](#empty)       |

| [hasClass()](#hasClass)    |

| [html()](#html)        |

| [precede()](#precede)      | *before()* |

| [prependWith()](#prependWith)     | *prepend()* |

| [prependTo()](#prependTo)   |

| [removeAttr()](#removeAttr)  |

| [removeClass()](#removeClass) |

| [substituteWith()](#substituteWith) | *replaceWith()* |

| [text()](#text)        |

| [unwrap()](#unwrap)      |

| [wrap()](#wrap)        |

| [wrapAll()](#wrapAll)     |

| [wrapInner()](#wrapInner)   |

### Traversal

| Method | jQuery Equivalent *(if different)* |

|--------|------------------------------|

| [add()](#add)          |

| [children()](#children)     |

| [closest()](#closest)      |

| [contents()](#contents)     |

| [eq()](#eq)           |

| [filter()](#filter)       |

| [find()](#find)         |

| [first()](#first)        |

| [has()](#has)          |

| [is()](#is)           |

| [last()](#last)         |

| [map()](#map)          |

| [following()](#following)         | *next()* |

| [followingAll()](#followingAll)      | *nextAll()* |

| [followingUntil()](#followingUntil)    | *nextUntil()* |

| [not()](#not)          |

| [parent()](#parent)       |

| [parents()](#parents)      |

| [parentsUntil()](#parentsUntil) |

| [preceding()](#preceding)         | *prev()* |

| [precedingAll()](#precedingAll)      | *prevAll()* |

| [precedingUntil()](#precedingUntil)    | *prevUntil()* |

| [siblings()](#siblings)     |

| [slice()](#slice)        |

### Other

| Method | jQuery Equivalent *(if different)* |

|--------|------------------------------|

| [count()](#count)        | *length* (property) |

| [each()](#each)

## Usage

Example #1:

``` php

use DOMWrap\Document;

$html = '


First

Second

Third

';

$doc = new Document();

$doc->html($html);

$nodes = $doc->find('li');

// Returns '3'

var_dump($nodes->count());

// Append as a child node to each 


$nodes->appendWith('!');

// Returns: 


First!



Second!



Third!





var_dump($doc->html());

```

---

## Methods

### Manipulation

#### addClass

```

self addClass(string|callable $class)

```

##### Example

```php

$doc = (new Document())->html('
first paragraph

second paragraph');

$doc->find('p')->addClass('text-center');

```

*Result:*

``` html

first paragraph

second paragraph

```

---

#### follow

```

self follow(string|NodeList|\DOMNode|callable $input)

```

Insert the argument as a sibling directly after each of the nodes operated on.

##### Example

``` php

$doc = (new Document())->html('


first

second

');

$doc->find('li')->first()->follow('
first-and-a-half
');

```

*Result:*

``` html



    first

    first-and-a-half

    second



```

---

#### appendWith

```

self appendWith(string|NodeList|\DOMNode|callable $input)

```

##### Example

``` php

$doc = (new Document())->html('
The quick brown fox jumps over the lazy dog');

$doc->find('div')->appendWith(' Appended!');

```

*Result:*

``` html

The quick brown fox jumps over the lazy dog Appended!



```

---

#### appendTo

```

self appendTo(string|NodeList|\DOMNode $selector)

```

##### Example

``` php

$doc = (new Document())->html('
The quick brown fox jumps over the lazy dog');

$doc->create(' Appended!')->appendTo('div');

```

*Result:*

``` html

The quick brown fox jumps over the lazy dog Appended!



```

---

#### attr

```

self|string attr(string $name[, mixed $value = null])

```

##### Example #1 (Set)

``` php

$doc = (new Document())->html('
');

$doc->attr('class', 'text-left');

```

*Result:*

``` html



```

##### Example #2 (Get)

``` php

$doc = (new Document())->html('
');

echo $doc->attr('text-center');

```

*Result:*

``` html

text-center

```

---

#### precede

```

self precede(string|NodeList|\DOMNode|callable $input)

```

Insert the argument as a sibling just before each of the nodes operated on.

##### Example

``` php

$doc = (new Document())->html('


first

second

');

doc->find('li')->first()->precede('zeroth');

```

*Result:*

``` html



    zeroth

    first

    second



```

---

#### clone

```

NodeList|\DOMNode clone()

```

##### Example

``` php

$doc = (new Document())->html('
Item');

$doc->find('div')->clone()->appendTo('ul'); 

```

*Result:*

``` html



Item

Item



```

---

#### destroy

```

self destroy([string $selector = null])

```

##### Example

``` php

$doc = (new Document())->html('






');

$doc->find('.first')->destroy();

```

*Result:*

``` html



```

---

#### detach

```

NodeList detach([string $selector = null])

```

##### Example

``` php

$doc = (new Document())->html('
Item
');

$el = $doc->find('ul.first li')->detach();

$doc->first('ul.second').append($el); 

```

*Result:*

``` html

Item

```

---

#### empty

```

self empty()

```

##### Example

``` php

$doc = (new Document())->html('
The quick brown fox jumps over the lazy dog');

$doc->find('div')->empty(); 

```

*Result:*

``` html



```

---

#### hasClass

```

bool hasClass(string $class)

```

##### Example

``` php

$doc = (new Document())->html('
');

echo $doc->first('div')->hasClass('text-center');

```

*Result:*

``` html

true

```

---

#### html

```

string|self html([string|NodeList|\DOMNode|callable $input = null])

```

##### Example #1 (Set)

``` php

$doc = (new Document());

$doc->html('
');

```

*Result:*

``` html



```

##### Example #1 (Get)

``` php

$doc = (new Document())->html('
');

$doc->find('div')->appendWith('Example!');

echo $doc->html();

```

*Result:*

``` html

Example!

```

---

#### prependWith

```

self prependWith(string|NodeList|\DOMNode|callable $input)

```

##### Example

``` php

$doc = (new Document())->html('
The quick brown fox jumps over the lazy dog');

$doc->find('div')->prependWith('Prepended! ');

```

*Result:*

``` html



Prepended! The quick brown fox jumps over the lazy dog

```

---

#### prependTo

```

self prependTo(string|NodeList|\DOMNode $selector)

```

##### Example

``` php

$doc = (new Document())->html('
The quick brown fox jumps over the lazy dog');

$doc->create('Prepended! ')->appendTo('div');

```

*Result:*

``` html



Prepended! The quick brown fox jumps over the lazy dog

```

---

#### removeAttr

```

self removeAttr(string $name)

```

##### Example

``` php

$doc = (new Document())->html('
');

$doc->find('div').removeAttr('class');

```

*Result:*

``` html



```

---

#### removeClass

```

self removeClass(string|callable $class)

```

##### Example

``` php

$doc = (new Document())->html('
');

$doc->find('div').removeClass('first');

```

*Result:*

``` html



```

---

#### substituteWith

```

self substituteWith(string|NodeList|\DOMNode|callable $input)

```

Replace each node in the current set with the contents provided.

##### Example

``` php

$doc = (new Document())->html('
Hello World!');

$doc->find('b')->substituteWith(function($node) {

    return '' . $node->text() . '';

});

echo $doc->html();

```

*Result:*

``` html

Hello World!

```

---

#### text

```

string|self text([string|NodeList|\DOMNode|callable $input = null])

```

Get the text contents of the current set.

##### Example (get)

``` php

$doc = (new Document())->html('
Hello World!');

echo $doc->find('.text')->text();

```

*Result:*

``` html

Hello World!

```

Set the text contents for current set.

##### Example (set)

``` php

$doc = (new Document())->html('
The quick brown fox jumps over the lazy dog

');

$doc->find('.text')->text('Hello World!');

echo $doc->html();

```

*Result:*

``` html

Hello World!

```

---

#### unwrap

```

self unwrap()

```

Unwrap each current node by removing its parent, replacing the parent

with its children (i.e. the current node and its siblings).

Note that each node is operated on separately, so when you call

`unwrap()` on a `NodeList` containing two siblings, *two* parents will

be removed.

##### Example

``` php

$doc = (new Document())->html('






');

$doc->find('#first')->unwrap();

```

*Result:*

``` html





```

---

#### wrap

```

self wrap(string|NodeList|\DOMNode|callable $input)

```

Wrap the current node or nodes in the given structure.

The wrapping structure can be nested, but should only contain one node

on each level (any extra siblings are removed). The outermost node

replaces the node operated on, while the node operated on is put into

the innermost node.

If called on a `NodeList`, each of nodes in the list will be separately

wrapped. When such a list contains multiple nodes, the argument to

wrap() cannot be a `NodeList` or `\DOMNode`, since those can be used

to wrap a node only once. A string or callable returning a string or a

unique `NodeList` or `\DomNode` every time can be used in this case.

When a callable is passed, it is called once for each node operated on,

passing that node and its index. The callable should return either a

string, or a unique `NodeList` or `\DOMNode` ever time it is called.

Note that this returns the original node like all other methods, not the

(new) node(s) wrapped around it.

##### Example

``` php

$doc = (new Document())->html('foobar');

$doc->find->('span')->wrap('
');

```

*Result:*

``` html

foo

bar

```

---

#### wrapAll

```

self wrapAll(string|NodeList|\DOMNode|callable $input)

```

Like [wrap()](#wrap), but when operating on multiple nodes, all of them

will be wrapped together in a single instance of the given structure,

rather than each of them individually.

Note that the wrapping structure replaces the first node operated on, so

if the other nodes operated on are not siblings of the first, they will

be moved inside the document.

##### Example

``` php

$doc = (new Document())->html('foobar');

$doc->find->('span')->wrapAll('
');

```

*Result:*

``` html



    foo

    bar



```

---

#### wrapInner

```

self wrapInner(string|NodeList|\DOMNode|callable $input)

```

Like [wrap()](#wrap), but rather than wrapping the nodes that are being

operated on, this wraps their contents.

##### Example

``` php

$doc = (new Document())->html('foobar');

$doc->find('span')->wrapInner('');

```

*Result:*

``` html

foo

bar

```

---

### Traversal

#### add

```

NodeList add(string|NodeList|\DOMNode $input)

```

    

Add additional node(s) to the existing set.

##### Example

``` php

$nodes = $doc->find('a');

$nodes->add($doc->find('p'));

```

---

#### children

```

NodeList children()

```

    

Return all children of each element node in the current set.

##### Example

``` php

$nodes = $doc->find('p');

$childrenOfParagraphs = $nodes->children();

```

---

#### closest

```

Element|NodeList|null closest(string|NodeList|\DOMNode|callable $input)

```

    

Return the first element matching the supplied input by traversing up through the ancestors of each node in the current set. 

##### Example

``` php

$nodes = $doc->find('a');

$closestAncestors = $nodes->closest('p');

```

---

#### contents

```

NodeList contents()

```

    

Return all children of each node in the current set.

##### Example

``` php

$nodes = $doc->find('p');

$contents = $nodes->contents();

```

---

#### eq

```

\DOMNode|null eq(int $index)

```

    

Return node in the current set at the specified index.

##### Example

``` php

$nodes = $doc->find('a');

$nodeAtIndexOne = $nodes->eq(1);

```

---

#### filter

```

NodeList filter(string|NodeList|\DOMNode|callable $input)

```

    

Return nodes in the current set that match the input. 

##### Example

``` php

$nodes = $doc->filter('a')

$exampleATags = $nodes->filter('[href*=https://example.org/]');

```

---

#### find

```

NodeList find(string $selector[, string $prefix = 'descendant::'])

```

    

Return the decendants of the current set filtered by the selector and optional XPath axes.

##### Example

``` php

$nodes = $doc->find('a');

```

---

#### first

```

mixed first()

```

    

Return the first node of the current set.

##### Example

``` php

$nodes = $doc->find('a');

$firstNode = $nodes->first();

```

---

#### has

```

NodeList has(string|NodeList|\DOMNode|callable $input)

```

    

Return nodes with decendants of the current set matching the input. 

##### Example

``` php

$nodes = $doc->find('a');

$anchorTags = $nodes->has('span');

```

---

#### is

```

bool is(string|NodeList|\DOMNode|callable $input)

```

    

Test if nodes from the current set match the input. 

##### Example

``` php

$nodes = $doc->find('a');

$isAnchor = $nodes->is('[anchor]');

```

---

#### last

```

mixed last()

```

    

Return the last node of the current set.

##### Example

``` php

$nodes = $doc->find('a');

$lastNode = $nodes->last();

```

---

#### map

```

NodeList map(callable $function)

```

    

Apply a callback to nodes in the current set and return a new NodeList.

##### Example

``` php

$nodes = $doc->find('a');

$nodeValues = $nodes->map(function($node) {

    return $node->nodeValue;

});

```

---

#### following

```

\DOMNode|null following([string|NodeList|\DOMNode|callable $selector = null])

```

    

Return the sibling immediately following each element node in the current set. 

*Optionally filtered by selector.*

##### Example

``` php

$nodes = $doc->find('a');

$follwingNodes = $nodes->following();

```

---

#### followingAll

```

NodeList followingAll([string|NodeList|\DOMNode|callable $selector = null])

```

    

Return all siblings following each element node in the current set.

*Optionally filtered by selector.*

##### Example

``` php

$nodes = $doc->find('a');

$follwingAllNodes = $nodes->followingAll('[anchor]');

```

---

#### followingUntil

```

NodeList followingUntil([[string|NodeList|\DOMNode|callable $input = null], string|NodeList|\DOMNode|callable $selector = null])

```

    

Return all siblings following each element node in the current set upto but not including the node matched by $input.

*Optionally filtered by input.*


*Optionally filtered by selector.*

##### Example

``` php

$nodes = $doc->find('a');

$follwingUntilNodes = $nodes->followingUntil('.submit');

```

---

#### not

```

NodeList not(string|NodeList|\DOMNode|callable $input)

```

    

Return element nodes from the current set not matching the input. 

##### Example

``` php

$nodes = $doc->find('a');

$missingHrefAttribute = $nodes->not('[href]');

```

---

#### parent

```

Element|NodeList|null parent([string|NodeList|\DOMNode|callable $selector = null])

```

    

Return the immediate parent of each element node in the current set. 

*Optionally filtered by selector.*

##### Example

``` php

$nodes = $doc->find('a');

$parentNodes = $nodes->parent();

```

---

#### parents

```

NodeList parent([string $selector = null])

```

    

Return the ancestors of each element node in the current set. 

*Optionally filtered by selector.*

##### Example

``` php

$nodes = $doc->find('a');

$ancestorDivNodes = $nodes->parents('div');

```

---

#### parentsUntil

```

NodeList parentsUntil([[string|NodeList|\DOMNode|callable $input, [string|NodeList|\DOMNode|callable $selector = null])

```

    

Return the ancestors of each element node in the current set upto but not including the node matched by $selector.

*Optionally filtered by input.*


*Optionally filtered by selector.*

##### Example

``` php

$nodes = $doc->find('a');

$ancestorDivNodes = $nodes->parentsUntil('div');

```

---

#### preceding

```

\DOMNode|null preceding([string|NodeList|\DOMNode|callable $selector = null])

```

    

Return the sibling immediately preceding each element node in the current set. 

*Optionally filtered by selector.*

##### Example

``` php

$nodes = $doc->find('a');

$precedingNodes = $nodes->preceding();

```

---

#### precedingAll

```

NodeList precedingAll([string|NodeList|\DOMNode|callable $selector = null])

```

    

Return all siblings preceding each element node in the current set.

*Optionally filtered by selector.*

##### Example

``` php

$nodes = $doc->find('a');

$precedingAllNodes = $nodes->precedingAll('[anchor]');

```

---

#### precedingUntil

```

NodeList precedingUntil([[string|NodeList|\DOMNode|callable $input = null], string|NodeList|\DOMNode|callable $selector = null])

```

    

Return all siblings preceding each element node in the current set upto but not including the node matched by $input.

*Optionally filtered by input.*


*Optionally filtered by selector.*

##### Example

``` php

$nodes = $doc->find('a');

$precedingUntilNodes = $nodes->precedingUntil('.submit');

```

---

#### siblings

```

NodeList siblings([[string|NodeList|\DOMNode|callable $selector = null])

```

    

Return siblings of each element node in the current set.

*Optionally filtered by selector.*

##### Example

``` php

$nodes = $doc->find('p');

$siblings = $nodes->siblings();

```

---

#### slice

```

NodeList slice(int $start[, int $end])

```

    

Return a subset of the current set based on the start and end indexes.

##### Example

``` php

$nodes = $doc->find('p');

// Return nodes 1 through to 3 as a new NodeList

$slicedNodes = $nodes->slice(1, 3);

```

---

### Additional Methods

#### count

```

int count()

```

Return number of nodes in the current set

##### Example

``` php

$nodes = $doc->find('p');

echo $nodes->count();

```

---

#### each

```

self each(callable $function)

```

Iterate through for each item in the existing set via callback

##### Example

``` php

$nodes = $doc->find('p');

$nodes->each(function($node){

    echo $node->nodeName . "\n";

});

```

## Licensing

PHP DOM Wrapper is licensed by Andrew Scott under the BSD 3-Clause License, see the LICENSE file for more details.