Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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: 2 months ago
JSON representation

Wrappers around the PHP DOM classes

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]);



   // add 

   $link = $dom->getDocument()->createElement('a');

   $link->setAttribute('href', 'http://example.com/');

   $link->textContent = 'example';



   $dom->getBody()->appendChild($link);



   // save

   echo $dom->save();



Output:



::



  example



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:



::