scripts.carrubbers.org home scripts@carrubbers.org
*

Php.XPath Documentation

Documentation for the XPath.class.php file version 3.5

Contents


Introduction

Php.XPath by S.Blum / N.Swinson / D.Allen / (P.Mehl).

+======================================================================================================+
| A php class for searching an XML document using XPath, and making modifications using a DOM 
| style API. Does not require the DOM XML PHP library. 
|
+======================================================================================================+
| What Is XPath:
| --------------
| - "What SQL is for a relational database, XPath is for an XML document." -- Sam Blum
| - "The primary purpose of XPath is to address parts of an XML document. In support of this 
|    primary purpose, it also provides basic facilities for manipulting it." -- W3C
| 
| XPath in action and a very nice intro is under:
|    http://www.zvon.org/xxl/XPathTutorial/General/examples.html
| Specs Can be found under:
|    http://www.w3.org/TR/xpath     W3C XPath Recommendation 
|    http://www.w3.org/TR/xpath20   W3C XPath Recommendation 
|
| NOTE: Most of the XPath-spec has been realized, but not all. Usually this should not be
|       problem as the missing part is either rarely used or it's simpler to do with PHP itself.
+------------------------------------------------------------------------------------------------------+
| Requires PHP version  4.0.5 and up
+------------------------------------------------------------------------------------------------------+
| Main Active Authors:
| --------------------
| Nigel Swinson <nigelswinson@users.sourceforge.net>
|   Started around 2001-07, saved phpxml from near death and renamed to Php.XPath
|   Restructured XPath code to stay in line with XPath spec.
| Sam Blum <bs_php@infeer.com>
|   Started around 2001-09 1st major restruct (V2.0) and testbench initiator.   
|   2nd (V3.0) major rewrite in 2002-02
| Daniel Allen <bigredlinux@yahoo.com>
|   Started around 2001-10 working to make Php.XPath adhere to specs 
| Main Former Author: Michael P. Mehl <mpm@phpxml.org>
|   Inital creator of V 1.0. Stoped activities around 2001-03        
+------------------------------------------------------------------------------------------------------+
| Code Structure:
| --------------_
| The class is split into 3 main objects. To keep usability easy all 3 
| objects are in this file (but may be split in 3 file in future).
|   +-------------+ 
|   |  XPathBase  | XPathBase holds general and debugging functions. 
|   +------+------+
|          v      
|   +-------------+ XPathEngine is the implementation of the W3C XPath spec. It contains the 
|   | XPathEngine | XML-import (parser), -export  and can handle xPathQueries. It's a fully 
|   +------+------+ functional class but has no functions to modify the XML-document (see following).
|          v      
|   +-------------+ 
|   |    XPath    | XPath extends the functionality with actions to modify the XML-document.
|   +-------------+ We tryed to implement a DOM - like interface.
+------------------------------------------------------------------------------------------------------+
| Usage:
| ------
| Scroll to the end of this php file and you will find a short sample code to get you started
+------------------------------------------------------------------------------------------------------+
| Glossary:
| ---------
| To understand how to use the functions and to pass the right parameters, read following:
|     
| Document: (full node tree, XML-tree)
|     After a XML-source has been imported and parsed, it's stored as a tree of nodes sometimes 
|     refered to as 'document'.
|     
| AbsoluteXPath: (xPath, xPathSet)
|     A absolute XPath is a string. It 'points' to *one* node in the XML-document. We use the
|     term 'absolute' to emphasise that it is not an xPath-query (see xPathQuery). A valid xPath 
|     has the form like '/AAA[1]/BBB[2]/CCC[1]'. Usually functions that require a node (see Node) 
|     will also accept an abs. XPath.
|     
| Node: (node, nodeSet, node-tree)
|     Some funtions require or return a node (or a whole node-tree). Nodes are only used with the 
|     XPath-interface and have an internal structure. Every node in a XML document has a unique 
|     corresponding abs. xPath. That's why public functions that accept a node, will usually also 
|     accept a abs. xPath (a string) 'pointing' to an existing node (see absolutXPath).
|     
| XPathQuery: (xquery, query)
|     A xPath-query is a string that is matched against the XML-document. The result of the match 
|     is a xPathSet (vector of xPath's). It's always possible to pass a single absoluteXPath 
|     instead of a xPath-query. A valid xPathQuery could look like this:
|     '//XXX/*[contains(., "foo")]/..' (See the link in 'What Is XPath' to learn more).
|     
|     
+------------------------------------------------------------------------------------------------------+
| Internals:
| ----------
| - The Node Tree
|   -------------
| A central role of the package is how the XML-data is stored. The whole data is in a node-tree.
| A node can be seen as the equvalent to a tag in the XML soure with some extra info.
| For instance the following XML 
|                        <AAA foo="x">***<BBB/><CCC/>**<BBB/>*</AAA>
| Would produce folowing node-tree:
|                              'super-root'      <-- $nodeRoot (Very handy)  
|                                    |                                           
|             'depth' 0            AAA[1]        <-- top node. The 'textParts' of this node would be
|                                /   |   \                     'textParts' => array('***','','**','*')
|             'depth' 1     BBB[1] CCC[1] BBB[2]               (NOTE: Is always size of child nodes+1)
| - The Node
|   --------
| The node itself is an structure desiged mainly to be used in connection with the interface of PHP.XPath.
| That means it's possible for functions to return a sub-node-tree that can be used as input of an other 
| PHP.XPath function.
| 
| The main structure of a node is:
|   $node = array(
|     'name'        => '',      # The tag name. E.g. In <FOO bar="aaa"/> it would be 'FOO'
|     'attributes'  => array(), # The attributes of the tag E.g. In <FOO bar="aaa"/> it would be array('bar'=>'aaa')
|     'textParts'   => array(), # Array of text parts surrounding the children E.g. <FOO>aa<A>bb<B/>cc</A>dd</FOO> -> array('aa','bb','cc','dd')
|     'childNodes'  => array(), # Array of refences (pointers) to child nodes.
|     
| For optimisation reasions some additional data is stored in the node too:
|     'parentNode'  => NULL     # Reference (pointer) to the parent node (or NULL if it's 'super root')
|     'depth'       => 0,       # The tag depth (or tree level) starting with the root tag at 0.
|     'pos'         => 0,       # Is the zero-based position this node has in the parent's 'childNodes'-list.
|     'contextPos'  => 1,       # Is the one-based position this node has by counting the siblings tags (tags with same name)
|     'xpath'       => ''       # Is the abs. XPath to this node.
|     'generated_id'=> ''       # The id returned for this node by generate-id() (attribute and text nodes not supported)
| 
| - The NodeIndex
|   -------------
| Every node in the tree has an absolute XPath. E.g '/AAA[1]/BBB[2]' the $nodeIndex is a hash array
| to all the nodes in the node-tree. The key used is the absolute XPath (a string).
|    
+------------------------------------------------------------------------------------------------------+
| License:
| --------
| The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); 
| you may not use this file except in compliance with the License. You may obtain a copy of the 
| License at http://www.mozilla.org/MPL/ 
| 
| Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY
| OF ANY KIND, either express or implied. See the License for the specific language governing 
| rights and limitations under the License. 
|
| The Original Code is <phpXML/>. 
| 
| The Initial Developer of the Original Code is Michael P. Mehl. Portions created by Michael 
| P. Mehl are Copyright (C) 2001 Michael P. Mehl. All Rights Reserved.
|
| Contributor(s): N.Swinson / S.Blum / D.Allen
| 
| Alternatively, the contents of this file may be used under the terms of either of the GNU 
| General Public License Version 2 or later (the "GPL"), or the GNU Lesser General Public 
| License Version 2.1 or later (the "LGPL"), in which case the provisions of the GPL or the 
| LGPL License are applicable instead of those above.  If you wish to allow use of your version 
| of this file only under the terms of the GPL or the LGPL License and not to allow others to 
| use your version of this file under the MPL, indicate your decision by deleting the 
| provisions above and replace them with the notice and other provisions required by the 
| GPL or the LGPL License.  If you do not delete the provisions above, a recipient may use 
| your version of this file under either the MPL, the GPL or the LGPL License. 
| 
+======================================================================================================+

The complete public interface

Public functions of XPath

Public base class members inherited from XPathEngine

Public base class members inherited from XPathBase


Class XPathBase

Public Methods

Private Methods

You really shouldn't be raking about in these functions, as you should only be using the public interface. But if you need more control, then these are the internal functions that you can use if you want to get your hands really dirty.

Public Method Detail

Method Details: XPathBase



function XPathBase()

Constructor

Line:

Defined on line 195

Method Details: reset



function reset()

Resets the object so it's able to take a new xml sting/file

Constructing objects is slow.  If you can, reuse ones that you have used already
by using this reset() function.

Line:

Defined on line 234

Method Details: setVerbose



function setVerbose($levelOfVerbosity = 1)

Alter the verbose (error) level reporting.

Pass an int. >0 to turn on, 0 to turn off.  The higher the number, the 
higher the level of verbosity. By default, the class has a verbose level 
of 1.

Parameter:

int $levelOfVerbosity

default is 1 = on

Line:

Defined on line 538

Method Details: getLastError



function getLastError()

Returns the last occured error message.

Return Value:

string (may be empty if there was no error at all)

Similar Functions:

_setLastError(), _lastError

Line:

Defined on line 557

Private Method Detail

Method Details: _bracketsCheck



function _bracketsCheck($term)

This method checks the right amount and match of brackets

Parameter:

string $term

String in which is checked.

Return Value:

bool

TRUE: OK / FALSE: KO

Line:

Defined on line 248

Method Details: _searchString



function _searchString($term, $expression)

Looks for a string within another string -- BUT the search-string must be located *outside* of any brackets.

This method looks for a string within another string. Brackets in the
string the method is looking through will be respected, which means that
only if the string the method is looking for is located outside of
brackets, the search will be successful.

Parameter:

string $term

String in which the search shall take place.

string $expression

String that should be searched.

Return Value:

int

This method returns -1 if no string was found, otherwise the offset at which the string was found.

Line:

Defined on line 305

Method Details: _bracketExplode



function _bracketExplode($separator, $term)

Split a string by a searator-string -- BUT the separator-string must be located *outside* of any brackets.

Returns an array of strings, each of which is a substring of string formed 
by splitting it on boundaries formed by the string separator. 

Parameter:

string $separator

String that should be searched.

string $term

String in which the search shall take place.

Return Value:

array

see above

Line:

Defined on line 337

Method Details: _getEndGroups



function _getEndGroups($string, $open='[', $close=']')

Split a string at it's groups, ie bracketed expressions

Returns an array of strings, when concatenated together would produce the original
string.  ie a(b)cde(f)(g) would map to:
array ('a', '(b)', cde', '(f)', '(g)')

Parameter:

string $string

The string to process

string $open

The substring for the open of a group

string $close

The substring for the close of a group

Return Value:

array

The parsed string, see above

Line:

Defined on line 415

Method Details: _prestr



function _prestr(&$string, $delimiter, $offset=0)

Retrieves a substring before a delimiter.

This method retrieves everything from a string before a given delimiter,
not including the delimiter.

Parameter:

string $string

String, from which the substring should be extracted.

string $delimiter

String containing the delimiter to use.

Return Value:

string

Substring from the original string before the delimiter.

Similar Functions:

_afterstr()

Line:

Defined on line 501

Method Details: _afterstr



function _afterstr($string, $delimiter, $offset=0)

Retrieves a substring after a delimiter.

This method retrieves everything from a string after a given delimiter,
not including the delimiter.

Parameter:

string $string

String, from which the substring should be extracted.

string $delimiter

String containing the delimiter to use.

Return Value:

string

Substring from the original string after the delimiter.

Similar Functions:

_prestr()

Line:

Defined on line 519

Method Details: _setLastError



function _setLastError($message='', $line='-', $file='-')

Creates a textual error message and sets it.

example: 'XPath error in THIS_FILE_NAME:LINE. Message: YOUR_MESSAGE';

I don't think the message should include any markup because not everyone wants to debug 
into the browser window.

You should call _displayError() rather than _setLastError() if you would like the message,
dependant on their verbose settings, echoed to the screen.

Parameter:

string $message

a textual error message default is ''

int $line

the line number where the error occured, use __LINE__

Similar Functions:

getLastError()

Line:

Defined on line 576

Method Details: _displayError



function _displayError($message, $lineNumber='-', $file='-', $terminate=TRUE)

Displays an error message.

This method displays an error messages depending on the users verbose settings 
and sets the last error message.  

If also possibly stops the execution of the script.
### Terminate should not be allowed --fab.  Should it??  N.S.

Parameter:

string $message

Error message to be displayed.

int $lineNumber

line number given by __LINE__

bool $terminate

(default TURE) End the execution of this script.

Line:

Defined on line 593

Method Details: _displayMessage



function _displayMessage($message, $lineNumber='-', $file='-')

Displays a diagnostic message

This method displays an error messages

Parameter:

string $message

Error message to be displayed.

int $lineNumber

line number given by __LINE__

Line:

Defined on line 610

Method Details: _beginDebugFunction



function _beginDebugFunction($functionName)

Called to begin the debug run of a function.

This method starts a <DIV><PRE> tag so that the entry to this function
is clear to the debugging user.  Call _closeDebugFunction() at the
end of the function to create a clean box round the function call.

Parameter:

string $functionName

the name of the function we are beginning to debug

Return Value:

array

the output from the microtime() function.

Author:

Sam Blum <bs_php@infeer.com>

Similar Functions:

_closeDebugFunction()

Line:

Defined on line 629

Method Details: _closeDebugFunction



function _closeDebugFunction($aStartTime, $returnValue = "")

Called to end the debug run of a function.

This method ends a <DIV><PRE> block and reports the time since $aStartTime
is clear to the debugging user.

Parameter:

array $aStartTime

the time that the function call was started.

mixed $return_value

the return value from the function call that we are debugging

Author:

Nigel Swinson <nigelswinson@users.sourceforge.net>

Line:

Defined on line 655

Method Details: _profileFunction



function _profileFunction($aStartTime, $alertString)

Call to return time since start of function for Profiling

Parameter:

array $aStartTime

the time that the function call was started.

string $alertString

the string to describe what has just finished happening

Line:

Defined on line 680

Method Details: _printContext



function _printContext($context)

Echo an XPath context for diagnostic purposes

Parameter:

array $context

An XPath context

Line:

Defined on line 693

Method Details: _treeDump



function _treeDump($node, $indent = '')

This is a debug helper function. It dumps the node-tree as HTML

*QUICK AND DIRTY*. Needs some polishing.

Parameter:

array $node

A node

string $indent

(optional, default=''). For internal recursive calls.

Line:

Defined on line 705

Class XPathEngine

The XPathEngine class extends the XPathBase class.

Public Methods

Private Methods

You really shouldn't be raking about in these functions, as you should only be using the public interface. But if you need more control, then these are the internal functions that you can use if you want to get your hands really dirty.

Public Method Detail

Method Details: XPathEngine



function XPathEngine($userXmlOptions=array())

Constructor

Optionally you may call this constructor with the XML-filename to parse and the 
XML option vector. Each of the entries in the option vector will be passed to
xml_parser_set_option().

A option vector sample: 
  $xmlOpt = array(XML_OPTION_CASE_FOLDING => FALSE, 
                  XML_OPTION_SKIP_WHITE => TRUE);

Parameter:

array $userXmlOptions

(optional) Vector of (<optionID>=><value>, <optionID>=><value>, ...). See PHP's xml_parser_set_option() docu for a list of possible options.

Similar Functions:

importFromFile(), importFromString(), setXmlOptions()

Line:

Defined on line 841

Method Details: reset



function reset()

Resets the object so it's able to take a new xml sting/file

Constructing objects is slow.  If you can, reuse ones that you have used already
by using this reset() function.

Line:

Defined on line 861

Method Details: getProperties



function getProperties($param=NULL)

Returns the property/ies you want.

if $param is not given, all properties will be returned in a hash.

Parameter:

string $param

the property you want the value of, or NULL for all the properties

Return Value:

mixed

string OR hash of all params, or NULL on an unknown parameter.

Line:

Defined on line 887

Method Details: setXmlOption



function setXmlOption($optionID, $value)

Set an xml_parser_set_option()

Parameter:

int $optionID

The option ID (e.g. XML_OPTION_SKIP_WHITE)

int $value

The option value.

Similar Functions:

XML parser functions in PHP doc

Line:

Defined on line 908

Method Details: setXmlOptions



function setXmlOptions($userXmlOptions=array())

Sets a number of xml_parser_set_option()s

Parameter:

array $userXmlOptions

An array of parser options.

Similar Functions:

setXmlOption

Line:

Defined on line 919

Method Details: setCaseFolding



function setCaseFolding($onOff=TRUE)

Alternative way to control whether case-folding is enabled for this XML parser.

Short cut to setXmlOptions(XML_OPTION_CASE_FOLDING, TRUE/FALSE)

When it comes to XML, case-folding simply means uppercasing all tag- 
and attribute-names (NOT the content) if set to TRUE.  Note if you
have this option set, then your XPath queries will also be case folded 
for you.

Parameter:

bool $onOff

(default TRUE)

Similar Functions:

XML parser functions in PHP doc

Line:

Defined on line 939

Method Details: setSkipWhiteSpaces



function setSkipWhiteSpaces($onOff=TRUE)

Alternative way to control whether skip-white-spaces is enabled for this XML parser.

Short cut to setXmlOptions(XML_OPTION_SKIP_WHITE, TRUE/FALSE)

When it comes to XML, skip-white-spaces will trim the tag content.
An XML file with no whitespace will be faster to process, but will make 
your data less human readable when you come to write it out.

Running with this option on will slow the class down, so if you want to 
speed up your XML, then run it through once skipping white-spaces, then
write out the new version of your XML without whitespace, then use the
new XML file with skip whitespaces turned off.

Parameter:

bool $onOff

(default TRUE)

Similar Functions:

XML parser functions in PHP doc

Line:

Defined on line 960

Method Details: getNode



function &getNode($absoluteXPath='')

Get the node defined by the $absoluteXPath.

Parameter:

string $absoluteXPath

(optional, default is 'super-root') xpath to the node.

Return Value:

array

The node, or FALSE if the node wasn't found.

Line:

Defined on line 970

Method Details: wholeText



function &wholeText($absoluteXPath, $textPartNr=NULL)

Get a the content of a node text part or node attribute.

If the absolute Xpath references an attribute (Xpath ends with @ or attribute::), 
then the text value of that node-attribute is returned.
Otherwise the Xpath is referencing a text part of the node. This can be either a 
direct reference to a text part (Xpath ends with text()[<nr>]) or indirect reference 
(a simple abs. Xpath to a node).
1) Direct Reference (xpath ends with text()[<part-number>]):
  If the 'part-number' is omitted, the first text-part is assumed; starting by 1.
  Negative numbers are allowed, where -1 is the last text-part a.s.o.
2) Indirect Reference (a simple abs. Xpath to a node):
  Default is to return the *whole text*; that is the concated text-parts of the matching
  node. (NOTE that only in this case you'll only get a copy and changes to the returned  
  value wounld have no effect). Optionally you may pass a parameter 
  $textPartNr to define the text-part you want;  starting by 1.
  Negative numbers are allowed, where -1 is the last text-part a.s.o.

