ExplorerIndex phpBanners PhpiCalLib PhpXDb Php.XPath SCMS

Php.XPath Documentation

Documentation for the XPath.class.php file version 3.5

Introduction
The complete public interface
class - XPathBase
class - XPathEngine
class - XPath

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

XPath : Constructor of the class
reset : Resets the object so it's able to take a new xml sting/file
setModMatch : Resolves and xPathQuery array depending on the property['modMatch']
nodeName : Retrieves the name(s) of a node or a group of document nodes.
removeChild : Removes a node from the XML document.
replaceChildByData : Replace a node with any data string. The $data is taken 1:1.
replaceChild : Replace the node(s) that matches the xQuery with the passed node (or passed node-tree)
insertChild : Insert passed node (or passed node-tree) at the node(s) that matches the xQuery.
appendChild : Appends a child to anothers children.
insertBefore : Inserts a node before the reference node with the same parent.
getAttributes : Retrieves a dedecated attribute value or a hash-array of all attributes of a node.
setAttribute : Set attributes of a node(s).
setAttributes : Version of setAttribute() that sets multiple attributes to node(s).
removeAttribute : Removes an attribute of a node(s).
getData : Retrieve all the text from a node as a single string.
getDataParts : Retrieve all the text from a node as a vector of strings
substringData : Retrieves a sub string of a text-part OR attribute-value.
replaceData : Replace a sub string of a text-part OR attribute-value.
insertData : Insert a sub string in a text-part OR attribute-value.
appendData : Append text data to the end of the text for an attribute OR node text-part.
deleteData : Delete the data of a node.

Public base class members inherited from XPathEngine

XPathEngine : Constructor
reset : Resets the object so it's able to take a new xml sting/file
getProperties : Returns the property/ies you want.
setXmlOption : Set an xml_parser_set_option()
setXmlOptions : Sets a number of xml_parser_set_option()s
setCaseFolding : Alternative way to control whether case-folding is enabled for this XML parser.
setSkipWhiteSpaces : Alternative way to control whether skip-white-spaces is enabled for this XML parser.
getNode : Get the node defined by the $absoluteXPath.
wholeText : Get a the content of a node text part or node attribute.
exportAsHtml : Returns the containing XML as marked up HTML with specified nodes hi-lighted
exportAsXml : Given a context this function returns the containing XML
exportToFile : Generates a XML string with the content of the current document and writes it to a file.
importFromFile : Reads a file or URL and parses the XML data.
importFromString : Reads a string and parses the XML data.
reindexNodeTree : Update nodeIndex and every node of the node-tree.
cloneNode : Clone a node and it's child nodes.
match : Matches (evaluates) an XPath query
evaluate : Alias for the match function
decodeEntities : Decodes the character set entities in the given string.
equalNodes : Compare two nodes to see if they are equal (point to the same node in the doc)
getNodePath : Get the absolute XPath of a node that is in a document tree.
getParentXPath : Retrieves the absolute parent XPath query.
hasChildNodes : Returns TRUE if the given node has child nodes below it

Public base class members inherited from XPathBase

XPathBase : Constructor
reset : Resets the object so it's able to take a new xml sting/file
setVerbose : Alter the verbose (error) level reporting.
getLastError : Returns the last occured error message.

Class XPathBase

Public Methods
Private Methods
Public Methods Detail
Private Methods Detail

Public Methods

XPathBase : Constructor
reset : Resets the object so it's able to take a new xml sting/file
setVerbose : Alter the verbose (error) level reporting.
getLastError : Returns the last occured error message.

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.

_bracketsCheck : This method checks the right amount and match of brackets
_searchString : Looks for a string within another string -- BUT the search-string must be located *outside* of any brackets.
_bracketExplode : Split a string by a searator-string -- BUT the separator-string must be located *outside* of any brackets.
_getEndGroups : Split a string at it's groups, ie bracketed expressions
_prestr : Retrieves a substring before a delimiter.
_afterstr : Retrieves a substring after a delimiter.
_setLastError : Creates a textual error message and sets it.
_displayError : Displays an error message.
_displayMessage : Displays a diagnostic message
_beginDebugFunction : Called to begin the debug run of a function.
_closeDebugFunction : Called to end the debug run of a function.
_profileFunction : Call to return time since start of function for Profiling
_printContext : Echo an XPath context for diagnostic purposes
_treeDump : This is a debug helper function. It dumps the node-tree as HTML

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
Public Methods Detail
Private Methods Detail

Public Methods

XPathEngine : Constructor
reset : Resets the object so it's able to take a new xml sting/file
getProperties : Returns the property/ies you want.
setXmlOption : Set an xml_parser_set_option()
setXmlOptions : Sets a number of xml_parser_set_option()s
setCaseFolding : Alternative way to control whether case-folding is enabled for this XML parser.
setSkipWhiteSpaces : Alternative way to control whether skip-white-spaces is enabled for this XML parser.
getNode : Get the node defined by the $absoluteXPath.
wholeText : Get a the content of a node text part or node attribute.
exportAsHtml : Returns the containing XML as marked up HTML with specified nodes hi-lighted
exportAsXml : Given a context this function returns the containing XML
exportToFile : Generates a XML string with the content of the current document and writes it to a file.
importFromFile : Reads a file or URL and parses the XML data.
importFromString : Reads a string and parses the XML data.
reindexNodeTree : Update nodeIndex and every node of the node-tree.
cloneNode : Clone a node and it's child nodes.
match : Matches (evaluates) an XPath query
evaluate : Alias for the match function
decodeEntities : Decodes the character set entities in the given string.
equalNodes : Compare two nodes to see if they are equal (point to the same node in the doc)
getNodePath : Get the absolute XPath of a node that is in a document tree.
getParentXPath : Retrieves the absolute parent XPath query.
hasChildNodes : Returns TRUE if the given node has child nodes below it

