A PHP jQuery Library: QueryPath Overview

Aug 8 2010

jQuery is a JavaScript library for efficiently working with HTML and CSS. Its chainable and compact API has made it a popular choice for web developers seeking to quickly build rich web applications. But did you know there is a PHP jQuery library? QueryPath is a PHP implementation of jQuery's interface. It provides all of the DOM manipulation functions, a full CSS selector engine, and as much of jQuery's other features as is practically implemented server-side. But that's not all. This powerful library delivers many server-side features designed to make working with XML services simple, robust, and reliable. <!--break-->

Side-by-Side jQuery and QueryPath

Here is a typical example of using jQuery to manipulate the browser's document:

$('#content').append('<p>Hello World</p>');

This takes the current document, finds some element with id=content, and appends a paragraph to the end of that element's contents. You can accomplish an identical task with QueryPath on the server side:

<?php
qp($html, '#content')->append('<p>Hello World</p>');
?>

There are two minor differences between the two.

  1. The first is the obvious difference in language syntax. JavaScript's dot notation is replaced by PHP's arrow notation. Additionally, since PHP assigns special significance to the $ sign, we use the function qp() instead of the function $().
  2. The second difference is that QueryPath needs to know what file it is working with. On the browser side, there is typically only one document to work with: The present HTML document. But QueryPath cannot assume that there is some default document. So you will need to explicitly provide it a filename, a string of HTML or XML, or a URL from which to retrieve a document.

In spite of these few differences, there are some important similarities to point out:

  • Both jQuery and QueryPath use CSS3 selectors to find items in HTML and XML documents. In fact, all of the standard extensions that jQuery implements are also implemented by QueryPath. You do not need to learn XPath to use QueryPath (though XPath experts can use QueryPath's XPath support).
  • jQuery's traversal and manipulation features are all implemented in QueryPath. QueryPath does add a few more that are designed for server-specific processing (like the ability to write straight to a file).
  • Like jQuery, QueryPath can chain functions together. $('#foo').children('.bar').find('>.baz').text('more') in jQuery is written as this in QueryPath: qp($file, '#foo')->children('.bar')->find('>.baz')->text('more').
  • Much of jQuery's success is due to the ease with which jQuery can be extended. QueryPath's powerful extension mechanism allows the PHP equivalent, and a few sample extensions are provided to get you started. (One of them provides seemless interaction between database backends and QueryPath).
  • Of course, an API is only as good as its documentation, and jQuery is impeccable in this regard. QueryPath also comes with complete API documentation, available online at http://api.querypath.org.
  • jQuery can operate on fragments of markup. So can QueryPath. In fact, developers can quickly create ad hoc documents:
<?php
$qp = qp('<html><head></head><body></body></html>', '#head')
  ->append('<title>Some Title</title>') // Add a title
  ->top('body') // Go back to the top of the document, and then find the body tag
  ->append('<ul></ul>') // Add an unordered list.
  ->children('ul'); // Set the focus on the newly added UL list. We're working with the UL now.

// Create an array of colors 
$colors = array('red', 'green', 'blue');

// Add these colors as LI elements inside of our UL.
foreach ($colors as $color) {
  $qp->append('<li>' . $color . '</li>');
}

// Write the whole HTML document to the client.
$qp->writeHTML();
?>

The above will print an HTML document looking something like this:

  <html>
    <head>
      <title>Some Title</title>
    </head>
    <body>
      <ul>
        <li>Red</li>
        <li>Green</li>
        <li>Blue</li>
    </body>
  </html>

In fact, there are even shortcuts to make the above faster. But those will be the subject of another article.

Server-Side Specialties

QueryPath runs on the server, not the client. So we've added some special server-centered capabilities extending beyond jQuery:

  • Read data from the file system, from remote sites, or from anything with a PHP stream wrapper. For example, we can get a copy of Google's home page with qp('http://google.com').
  • Write to the client's web browser or a file. Using extensions, you can even write to a database (SQL or NoSQL) or just about any other data storage mechanism.
  • Use PHP's built-in looping mechanisms: foreach (qp($file, 'p') as $paragraph) { ... }.
  • With PHP 5.3, you can use closures and anonymous functions to manipulate elements (See the QueryPath::each() function).
  • Work with XML web services like those provided by Twitter, Flickr, YouTube, and ShoppingDotCom.
  • HTML is icky, and this makes "web scraping" difficult. QueryPath makes this easier by providing a special mode designed to find and fix encoding errors, entities, and other generally whacked-out HTML junk. Use htmlqp() instead of plain old qp(), and QueryPath will parse and fix old HTML 2.x, 3.x, and 4.x documents.

Get Started Fast

Interested in trying QueryPath? Go to http://querypath.org and download the most recent version. All you need to do is drop the QueryPath library into your application or PHP's path, and you can get started by including the main QueryPath library. Here's another quick example. Here we create a new XML document, add some basic content, and then write it to a file.

<?php
require_once 'QueryPath/QueryPath.php';

$qp = qp('<?xml version="1.0"?><root></root>', 'root')->text('Set me as the text.');
// ... 
$qp->writeXML('somefile.xml'); // Write a new file on the file system
?>

Would you like to read a longer introduction? Try the IBM DeveloperWorks article:

Get to Know the QueryPath Library

Update: Added more inline documentation to code samples.