NOTE I : The returned value can be fetched by reference
         E.g. $text =& wholeText(). If you wish to modify the text.
NOTE II: text-part numbers out of range will return FALSE
SIDENOTE:The function name is a suggestion from W3C in the XPath specification level 3.

Parameter:

string $absoluteXPath

xpath to the node (See above).

int $textPartNr

If referring to a node, specifies which text part to query.

Return Value:

&string

A *reference* to the text if the node that the other parameters describe or FALSE if the node is not found.

Line:

Defined on line 1006

Method Details: exportAsHtml



function exportAsHtml($absoluteXPath='', $hilightXpathList=array())

Returns the containing XML as marked up HTML with specified nodes hi-lighted

Parameter:

string $absoluteXPath

The address of the node you would like to export. If empty the whole document will be exported.

array $hilighXpathList

A list of nodes that you would like to highlight

Return Value:

mixed

The Xml document marked up as HTML so that it can be viewed in a browser, including any XML headers. FALSE on error.

Similar Functions:

_export()

Line:

Defined on line 1116

Method Details: exportAsXml



function exportAsXml($absoluteXPath='', $xmlHeader=NULL)

Given a context this function returns the containing XML

Parameter:

string $absoluteXPath

The address of the node you would like to export. If empty the whole document will be exported.

