DOM library

GDmac edited this page Nov 7, 2012 · 29 revisions
Clone this wiki locally

Category:Libraries

DOMLib

This library was built to ease the use of the PHP DOM object. I found it too tedious to always be writing this:

$this->doc                        = new DOMDocument ('1.0', 'iso-8859-1');
$this->doc->preserveWhiteSpace    = false;
$this->doc->formatOutput          = true;
$root       = $this->doc->createElement('root');
$this->doc->appendChild($root);

An example of the above using this library would be:

// Must load the library properly, example:
$this->load->library('domlib'); // In controller
$doc = $this->domlib->domNew(false); // Creates new DOMDocument object.
$this->domlib->domRoot('root', $doc); // Creates root element and appends to the document.

The XML version, encoding, and formatOutput are set as constants.

XML_VERSION   = '1.0';
XML_ENCODING  = 'iso-8859-1';
FORMAT_OUTPUT = 'TRUE';

This library includes pretty much all of the most common functions - I may include full DOM functionality in the near future.

You can create these types of nodes with the library:

  • Standard XML elements
  • Element text (must be appended TO an element)
  • Element attributes (must be appended TO an element)
  • XML comments <!-- comment -->
  • CDATA sections [[CDATA[
  • Transforms with XSLT and optional parameters
  • Output DOMDocument tree as an XML string to browser
  • Output DOMDocument tree as a file
  • Load an XML document for processing

The code is pretty well commented, so with these examples you should be able to figure out how to use the rest of the functions.

Familiarity with the PHP DOM object is highly recommended, and this is PHP5 only.

Installation

This is easy - put it in your /application/libraries/ folder.

Documentation

The functions are easy to use. First you must create a new DOMDocument:

// First things first, load it!
$this->load->library('domlib');
// Assigning to a var makes it easier for appending elements
$doc = $this->domlib->domNew(false); 

The parameter sets the boolean value for the 'preserveWhitespace' function when Document output occurs.

For root elements (to be valid XML you must have a root element!):

// Assigning to a var makes it easier for appending elements
$root = $this->domlib->domRoot('root', $doc);

The first parameter sets the name of the element, and the second parameter appends the root element to the DOMDocument; the third parameter sets the value of the element.

For regular elements you would do this:

// Assigning to a var makes it easier for appending elements
$somelement = $this->domlib->domElement('somelement', $root, 'This is an element value');

The first parameter sets the name of your element, second parameter appends it to any parent elements you choose (at the moment, the only one we have is the root element)

Now say you wanted an attribute on your element, you would do this:

// No need to assign to a variable, as we won't be appending elements to an attribute
$this->domlib->domAttribute('id', $somelement, 'uniqueId');

Now to output all of this as an XML file we would do this:

$this->domlib->save('example.xml');

The parameter is simply a string for the name (including extension) you wish to save the Document as or to. If it does not exist it will create it, if it does exist it will overwrite it (if it has the permissions to do so).

This, so far, is what our document on output would look like if you opened up the XML file:

<?xml version="1.0" encoding="ISO-8859-1"?>
<root>
  <somelement id="uniqueId">This is a value!</somelement>
</root>

And this is the example as a whole:

<?php
class Example extends Controller
{
   function testDom()
   {
      // First things first, load it!
      $this->load->library('domlib');
      // Assigning to a var makes it easier for appending elements
      $doc = $this->domlib->domNew(false); 
      // Assigning to a var makes it easier for appending elements
      $root = $this->domlib->domRoot('root', $doc);
      // Assigning to a var makes it easier for appending elements
      $somelement = $this->domlib->domElement('somelement', $root, 'This is a value');
      // No need to assign to a variable, as we won't be appending elements to an attribute
      $this->domlib->domAttribute('id', $somelement, 'uniqueId');
      $this->domlib->save('example.xml');
   }
}

Download and further information

Download is not available, I am having hosting issues - if there is enough demand for it, or someone is willing to host it, PM me through the forums! (Iksander)

The forum topic is here: DOMLib thread

Category:Contributions::Libraries::PHP