PhpConcept
 
 

PclXml 0.4 - User Manual

 
 

Introduction

PclXml is a PHP class to easily manage XML files and strings.

PclXml allow you to read an XML file and store the XML tokens values and properties in a hierarchically organized object. PclXml define several methods that allow for quick and easy access to attributes (properties) values, childs in the hiearachy, content, ... PclXml can also save the XML hierarchy in a file.

Quick Start Guide

1 - Read XML File

PclXml can load an XML file in a PclXmlTag object. This object will allow manipulation of XML informations.
<?php
  require_once('pclxml.lib.php');
  $v_filename = 'files/my_file.xml';
  $v_xml = new PclXmlTag();
  if ($v_xml->read_file($v_filename) !== PCLXML_ERR_NO_ERROR) {
    echo 'Error while reading file :'.$v_xml->error_message(true);
    exit;
  }
?>

2 - Get XML Token value

PclXml is able to walk through the XML hierarchy to find a specific XML token and return its value.

Get the value fo the top most XML token :

<?php
  if (($v_result = $v_xml->get_value()) === PCLXML_ERR_ERROR) {
    echo 'Unable to find a value :'.$v_xml->error_message(true);
    exit;
  }
  else {
    echo "Value is : ".$v_value;
  }
?>

Get the value of a child XML token of the current object :

File is :
<members>
  <user>
    <name>Martin</name>
  </user>
</members>

PHP Code is :
<?php
  if (($v_result = $v_xml->get_value('members.user.name')) === PCLXML_ERR_ERROR) {
    echo 'Unable to find a value :'.$v_xml->error_message(true);
    exit;
  }
  else {
    echo "Value is : ".$v_value;
  }
?>

If a token has several childs of same name, then the index of the requested child must be used. Else only the first one in the child list will be returned :.

File is :
<members>
  <user>
    <name>Martin</name>
  </user>
  <user>
    <name>Lernou</name>
  </user>
</members>

PHP Code is :
<?php
  if (($v_result = $v_xml->get_value('members.user[1].name')) === PCLXML_ERR_ERROR) {
    echo 'Unable to find a value :'.$v_xml->error_message(true);
    exit;
  }
  else {
    echo "Value is : ".$v_value;
  }
?>

2 - Set XML Token value

The value of the current XML token or of any token in the hierarchy can be set by the set_value() method.

To set the value of the current XML token, just give the value :

<?php
  if (($v_result = $v_xml->set_value('The new value to set')) === PCLXML_ERR_ERROR) {
    echo 'Unable to set a value :'.$v_xml->error_message(true);
    exit;
  }
?>

To set the value of a child XML token of a PclXmlTag Object, give the value and the path to a valid child object :

<?php
  if (($v_result = $v_xml->set_value('Martin', 'members.user.name')) === PCLXML_ERR_ERROR) {
    echo 'Unable to set a value :'.$v_xml->error_message(true);
    exit;
  }
?>

 

3 - Get XML Token attribute

Each XML token can have a value but also attributes. PclXml allow for access of the attributes in the same way as getting the value of a token :

File is :
<members>
  <user name="Malin" first_name="John"></user>
  <user name="Marlin" first_name="Jake"></user>
  <user name="Lernou" first_name="Paul"></user>
</members>

PHP Code is :
<?php
  if (($v_result = $v_xml->get_attribute('members.user[2].name')) === PCLXML_ERR_ERROR) {
    echo 'Unable to find a value :'.$v_xml->error_message(true);
    exit;
  }
  else {
    // Result will be "Lernou"
    echo "Length attribute value is : ".$v_value;
  }
?>

4 - Set XML Token attribute

Attributes can be set for current PclXmlTag object and for childs of this object.

Setting attribute for the current object :

File is :
<members type="list">
  <user name="Malin" first_name="John"></user>
  <user name="Marlin" first_name="Jake"></user>
  <user name="Lernou" first_name="Paul"></user>
</members>

PHP Code is :
<?php
  if (($v_result = $v_xml->set_attribute('type', 'tree')) === PCLXML_ERR_ERROR) {
    echo 'Unable to set an attribute :'.$v_xml->error_message(true);
    exit;
  }
?>

Setting attribute for a child object :