array $xmlHeader

The string that you would like to appear before the XML content. ie before the <root></root>. If you do not specify this argument, the xmlHeader that was found in the parsed xml file will be used instead.

Return Value:

mixed

The Xml fragment/document, suitable for writing out to an .xml file or as part of a larger xml file, or FALSE on error.

Similar Functions:

_export()

Line:

Defined on line 1136

Method Details: exportToFile



function exportToFile($fileName, $absoluteXPath='', $xmlHeader=NULL)

Generates a XML string with the content of the current document and writes it to a file.

Per default includes a <?xml ...> tag at the start of the data too. 

Parameter:

string $absoluteXPath

The path to the parent node you want(see text above)

array $xmlHeader

The string that you would like to appear before the XML content. ie before the <root></root>. If you do not specify this argument, the xmlHeader that was found in the parsed xml file will be used instead.

Return Value:

string

The returned string contains well-formed XML data or FALSE on error.

Similar Functions:

exportAsXml(), exportAsHtml()

Line:

Defined on line 1156

Method Details: importFromFile



function importFromFile($fileName)

Reads a file or URL and parses the XML data.

Parse the XML source and (upon success) store the information into an internal structure.

Parameter:

string $fileName

Path and name (or URL) of the file to be read and parsed.

Return Value:

bool

