simplexml44 - PHP4 backport of PHP5 SimpleXML

- NAME
- OVERVIEW
- REQUIREMENTS
- SHORT TUTORIAL
- DIFFERENCES
- PITFALLS

- Using `setCDATA()`
- Character Sets
- Memory Consumption
- 'Call to a member function on a non-object'

- DOCUMENTATION
- CHANGELOG

- 0.4.4
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4.0

- TESTS
- AUTHOR

back to top

# NAME

simplexml44 - PHP4 backport of PHP5 SimpleXML

back to top

# OVERVIEW

simplexml44 is a PHP4 backport of the new PHP5 API called SimpleXML. It provides a simple access to XML files, optimzed for reading. It is possible to change CDATA nodes or attributes, but it is not possible to add or delete certain nodes of the internal DOM like tree. simplexml44 is written in pure PHP.

back to top

# REQUIREMENTS

PHP >= 4.2.0

XML Parser Extension (Expat)

back to top

# SHORT TUTORIAL

As the name says it is simple and easy to use simplexml44. You may refer to the PHP documentation to get an idea of SimpleXML as it is implemented with PHP5. Due to the nature of PHP4 simplexml44 is a little bit different, but usage of this package is straightforward too.

Here is an example XML file, its name is 'simple.xml':

     <?xml version="1.0" encoding="utf-8" standalone="yes"?>
     <root>
        <node>
          <child gender="m">Tom Foo</child>
          <child gender="f">Tamara Bar</child>
        </node>
     </root>

And here is how to access this file:

     <?php
     require_once('class/IsterXmlSimpleXMLImpl.php');

     // read and write a document
     $impl = new IsterXmlSimpleXMLImpl;
     $doc  = $impl->load_file('simple.xml');
     print $doc->asXML();
     // output is the file as given above

     // access a node's CDATA
     print $doc->root->node->child[0]->CDATA();
     print "\n";
     // output is "Tom Foo"

     // access attributes
     $attr = $doc->root->node->child[1]->attributes();
     print $attr['gender'];
     print "\n";
     // output is "f"

     // access children
     foreach( $doc->root->node->children() as $child ) {
        print $child->CDATA();
        print "\n";
     }
     // output is:
     // Tom Foo
     // Tamara Bar

     // change or add CDATA
     $doc->root->node->child[0]->setCDATA('Jane Foo');
     print $doc->asXML();

     // change or add attribute
     $doc->root->node->child[0]->setAttribute('gender', 'f');
     print $doc->asXML();

     ?>

back to top

# DIFFERENCES

Because it's not possible to use the PHP5 ArrayIterator interface with PHP4 there are some differences between this implementation and that of PHP5:

The access to the root node has to be explicit in IsterXmlSimpleXMLImpl, not implicit as with PHP5. Write $doc->root->node instead of $doc->node

You cannot access CDATA using array syntax. Use methods `CDATA()` and `setCDATA()` instead.

You cannot access attributes directly with array syntax. Always use `attributes()` to read and `setAttribute()` to write attributes.

Comments are ignored.

Last and least, this is not as fast as PHP5 SimpleXML--it's pure PHP4.

back to top

# PITFALLS

## Using `setCDATA()`

If you have a document like this:

     <?xml version="1.0" ?>
     <root>
        <node>cdata<p/></node>
     </root>

And you handle it like this:

     $doc->root->node->setCDATA('foo bar');

The resulting document will be this:

     <?xml version="1.0" ?>
     <root>
        <node>foo bar</node>
     </root>

Note the missing </p> tag. This is intentionally a feature not a bug, but it may be subject to further discussion.

## Character Sets

Take care on your character encoding. The parser expects UTF-8 XML files and will produce UTF-8 output as well. Currently there is no way to change this unless you decide to patch the sources (and the underlying expat parser restricts character sets to UTF-8, ISO-8859-1 and US-ASCII). As long as you are using only ASCII characters there is no difference between ISO-8859-1 and UTF-8 and you will notice no problems, but if you are using characters of the higher part of ISO-8859-1 the differences will come into effect.

## Memory Consumption

As with any DOM based API this is a little memory expensive. If you reuse the `IsterXmlSimpleXMLImpl` object to parse different files and create multiple documents in a single script you should consider to `unset()` documents not longer used.

## 'Call to a member function on a non-object'

If you access a node with SimpleXML syntax and you encounter a 'Fatal error: Call to a member function on a non-object' you may check if you have used the proper array index for this node. Sure, it is also a good idea to check each node if it is an object at all.

back to top

# DOCUMENTATION

To generate a detailed documentation of the provided classes you may use phpdocumentor (http://www.phpdoc.org/).

back to top

# CHANGELOG

## 0.4.4

fix: `IsterXmlExpat::parse()` buffer bug

## 0.4.3

fix: first element of a number of elements with equal name not in output when calling `IsterSimpleXMLElement::children()`

## 0.4.2

fix: broken references in conjunction with nested arrays break sometimes `IsterSimpleXMLElement::asXML()`

## 0.4.1

Make tests work with PHP 4.2.x.

## 0.4.0

First public release.

back to top

# TESTS

Enter ./test directory and write 'make test' at the command prompt to execute unit tests. This requires GNU make utility on your mashine. The php cli binary is expected at /usr/bin/php (change Makefile to meet your installation).

back to top

# AUTHOR

Ingo Schramm

http://www.ister.org

back to top

simplexml44 - PHP4 backport of PHP5 SimpleXML