QueryPath is a PHP library for working with XML and HTML. It is a PHP implementation of jQuery's traversal and modification libraries.

Getting Started

To being using QueryPath, you will probably want to take a look at these three pieces of documentation:

qp(): The main QueryPath function (like jQuery's $ function.)
htmlqp(): A specialized version of qp() for dealing with poorly formatted HTML.
QueryPath: The QueryPath class, which has all of the main functions.

One substantial difference from jQuery is that QueryPath does not return a new object for each call (for performance reasons). Instead, the same object is mutated from call to call. A chain, then, typically performs all methods on the same object. When you need multiple objects, QueryPath has a QueryPath::branch() function that will return a cloned QueryPath object.

QueryPath also has numerous functions that jQuery does not. Some (like QueryPath::top() and QueryPath::dataURL()) are extensions we find useful. Most, however, are to either emphasize PHP features (QueryPath::filterPreg()) or adapt to server-side needs (QueryPathEntities::replaceAllEntities()).

A Few Basic Examples

Here is a basic example of QueryPath usage:

 require 'QueryPath/QueryPath.php';
 
 qp('<?xml version="1.0"?><root><foo/></root>', 'foo')->append('<bar>baz</bar>')->writeXML();

The above will create a new document from the XML string, find the foo element, and then append the bar element (complete with its text). Finally, the call to QueryPath::writeXML() will print the entire finished XML document to standard out (usually the web browser).

Here's an example using htmlqp():

 require 'QueryPath/QueryPath.php';
 
 // URL to fetch:
 $url = 'http://technosophos.com';

 print qp($url, 'title')->text();

The above will fetch the HTML from the given URL and then find the title tag. It will extract the text (QueryPath::text()) from the title and print it.

For more examples, check out the #Examples namespace (start with examples/html.php). Also, read about the qp() and htmlqp() functions.

Online Sources

The official QueryPath site http://querypath.org
The latest API docs http://api.querypath.org
IBM DeveloperWorks Intro to QueryPath http://www.ibm.com/developerworks/web/library/os-php-querypath/index.html
QueryPath articles at TechnoSophos.Com http://technosophos.com/qp/articles
The QueryPath GitHub repository http://github.com/technosophos/querypath

If you find a good online resource, please submit it as an issue in GitHub, and we will most likely add it here.

A Larger Example

<?php
/** @file
 * Using QueryPath.
 *
 * This file contains an example of how QueryPath can be used
 * to generate web pages. Part of the design of this example is to exhibit many
 * different QueryPath functions in one long chain. All of the methods shown 
 * here are fully documented in {@link QueryPath}.
 *
 * The method used in this example is a typical example of how QueryPath can 
 * gradually build up content. Other methods include using {@link QPTPL} for 
 * templates, injecting database information with {@link QPDB}, and merging
 * data from one QueryPath to another.
 *
 * @author M Butcher <matt@aleph-null.tv>
 * @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
 */
 
require_once '../src/QueryPath/QueryPath.php';

// Begin with an HTML stub document (XHTML, actually), and navigate to the title.
qp(QueryPath::HTML_STUB, 'title')
  // Add some text to the title
  ->text('Example of QueryPath.')
  // Now look for the <body> element
  ->find(':root body')
  // Inside the body, add a title and paragraph.
  ->append('<h1>This is a test page</h1><p>Test text</p>')
  // Now we select the paragraph we just created inside the body
  ->children('p')
  // Add a 'class="some-class"' attribute to the paragraph
  ->attr('class', 'some-class')
  // And add a style attribute, too, setting the background color.
  ->css('background-color', '#eee')
  // Now go back to the paragraph again
  ->parent()
  // Before the paragraph and the title, add an empty table.
  ->prepend('<table id="my-table"></table>')
  // Now let's go to the table...
  ->find('#my-table')
  // Add a couple of empty rows
  ->append('<tr></tr><tr></tr>')
  // select the rows (both at once)
  ->children()
  // Add a CSS class to both rows
  ->addClass('table-row')
  // Now just get the first row (at position 0)
  ->eq(0)
  // Add a table header in the first row
  ->append('<th>This is the header</th>')
  // Now go to the next row
  ->next()
  // Add some data to this row
  ->append('<td>This is the data</td>')
  // Write it all out as HTML
  ->writeHTML();
?>