TRUE on success, FALSE on failure (check getLastError())

Similar Functions:

importFromString(), getLastError(),

Line:

Defined on line 1552

Method Details: importFromString



function importFromString($xmlString, $absoluteParentPath = '')

Reads a string and parses the XML data.

Parse the XML source and (upon success) store the information into an internal structure.
If a parent xpath is given this means that XML data is to be *appended* to that parent.

### If a function uses setLastError(), then say in the function header that getLastError() is useful.

Parameter:

string $xmlString

Name of the string to be read and parsed.

string $absoluteParentPath

Node to append data too (see above)

Return Value:

bool

TRUE on success, FALSE on failure (check getLastError())

Line:

Defined on line 1617

Method Details: reindexNodeTree



function reindexNodeTree()

Update nodeIndex and every node of the node-tree.

Call after you have finished any tree modifications other wise a match with 
an xPathQuery will produce wrong results.  The $this->nodeIndex[] is recreated 
and every nodes optimization data is updated.  The optimization data is all the
data that is duplicate information, would just take longer to find. Child nodes 
with value NULL are removed from the tree.

By default the modification functions in this component will automatically re-index
the nodes in the tree.  Sometimes this is not the behaver you want. To surpress the 
reindex, set the functions $autoReindex to FALSE and call reindexNodeTree() at the 
end of your changes.  This sometimes leads to better code (and less CPU overhead).

Sample:
=======
Given the xml is <AAA><B/>.<B/>.<B/></AAA> | Goal is <AAA>.<B/>.</AAA>  (Delete B[1] and B[3])
  $xPathSet = $xPath->match('//B'); # Will result in array('/AAA[1]/B[1]', '/AAA[1]/B[2]', '/AAA[1]/B[3]');
Three ways to do it.
1) Top-Down  (with auto reindexing) - Safe, Slow and you get easily mix up with the the changing node index
   removeChild('/AAA[1]/B[1]'); // B[1] removed, thus all B[n] become B[n-1] !!
   removeChild('/AAA[1]/B[2]'); // Now remove B[2] (That originaly was B[3])
