README

English | Русский

DOM Manager

A simple library for management the DOM (XML, HTML) document.

Project repository: https://github.com/cs-eliseev/dom-manager

DEMO

use cse\DOMManager\DomManager;
...
$content = file_get_contents('https://www.w3schools.com/xml/simple.xml');
$easyLoader = new DomManager();
$node = $easyLoader->parse($content);
$name = $node->find('name')->first()->text(); // Belgian Waffles

Install

You can find the most recent version of this project here.

Composer

Execute the following command to get the latest version of the package:

composer require cse/dom-manager

Or file composer.json should include the following contents:

{
    "require": {
        "cse/dom-manager": "*"
    }
}

Git

Clone this repository locally:

git clone https://github.com/cs-eliseev/dom-manager.git

Download

Download the latest release here.

Usage

The following demonstrates how to use the functions of this library in a PHP application.

Init

The DomManager instance convert data into a structure for manipulating the DOM tree.

Converting XML structure:

use cse\DOMManager\IDomManager;
...
$easyLoader = new IDomManager();
$nodes = $easyLoader->parse('<div><br/><br/></div>'); // Nodes entity

Converting HTML structure via DOMDocument:

use cse\DOMManager\DomManager;
...
$domDocument = new DOMDocument('1.0', 'UTF-8');
$domDocument->loadHTML('<div><br><br></div>');
$easyLoader = new DomManager();
$nodes = $easyLoader->parse($domDocument); // Nodes entity

Converting DOMNodeList:

use cse\DOMManager\DomManager;
...
$domDocument = new DOMDocument('1.0', 'UTF-8');
$domDocument->loadXML('<div><br/><br/></div>');

$easyLoader = new DomManager();
$nodes = $easyLoader->parse($domDocument->getElementsByTagName('br')); // Nodes entity

Converting DOMNode:

use cse\DOMManager\DomManager;
...
$domDocument = new DOMDocument('1.0', 'UTF-8');
$domDocument->loadXML('<div><br/><br/></div>');

$easyLoader = new DomManager();
$nodes = $easyLoader->parse($domDocument->getElementsByTagName('br')->item(1)); // Nodes entity

An instance of the Nodes represents a list of DOMNode objects, can be manipulation.

Methods

Example

Example of document content:

<main class="main" role="main">
    <div class="content">
        <div>
            <h1><i class="icon"/><span>Header</span>-subheader</h1>
            <img src="content_img.jpg" alt="content img"/>
            <p><span class="text">First text</span></p>
        </div>
        <br/>
        <p>Last text</p>
    </div>
    <div class="description" role="contentinfo">
        <p>First description</p>
        <br/>
        <em>Middle description</em>
        <p><span>Last description</span></p>
    </div>
</main>

Find elements

Returns all found node elements.

Search by tag name:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('div');

Result:

<div class="content"><div><h1><i class="icon"/><span>Header</span>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><span class="text">First text</span></p></div><br/><p>Last text</p></div>
<div><h1><i class="icon"/><span>Header</span>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><span class="text">First text</span></p></div>
<div class="description" role="contentinfo"><p>First description</p><br/><em>Middle description</em><p><span>Last description</span></p></div>

Find by XPath:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('//div/div');

Result:

<div><h1><i class="icon"/><span>Header</span>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><span class="text">First text</span></p></div>

Find by attributes:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('//*[@class="content"]');

Result:

<div class="content"><div><h1><i class="icon"/><span>Header</span>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><span class="text">First text</span></p></div><br/><p>Last text</p></div>

First element

Returns the first found node element.

The first item in the list:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->first();

Result:

<p><span class="text">First text</span></p>

First found elements in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->first('p');

Result:

<p><span class="text">First text</span></p>

First found elements in a node by XPath:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->first('//span[@class]');

Result:

<span class="text">First text</span>

First found elements in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('div')->first('p');

Result:

<p><span class="text">First text</span></p>
<p><span class="text">First text</span></p>
<p>First description</p>

Last elements

Returns the last found node element.

The last item in the list:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->last();

Result:

<p><span>Last description</span></p>

Last found elements in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->last('p');

Result:

<p><span>Last description</span></p>

Last found elements in a node by XPath:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->last('//span[@class]');

Result:

<span class="text">First text</span>

Last found elements in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('div')->last('p');

Result:

<p>Last text</p>
<p><span class="text">First text</span></p>
<p><span>Last description</span></p>

N element

Returns the element by index.

N list item:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->getByPosition(1);

Result:

<p>Last text</p>

