cse / dom-manager
A simple library for management the DOM (XML, HTML) document.
Requires
- php: >=7.2
- ext-dom: *
- ext-libxml: *
Requires (Dev)
This package is auto-updated.
Last update: 2024-10-16 01:02:11 UTC
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