2) Bottom-Up (with auto reindexing) -  Safe, Slow and the changing node index (caused by auto-reindex) can be ignored.
   for ($i=sizeOf($xPathSet)-1; $i>=0; $i--) {
     if ($i==1) continue; 
     removeChild($xPathSet[$i]);
   }
3) // Top-down (with *NO* auto reindexing) - Fast, Safe as long as you call reindexNodeTree()
   foreach($xPathSet as $xPath) {
     // Specify no reindexing
     if ($xPath == $xPathSet[1]) continue; 
     removeChild($xPath, $autoReindex=FALSE);
     // The object is now in a slightly inconsistent state.
   }
   // Finally do the reindex and the object is consistent again
   reindexNodeTree();

Return Value:

bool

TRUE on success, FALSE otherwise.

Similar Functions:

_recursiveReindexNodeTree()

Line:

Defined on line 2062

Method Details: cloneNode



function &cloneNode($node, $recursive=FALSE)

Clone a node and it's child nodes.

NOTE: If the node has children you *MUST* use the reference operator!
      E.g. $clonedNode =& cloneNode($node);
      Otherwise the children will not point back to the parent, they will point 
      back to your temporary variable instead.

Parameter:

mixed $node

Either a node (hash array) or an abs. Xpath to a node in the current doc

Return Value:

&array

A node and it's child nodes.

Line:

Defined on line 2196

Method Details: match



function match($xPathQuery, $baseXPath='')

Matches (evaluates) an XPath query

This method tries to evaluate an XPath query by parsing it. A XML source must 
have been imported before this method is able to work.

Parameter:

string $xPathQuery

XPath query to be evaluated.

string $baseXPath

(default is super-root) XPath query to a single document node, from which the XPath query should start evaluating.

Return Value:

mixed

The result of the XPath expression. Either: node-set (an ordered collection of absolute references to nodes without duplicates) boolean (true or false) number (a floating-point number) string (a sequence of UCS characters)

Line:

Defined on line 2271

Method Details: evaluate



function evaluate($xPathQuery, $baseXPath='')

Alias for the match function

Similar Functions:

match()

Line:

Defined on line 2335

Method Details: decodeEntities



function decodeEntities($encodedData, $reverse=FALSE)

Decodes the character set entities in the given string.

This function is given for convenience, as all text strings or attributes
are going to come back to you with their entities still encoded.  You can
use this function to remove these entites.

It makes use of the get_html_translation_table(HTML_ENTITIES) php library 
call, so is limited in the same ways.  At the time of writing this seemed
be restricted to iso-8859-1

### Provide an option that will do this by default.

Parameter:

mixed $encodedData

The string or array that has entities you would like to remove

bool $reverse

If TRUE entities will be encoded rather than decoded, ie < to &lt; rather than &lt; to <.

Return Value:

mixed

The string or array returned with entities decoded.

Line:

Defined on line 4955

Method Details: equalNodes



function equalNodes($node1, $node2)

Compare two nodes to see if they are equal (point to the same node in the doc)

2 nodes are considered equal if the absolute XPath is equal.

Parameter:

mixed $node1

Either an absolute XPath to an node OR a real tree-node (hash-array)

mixed $node2

Either an absolute XPath to an node OR a real tree-node (hash-array)

Return Value:

bool

TRUE if equal (see text above), FALSE if not (and on error).

Line:

Defined on line 4995

Method Details: getNodePath



function getNodePath($node)

Get the absolute XPath of a node that is in a document tree.

Parameter:

array $node

A real tree-node (hash-array)

Return Value:

string

The string path to the node or FALSE on error.

Line:

Defined on line 5007

Method Details: getParentXPath



function getParentXPath($absoluteXPath)

Retrieves the absolute parent XPath query.

The parents stored in the tree are only relative parents...but all the parent
information is stored in the XPath query itself...so instead we use a function
to extract the parent from the absolute Xpath query

Parameter:

string $childPath

String containing an absolute XPath query

Return Value:

string

returns the absolute XPath of the parent

Line:

Defined on line 5034

Method Details: hasChildNodes



function hasChildNodes($absoluteXPath)

Returns TRUE if the given node has child nodes below it

Parameter:

string $absoluteXPath

full path of the potential parent node

Return Value:

bool

TRUE if this node exists and has a child, FALSE otherwise

Line:

Defined on line 5049

Private Method Detail

Method Details: _stringValue



function _stringValue($node)

Obtain the string value of an object

http://www.w3.org/TR/xpath#dt-string-value

"For every type of node, there is a way of determining a string-value for a node of that type. 
For some types of node, the string-value is part of the node; for other types of node, the 
string-value is computed from the string-value of descendant nodes."

Parameter:

node $node

The node we have to convert

Return Value:

string

The string value of the node. "" if the object has no evaluatable string value

Line:

Defined on line 1096

Method Details: _export



function _export($absoluteXPath='', $xmlHeader=NULL, $hilightXpathList='')

Generates a XML string with the content of the current document.

This is the start for extracting the XML-data from the node-tree. We do some preperations
and then call _InternalExport() to fetch the main XML-data. You optionally may pass 
xpath to any node that will then be used as top node, to extract XML-parts of the 
document. Default is '', meaning to extract the whole document.

You also may pass a 'xmlHeader' (usually something like <?xml version="1.0"? > that will
overwrite any other 'xmlHeader', if there was one in the original source.  If there
wasn't one in the original source, and you still don't specify one, then it will
use a default of <?xml version="1.0"? >
Finaly, when exporting to HTML, you may pass a vector xPaths you want to hi-light.
The hi-lighted tags and attributes will receive a nice color. 

NOTE I : The output can have 2 formats:
      a) If "skip white spaces" is/was set. (Not Recommended - slower)
         The output is formatted by adding indenting and carriage returns.
      b) If "skip white spaces" is/was *NOT* set.
         'as is'. No formatting is done. The output should the same as the 
         the original parsed XML source. 