Private Methods

_stringValue : Obtain the string value of an object
_export : Generates a XML string with the content of the current document.
_InternalExport : Export the xml document starting at the named node.
_handleStartElement : Handles opening XML tags while parsing.
_handleEndElement : Handles closing XML tags while parsing.
_handleCharacterData : Handles character data while parsing.
_handleDefaultData : Default handler for the XML parser.
_handlePI : Handles processing instruction (PI)
_createSuperRoot : Creates a super root node.
_internalAppendChild : Adds a new node to the XML document tree during xml parsing.
_generate_ids : Create the ids that are accessable through the generate-id() function
_recursiveReindexNodeTree : Here's where the work is done for reindexing (see reindexNodeTree)
__sleep : PHP cals this function when you call PHP's serialize.
__wakeup : PHP cals this function when you call PHP's unserialize.
_removeLiterals : Parse out the literals of an XPath expression.
_asLiteral : Returns the given string as a literal reference.
_addLiteral : Adds a literal to our array of literals
_GetOperator : Look for operators in the expression
_evaluatePrimaryExpr : Evaluates an XPath PrimaryExpr
_evaluateExpr : Evaluates an XPath Expr
_evaluateOperator : Evaluate the result of an operator whose operands have been evaluated
_evaluatePathExpr : Evaluates an XPath PathExpr
_sortByDocOrder : Sort an xPathSet by doc order.
_evaluateStep : Evaluate a step from a XPathQuery expression at a specific contextPath.
_checkPredicates : Checks whether a node matches predicates.
_evaluateFunction : Evaluates an XPath function
_checkNodeTest : Checks whether a node matches a node-test.
_getAxis : Retrieves axis information from an XPath query step.
_handleAxis_child : Handles the XPath child axis.
_handleAxis_parent : Handles the XPath parent axis.
_handleAxis_attribute : Handles the XPath attribute axis.
_handleAxis_self : Handles the XPath self axis.
_handleAxis_descendant : Handles the XPath descendant axis.
_handleAxis_ancestor : Handles the XPath ancestor axis.
_handleAxis_namespace : Handles the XPath namespace axis.
_handleAxis_following : Handles the XPath following axis.
_handleAxis_preceding : Handles the XPath preceding axis.
_handleAxis_following_sibling : Handles the XPath following-sibling axis.
_handleAxis_preceding_sibling : Handles the XPath preceding-sibling axis.
_handleAxis_descendant_or_self : Handles the XPath descendant-or-self axis.
_handleAxis_ancestor_or_self : Handles the XPath ancestor-or-self axis.
_handleFunction_last : Handles the XPath function last.
_handleFunction_position : Handles the XPath function position.
_handleFunction_count : Handles the XPath function count.
_handleFunction_id : Handles the XPath function id.
_handleFunction_name : Handles the XPath function name.
_handleFunction_string : Handles the XPath function string.
_handleFunction_concat : Handles the XPath function concat.
_handleFunction_starts_with : Handles the XPath function starts-with.
_handleFunction_contains : Handles the XPath function contains.
_handleFunction_substring_before : Handles the XPath function substring-before.
_handleFunction_substring_after : Handles the XPath function substring-after.
_handleFunction_substring : Handles the XPath function substring.
_handleFunction_string_length : Handles the XPath function string-length.
_handleFunction_normalize_space : Handles the XPath function normalize-space.
_handleFunction_translate : Handles the XPath function translate.
_handleFunction_boolean : Handles the XPath function boolean.
_handleFunction_not : Handles the XPath function not.
_handleFunction_true : Handles the XPath function TRUE.
_handleFunction_false : Handles the XPath function FALSE.
_handleFunction_lang : Handles the XPath function lang.
_handleFunction_number : Handles the XPath function number.
_handleFunction_sum : Handles the XPath function sum.
_handleFunction_floor : Handles the XPath function floor.
_handleFunction_ceiling : Handles the XPath function ceiling.
_handleFunction_round : Handles the XPath function round.
_handleFunction_x_lower : Handles the XPath function x-lower.
_handleFunction_x_upper : Handles the XPath function x-upper.
_handleFunction_generate_id : Handles the XPath function generate-id.
_translateAmpersand : Translate all ampersands to it's literal entities '&' and back.

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 < rather than < 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:
array
A vector containing all nodes that were found, during the evaluation of the axis.
Similar Functions:
evaluate()
Line:
Defined on line 3977
Method Details: _handleAxis_attribute

function _handleAxis_attribute($axis, $contextPath)
Handles the XPath attribute 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:
array
A vector containing all nodes that were found, during the evaluation of the axis.
Similar Functions:
evaluate()
Line:
Defined on line 3996
Method Details: _handleAxis_self

function _handleAxis_self($axis, $contextPath)
Handles the XPath self 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:
array
A vector containing all nodes that were found, during the evaluation of the axis.
Similar Functions:
evaluate()
Line:
Defined on line 4021
Method Details: _handleAxis_descendant

function _handleAxis_descendant($axis, $contextPath)
Handles the XPath descendant 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:
array
A vector containing all nodes that were found, during the evaluation of the axis.
Similar Functions:
evaluate()
Line:
Defined on line 4039
Method Details: _handleAxis_ancestor

function _handleAxis_ancestor($axis, $contextPath)
Handles the XPath ancestor 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:
array
A vector containing all nodes that were found, during the evaluation of the axis.
Similar Functions:
evaluate()
Line:
Defined on line 4067
Method Details: _handleAxis_namespace