<?php
  if (($v_result = $v_xml->set_attribute('members.user[2].name', 'Lernou')) === PCLXML_ERR_ERROR) {
    echo 'Unable to set an attribute :'.$v_xml->error_message(true);
    exit;
  }
?>

Note : If the attribute does not exist, then it is created. If you want to set only existing attribute, use first get_attribute() to see if attribute exists.

5 - Walk Through Childs

Sometimes you don't know which childs are in a XML Token. The walk through child method will allow you to access the childs of a specific PclXmlObject in a sequential way :

<?php
  
  $v_xml->walk_reset();

  while (($v_result = $v_xml->walk_childs()) !== PCLXML_ERR_ERROR) {
    echo "Child name : '".$v_result['name']."'<br>";
    // Also a direct reference to the PclXmltag child
    echo "Child name : '".$v_result['child']->get_name()."'<br>";
  }

  $v_xml->walk_reset();

?>

Child walk can also be done on child objects :

<?php

  $v_xml->walk_reset();

  while (($v_result = $v_xml->walk_childs('core.mysql')) !== PCLXML_ERR_ERROR) {
    echo "Child name : '".$v_result['name']."'<br>";
    // Also a direct reference to the PclXmltag child
    echo "Child name : '".$v_result['child']->get_name()."'<br>";
  }

  $v_xml->walk_reset();

?>

walk_reset() must be used to initiate the walk through the PclXmlTag object. Notice that walk_reset() apply both for child walk and attribute walk.
Note also that it is good practice to reset the walk after operation to limit ressource usage and side effects.

6 - Walk Through Attributes

Sometimes you don't know which attributes are defined in a XML Token. The walk through attribute method will allow you to access the attribute of a specific PclXmlObject in a sequential way :

<?php
  
  $v_xml->walk_reset();

  while (($v_result = $v_xml->walk_attributes()) !== PCLXML_ERR_ERROR) {
    echo "Attribute name : '".$v_result['name']."' = '".$v_result['value']."'<br>";
  }

  $v_xml->walk_reset();

?>

Attribute walk can also be done on child objects :

<?php
  
  $v_xml->walk_reset();

  while (($v_result = $v_xml->walk_attributes('core.mysql')) !== PCLXML_ERR_ERROR) {
    echo "Attribute name : '".$v_result['name']."' = '".$v_result['value']."'<br>";
  }

  $v_xml->walk_reset();

?>

walk_reset() must be used to initiate the walk through the PclXmlTag object. Notice that walk_reset() apply both for child walk and attribute walk.
Note also that it is good practice to reset the walk after operation to limit ressource usage and side effects.

7 - Get a Child by Path

You may want to have access to a specific child of the current PclXmlTag object. The get_child() method gives an access to a reference of the requested child :

<?php

  if (($v_child = &$v_xml->get_child('core.mysql')) === PCLXML_ERR_ERROR) {
    echo 'Unable to get a child with this path :'.$v_xml->error_message(true);
    exit;
  }

?>

 

7 - Get or Set Name of an XML Token

<?php

  $v_name = $v_xml->get_name();

  if (($v_result = $v_xml->set_name('new_name')) === PCLXML_ERR_ERROR) {
    echo 'Unable to set a name for this object :'.$v_xml->error_message(true);
    exit;
  }

?>

 

Advanced Features

To Be Completed

 

 

Error Management

To Be Completed

FAQ - Frequently Asked Questions

Nothing yet ;-)

Limitations & Prerequisits

ToBeCompleted.

License & Copyrights

PclXml is released by Vincent Blavet (vincent@phpconcept.net) under GNU LGPL License. So you can use it at no cost.

HOWEVER, if you release a script, an application, a library or any kind of code including PclXml, YOU MUST :
- Release your work with the warnings associated with PclXml release,
- You must indicate in the documentation (or a readme file), that your work include PclXml script, and make a reference to the author and the web site http://www.phpconcept.net

I will also appreciate that you send me an email (vincent@phpconcept.net), just to be aware that someone is using PclXml somewhere in the world.

For more information on GNU/LGPL licensing : http://www.gnu.org

Warnings

This application and the associated files are non commercial, non professional work.
It should not have unexpected results. However if any damage is caused by this software the author can not be responsible.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

The use of this software is at the risk of the user.

 

 

 

Member login - Stats
Copyright 2003 - PhpConcept

Powered by PcWeb