Parameter:

string $absoluteXPath

(optional, default is root) The node we choose as top-node

string $xmlHeader

(optional) content before <root/> (see text above)

array $hilightXpath

(optional) a vector of xPaths to nodes we wat to hi-light (see text above)

Return Value:

mixed

The xml string, or FALSE on error.

Line:

Defined on line 1227

Method Details: _InternalExport



function _InternalExport($node)

Export the xml document starting at the named node.

Parameter:

node $node

The node we have to start exporting from

Return Value:

string

The string representation of the node.

Line:

Defined on line 1301

Method Details: _handleStartElement



function _handleStartElement($parser, $nodeName, $attributes)

Handles opening XML tags while parsing.

While parsing a XML document for each opening tag this method is
called. It'll add the tag found to the tree of document nodes.

Parameter:

int $parser

Handler for accessing the current XML parser.

string $name

Name of the opening tag found in the document.

array $attributes

Associative array containing a list of all attributes of the tag found in the document.

Similar Functions:

_handleEndElement(), _handleCharacterData()

Line:

Defined on line 1757

Method Details: _handleEndElement



function _handleEndElement($parser, $name)

Handles closing XML tags while parsing.

While parsing a XML document for each closing tag this method is called.

Parameter:

int $parser

Handler for accessing the current XML parser.

string $name

Name of the closing tag found in the document.

Similar Functions:

_handleStartElement(), _handleCharacterData()

Line:

Defined on line 1815

Method Details: _handleCharacterData



function _handleCharacterData($parser, $text)

Handles character data while parsing.

While parsing a XML document for each character data this method
is called. It'll add the character data to the document tree.

Parameter:

int $parser

Handler for accessing the current XML parser.

string $text

Character data found in the document.

Similar Functions:

_handleStartElement(), _handleEndElement()

Line:

Defined on line 1865

Method Details: _handleDefaultData



function _handleDefaultData($parser, $text)

Default handler for the XML parser.

While parsing a XML document for string not caught by one of the other
handler functions, we end up here.

Parameter:

int $parser

Handler for accessing the current XML parser.

string $text

Character data found in the document.

Similar Functions:

_handleStartElement(), _handleEndElement()

Line:

Defined on line 1898

Method Details: _handlePI



function _handlePI($parser, $target, $data)

Handles processing instruction (PI)

A processing instruction has the following format: 
<?  target data  ? > e.g.  <? dtd version="1.0" ? >

Currently I have no bether idea as to left it 'as is' and treat the PI data as normal 
text (and adding the surrounding PI-tags <? ? >). 

Parameter:

int $parser

Handler for accessing the current XML parser.

string $target

Name of the PI target. E.g. XML, PHP, DTD, ...

string $data

Associative array containing a list of

Similar Functions:

PHP's manual "xml_set_processing_instruction_handler"

Line:

Defined on line 1926

Method Details: _createSuperRoot



function _createSuperRoot()

Creates a super root node.

Line:

Defined on line 1940

Method Details: _internalAppendChild



function _internalAppendChild($stackParentIndex, $nodeName)

Adds a new node to the XML document tree during xml parsing.

This method adds a new node to the tree of nodes of the XML document
being handled by this class. The new node is created according to the
parameters passed to this method.  This method is a much watered down
version of appendChild(), used in parsing an xml file only.

It is assumed that adding starts with root and progresses through the
document in parse order.  New nodes must have a corresponding parent. And
once we have read the </> tag for the element we will never need to add
any more data to that node.  Otherwise the add will be ignored or fail.

The function is faciliated by a nodeStack, which is an array of nodes that
we have yet to close.

Parameter:

int $stackParentIndex

The index into the nodeStack[] of the parent node to which the new node should be added as a child. *READONLY*

string $nodeName

Name of the new node. *READONLY*

Return Value:

bool

TRUE if we successfully added a new child to the node stack at index $stackParentIndex + 1, FALSE on error.

Line:

Defined on line 1972

Method Details: _generate_ids



function _generate_ids()

Create the ids that are accessable through the generate-id() function

Line:

Defined on line 2076

Method Details: _recursiveReindexNodeTree



function _recursiveReindexNodeTree($absoluteParentPath)

Here's where the work is done for reindexing (see reindexNodeTree)

Parameter:

string $absoluteParentPath

the xPath to the parent node

Return Value:

bool

TRUE on success, FALSE otherwise.

Similar Functions:

reindexNodeTree()

Line:

Defined on line 2103

Method Details: __sleep



function __sleep()

PHP cals this function when you call PHP's serialize.

It prevents cyclic referencing, which is why print_r() of an XPath object doesn't work.

Line:

Defined on line 2231

Method Details: __wakeup



function __wakeup()

PHP cals this function when you call PHP's unserialize.

It reindexes the node-tree

Line:

Defined on line 2246

Method Details: _removeLiterals



function _removeLiterals($xPathQuery)

Parse out the literals of an XPath expression.

Instead of doing a full lexical parse, we parse out the literal strings, and then
Treat the sections of the string either as parts of XPath or literal strings.  So
this function replaces each literal it finds with a literal reference, and then inserts
the reference into an array of strings that we can access.  The literals can be accessed
later from the literals associative array.

Example:
 XPathExpr = /AAA[@CCC = "hello"]/BBB[DDD = 'world'] 
 =>  literals: array("hello", "world")
     return value: /AAA[@CCC = $1]/BBB[DDD = $2] 

Note: This does not interfere with the VariableReference syntactical element, as these 
elements must not start with a number.

Parameter:

string $xPathQuery

XPath expression to be processed

Return Value:

string

The XPath expression without the literals.

Line:

Defined on line 2360

Method Details: _asLiteral



function _asLiteral($string)

Returns the given string as a literal reference.

Parameter:

string $string

The string that we are processing

Return Value:

mixed

The literal string. FALSE if the string isn't a literal reference.

Line:

Defined on line 2395

Method Details: _addLiteral



function _addLiteral($string)

Adds a literal to our array of literals

In order to make sure we don't interpret literal strings as XPath expressions, we have to
encode literal strings so that we know that they are not XPaths.