N found elements in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->getByPosition(1, 'p');

Result:

<p>Last text</p>

N found elements in a node by XPath:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->getByPosition(2, '//*[@class]');

Result:

<i class="icon"/>

N found elements in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('div')->getByPosition(1, 'p');

Result:

<p>Last text</p>
<p><span>Last description</span></p>

Closest

Returns the closest parent element.

Closest parent element by tag name:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('span')->closest('div');

Result:

<div><h1><i class="icon"/><span>Header</span>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><span class="text">First text</span></p></div>
<div><h1><i class="icon"/><span>Header</span>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><span class="text">First text</span></p></div>
<div class="description" role="contentinfo"><p>First description</p><br/><em>Middle description</em><p><span>Last description</span></p></div>

Parent element:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('span')->closest();

Result:

<h1><i class="icon"/><span>Header</span>-subheader</h1>
<p><span class="text">First text</span></p>
<p><span>Last description</span></p>

Parent

Returns the parent element.

Parent element:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('span')->parent();

Result:

<h1><i class="icon"/><span>Header</span>-subheader</h1>
<p><span class="text">First text</span></p>
<p><span>Last description</span></p>

Root

Returns the root element.

Main parent:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('span')->root();

Result:

<main class="main" role="main"><div class="content"><div><h1><i class="icon"/><span>Header</span>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><span class="text">First text</span></p></div><br/><p>Last text</p></div><div class="description" role="contentinfo"><p>First description</p><br/><em>Middle description</em><p><span>Last description</span></p></div></main>

Childes

Returns all children of the node.

Get the childes in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->childes();

Result:

<span class="text">First text</span>
<span>Last description</span>

Find the childes in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->childes('p');

Result:

<span class="text">First text</span>
<span>Last description</span>

Find by XPath:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->childes('//*[@class="description"]/p');

Result:

<span>Last description</span>

First childes

Returns the first child of the node.

Get the first childes in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('div')->firstChild();

Result:

<div><h1><i class="icon"/><span>Header</span>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><span class="text">First text</span></p></div>
<h1><i class="icon"/><span>Header</span>-subheader</h1>
<p>First description</p>

Find the childes in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->firstChild();

Result:

<span class="text">First text</span>
<span>Last description</span>

Find the childes in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->firstChild('div');

Result:

<span class="text">First text</span>
<span>Last description</span>

Find the childes in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->firstChild('p');

Result:

<div><h1><i class="icon"/><span>Header</span>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><span class="text">First text</span></p></div>
<h1><i class="icon"/><span>Header</span>-subheader</h1>
<p>First description</p>

Find by XPath:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->firstChild('//div/div');

Result:

<h1><i class="icon"/><span>Header</span>-subheader</h1>

Get DOMNode

Returns the DOMNode element by index.

Get an element by index:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->getNodeByPosition(1);

Result:

class DOMElement {}

Find DOMNode

Returns the found DOMNode element by index.

Find element:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->findNodeByPosition(1, 'p');

Result:

class DOMElement {}

Node name

Returns node name.

Node name:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('div')->name();

Result:

div
div
div

Rename node

Rename node.

Rename current node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('div')->rename('section');

Result:

<section class="content"><section><h1><i class="icon"/><span>Header</span>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><span class="text">First text</span></p></section><br/><p>Last text</p></section>
<section><h1><i class="icon"/><span>Header</span>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><span class="text">First text</span></p></section>
<section class="description" role="contentinfo"><p>First description</p><br/><em>Middle description</em><p><span>Last description</span></p></section>

Find and rename a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->rename('section', 'div');

<div class="content"><div><h1><i class="icon"/><strong>Header</strong>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><strong class="text">First text</strong></p></div><br/><p>Last text</p></div>
<div><h1><i class="icon"/><strong>Header</strong>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><strong class="text">First text</strong></p></div>
<div class="description" role="contentinfo"><p>First description</p><br/><em>Middle description</em><p><strong>Last description</strong></p></div>

Replace node

Replace node.

Replace current node.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('div')->replace('<section><div>Header</div>Content</section>');

<main class="main" role="main"><section><div>Header</div>Content</section><section><div>Header</div>Content</section></main>

Finde nad replace a node.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->replace('<section><div>Header</div>Content</section>', 'div');

Result:

<main class="main" role="main"><section><div>Header</div>Content</section><section><div>Header</div>Content</section></main>

Find by XPath and replace node.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->replace('<section><div>Header</div>Content</section>', '//div/div');

Result:

<main class="main" role="main"><div class="content"><section><div>Header</div>Content</section><br/><p>Last text</p></div><div class="description" role="contentinfo"><p>First description</p><br/><em>Middle description</em><p><span>Last description</span></p></div></main>

Remove node

Remove node.

Remove current node.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('div')->remove();

Result:

<main class="main" role="main"/>

Find and remove a node.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->remove('div');

Result:

<main class="main" role="main"/>

Find by XPath and remove node.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->remove('//div/div');

Result:

<main class="main" role="main"><div class="content"><br/><p>Last text</p></div><div class="description" role="contentinfo"><p>First description</p><br/><em>Middle description</em><p><span>Last description</span></p></div></main>

Count

Counting the number of elements.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->count();     // 4
$nodes->count('p');             // 4
$nodes->count('//*[@class]');   // 5

Element exist

Checking for node existence.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->exist();     // true
$nodes->exist('p');             // true
$nodes->exist('//*[@class]');   // true
$nodes->exist('hr');            // false

Element not exist

Checking for node not existence.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->notExist();      // false
$nodes->notExist('p');              // false
$nodes->notExist('//*[@class]');    // false
$nodes->notExist('hr');             // true

Is element

Checking that the number of elements is 1.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('img')->isElem();  // true
$nodes->find('p')->isElem();    // false

Is list

Checks that the number of elements is more than 1.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('img')->isList();  // false
$nodes->find('p')->isList();    // true

DomComment

Validate DOMComment. Use isElem. Parsing by default ignore the node DOMComment.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('img')->isDomComment();  // false
$nodes->find('p')->isDomComment();    // false

DomElement

Validate DomElement. Use isElem.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('img')->isDomElement();        // true
$nodes->find('p')->isDomElement();          // false
$nodes->find('p')->first()->isDomElement(); // true

DomText

Validate DomText. Use isElem. Parsing by default ignore the node DomText.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('img')->isDomText();  // false
$nodes->find('p')->isDomText();    // false

Node type

Node type. Parsing by default ignore the node type not 1.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('img')->type();  // 1
$nodes->find('p')->type();    // 1\n1\n1\n1

Text

Returns text.

Get the text of the current item:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('//h1/span')->text();              // Header
$nodes->find('h1')->text();                     // Header-subheader
$nodes->find('//*[@class="content"]')->text();  // Header-subheaderFirst textLast text

Get the text of the list:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->text();

Result:

First text
Last text
First description
Last description

Add text

Adds text to the end of a node.

Adding text to an empty element:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('//h1/i')->addText('add text');

Result:

<i class="icon">add text</i>

Adding text to the end of an element:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('h1')->addText('add text');

Result:

<h1><i class="icon"/><span>Header</span>-subheaderadd text</h1>

Adding text to the list:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->addText('add text');

Result:

<p><span class="text">First text</span>add text</p>
<p>Last textadd text</p>
<p>First descriptionadd text</p>
<p><span>Last description</span>add text</p>

Replace text

Replace text in a node.

Adding text to an empty element:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('//h1/i')->replaceText('change text');

Result:

<i class="icon">add text</i>

Replace text in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('h1')->replaceText('change text');

Result:

<h1><i class="icon"/><span>Header</span>change text</h1>

Replace text to the list:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->replaceText('change text');

Result:

<p><span class="text">First text</span>change text</p>
<p>change text</p>
<p>change text</p>
<p><span>Last description</span>change text</p>

Remove text

Remove text in a node.

Remove text in a node:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('h1')->removeText();

Result:

<h1><i class="icon"/><span>Header</span></h1>

Remove text to the list:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->replaceText('change text');

Result:

<p><span class="text">First text</span></p>
<p></p>
<p></p>
<p><span>Last description</span></p>

Attribute

Return attribute value.

Get list values:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('h1')->attr('class');

Result:

content
description

Get value:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('h1')->attr('role');

Result:

contentinfo

Default value:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('h1')->attr('role', 'default');

Result:

default
default
contentinfo

Has attribute

Checking if an attribute exists.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('img')->hasAttr('src');        // true
$nodes->find('i')->hasAttr('class');        // true
$nodes->find('p')->hasAttr('class');        // false
$nodes->find('div')->hasAttr('class');      // false

Set attribute

Set attribute value.

Set attribute to the element:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$elem = $nodes->find('i');
$elem->setAttr('class', 'value');               // <i class="value"/>
$elem->setAttr('data-value', 'edit');           // <i class="value" data-value="edit"/>
$elem->setAttr('class', 'icon value');          // <i class="icon value" data-value="edit"/>

