What is the difference between DOMXPath::evaluate and DOMXPath::query?

Question

Trying to decide which is more appropriate for my use case...

After comparing the documentation for these methods, my vague understanding is evaluate returns a typed result but query doesn't. Furthermore, the query example includes looping through many results but the evaluate example assumes a single typed result.

Still not much the wiser! Could anyone explain (in as close as possible to layman's terms) when you would use one or the other - e.g. will the multiple/single results mentioned above always be the case?

Answer 1

DOMXPath::query() supports only expressions that return a node list. DOMXPath::evaluate() supports all valid expressions. The official method is named evaluate(), too: http://www.w3.org/TR/DOM-Level-3-XPath/xpath.html#XPathEvaluator

Select all p elements inside a div: //div//p

Select all href attributes in a elements the current document: //a/@href

You can use the string() function to cast the first element of a node list to a string. This will not work with DOMXpath::query().

Select the title text of a document: string(/html/head/title)

There are other function and operators that will change the result type of an expression. But it is always unambiguous. You will always know what type the result is.

Answer 2

query will return a DOMNodeList regardless of your actual XPath expression. This suggests that you don't know what the result may be. So you can iterate over the list and check the node type of the nodes and do something based on the type.

But query is not limited to this use case. You can still use this when you know what type you will get. It may be more readable in the future what you wanted to achieve and therefore easier to maintain.

evaluate on the other hand gives you exactly the type that you select. As the examples point out:

$xpath->evaluate("1 = 0"); // FALSE
$xpath->evaluate("string(1 = 0)"); // "false"

As it turns out selecting attributes //div/@id or text nodes //div/text() still yields DOMNodeList instead of strings. So the potential use cases are limited. You would have to enclose them in string: string(//div/@id) or text nodes string(//div/text()).

The main advantage of evaluate is that you can get strings out of your DOMDocument with fewer lines of code. Otherwise it will produce the same output as query.

ThW's answer is right that some expressions will not work with query:

$xpath->query("string(//div/@id)") // DOMNodeList of length 0
$xpath->evaluate("string(//div/@id)") // string with the found id