https://github.com/kuria/dom
Wrappers around the PHP DOM classes
https://github.com/kuria/dom
document-object-model dom domdocument html php wrapper xml xpath
Last synced: 5 months ago
JSON representation
Wrappers around the PHP DOM classes
- Host: GitHub
- URL: https://github.com/kuria/dom
- Owner: kuria
- License: mit
- Created: 2014-11-03T13:53:50.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2023-04-22T14:38:48.000Z (almost 3 years ago)
- Last Synced: 2025-04-14T23:13:36.856Z (10 months ago)
- Topics: document-object-model, dom, domdocument, html, php, wrapper, xml, xpath
- Language: PHP
- Homepage:
- Size: 78.1 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.rst
- License: LICENSE
Awesome Lists containing this project
README
DOM
###
Wrappers around the `PHP DOM classes `__
that handle the common DOM extension pitfalls.
.. image:: https://travis-ci.com/kuria/dom.svg?branch=master
:target: https://travis-ci.com/kuria/dom
.. contents::
Features
********
- HTML documents
- encoding sniffing
- optional tidy support (automatically fix broken HTML)
- HTML fragments
- XML documents
- XML fragments
- XPath queries
- creating documents from scratch
- optional error suppression
- helper methods for common tasks, such as:
- querying multiple or a single node
- checking for containment
- removing a node
- removing all nodes from a list
- prepending a child node
- inserting a node after another node
- fetching ```` and ```` elements (HTML)
- fetching root elements (XML)
Requirements
************
- PHP 7.1+
Container methods
*****************
These methods are shared by both HTML and XML containers.
Loading documents
=================
.. code:: php
setLibxmlFlags($customLibxmlFlags); // optional
$dom->setIgnoreErrors($ignoreErrors); // optional
$dom->loadString($html);
// using static loadString() shortcut
$dom = HtmlDocument::fromString($html);
// using existing document instance
$dom = new HtmlDocument();
$dom->loadDocument($document);
// using static loadDocument() shortcut
$dom = HtmlDocument::fromDocument($document);
// creating an empty document
$dom = new HtmlDocument();
$dom->loadEmpty();
Getting or changing document encoding
=====================================
.. code:: php
getEncoding();
// set encoding
$dom->setEncoding($newEncoding);
.. NOTE::
The DOM extension uses UTF-8 encoding.
This means that text nodes, attributes, etc.:
- will be encoded using UTF-8 when read (e.g. ``$elem->textContent``)
- should be encoded using UTF-8 when written (e.g. ``$elem->setAttribute()``)
The encoding configured by ``setEncoding()`` is used when saving the document,
see `Saving documents`_.
Saving documents
================
.. code:: php
save();
// single element
$content = $dom->save($elem);
// children of a single element
$content = $dom->save($elem, true);
Getting DOM instances
=====================
After a document has been loaded, the DOM instances are available via getters:
.. code:: php
getDocument();
$xpath = $dom->getXpath();
Running XPath queries
=====================
.. code:: php
query('//div');
// get a single DOMNode (or null)
$div = $dom->query('//div');
// check if a query matches
$divExists = $dom->exists('//div');
Escaping strings
================
.. code:: php
escape($string);
DOM manipulation and traversal helpers
======================================
Helpers for commonly needed tasks that aren't easily achieved via existing
DOM methods:
.. code:: php
contains($node);
// check if a node contains another node
$hasNode = $dom->contains($node, $parentNode);
// remove a node
$dom->remove($node);
// remove a list of nodes
$dom->removeAll($nodes);
// prepend a child node
$dom->prependChild($newNode, $existingNode);
// insert a node after another node
$dom->insertAfter($newNode, $existingNode);
Usage examples
**************
HTML documents
==============
Loading an existing document
----------------------------
.. code:: php
Example document
Hello world!
HTML;
$dom = HtmlDocument::fromString($html);
var_dump($dom->queryOne('//title')->textContent);
var_dump($dom->queryOne('//h1')->textContent);
Output:
::
string(16) "Example document"
string(12) "Hello world!"
Optionally, the markup can be fixed by `Tidy `_
prior to being loaded.
.. code:: php
setTidyEnabled(true);
$dom->loadString($html);
.. NOTE::
HTML documents ignore errors by default, so there is no need to call
``$dom->setIgnoreErrors(true)``.
Creating an new document
------------------------
.. code:: php
loadEmpty(['formatOutput' => true]);
// add
$title = $dom->getDocument()->createElement('title');
$title->textContent = 'Lorem ipsum';
$dom->getHead()->appendChild($title);
// save
echo $dom->save();
Output:
::
Lorem ipsum
HTML fragments
==============
Loading an existing fragment
----------------------------
.. code:: php
Hello');
$element = $dom->queryOne('/div[@id="test"]/span');
if ($element) {
var_dump($element->textContent);
}
Output:
::
string(5) "Hello"
.. NOTE::
HTML fragments ignore errors by default, so there is no need to call
``$dom->setIgnoreErrors(true)``.
Creating a new fragment
-----------------------
.. code:: php
loadEmpty(['formatOutput' => true]);
$dom->getBody()->appendChild($link);
// save
echo $dom->save();
Output:
::
XML documents
=============
Loading an existing document
----------------------------
.. code:: php
XML;
$dom = XmlDocument::fromString($xml);
foreach ($dom->query('/library/book') as $book) {
/** @var \DOMElement $book */
var_dump("{$book->getAttribute('name')} by {$book->getAttribute('author')}");
}
Output:
::
string(34) "Don Quixote by Miguel de Cervantes"
string(29) "Hamlet by William Shakespeare"
string(49) "Alice's Adventures in Wonderland by Lewis Carroll"
Creating a new document
-----------------------
.. code:: php
loadEmpty(['formatOutput' => true]);
// add
$document = $dom->getDocument();
$document->appendChild($document->createElement('users'));
// add some users
$bob = $document->createElement('user');
$bob->setAttribute('username', 'bob');
$bob->setAttribute('access-token', '123456');
$john = $document->createElement('user');
$john->setAttribute('username', 'john');
$john->setAttribute('access-token', 'foobar');
$dom->getRoot()->appendChild($bob);
$dom->getRoot()->appendChild($john);
// save
echo $dom->save();
Output:
::
Handling XML namespaces in XPath queries
----------------------------------------
.. code:: php
XML;
$dom = XmlDocument::fromString($xml);
// register namespace in XPath
$dom->getXpath()->registerNamespace('lib', 'http://example.com/');
// query using the prefix
foreach ($dom->query('//lib:book') as $book) {
/** @var \DOMElement $book */
var_dump($book->getAttribute('name'));
}
Output:
::
string(11) "Don Quixote"
string(6) "Hamlet"
string(32) "Alice's Adventures in Wonderland"
XML fragments
=============
Loading an existing fragment
----------------------------
.. code:: php
');
foreach ($dom->query('/fruits/fruit') as $fruit) {
/** @var \DOMElement $fruit */
var_dump($fruit->getAttribute('name'));
}
Output:
::
string(5) "Apple"
string(6) "Banana"
Creating a new fragment
-----------------------
.. code:: php
loadEmpty(['formatOutput' => true]);
// add a new element
$person = $dom->getDocument()->createElement('person');
$person->setAttribute('name', 'John Smith');
$dom->getRoot()->appendChild($person);
// save
echo $dom->save();
Output:
::