Parameter:

string $string

The literal string that we need to store for future access

Return Value:

mixed

A reference string to this literal.

Line:

Defined on line 2424

Method Details: _GetOperator



function _GetOperator($xPathQuery)

Look for operators in the expression

Parses through the given expression looking for operators.  If found returns
the operands and the operator in the resulting array.

Parameter:

string $xPathQuery

XPath query to be evaluated.

Return Value:

array

If an operator is found, it returns an array containing information about the operator. If no operator is found then it returns an empty array. If an operator is found, but has invalid operands, it returns FALSE. The resulting array has the following entries: 'operator' => The string version of operator that was found, trimmed for whitespace 'left operand' => The left operand, or empty if there was no left operand for this operator. 'right operand' => The right operand, or empty if there was no right operand for this operator.

Line:

Defined on line 2451

Method Details: _evaluatePrimaryExpr



function _evaluatePrimaryExpr($xPathQuery, $context, &$result)

Evaluates an XPath PrimaryExpr

http://www.w3.org/TR/xpath#section-Basics

 [15]    PrimaryExpr    ::= VariableReference  
                            | '(' Expr ')'  
                            | Literal  
                            | Number  
                            | FunctionCall 

Parameter:

string $xPathQuery

XPath query to be evaluated.

array $context

The context from which to evaluate

mixed $results

If the expression could be parsed and evaluated as one of these syntactical elements, then this will be either: - node-set (an ordered collection of nodes without duplicates) - boolean (true or false) - number (a floating-point number) - string (a sequence of UCS characters)

Return Value:

string

An empty string if the query was successfully parsed and evaluated, else a string containing the reason for failing.

Similar Functions:

evaluate()

Line:

Defined on line 2600

Method Details: _evaluateExpr



function _evaluateExpr($xPathQuery, $context)

Evaluates an XPath Expr

$this->evaluate() is the entry point and does some inits, while this 
function is called recursive internaly for every sub-xPath expresion we find.
It handles the following syntax, and calls evaluatePathExpr if it finds that none
of this grammer applies.

http://www.w3.org/TR/xpath#section-Basics

[14]    Expr               ::= OrExpr 
[21]    OrExpr             ::= AndExpr  
                               | OrExpr 'or' AndExpr  
[22]    AndExpr            ::= EqualityExpr  
                               | AndExpr 'and' EqualityExpr  
[23]    EqualityExpr       ::= RelationalExpr  
                               | EqualityExpr '=' RelationalExpr  
                               | EqualityExpr '!=' RelationalExpr  
[24]    RelationalExpr     ::= AdditiveExpr  
                               | RelationalExpr '<' AdditiveExpr  
                               | RelationalExpr '>' AdditiveExpr  
                               | RelationalExpr '<=' AdditiveExpr  
                               | RelationalExpr '>=' AdditiveExpr  
[25]    AdditiveExpr       ::= MultiplicativeExpr  
                               | AdditiveExpr '+' MultiplicativeExpr  
                               | AdditiveExpr '-' MultiplicativeExpr  
[26]    MultiplicativeExpr ::= UnaryExpr  
                               | MultiplicativeExpr MultiplyOperator UnaryExpr  
                               | MultiplicativeExpr 'div' UnaryExpr  
                               | MultiplicativeExpr 'mod' UnaryExpr  
[27]    UnaryExpr          ::= UnionExpr  
                               | '-' UnaryExpr 
[18]    UnionExpr          ::= PathExpr  
                               | UnionExpr '|' PathExpr 

NOTE: The effect of the above grammar is that the order of precedence is 
(lowest precedence first): 
1) or 
2) and 
3) =, != 
4) <=, <, >=, > 
5) +, -
6) *, div, mod
7) - (negate)
8) |

Parameter:

string $xPathQuery

XPath query to be evaluated.

array $context

An associative array the describes the context from which to evaluate the XPath Expr. Contains three members: 'nodePath' => The absolute XPath expression to the context node 'size' => The context size 'pos' => The context position

Return Value:

mixed

The result of the XPath expression. Either: node-set (an ordered collection of nodes without duplicates) boolean (true or false) number (a floating-point number) string (a sequence of UCS characters)

Similar Functions:

evaluate()

Line:

Defined on line 2764

Method Details: _evaluateOperator



function _evaluateOperator($left, $operator, $right, $operatorType, $context)

Evaluate the result of an operator whose operands have been evaluated

If the operator type is not "NodeSet", then neither the left or right operators 
will be node sets, as the processing when one or other is an array is complex,
and should be handled by the caller.

Parameter:

mixed $left

The left operand

mixed $right

The right operand

string $operator

The operator to use to combine the operands

string $operatorType

The type of the operator. Either 'Boolean', 'Integer', 'String', or 'NodeSet'

array $context

The context from which to evaluate

Return Value:

mixed

The result of the XPath expression. Either: node-set (an ordered collection of nodes without duplicates) boolean (true or false) number (a floating-point number) string (a sequence of UCS characters)

Line:

Defined on line 3018

Method Details: _evaluatePathExpr



function _evaluatePathExpr($PathExpr, $context)

Evaluates an XPath PathExpr

It handles the following syntax:

http://www.w3.org/TR/xpath#node-sets
http://www.w3.org/TR/xpath#NT-LocationPath
http://www.w3.org/TR/xpath#path-abbrev
http://www.w3.org/TR/xpath#NT-Step

[19]   PathExpr              ::= LocationPath  
                                 | FilterExpr  
                                 | FilterExpr '/' RelativeLocationPath  
                                 | FilterExpr '//' RelativeLocationPath
[20]   FilterExpr            ::= PrimaryExpr  
                                 | FilterExpr Predicate 
[1]    LocationPath          ::= RelativeLocationPath  
                                 | AbsoluteLocationPath  
[2]    AbsoluteLocationPath  ::= '/' RelativeLocationPath?  
                                 | AbbreviatedAbsoluteLocationPath
[3]    RelativeLocationPath  ::= Step  
                                 | RelativeLocationPath '/' Step  
                                 | AbbreviatedRelativeLocationPath