function _handleAxis_namespace($axis, $contextPath)
Handles the XPath namespace 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:
array
A vector containing all nodes that were found, during the evaluation of the axis.
Similar Functions:
evaluate()
Line:
Defined on line 4092
Method Details: _handleAxis_following

function _handleAxis_following($axis, $contextPath)
Handles the XPath following 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:
array
A vector containing all nodes that were found, during the evaluation of the axis.
Similar Functions:
evaluate()
Line:
Defined on line 4104
Method Details: _handleAxis_preceding

function _handleAxis_preceding($axis, $contextPath)
Handles the XPath preceding 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:
array
A vector containing all nodes that were found, during the evaluation of the axis.
Similar Functions:
evaluate()
Line:
Defined on line 4139
Method Details: _handleAxis_following_sibling

function _handleAxis_following_sibling($axis, $contextPath)
Handles the XPath following-sibling 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:
array
A vector containing all nodes that were found, during the evaluation of the axis.
Similar Functions:
evaluate()
Line:
Defined on line 4169
Method Details: _handleAxis_preceding_sibling

function _handleAxis_preceding_sibling($axis, $contextPath)
Handles the XPath preceding-sibling 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:
array
A vector containing all nodes that were found, during the evaluation of the axis.
Similar Functions:
evaluate()
Line:
Defined on line 4205
Method Details: _handleAxis_descendant_or_self

function _handleAxis_descendant_or_self($axis, $contextPath)
Handles the XPath descendant-or-self 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:
array
A vector containing all nodes that were found, during the evaluation of the axis.
Similar Functions:
evaluate()
Line:
Defined on line 4235
Method Details: _handleAxis_ancestor_or_self

function _handleAxis_ancestor_or_self ( $axis, $contextPath)
Handles the XPath ancestor-or-self axis.
This method handles the XPath ancestor-or-self 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:
array
A vector containing all nodes that were found, during the evaluation of the axis.
Similar Functions:
evaluate()
Line:
Defined on line 4256
Method Details: _handleFunction_last

function _handleFunction_last($arguments, $context)
Handles the XPath function last.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4280
Method Details: _handleFunction_position

function _handleFunction_position($arguments, $context)
Handles the XPath function position.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4292
Method Details: _handleFunction_count

function _handleFunction_count($arguments, $context)
Handles the XPath function count.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4304
Method Details: _handleFunction_id

function _handleFunction_id($arguments, $context)
Handles the XPath function id.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4317
Method Details: _handleFunction_name

function _handleFunction_name($arguments, $context)
Handles the XPath function name.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4342
Method Details: _handleFunction_string

function _handleFunction_string($arguments, $context)
Handles the XPath function string.
http://www.w3.org/TR/xpath#section-String-Functions
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4367
Method Details: _handleFunction_concat

function _handleFunction_concat($arguments, $context)
Handles the XPath function concat.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4424
Method Details: _handleFunction_starts_with

function _handleFunction_starts_with($arguments, $context)
Handles the XPath function starts-with.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4446
Method Details: _handleFunction_contains

function _handleFunction_contains($arguments, $context)
Handles the XPath function contains.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4465
Method Details: _handleFunction_substring_before

function _handleFunction_substring_before($arguments, $context)
Handles the XPath function substring-before.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4493
Method Details: _handleFunction_substring_after

function _handleFunction_substring_after($arguments, $context)
Handles the XPath function substring-after.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4512
Method Details: _handleFunction_substring

function _handleFunction_substring($arguments, $context)
Handles the XPath function substring.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4531
Method Details: _handleFunction_string_length

function _handleFunction_string_length($arguments, $context)
Handles the XPath function string-length.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4556
Method Details: _handleFunction_normalize_space

function _handleFunction_normalize_space($arguments, $context)
Handles the XPath function normalize-space.
The normalize-space function returns the argument string with whitespace normalized by stripping leading and trailing whitespace and replacing sequences of whitespace characters by a single space. If the argument is omitted, it defaults to the context node converted to a string, in other words the string-value of the context node
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
stri
g trimed string
Similar Functions:
evaluate()
Line:
Defined on line 4577
Method Details: _handleFunction_translate

function _handleFunction_translate($arguments, $context)
Handles the XPath function translate.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4595
Method Details: _handleFunction_boolean

function _handleFunction_boolean($arguments, $context)
Handles the XPath function boolean.
http://www.w3.org/TR/xpath#section-Boolean-Functions
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4617
Method Details: _handleFunction_not

function _handleFunction_not($arguments, $context)
Handles the XPath function not.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4665
Method Details: _handleFunction_true

function _handleFunction_true($arguments, $context)
Handles the XPath function TRUE.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4680
Method Details: _handleFunction_false

function _handleFunction_false($arguments, $context)
Handles the XPath function FALSE.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4692
Method Details: _handleFunction_lang

function _handleFunction_lang($arguments, $context)
Handles the XPath function lang.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4704
Method Details: _handleFunction_number

function _handleFunction_number($arguments, $context)
Handles the XPath function number.
http://www.w3.org/TR/xpath#section-Number-Functions
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4728
Method Details: _handleFunction_sum

function _handleFunction_sum($arguments, $context)
Handles the XPath function sum.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4778
Method Details: _handleFunction_floor

function _handleFunction_floor($arguments, $context)
Handles the XPath function floor.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4806
Method Details: _handleFunction_ceiling

function _handleFunction_ceiling($arguments, $context)
Handles the XPath function ceiling.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4822
Method Details: _handleFunction_round