Set attribute to the list:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$elem = $nodes->find('p')->setAttr('class', 'text');

Result:

<p class="text"><span class="text">First text</span></p>
<p class="text">Last text</p>
<p class="text">First description</p>
<p class="text"><span>Last description</span></p>

Remove attribute

Remove attribute.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$elem = $nodes->find('span')->removeAttr('class');

Result:

<span>Header</span>
<span>First text</span>
<span>Last description</span>

Append child

Adding child node.

Adding to an empty element:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('i')->appendChild('<section><div>Header</div>Content</section>');

Result:

<i class="icon"><section><div>Header</div>Content</section></i>

Adding to the list:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->appendChild('<section><div>Header</div>Content</section>');

Result:

<p><span class="text">First text</span><section><div>Header</div>Content</section></p>
<p>Last text<section><div>Header</div>Content</section></p>
<p>First description<section><div>Header</div>Content</section></p>
<p><span>Last description</span><section><div>Header</div>Content</section></p>

Find and add:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->appendChild('<section><div>Header</div>Content</section>', 'p');

Result:

<p><span class="text">First text</span><section><div>Header</div>Content</section></p>
<p>Last text<section><div>Header</div>Content</section></p>
<p>First description<section><div>Header</div>Content</section></p>
<p><span>Last description</span><section><div>Header</div>Content</section></p>

Replace childes

Replace childes node.

Replacing all childes:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('h1')->replaceChildes('<section><div>Header</div>Content</section>');

Result:

<h1><section><div>Header</div>Content</section><section><div>Header</div>Content</section>-subheader</h1>

Replacing children by node name:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('h1')->replaceChildes('<section><div>Header</div>Content</section>', 'i');

Result:

<h1><section><div>Header</div>Content</section><span>Header</span>-subheader</h1>

Remove chides

Remove childes node.

Removing all childes:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('h1')->removeChildes();

Result:

<h1>-subheader</h1>

Removing descendants by node name:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('h1')->removeChildes('i');

Result:

<h1><span>Header</span>-subheader</h1>

DOMNode list

Returns a list of DOMNode elements.

List:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->toArray();

Result:

[
    class DOMElement {},
    class DOMElement {},
    class DOMElement {},
    class DOMElement {}
]

NodeList

Return NodeList.

NodeList:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('p')->toList();

Result:

class NodeList {}

Content

Returns the markup of an element, including its content.

Get the content of the current element:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->find('h1')->toString();

Result:

<h1><i class="icon"/><span>Header</span>-subheader</h1>

Find and get the content of the element:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->toString('h1');

Result:

<h1><i class="icon"/><span>Header</span>-subheader</h1>

Find by XPath and get the content of the element:

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$nodes->toString('//div/p');

Result:

<p><span class="text">First text</span></p>
<p>Last text</p>
<p>First description</p>
<p><span>Last description</span></p>a

Foreach elements

Calls a callback function for each item.

/** @var \cse\DOMManager\Nodes\Nodes $nodes */
$elem = $nodes->find('div');
$elem->each(function (\cse\DOMManager\Nodes\Nodes $item) {
    if ($item->hasAttr('class')) {
        $item->removeAttr('class');
    }
    $item->addText('this div element');
});
echo $elem->root()->content();

Result:

<main class="main" role="main"><div><div><h1><i class="icon"/><span>Header</span>-subheader</h1><img src="content_img.jpg" alt="content img"/><p><span class="text">First text</span></p>this div element</div><br/><p>Last text</p>this div element</div><div role="contentinfo"><p>First description</p><br/><em>Middle description</em><p><span>Last description</span></p>this div element</div></main>

Testing & Code Coverage

PHPUnit is used for unit testing. Unit tests ensure that class and methods does exactly what it is meant to do.

General PHPUnit documentation can be found at https://phpunit.de/documentation.html.

To run the PHPUnit unit tests, execute:

phpunit PATH/TO/PROJECT/tests/

If you want code coverage reports, use the following:

phpunit --coverage-html ./report PATH/TO/PROJECT/tests/

Used PHPUnit default config:

phpunit --configuration PATH/TO/PROJECT/phpunit.xml

Support project

Many thanks to those who are ready to help in the development of the project. You can help:

• Add a bug report or suggestion for improvement.
• Share code improvements by sending a Pull Request.
• Make a translation or optimize it for your country.
• Modify the documentation.
• Also any other help.

License

This PHP library is open-source under the MIT license. Please see License File for more information.

GitHub @cs-eliseev