Constructor XPathEngine (line 950)

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);

• see: XPathEngine::importFromFile(), XPathEngine::importFromString(), XPathEngine::setXmlOptions()

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

decodeEntities (line 5037)

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.

• return: The string or array returned with entities decoded.

• $encodedData $encodedData: (mixed) The string or array that has entities you would like to remove
• $reverse $reverse: (bool) If TRUE entities will be encoded rather than decoded, ie < to &lt; rather than &lt; to <.

evaluate (line 2432)

Alias for the match function

• see: XPathEngine::match()

• $xPathQuery
• $baseXPath

exportAsXml (line 1245)

Given a context this function returns the containing XML

• return: The Xml fragment/document, suitable for writing out to an .xml file or as part of a larger xml file, or FALSE on error.
• see: XPathEngine::_export()

• $absoluteXPath $absoluteXPath: (string) The address of the node you would like to export. If empty the whole document will be exported.
• $xmlHeader $xmlHeader: (array) 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.

getNode (line 1079)

Get the node defined by the $absoluteXPath.

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

• $absoluteXPath $absoluteXPath: (string) (optional, default is 'super-root') xpath to the node.

getParentXPath (line 5116)

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

• return: returns the absolute XPath of the parent

• $childPath $absoluteXPath: (string) String containing an absolute XPath query

hasChildNodes (line 5131)

Returns TRUE if the given node has child nodes below it

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

• $absoluteXPath $absoluteXPath: (string) full path of the potential parent node

importFromString (line 1724)

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.

• return: TRUE on success, FALSE on failure (check getLastError())

• $xmlString $xmlString: (string) Name of the string to be read and parsed.
• $absoluteParentPath $absoluteParentPath: (string) Node to append data too (see above)

reindexNodeTree (line 2159)

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: TRUE on success, FALSE otherwise.
• see: XPathEngine::_recursiveReindexNodeTree()

setCaseFolding (line 1048)

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.

• see: XML parser functions in PHP doc

• $onOff $onOff: (bool) (default TRUE)

setXmlOption (line 1017)

Set an xml_parser_set_option()

• see: XML parser functions in PHP doc

• $optionID $optionID: (int) The option ID (e.g. XML_OPTION_SKIP_WHITE)
• $value $value: (int) The option value.

wholeText (line 1115)

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.

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

• $absoluteXPath $absoluteXPath: (string) xpath to the node (See above).
• $textPartNr $textPartNr: (int) If referring to a node, specifies which text part to query.

_asLiteral (line 2492)

Returns the given string as a literal reference.

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

• $string $string: (string) The string that we are processing

_checkPredicates (line 3561)

Checks whether a node matches predicates.

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

• return: Vector of absolute XPath's that match the given predicates.
• see: XPathEngine::_evaluateStep()

• $xPathSet $xPathSet: (array) Array of full paths of all nodes to be tested.
• $predicates $predicates: (array) Array of predicates to use.

_evaluateExpr (line 2858)

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) |

• return: 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)
• see: XPathEngine::evaluate()

• $xPathQuery $xPathQuery: (string) XPath query to be evaluated.
• $context $context: (array) 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

_evaluateOperator (line 3109)

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.

• return: 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)

• $left $left: (mixed) The left operand
• $right $operator: (mixed) The right operand
• $operator $right: (string) The operator to use to combine the operands
• $operatorType $operatorType: (string) The type of the operator. Either 'Boolean', 'Integer', 'String', or 'NodeSet'
• $context $context: (array) The context from which to evaluate

_evaluatePrimaryExpr (line 2697)

Evaluates an XPath PrimaryExpr

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

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

• return: An empty string if the query was successfully parsed and evaluated, else a string containing the reason for failing.
• see: XPathEngine::evaluate()

• $xPathQuery $xPathQuery: (string) XPath query to be evaluated.
• $context $context: (array) The context from which to evaluate
• $results &$result: (mixed) 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)

_export (line 1336)

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.

• return: The xml string, or FALSE on error.

• $absoluteXPath $absoluteXPath: (string) (optional, default is root) The node we choose as top-node
• $xmlHeader $xmlHeader: (string) (optional) content before <root/> (see text above)
• $hilightXpath $hilightXpathList: (array) (optional) a vector of xPaths to nodes we wat to hi-light (see text above)

_getAxis (line 3815)

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'

• return: Contains information about the axis found in the step, or FALSE if the string isn't a valid step.
• see: XPathEngine::_evaluateStep()

• $step $step: (string) String containing a step of an XPath query.

_handleAxis_ancestor (line 4149)

Handles the XPath ancestor axis.

• return: A vector containing all nodes that were found, during the evaluation of the axis.
• see: XPathEngine::evaluate()

• $axis $axis: (array) Array containing information about the axis.
• $contextPath $contextPath: (string) xpath to starting node from which the axis should be processed.

_handleAxis_attribute (line 4078)

Handles the XPath attribute axis.

• return: A vector containing all nodes that were found, during the evaluation of the axis.
• see: XPathEngine::evaluate()

• $axis $axis: (array) Array containing information about the axis.
• $contextPath $contextPath: (string) xpath to starting node from which the axis should be processed.

_handleAxis_descendant (line 4121)

Handles the XPath descendant axis.

• return: A vector containing all nodes that were found, during the evaluation of the axis.
• see: XPathEngine::evaluate()

• $axis $axis: (array) Array containing information about the axis.
• $contextPath $contextPath: (string) xpath to starting node from which the axis should be processed.

_handleAxis_following (line 4186)

Handles the XPath following axis.

• return: A vector containing all nodes that were found, during the evaluation of the axis.
• see: XPathEngine::evaluate()

• $axis $axis: (array) Array containing information about the axis.
• $contextPath $contextPath: (string) xpath to starting node from which the axis should be processed.

_handleAxis_namespace (line 4174)

Handles the XPath namespace axis.

• return: A vector containing all nodes that were found, during the evaluation of the axis.
• see: XPathEngine::evaluate()

• $axis $axis: (array) Array containing information about the axis.
• $contextPath $contextPath: (string) xpath to starting node from which the axis should be processed.

_handleAxis_preceding (line 4221)

Handles the XPath preceding axis.

• return: A vector containing all nodes that were found, during the evaluation of the axis.
• see: XPathEngine::evaluate()

• $axis $axis: (array) Array containing information about the axis.
• $contextPath $contextPath: (string) xpath to starting node from which the axis should be processed.

_handleAxis_self (line 4103)

Handles the XPath self axis.

• return: A vector containing all nodes that were found, during the evaluation of the axis.
• see: XPathEngine::evaluate()

• $axis $axis: (array) Array containing information about the axis.
• $contextPath $contextPath: (string) xpath to starting node from which the axis should be processed.

_handleDefaultData (line 1994)

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.

• see: XPathEngine::_handleStartElement(), XPathEngine::_handleEndElement()

• $parser $parser: (int) Handler for accessing the current XML parser.
• $text $text: (string) Character data found in the document.

_handleFunction_boolean (line 4699)

Handles the XPath function boolean.

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

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_concat (line 4506)

Handles the XPath function concat.

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_count (line 4386)

Handles the XPath function count.

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_floor (line 4888)

Handles the XPath function floor.

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_id (line 4399)

Handles the XPath function id.

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_last (line 4362)

Handles the XPath function last.

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_normalize_space (line 4659)

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

• return: trimed string
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_number (line 4810)

Handles the XPath function number.

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

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_round (line 4920)

Handles the XPath function round.

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_string (line 4449)

Handles the XPath function string.

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

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_substring (line 4613)

Handles the XPath function substring.

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_substring_before (line 4575)

Handles the XPath function substring-before.

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_translate (line 4677)

Handles the XPath function translate.

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handleFunction_x_lower (line 4943)

Handles the XPath function x-lower.

lower case a string. string x-lower(string)

• return: Depending on the type of function being processed
• see: XPathEngine::evaluate()

• $arguments $arguments: (string) String containing the arguments that were passed to the function.
• $context $context: (array) The context from which to evaluate the function

_handlePI (line 2022)

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 <? ? >).

• see: PHP's manual "xml_set_processing_instruction_handler"

• $parser $parser: (int) Handler for accessing the current XML parser.
• $target $target: (string) Name of the PI target. E.g. XML, PHP, DTD, ...
• $data $data: (string) Associative array containing a list of

_internalAppendChild (line 2068)

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.

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

• $stackParentIndex $stackParentIndex: (int) The index into the nodeStack[] of the parent node to which the new node should be added as a child. *READONLY*
• $nodeName $nodeName: (string) Name of the new node. *READONLY*

_recursiveReindexNodeTree (line 2200)

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

• return: TRUE on success, FALSE otherwise.
• see: XPathEngine::reindexNodeTree()

• $absoluteParentPath $absoluteParentPath: (string) the xPath to the parent node

_sortByDocOrder (line 3365)

Sort an xPathSet by doc order.

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

• $xPathSet $xPathSet: (array) Array of full paths to nodes that need to be sorted

_translateAmpersand (line 5177)

Translate all ampersands to it's literal entities '&amp;' 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. &lt; 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 &amp;, &lt; &gt; and &quot;. *ALL* others (like &nbsp; &copy; 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> &lt; &nbsp; &gt; </AAA>" Try to parse it and PHP's XML parser will fail with a XML_ERROR_UNDEFINED_ENTITY becaus of the unknown litteral-entity '&nbsp;'. (The numeric equivalent '&#160;' would work though). Next try is to use the numeric equivalent 160 for '&nbsp;', thus "<AAA> &lt; &#160; &gt; </AAA>" The data we receive in the tag <AAA> is " < > ". So we get the *translated entities* and NOT the 3 entities &lt; &#160; &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 &nbsp; or &quot;. 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> &amp;lt; &amp;nbsp; &amp;gt; </AAA>" The data we receive now for the tag <AAA> is " &lt; &nbsp; &gt; ". 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.

• return: The XML string with translated ampersands.

• $xmlSource $xmlSource: (string) The XML string
• $reverse