function _handleFunction_round($arguments, $context)
Handles the XPath function round.
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4838
Method Details: _handleFunction_x_lower

function _handleFunction_x_lower($arguments, $context)
Handles the XPath function x-lower.
lower case a string. string x-lower(string)
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4861
Method Details: _handleFunction_x_upper

function _handleFunction_x_upper($arguments, $context)
Handles the XPath function x-upper.
upper case a string. string x-upper(string)
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Similar Functions:
evaluate()
Line:
Defined on line 4879
Method Details: _handleFunction_generate_id

function _handleFunction_generate_id($arguments, $context)
Handles the XPath function generate-id.
Produce a unique id for the first node of the node set. Example usage, produces an index of all the nodes in an .xml document, where the content of each "section" is the exported node as XML. $aFunctions = $xPath->match('//'); foreach ($aFunctions as $Function) { $id = $xPath->match("generate-id($Function)"); echo "<a href='#$id'>$Function</a><br>"; } foreach ($aFunctions as $Function) { $id = $xPath->match("generate-id($Function)"); echo "<h2 id='$id'>$Function</h2>"; echo htmlspecialchars($xPath->exportAsXml($Function)); }
Parameter:

string $arguments
String containing the arguments that were passed to the function.

array $context
The context from which to evaluate the function

Return Value:
mixed
Depending on the type of function being processed
Author:
Ricardo Garcia
Similar Functions:
evaluate()
Line:
Defined on line 4913
Method Details: _translateAmpersand

function _translateAmpersand($xmlSource, $reverse=FALSE)
Translate all ampersands to it's literal entities '&' and back.
I wasn't aware of this problem at first but it's important to understand why we do this. At first you must know: a) PHP's XML parser *translates* all entities to the equivalent char E.g. < is returned as '<' b) PHP's XML parser (in V 4.1.0) has problems with most *literal* entities! The only one's that are recognized are &, < > and ". *ALL* others (like   © a.s.o.) cause an XML_ERROR_UNDEFINED_ENTITY error. I reported this as bug at http://bugs.php.net/bug.php?id=15092 (It turned out not to be a 'real' bug, but one of those nice W3C-spec things). Forget position b) now. It's just for info. Because the way we will solve a) will also solve b) too. THE PROBLEM To understand the problem, here a sample: Given is the following XML: "<AAA> <   > </AAA>" Try to parse it and PHP's XML parser will fail with a XML_ERROR_UNDEFINED_ENTITY becaus of the unknown litteral-entity ' '. (The numeric equivalent ' ' would work though). Next try is to use the numeric equivalent 160 for ' ', thus "<AAA> <   > </AAA>" The data we receive in the tag <AAA> is " < > ". So we get the *translated entities* and NOT the 3 entities <   &gt. Thus, we will not even notice that there were entities at all! In *most* cases we're not able to tell if the data was given as entity or as 'normal' char. E.g. When receiving a quote or a single space were not able to tell if it was given as 'normal' char or as   or ". Thus we loose the entity-information of the XML-data! THE SOLUTION The better solution is to keep the data 'as is' by replacing the '&' before parsing begins. E.g. Taking the original input from above, this would result in "<AAA> &lt; &nbsp; &gt; </AAA>" The data we receive now for the tag <AAA> is " <   > ". and that's what we want. The bad thing is, that a global replace will also replace data in section that are NOT translated by the PHP XML-parser. That is comments (), IP-sections (stuff between <? ? >) and CDATA-block too. So all data comming from those sections must be reversed. This is done during the XML parse phase. So: a) Replacement of all '&' in the XML-source. b) All data that is not char-data or in CDATA-block have to be reversed during the XML-parse phase.
Parameter:

string $xmlSource
The XML string

Return Value:
string
The XML string with translated ampersands.
Line:
Defined on line 5095

Class XPath

The XPath class extends the XPathEngine class.

Public Methods
Private Methods
Public Methods Detail
Private Methods Detail

Public Methods

XPath : Constructor of the class
reset : Resets the object so it's able to take a new xml sting/file
setModMatch : Resolves and xPathQuery array depending on the property['modMatch']
nodeName : Retrieves the name(s) of a node or a group of document nodes.
removeChild : Removes a node from the XML document.
replaceChildByData : Replace a node with any data string. The $data is taken 1:1.
replaceChild : Replace the node(s) that matches the xQuery with the passed node (or passed node-tree)
insertChild : Insert passed node (or passed node-tree) at the node(s) that matches the xQuery.
appendChild : Appends a child to anothers children.
insertBefore : Inserts a node before the reference node with the same parent.
getAttributes : Retrieves a dedecated attribute value or a hash-array of all attributes of a node.
setAttribute : Set attributes of a node(s).
setAttributes : Version of setAttribute() that sets multiple attributes to node(s).
removeAttribute : Removes an attribute of a node(s).
getData : Retrieve all the text from a node as a single string.
getDataParts : Retrieve all the text from a node as a vector of strings
substringData : Retrieves a sub string of a text-part OR attribute-value.
replaceData : Replace a sub string of a text-part OR attribute-value.
insertData : Insert a sub string in a text-part OR attribute-value.
appendData : Append text data to the end of the text for an attribute OR node text-part.
deleteData : Delete the data of a node.

Private Methods

_xml2Document : Parse the XML to a node-tree. A so called 'document'
_getTextSet : Get a reference-list to node text part(s) or node attribute(s).
_resolveXPathQueryForNodeMod : Resolves an xPathQuery vector for a node op for modification
_resolveXPathQuery : Resolves an xPathQuery vector depending on the property['modMatch']
_title : Produces a short title line.

Public Method Detail

Method Details: XPath

function XPath($fileName='', $userXmlOptions=array())
Constructor of the class
Optionally you may call this constructor with the XML-filename to parse and the XML option vector. 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>, ...)

string $fileName
(optional) Filename of XML file to load from. It is recommended that you call importFromFile() instead as you will get an error code. If the import fails, the object will be set to FALSE.

Similar Functions:
parent::XPathEngine()
Line:
Defined on line 5134
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 5153
Method Details: setModMatch

function setModMatch($modMatch = XPATH_QUERYHIT_ALL)
Resolves and xPathQuery array depending on the property['modMatch']
Most of the modification functions of XPath will also accept a xPathQuery (instead of an absolute Xpath). The only problem is that the query could match more the one node. The question is, if the none, the fist or all nodes are to be modified. The behaver can be set with setModMatch()
Parameter:

int $modMatch
One of the following: - XPATH_QUERYHIT_ALL (default) - XPATH_QUERYHIT_FIRST - XPATH_QUERYHIT_UNIQUE // If the query matches more then one node.

Similar Functions:
_resolveXPathQuery()
Line:
Defined on line 5176
Method Details: nodeName

function nodeName($xPathQuery)
Retrieves the name(s) of a node or a group of document nodes.
This method retrieves the names of a group of document nodes specified in the argument. So if the argument was '/A[1]/B[2]' then it would return 'B' if the node did exist in the tree.
Parameter:

mixed $xPathQuery
Array or single full document path(s) of the node(s), from which the names should be retrieved.

Return Value:
mixed
Array or single string of the names of the specified nodes, or just the individual name. If the node did not exist, then returns FALSE.
Line:
Defined on line 5205
Method Details: removeChild

function removeChild($xPathQuery, $autoReindex=TRUE)
Removes a node from the XML document.
This method removes a node from the tree of nodes of the XML document. If the node is a document node, all children of the node and its character data will be removed. If the node is an attribute node, only this attribute will be removed, the node to which the attribute belongs as well as its children will remain unmodified. NOTE: When passing a xpath-query instead of an abs. Xpath. Depending on setModMatch() one, none or multiple nodes are affected.
Parameter:

string $xPathQuery
xpath to the node (See note above).

bool $autoReindex
(optional, default=TRUE) Reindex the document to reflect the changes. A performance helper. See reindexNodeTree()

Return Value:
bool
TRUE on success, FALSE on error;
Similar Functions:
setModMatch(), reindexNodeTree()
Line:
Defined on line 5246
Method Details: replaceChildByData

function replaceChildByData($xPathQuery, $data, $autoReindex=TRUE)
Replace a node with any data string. The $data is taken 1:1.
This function will delete the node you define by $absoluteXPath (plus it's sub-nodes) and substitute it by the string $text. Often used to push in not well formed HTML. WARNING: The $data is taken 1:1. You are in charge that the data you enter is valid XML if you intend to export and import the content again. NOTE: When passing a xpath-query instead of an abs. Xpath. Depending on setModMatch() one, none or multiple nodes are affected.
Parameter:

string $xPathQuery
xpath to the node (See note above).

string $data
String containing the content to be set. *READONLY*

bool $autoReindex
(optional, default=TRUE) Reindex the document to reflect the changes. A performance helper. See reindexNodeTree()

Return Value:
bool
TRUE on success, FALSE on error;
Similar Functions:
setModMatch(), replaceChild(), reindexNodeTree()
Line:
Defined on line 5311
Method Details: replaceChild

function &replaceChild($xPathQuery, $node, $autoReindex=TRUE)
Replace the node(s) that matches the xQuery with the passed node (or passed node-tree)
If the passed node is a string it's assumed to be XML and replaceChildByXml() will be called. NOTE: When passing a xpath-query instead of an abs. Xpath. Depending on setModMatch() one, none or multiple nodes are affected.
Parameter:

string $xPathQuery
Xpath to the node being replaced.

mixed $node
String or Array (Usually a String) If string: Vaild XML. E.g. "<A/>" or "<A> foo <B/> bar <A/>" If array: A Node (can be a whole sub-tree) (See comment in header)

bool $autoReindex
(optional, default=TRUE) Reindex the document to reflect the changes. A performance helper. See reindexNodeTree()

Return Value:
array
The last replaced $node (can be a whole sub-tree)
Similar Functions:
reindexNodeTree()
Line:
Defined on line 5366
Method Details: insertChild

function insertChild($xPathQuery, $node, $shiftRight=TRUE, $afterText=TRUE, $autoReindex=TRUE)
Insert passed node (or passed node-tree) at the node(s) that matches the xQuery.
With parameters you can define if the 'hit'-node is shifted to the right or left and if it's placed before of after the text-part. Per derfault the 'hit'-node is shifted to the right and the node takes the place the of the 'hit'-node. NOTE: When passing a xpath-query instead of an abs. Xpath. Depending on setModMatch() one, none or multiple nodes are affected. E.g. Following is given: AAA[1] / \ ..BBB[1]..BBB[2] .. a) insertChild('/AAA[1]/BBB[2]', <node CCC>) b) insertChild('/AAA[1]/BBB[2]', <node CCC>, $shiftRight=FALSE) c) insertChild('/AAA[1]/BBB[2]', <node CCC>, $shiftRight=FALSE, $afterText=FALSE) a) b) c) AAA[1] AAA[1] AAA[1] / | \ / | \ / | \ ..BBB[1]..CCC[1]BBB[2].. ..BBB[1]..BBB[2]..CCC[1] ..BBB[1]..BBB[2]CCC[1].. #### Do a complete review of the "(optional)" tag after several arguments.
Parameter:

string $xPathQuery
Xpath to the node to append.

mixed $node
String or Array (Usually a String) If string: Vaild XML. E.g. "<A/>" or "<A> foo <B/> bar <A/>" If array: A Node (can be a whole sub-tree) (See comment in header)

bool $shiftRight
(optional, default=TRUE) Shift the target node to the right.

bool $afterText
(optional, default=TRUE) Insert after the text.

bool $autoReindex
(optional, default=TRUE) Reindex the document to reflect the changes. A performance helper. See reindexNodeTree()

Return Value:
mixed
FALSE on error (or no match). On success we return the path(s) to the newly appended nodes. That is: Array of paths if more then 1 node was added or a single path string if only one node was added. NOTE: If autoReindex is FALSE, then we can't return the *complete* path as the exact doc-pos isn't available without reindexing. In that case we leave out the last [docpos] in the path(s). ie we'd return /A[3]/B instead of /A[3]/B[2]
Similar Functions:
appendChildByXml(), reindexNodeTree()
Line:
Defined on line 5451
Method Details: appendChild

function appendChild($xPathQuery, $node, $afterText=FALSE, $autoReindex=TRUE)
Appends a child to anothers children.
If you intend to do a lot of appending, you should leave autoIndex as FALSE and then call reindexNodeTree() when you are finished all the appending.
Parameter:

string $xPathQuery
Xpath to the node to append to.

mixed $node
String or Array (Usually a String) If string: Vaild XML. E.g. "<A/>" or "<A> foo <B/> bar <A/>" If array: A Node (can be a whole sub-tree) (See comment in header)

bool $afterText
(optional, default=FALSE) Insert after the text.

bool $autoReindex
(optional, default=TRUE) Reindex the document to reflect the changes. A performance helper. See reindexNodeTree()

Return Value:
mixed
FALSE on error (or no match). On success we return the path(s) to the newly appended nodes. That is: Array of paths if more then 1 node was added or a single path string if only one node was added. NOTE: If autoReindex is FALSE, then we can't return the *complete* path as the exact doc-pos isn't available without reindexing. In that case we leave out the last [docpos] in the path(s). ie we'd return /A[3]/B instead of /A[3]/B[2]
Similar Functions:
insertChild(), reindexNodeTree()
Line:
Defined on line 5549
Method Details: insertBefore

function insertBefore($xPathQuery, $node, $afterText=TRUE, $autoReindex=TRUE)
Inserts a node before the reference node with the same parent.
If you intend to do a lot of appending, you should leave autoIndex as FALSE and then call reindexNodeTree() when you are finished all the appending.
Parameter:

string $xPathQuery
Xpath to the node to insert new node before

mixed $node
String or Array (Usually a String) If string: Vaild XML. E.g. "<A/>" or "<A> foo <B/> bar <A/>" If array: A Node (can be a whole sub-tree) (See comment in header)

bool $afterText
(optional, default=FLASE) Insert after the text.

bool $autoReindex
(optional, default=TRUE) Reindex the document to reflect the changes. A performance helper. See reindexNodeTree()

Return Value:
mixed
FALSE on error (or no match). On success we return the path(s) to the newly appended nodes. That is: Array of paths if more then 1 node was added or a single path string if only one node was added. NOTE: If autoReindex is FALSE, then we can't return the *complete* path as the exact doc-pos isn't available without reindexing. In that case we leave out the last [docpos] in the path(s). ie we'd return /A[3]/B instead of /A[3]/B[2]
Similar Functions:
reindexNodeTree()
Line:
Defined on line 5629
Method Details: getAttributes

function getAttributes($absoluteXPath, $attrName=NULL)
Retrieves a dedecated attribute value or a hash-array of all attributes of a node.
The first param $absoluteXPath must be a valid xpath OR a xpath-query that results to *one* xpath. If the second param $attrName is not set, a hash-array of all attributes of that node is returned. Optionally you may pass an attrubute name in $attrName and the function will return the string value of that attribute.
Parameter:

string $absoluteXPath
Full xpath OR a xpath-query that results to *one* xpath.

string $attrName
(Optional) The name of the attribute. See above.

Return Value:
mixed
hash-array or a string of attributes depending if the parameter $attrName was set (see above). FALSE if the node or attribute couldn't be found.
Similar Functions:
setAttribute(), removeAttribute()
Line:
Defined on line 5655
Method Details: setAttribute

function setAttribute($xPathQuery, $name, $value, $overwrite=TRUE)
Set attributes of a node(s).
This method sets a number single attributes. An existing attribute is overwritten (default) with the new value, but setting the last param to FALSE will prevent overwritten. NOTE: When passing a xpath-query instead of an abs. Xpath. Depending on setModMatch() one, none or multiple nodes are affected.
Parameter:

string $xPathQuery
xpath to the node (See note above).

string $name
Attribute name.

string $value
Attribute value.

bool $overwrite
If the attribute is already set we overwrite it (see text above)

Return Value:
bool
TRUE on success, FALSE on failure.
Similar Functions:
getAttribute(), removeAttribute()
Line:
Defined on line 5688
Method Details: setAttributes

function setAttributes($xPathQuery, $attributes, $overwrite=TRUE)
Version of setAttribute() that sets multiple attributes to node(s).
This method sets a number of attributes. Existing attributes are overwritten (default) with the new values, but setting the last param to FALSE will prevent overwritten. NOTE: When passing a xpath-query instead of an abs. Xpath. Depending on setModMatch() one, none or multiple nodes are affected.
Parameter:

string $xPathQuery
xpath to the node (See note above).

array $attributes
associative array of attributes to set.

bool $overwrite
If the attributes are already set we overwrite them (see text above)

Return Value:
bool
TRUE on success, FALSE otherwise
Similar Functions:
setAttribute(), getAttribute(), removeAttribute()
Line:
Defined on line 5706
Method Details: removeAttribute

function removeAttribute($xPathQuery, $attrList=NULL)
Removes an attribute of a node(s).
This method removes *ALL* attributres per default unless the second parameter $attrList is set. $attrList can be either a single attr-name as string OR a vector of attr-names as array. E.g. removeAttribute(<xPath>); # will remove *ALL* attributes. removeAttribute(<xPath>, 'A'); # will only remove attributes called 'A'. removeAttribute(<xPath>, array('A_1','A_2')); # will remove attribute 'A_1' and 'A_2'. NOTE: When passing a xpath-query instead of an abs. Xpath. Depending on setModMatch() one, none or multiple nodes are affected.
Parameter:

string $xPathQuery
xpath to the node (See note above).

mixed $attrList
(optional) if not set will delete *all* (see text above)

Return Value:
bool
TRUE on success, FALSE if the node couldn't be found
Similar Functions:
getAttribute(), setAttribute()
Line:
Defined on line 5746
Method Details: getData

function getData($xPathQuery)
Retrieve all the text from a node as a single string.
Sample Given is: <AA> This <BB\>is <BB\> some<BB\>text </AA> Return of getData('/AA[1]') would be: " This is sometext " The first param $xPathQuery must be a valid xpath OR a xpath-query that results to *one* xpath.
Parameter:

string $xPathQuery
xpath to the node - resolves to *one* xpath.

Return Value:
mixed
The returned string (see above), FALSE if the node couldn't be found or is not unique.
Similar Functions:
getDataParts()
Line:
Defined on line 5785
Method Details: getDataParts

function getDataParts($xPathQuery)
Retrieve all the text from a node as a vector of strings
Where each element of the array was interrupted by a non-text child element. Sample Given is: <AA> This <BB\>is <BB\> some<BB\>text </AA> Return of getDataParts('/AA[1]') would be: array([0]=>' This ', [1]=>'is ', [2]=>' some', [3]=>'text '); The first param $absoluteXPath must be a valid xpath OR a xpath-query that results to *one* xpath.
Parameter:

string $xPathQuery
xpath to the node - resolves to *one* xpath.

Return Value:
mixed
The returned array (see above), or FALSE if node is not found or is not unique.
Similar Functions:
getData()
Line:
Defined on line 5807
Method Details: substringData

function substringData($absoluteXPath, $offset = 0, $count = NULL)
Retrieves a sub string of a text-part OR attribute-value.
This method retrieves the sub string of a specific text-part OR (if the $absoluteXPath references an attribute) the the sub string of the attribute value. If no 'direct referencing' is used (Xpath ends with text()[<part-number>]), then the first text-part of the node ist returned (if exsiting).
Parameter:

string $absoluteXPath
Xpath to the node (See note above).

int $offset
(optional, default is 0) Starting offset. (Just like PHP's substr())

number $count
(optional, default is ALL) Character count (Just like PHP's substr())

Return Value:
mixed
The sub string, FALSE if not found or on error
Similar Functions:
XPathEngine::wholeText(), PHP's substr()
Line:
Defined on line 5847
Method Details: replaceData

function replaceData($xPathQuery, $replacement, $offset = 0, $count = 0, $textPartNr=1)
Replace a sub string of a text-part OR attribute-value.
NOTE: When passing a xpath-query instead of an abs. Xpath. Depending on setModMatch() one, none or multiple nodes are affected.
Parameter:

string $xPathQuery
xpath to the node (See note above).

string $replacement
The string to replace with.

int $offset
(optional, default is 0) Starting offset. (Just like PHP's substr_replace ())

number $count
(optional, default is 0=ALL) Character count (Just like PHP's substr_replace())

int $textPartNr
(optional) (see _getTextSet() )

Return Value:
bool
The new string value on success, FALSE if not found or on error
Similar Functions:
substringData()
Line:
Defined on line 5870
Method Details: insertData

function insertData($xPathQuery, $data, $offset=0)
Insert a sub string in a text-part OR attribute-value.
NOTE: When passing a xpath-query instead of an abs. Xpath. Depending on setModMatch() one, none or multiple nodes are affected.
Parameter:

string $xPathQuery
xpath to the node (See note above).

string $data
The string to replace with.

int $offset
(optional, default is 0) Offset at which to insert the data.

Return Value:
bool
The new string on success, FALSE if not found or on error
Similar Functions:
replaceData()
Line:
Defined on line 5895
Method Details: appendData

function appendData($xPathQuery, $data, $textPartNr=1)
Append text data to the end of the text for an attribute OR node text-part.
This method adds content to a node. If it's an attribute node, then the value of the attribute will be set, otherwise the passed data will append to character data of the node text-part. Per default the first text-part is taken. NOTE: When passing a xpath-query instead of an abs. Xpath. Depending on setModMatch() one, none or multiple nodes are affected.
Parameter:

string $xPathQuery
to the node(s) (See note above).

string $data
String containing the content to be added.

int $textPartNr
(optional, default is 1) (see _getTextSet())

Return Value:
bool
TRUE on success, otherwise FALSE
Similar Functions:
_getTextSet()
Line:
Defined on line 5915
Method Details: deleteData

function deleteData($xPathQuery, $offset=0, $count=0, $textPartNr=1)
Delete the data of a node.
This method deletes content of a node. If it's an attribute node, then the value of the attribute will be removed, otherwise the node text-part. will be deleted. Per default the first text-part is deleted. NOTE: When passing a xpath-query instead of an abs. Xpath. Depending on setModMatch() one, none or multiple nodes are affected.
Parameter:

string $xPathQuery
to the node(s) (See note above).

int $offset
(optional, default is 0) Starting offset. (Just like PHP's substr_replace())

number $count
(optional, default is 0=ALL) Character count. (Just like PHP's substr_replace())

int $textPartNr
(optional, default is 0) the text part to delete (see _getTextSet())

Return Value:
bool
TRUE on success, otherwise FALSE
Similar Functions:
_getTextSet()
Line:
Defined on line 5941

Private Method Detail

Method Details: _xml2Document

function &_xml2Document($xmlString)
Parse the XML to a node-tree. A so called 'document'
Parameter:

string $xmlString
The string to turn into a document node.

Return Value:
&array
a node-tree
Line:
Defined on line 5963
Method Details: _getTextSet

function _getTextSet($xPathQuery, $textPartNr=1)
Get a reference-list to node text part(s) or node attribute(s).
If the Xquery references an attribute(s) (Xquery ends with attribute::), then the text value of the node-attribute(s) is/are returned. Otherwise the Xquery is referencing to text part(s) of node(s). This can be either a direct reference to text part(s) (Xquery ends with text()[<nr>]) or indirect reference (a simple Xquery to node(s)). 1) Direct Reference (Xquery 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 Xquery to node(s)): Default is to return the first text part(s). 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 vector is a set of references to the text parts / attributes. This is handy, if you wish to modify the contents. NOTE II: text-part numbers out of range will not be in the list NOTE III:Instead of an absolute xpath you may also pass a xpath-query. Depending on setModMatch() one, none or multiple nodes are affected.
Parameter:

string $xPathQuery
xpath to the node (See note above).

int $textPartNr
String containing the content to be set.

Return Value:
mixed
A vector of *references* to the text that match, or FALSE on error
Similar Functions:
XPathEngine::wholeText()
Line:
Defined on line 6006
Method Details: _resolveXPathQueryForNodeMod

function _resolveXPathQueryForNodeMod($xPathQuery, $functionName)
Resolves an xPathQuery vector for a node op for modification
It is possible to create a brand new object, and try to append and insert nodes into it, so this is a version of _resolveXPathQuery() that will autocreate the super root if it detects that it is not present and the $xPathQuery is empty. Also it demands that there be at least one node returned, and displays a suitable error message if the returned xPathSet does not contain any nodes.
Parameter:

string $xPathQuery
An xpath query targeting a single node. If empty() returns the root node and auto creates the root node if it doesn't exist.

string $function
The function in which this check was called

Return Value:
array
Vector of $absoluteXPath's (May be empty)
Similar Functions:
_resolveXPathQuery()
Line:
Defined on line 6118
Method Details: _resolveXPathQuery

function _resolveXPathQuery($xPathQuery, $function)
Resolves an xPathQuery vector depending on the property['modMatch']
To: - all matches, - the first - none (If the query matches more then one node.) see setModMatch() for details
Parameter:

string $xPathQuery
An xpath query targeting a single node. If empty() returns the root node (if it exists).

string $function
The function in which this check was called

Return Value:
array
Vector of $absoluteXPath's (May be empty)
Similar Functions:
setModMatch()
Line:
Defined on line 6155
Method Details: _title

function _title($title)
Produces a short title line.
Line:
Defined on line 6206

Last updated: 17 April 2008 02:15:13.

Php.XPath Documentation

Contents

Introduction

The complete public interface

Class XPathBase

Public Methods

Private Methods

Public Method Detail

Method Details: XPathBase

Method Details: reset

Method Details: setVerbose

Method Details: getLastError

Private Method Detail

Method Details: _bracketsCheck

Method Details: _searchString

Method Details: _bracketExplode

Method Details: _getEndGroups

Method Details: _prestr

Method Details: _afterstr

Method Details: _setLastError

Method Details: _displayError

Method Details: _displayMessage

Method Details: _beginDebugFunction

Method Details: _closeDebugFunction

Method Details: _profileFunction

Method Details: _printContext

Method Details: _treeDump

Class XPathEngine

Public Methods

Private Methods

Public Method Detail

Method Details: XPathEngine

Method Details: reset

Method Details: getProperties

Method Details: setXmlOption

Method Details: setXmlOptions

Method Details: setCaseFolding

Method Details: setSkipWhiteSpaces

Method Details: getNode

Method Details: wholeText

Method Details: exportAsHtml

Method Details: exportAsXml

Method Details: exportToFile

Method Details: importFromFile

Method Details: importFromString

Method Details: reindexNodeTree

Method Details: cloneNode

Method Details: match

Method Details: evaluate

Method Details: decodeEntities

Method Details: equalNodes

Method Details: getNodePath

Method Details: getParentXPath

Method Details: hasChildNodes

Private Method Detail

Method Details: _stringValue

Method Details: _export

Method Details: _InternalExport

Method Details: _handleStartElement

Method Details: _handleEndElement

Method Details: _handleCharacterData

Method Details: _handleDefaultData

Method Details: _handlePI

Method Details: _createSuperRoot

Method Details: _internalAppendChild

Method Details: _generate_ids

Method Details: _recursiveReindexNodeTree

Method Details: __sleep

Method Details: __wakeup

Method Details: _removeLiterals

Method Details: _asLiteral

Method Details: _addLiteral

Method Details: _GetOperator

Method Details: _evaluatePrimaryExpr

Method Details: _evaluateExpr

Method Details: _evaluateOperator

Method Details: _evaluatePathExpr

Method Details: _sortByDocOrder

Method Details: _evaluateStep

Method Details: _checkPredicates