[4]    Step                  ::= AxisSpecifier NodeTest Predicate*  
                                 | AbbreviatedStep  
[5]    AxisSpecifier         ::= AxisName '::'  
                                 | AbbreviatedAxisSpecifier  
[10]   AbbreviatedAbsoluteLocationPath
                             ::= '//' RelativeLocationPath
[11]   AbbreviatedRelativeLocationPath
                             ::= RelativeLocationPath '//' Step
[12]   AbbreviatedStep       ::= '.'  
                                 | '..'  
[13]   AbbreviatedAxisSpecifier    
                             ::= '@'? 

If you expand all the abbreviated versions, then the grammer simplifies to:

[19]   PathExpr              ::= RelativeLocationPath  
                                 | '/' RelativeLocationPath?  
                                 | FilterExpr  
                                 | FilterExpr '/' RelativeLocationPath  
[20]   FilterExpr            ::= PrimaryExpr  
                                 | FilterExpr Predicate 
[3]    RelativeLocationPath  ::= Step  
                                 | RelativeLocationPath '/' Step  
[4]    Step                  ::= AxisName '::' NodeTest Predicate*  

Conceptually you can say that we should split by '/' and try to treat the parts
as steps, and if that fails then try to treat it as a PrimaryExpr.  

Parameter:

string $PathExpr

PathExpr syntactical element

array $context

The context from which to evaluate

Return Value:

mixed

The result of the XPath expression. Either: node-set (an ordered collection of nodes without duplicates) boolean (true or false) number (a floating-point number) string (a sequence of UCS characters)

Similar Functions:

evaluate()

Line:

Defined on line 3207

Method Details: _sortByDocOrder



function _sortByDocOrder($xPathSet)

Sort an xPathSet by doc order.

Parameter:

array $xPathSet

Array of full paths to nodes that need to be sorted

Return Value:

array

Array containing the same contents as $xPathSet, but with the contents in doc order

Line:

Defined on line 3279

Method Details: _evaluateStep



function _evaluateStep($steps, $context)

Evaluate a step from a XPathQuery expression at a specific contextPath.

Steps are the arguments of a XPathQuery when divided by a '/'. A contextPath is a 
absolute XPath (or vector of XPaths) to a starting node(s) from which the step should 
be evaluated.

Parameter:

array $steps

Vector containing the remaining steps of the current XPathQuery expression.

array $context

The context from which to evaluate

Return Value:

array

Vector of absolute XPath's as a result of the step evaluation. The results will not necessarily be in doc order

Similar Functions:

_evaluatePathExpr()

Line:

Defined on line 3378

Method Details: _checkPredicates



function _checkPredicates($xPathSet, $predicates)

Checks whether a node matches predicates.

This method checks whether a list of nodes passed to this method match
a given list of predicates. 

Parameter:

array $xPathSet

Array of full paths of all nodes to be tested.

array $predicates

Array of predicates to use.

Return Value:

array

Vector of absolute XPath's that match the given predicates.

Similar Functions:

_evaluateStep()

Line:

Defined on line 3477

Method Details: _evaluateFunction



function _evaluateFunction($function, $arguments, $context)

Evaluates an XPath function

This method evaluates a given XPath function with its arguments on a
specific node of the document.

Parameter:

string $function

Name of the function to be evaluated.

string $arguments

String containing the arguments being passed to the function.

array $context

The context from which to evaluate

Return Value:

mixed

This method returns the result of the evaluation of the function. Depending on the function the type of the return value can be different.

Similar Functions:

evaluate()

Line:

Defined on line 3574

Method Details: _checkNodeTest



function _checkNodeTest($contextPath, $nodeTest)

Checks whether a node matches a node-test.

This method checks whether a node in the document matches a given node-test.
A node test is something like text(), node(), or an element name.

Parameter:

string $contextPath

Full xpath of the node, which should be tested for matching the node-test.

string $nodeTest

String containing the node-test for the node.

Return Value:

boolean

This method returns TRUE if the node matches the node-test, otherwise FALSE.

Similar Functions:

evaluate()

Line:

Defined on line 3632

Method Details: _getAxis



function _getAxis($step)

Retrieves axis information from an XPath query step.

This method tries to extract the name of the axis and its node-test
from a given step of an XPath query at a given node.  If it can't parse
the step, then we treat it as a PrimaryExpr.

[4]    Step            ::= AxisSpecifier NodeTest Predicate*  
                           | AbbreviatedStep  
[5]    AxisSpecifier   ::= AxisName '::'  
                           | AbbreviatedAxisSpecifier 
[12]   AbbreviatedStep ::= '.'  
                           | '..'  
[13]   AbbreviatedAxisSpecifier    
                       ::=    '@'? 

[7]    NodeTest        ::= NameTest  
                           | NodeType '(' ')'  
                           | 'processing-instruction' '(' Literal ')'  
[37]   NameTest        ::= '*'  
                           | NCName ':' '*'  
                           | QName  
[38]   NodeType        ::= 'comment'  
                           | 'text'  
                           | 'processing-instruction'  
                           | 'node' 

Parameter:

string $step

String containing a step of an XPath query.

Return Value:

array

Contains information about the axis found in the step, or FALSE if the string isn't a valid step.

Similar Functions:

_evaluateStep()

Line:

Defined on line 3734

Method Details: _handleAxis_child



function _handleAxis_child($axis, $contextPath)

Handles the XPath child axis.

This method handles the XPath child axis.  It essentially filters out the
children to match the name specified after the '/'.

Parameter:

array $axis

Array containing information about the axis.

string $contextPath

xpath to starting node from which the axis should be processed.

Return Value:

array

A vector containing all nodes that were found, during the evaluation of the axis.

Similar Functions:

evaluate()

Line:

Defined on line 3930

Method Details: _handleAxis_parent



function _handleAxis_parent($axis, $contextPath)

Handles the XPath parent axis.

Parameter:

array $axis

Array containing information about the axis.

string $contextPath

xpath to starting node from which the axis should be processed.

Return Value: