The (currently undocumentednow documented³) DOMXPath::registerPHPFunctions method is available as of PHP 5.3.0 (it was added to the code base back in December 2006) and allows the use of PHP functions (and static methods) within XPath queries to complement the normal set of XPath functions².

Description

void DOMXPath::registerPHPFunctions ([ string|array $restrict] )

Enables the use of PHP functions as XPath functions.

Parameters

restrict

Use this parameter to only allow certain functions to be called from XPath; it can be either a string (a function name) or an array of function names.

Return Values

No value is returned.

Examples

Note: The following examples load a sample XML document called book.xml with the following contents:

Example #1: Call a PHP function in XPath with php:functionString

This example demonstrates the basic use of DOMXPath::registerPHPFunctions by replicating the substring XPath function. The first thing that needs to be done is to register the php namespace with the associated URI http://php.net/xpath. Don’t question it, it just needs to be done!

Next, we call DOMXPath::registerPHPFunctions on our object. If no arguments are used, as in this example, then the range of functions allowed to be called is not restricted—you can call any⁴ function from XPath. I would always advise restricting the functions which can be called, see example 2.

Within our XPath query, we use php:functionString which allows us to name a function and provide some parameters (or indeed, no parameters) to be passed to that function. There are two flavours which can be used here: php:functionString which passes an XML node/attribute as a string and php:function (see example 3) which passes an array of XML node/attribute objects (in DOMElement / DOMAttr / etc. form) to the function . In this example the PHP function substr is called, passing along the book’s title (in string form), an offset of 0 and length of 3. This returns the first 3 characters of the book’s title which is then compared to the string PHP in order to filter our list of books down to those having titles starting with PHP.

The example will output something like:

Example #2: Restricting the functions available to XPath

To restrict the functions made available to XPath, provide either a string containing the name of the single function that you wish to allow or an array of strings containing function names as the restrict parameter (note: static methods can also be used, e.g. “Classname::method“). If functions were added with restrict and a function is called in XPath which is not one of them, an E_WARNING will be raised stating Not allowed to call handler ‘function()’ (where function is the name of the function that cannot be called).

The example will output something like:

Example #3: Passing DOM objects using php:function

Up to now, the examples have both used php:functionString. As mentioned above, instead of passing a string value to the PHP function it is possible to pass along an array of DOM* objects to manipulate them as you please by using php:function.

The example will output something like:

Summary

Just to quickly summarise everything, here is a quick run-down. In PHP, make sure to register the php namespace (with the URI http://php.net/xpath) and then register your PHP functions (whether core, extensions or user-defined) or static methods with DOMXPath::registerPHPFunctions. In XPath, use php:functionString or php:function to call the PHP function.

If you have made use of this feature, or want to know more, then do feel free to comment. Thanks for reading.

Footnotes

1. http://php.net/dom
2. http://schlitt.info/opensource/blog/0704_xpath.html
3. The documentation page, when it gets written, will beis available at http://php.net/domxpath.registerphpfunctions
4. In truth, some functions are not suitable such as those that return non-scalar values (and cannot be cast to one) which XPath will not understand.

Easy enough, XPath contains (pardon the pun, see later) some nifty functions which can act on nodes and their values to be used in conditional checks like I needed. I’ve been using the technique outlined in this post for a very long while (usually with XPath in PHP) and originally stumbled upon the basic idea from How to map CSS selectors to XPath queries (Thanks ever so much!) Today’s use of it prompted this blog post.

For example, to grab any li elements with a class of active (and only that one class) out of the document it would be easy enough to use:

Now, as I said that will only grab the list items which have that specific class like <li class="active">. What if there is more than one class in there, ala <li class="hot active">? We could use the XPath function contains which looks to see if a string contains another string but that would cause problems (e.g. searching for “a” in conjunction with classes like “active”, “nav”, etc. would result in false positives).

To match any list item with a classes which contains the letter “a” can be sought with:

Nearly there, now to work out how to not match false positives. To do this, we can look for “[space]a[space]” with a slightly modified class string (classes at the start/end of the string wouldn’t normally have spaces before/after respectively). Whilst we’re at it, we can normalize the spaces in the class string which converts any number of spaces, tabs, etc. characters into just a single space.

So, to properly get at a class name of “active” for all list items, regardless of its position in the class string, the following XPath query can be used.

Note: there are single spaces in the first and last arguments for concat, and on either side of the word active.

Just as an observation, the comparable CSS selector to do this would be li[class~="active"] (or the more usual li.active) which would be awesome to use if XPath decided to implement a similar syntax.