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:

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