Docs For Class QueryPath

Description

Located in File: /src/QueryPath/QueryPath.php

The Query Path object is the primary tool in this library.

To create a new Query Path, use the qp() function.

If you are new to these documents, start at the QueryPath.php page. There you will find a quick guide to the tools contained in this project.

A note on serialization: QueryPath uses DOM classes internally, and those do not serialize well at all. In addition, QueryPath may contain many extensions, and there is no guarantee that extensions can serialize. The moral of the story: Don't serialize QueryPath.

see: - QueryPath.php
see: - qp()

Class Variables

Summary:

mixed $document

mixed $last

mixed $matches

$document = NULL (line 318)

Data type : mixed

The base DOMDocument.

access: - protected

$last = array() (line 333)

Data type : mixed

The last array of matches.

access: - protected

$matches = array() (line 329)

Data type : mixed

The array of matches.

access: - protected

Class Constants

Summary:

DEFAULT_PARSER_FLAGS

HTML_STUB

VERSION

XHTML_STUB

DEFAULT_PARSER_FLAGS = NULL (line 310)

Default parser flags.

These are flags that will be used if no global or local flags override them.

since: - 2.0

HTML_STUB = '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Untitled</title>
</head>
<body></body>
</html>' (line 269)

This is a stub HTML 4.01 document.

Using QueryPath::XHTML_STUB is preferred.

This is primarily for generating legacy HTML content. Modern web applications should use QueryPath::XHTML_STUB.

Use this stub with the HTML familiy of methods (html(), writeHTML(), innerHTML()).

VERSION = '2.1-Alpha1' (line 256)

The version string for this version of QueryPath.

Standard releases will be of the following form: <MAJOR>.<MINOR>[.<PATCH>][-STABILITY].

Examples:

2.0
2.1.1
2.0-alpha1

Developer releases will always be of the form dev-<DATE>.

since: - 2.0

XHTML_STUB = '<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Untitled</title>
</head>
<body></body>
</html>' (line 294)

This is a stub XHTML document.

Since XHTML is an XML format, you should use XML functions with this document fragment. For example, you should use xml(), innerXML(), and writeXML().

This can be passed into qp() to begin a new basic HTML document.

Example:

$qp = qp(QueryPath::XHTML_STUB); // Creates a new XHTML document
$qp->writeXML(); // Writes the document as well-formed XHTML.

since: - 2.0

Method Detail

Summary:

QueryPath __construct ([mixed $document = NULL], [string $string = NULL], [array $options = array()])

QueryPath add (string $selector)

QueryPath addClass (string $class)

QueryPath after (mixed $data)

QueryPath andSelf ()

QueryPath append (mixed $data)

QueryPath appendTo (QueryPath $dest, QueryPath $destination)

QueryPath attach (QueryPath $dest)

mixed attr (mixed $name, [string $value = NULL])

QueryPath before (mixed $data)

QueryPath branch ([string $selector = NULL])

QueryPath children ([string $selector = NULL])

QueryPath cloneAll ()

QueryPath closest (string $selector)

QueryPath contents ()

QueryPath css ([mixed $name = NULL], [ $value = ''])

QueryPath deepest ()

array deepestNode ( $ele, [int $depth = 0], [mixed $current = NULL], [ &$deepest = NULL], DOMNode $deepest)

QueryPath detach ([string $selector = NULL])

QueryPath each (callback $callback)

QueryPath eachLambda (string $lambda)

QueryPath emptyElement ()

QueryPath end ()

QueryPath eq ($index $index)

QueryPath even ()

QueryPath filter (string $selector)

QueryPath filterCallback ($callback. $callback)

QueryPath filterLambda ( $fn, string $function)

QueryPath find (string $selector)

QueryPath first ()

QueryPath firstChild ()

mixed get ([int $index = NULL], [boolean $asObject = FALSE])

Iterable getIterator ()

array getOptions ()

void has ( $contained)

boolean hasAttr (string $attrName)

boolean hasClass (string $class)

mixed html ([string $markup = NULL])

mixed index (DOMElement $subject)

string innerHTML ()

string innerXHTML ()

string innerXML ()

QueryPath insertAfter (QueryPath $dest)

QueryPath insertBefore (QueryPath $dest)

boolean is (string $selector)

void isXMLish ( $string)

QueryPath last ()

QueryPath lastChild ()

QueryPath map (callback $callback)

QueryPath next ([string $selector = NULL])

QueryPath nextAll ([string $selector = NULL])

QueryPath nextUntil ([string $selector = NULL])

QueryPath not (string $selector)

QueryPath odd ()

QueryPath parent ([string $selector = NULL])

QueryPath parents ([string $selector = NULL])

QueryPath parentsUntil ([string $selector = NULL])

void peers ([ $selector = NULL])

mixed prepareInsert (mixed $item)

QueryPath prepend ( $data, mixed $prependage)

QueryPath prependTo (QueryPath $dest)

QueryPath prev ([string $selector = NULL])

QueryPath prevAll ([string $selector = NULL])

QueryPath prevUntil ([string $selector = NULL])

QueryPath remove ([string $selector = NULL])

QueryPath removeAttr (string $name)

QueryPath removeChildren ()

QueryPath removeClass (string $class)

QueryPath replaceAll (string $selector, $document)

QueryPath replaceWith (mixed $new)

void setMatches ( $matches, [ $unique = TRUE])

QueryPath siblings ([string $selector = NULL])

int size ()

QueryPath slice (integer $start, [ $end = 0], integer $count)

string tag ()

mixed text ([string $text = NULL])

string textImplode ([ $sep = ', '], [ $filterEmpties = TRUE], string $separator)

QueryPath top ([string $selector = NULL])

mixed val ([string $value = NULL])

QueryPath wrap (mixed $markup)

QueryPath wrapAll (string $markup)

QueryPath wrapInner (string $markup)

QueryPath writeHTML ([string $path = NULL])

QueryPath writeXHTML ([string $path = NULL])

QueryPath writeXML ([string $path = NULL], [int $options = NULL])

mixed xhtml ([string $markup = NULL])

mixed xml ([string $markup = NULL])

QueryPath xpath (string $query)

void __call ( $name, $arguments)

void __clone ()

Constructor __construct (line 351)

QueryPath __construct( [mixed $document = NULL], [string $string = NULL], [array $options = array()])

Constructor.

This should not be called directly. Use the qp() factory function instead.

Parameters

mixed $document: A document-like object.
string $string: A CSS 3 Selector
array $options: An associative array of options.

Info

see - qp()
access - public

Method add (line 1755)

QueryPath add( string $selector)

Add more elements to the current set of matches.

This begins the new query at the top of the DOM again. The results found when running this selector are then merged into the existing results. In this way, you can add additional elements to the existing set.

Parameters

string $selector: A valid selector.

Info

return - The QueryPath object with the newly added elements.
see - QueryPath::end()
see - QueryPath::append()
see - QueryPath::andSelf()
see - QueryPath::after()
access - public

Method addClass (line 2724)

QueryPath addClass( string $class)

Add a class to all elements in the current QueryPath.

This searchers for a class attribute on each item wrapped by the current QueryPath object. If no attribute is found, a new one is added and its value is set to $class. If a class attribute is found, then the value is appended on to the end.

Parameters

string $class: The name of the class.

Info

return - Returns the QueryPath object.
see - QueryPath::hasClass()
see - QueryPath::css()
see - QueryPath::removeClass()
see - QueryPath::attr()
access - public

Method after (line 1355)

QueryPath after( mixed $data)

Insert the given data after each element in the current QueryPath object.

This inserts the element as a peer to the currently matched elements. Contrast this with append(), which inserts the data as children of matched elements.

Parameters

mixed $data: The data to be appended.

Info

return - The QueryPath object (with the items inserted).
see - QueryPath::before()
see - QueryPath::append()
throws - QueryPathException Thrown if $data is an unsupported object type.
access - public

Method andSelf (line 1819)

QueryPath andSelf( )

Combine the current and previous set of matched objects.

Example:

qp(document, 'p')->find('div')->andSelf();

The code above will contain a list of all p elements and all div elements that are beneath p elements.

Info

return - A QueryPath object with the results of the last two "destructive" operations.
see - QueryPath::end()
see - QueryPath::add()
see - end();
access - public

Method append (line 1171)

QueryPath append( mixed $data)

Insert the given markup as the last child.

The markup will be inserted into each match in the set.

The same element cannot be inserted multiple times into a document. DOM documents do not allow a single object to be inserted multiple times into the DOM. To insert the same XML repeatedly, we must first clone the object. This has one practical implication: Once you have inserted an element into the object, you cannot further manipulate the original element and expect the changes to be replciated in the appended object. (They are not the same -- there is no shared reference.) Instead, you will need to retrieve the appended object and operate on that.

Parameters

mixed $data: This can be either a string (the usual case), or a DOM Element.

Info

return - The QueryPath object.
see - QueryPath::appendTo()
see - QueryPath::prepend()
throws - QueryPathException Thrown if $data is an unsupported object type.
access - public

Method appendTo (line 1220)

QueryPath appendTo( QueryPath $dest, QueryPath $destination)

Append the current elements to the destination passed into the function.

This cycles through all of the current matches and appends them to the context given in $destination. If a selector is provided then the $destination is queried (using that selector) prior to the data being appended. The data is then appended to the found items.

Parameters

QueryPath $destination: A QueryPath object that will be appended to.
QueryPath $dest:

Info

return - The original QueryPath, unaltered. Only the destination QueryPath will be modified.
see - QueryPath::append()
see - QueryPath::prependTo()
throws - QueryPathException Thrown if $data is an unsupported object type.
access - public

Method attach (line 2962)

QueryPath attach( QueryPath $dest)

Attach any items from the list if they match the selector.

If no selector is specified, this will remove all current matches from the document.

Parameters

QueryPath $dest: A QueryPath Selector.

Info

return - The Query path wrapping a list of removed items.
author - eabrand
see - QueryPath::replaceAll()
see - QueryPath::removeChildren()
see - QueryPath::replaceWith()
since - 2.1
access - public

Method attr (line 687)

mixed attr( mixed $name, [string $value = NULL])

Get/set an attribute.

If both name and value are set, then this will set the attribute name/value pair for all items in this object.
If name is set, and is an array, then all attributes in the array will be set for all items in this object.
If name is a string and is set, then the attribute value will be returned.

When an attribute value is retrieved, only the attribute value of the FIRST match is returned.

Parameters

mixed $name: The name of the attribute or an associative array of name/value pairs.
string $value: A value (used only when setting an individual property).

Info

return - If this was a setter request, return the QueryPath object. If this was an access request (getter), return the string value.
see - QueryPath::hasClass()
see - QueryPath::removeAttr()
see - QueryPath::hasAttr()
see - QueryPath::tag()
access - public

Method before (line 1292)

QueryPath before( mixed $data)

Insert the given data before each element in the current set of matches.

Parameters

mixed $data: The data to be inserted. This can be XML in a string, a DomFragment, a DOMElement, or the other usual suspects. (See qp()).

Info

return - Returns the QueryPath with the new modifications. The list of elements currently selected will remain the same.
see - QueryPath::prepend()
see - QueryPath::insertBefore()
see - QueryPath::append()
see - QueryPath::after()
throws - QueryPathException Thrown if $data is an unsupported object type.
access - public

Method branch (line 2869)

QueryPath branch( [string $selector = NULL])

Branch the base QueryPath into another one with the same matches.

This function makes a copy of the QueryPath object, but keeps the new copy (initially) pointed at the same matches. This object can then be queried without changing the original QueryPath. However, changes to the elements inside of this QueryPath will show up in the QueryPath from which it is branched.

Compare this operation with cloneAll(). The cloneAll() call takes the current QueryPath object and makes a copy of all of its matches. You continue to operate on the same QueryPath object, but the elements inside of the QueryPath are copies of those before the call to cloneAll().

This, on the other hand, copies the QueryPath, but keeps valid references to the document and the wrapped elements. A new query branch is created, but any changes will be written back to the same document.

In practice, this comes in handy when you want to do multiple queries on a part of the document, but then return to a previous set of matches. (see QPTPL for examples of this in practice).

Example:

<?php
$qp = qp(QueryPath::HTML_STUB);
$branch = $qp->branch();
$branch->find('title')->text('Title');
$qp->find('body')->text('This is the body')->writeHTML;
?>

Notice that in the code, each of the QueryPath objects is doing its own query. However, both are modifying the same document. The result of the above would look something like this:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"></meta>
<title>Title</title>
</head>
<body>This is the body</body>
</html>

Notice that while $qp and $banch were performing separate queries, they both modified the same document.

In jQuery or a browser-based solution, you generally do not need a branching function because there is (implicitly) only one document. In QueryPath, there is no implicit document. Every document must be explicitly specified (and, in most cases, parsed -- which is costly). Branching makes it possible to work on one document with multiple QueryPath objects.

Parameters

string $selector: If a selector is passed in, an additional find() will be executed on the branch before it is returned. (Added in QueryPath 2.0.)

Info

return - A copy of the QueryPath object that points to the same set of elements that the original QueryPath was pointing to.
see - QueryPath::find()
see - QueryPath::cloneAll()
since - 1.1
access - public

Method children (line 1864)

QueryPath children( [string $selector = NULL])

Get the children of the elements in the QueryPath object.

If a selector is provided, the list of children will be filtered through the selector.

Parameters

string $selector: A valid selector.

Info

return - A QueryPath wrapping all of the children.
see - QueryPath::prev()
see - QueryPath::next()
see - QueryPath::parents()
see - QueryPath::removeChildren()
see - QueryPath::parent()
access - public

Method cloneAll (line 2888)

QueryPath cloneAll( )

Perform a deep clone of each node in the QueryPath.

This does not clone the QueryPath object, but instead clones the list of nodes wrapped by the QueryPath. Every element is deeply cloned.

This method is analogous to jQuery's clone() method.

This is a destructive operation, which means that end() will revert the list back to the clone's original.

Info

see - qp()
access - public

Method closest (line 1963)

QueryPath closest( string $selector)

Find the closest element matching the selector.

This finds the closest match in the ancestry chain. It first checks the present element. If the present element does not match, this traverses up the ancestry chain (e.g. checks each parent) looking for an item that matches.

It is provided for jQuery 1.3 compatibility.

Parameters

string $selector: A CSS Selector to match.

Info

return - The set of matches.
since - 2.0
access - public

Method contents (line 1898)

QueryPath contents( )

Get all child nodes (not just elements) of all items in the matched set.

It gets only the immediate children, not all nodes in the subtree.

This does not process iframes. Xinclude processing is dependent on the DOM implementation and configuration.

Info

return - A QueryPath object wrapping all child nodes for all elements in the QueryPath object.
see - QueryPath::xml()
see - QueryPath::innerXML()
see - QueryPath::find()
see - QueryPath::innerHTML()
see - QueryPath::html()
see - QueryPath::text()
access - public

Method css (line 766)

QueryPath css( [mixed $name = NULL], [ $value = ''])

Set/get a CSS value for the current element(s).

This sets the CSS value for each element in the QueryPath object. It does this by setting (or getting) the style attribute (without a namespace).

For example, consider this code:

<?php
qp(HTML_STUB, 'body')->css('background-color','red')->html();
?>

This will return the following HTML:

<body style="background-color: red"/>

If no parameters are passed into this function, then the current style element will be returned unparsed. Example:

<?php
qp(HTML_STUB, 'body')->css('background-color','red')->css();
?>

This will return the following:

background-color: red

Parameters

mixed $name: If this is a string, it will be used as a CSS name. If it is an array, this will assume it is an array of name/value pairs of CSS rules. It will apply all rules to all elements in the set.
$value:

Info

access - public

Method deepest (line 1534)

QueryPath deepest( )

Reduce the set of matches to the deepest child node in the tree.

This loops through the matches and looks for the deepest child node of all of the matches. "Deepest", here, is relative to the nodes in the list. It is calculated as the distance from the starting node to the most distant child node. In other words, it is not necessarily the farthest node from the root element, but the farthest note from the matched element.

In the case where there are multiple nodes at the same depth, all of the nodes at that depth will be included.

Info

return - The QueryPath wrapping the single deepest node.
access - public

Method deepestNode (line 1572)

array deepestNode( $ele, [int $depth = 0], [mixed $current = NULL], [ &$deepest = NULL], DOMNode $deepest)

A depth-checking function. Typically, it only needs to be invoked with the first parameter. The rest are used for recursion.

Parameters

DOMNode $ele: The element.
int $depth: The depth guage
mixed $current: The current set.
DOMNode $deepest: A reference to the current deepest node.
&$deepest:

Info

return - Returns an array of DOM nodes.
see - deepest();
access - protected

Method detach (line 2930)

QueryPath detach( [string $selector = NULL])

Detach any items from the list if they match the selector.

In other words, each item that matches the selector will be remove from the DOM document. The returned QueryPath wraps the list of removed elements.

If no selector is specified, this will remove all current matches from the document.

Parameters

string $selector: A CSS Selector.

Info

return - The Query path wrapping a list of removed items.
author - eabrand
see - QueryPath::replaceAll()
see - QueryPath::removeChildren()
see - QueryPath::replaceWith()
since - 2.1
access - public

Method each (line 1114)

QueryPath each( callback $callback)

Run a callback on each item in the list of items.

Rules of the callback:

A callback that returns FALSE will stop execution of the each() loop. This works like break in a standard loop.
A TRUE return value from the callback is analogous to a continue statement.
All other return values are ignored.

Parameters

callback $callback: The callback to run.

Info

return - The QueryPath.
see - QueryPath::map()
see - QueryPath::filter()
see - QueryPath::eachLambda()
access - public

Method eachLambda (line 1139)

QueryPath eachLambda( string $lambda)

An each() iterator that takes a lambda function.

Parameters

string $lambda: The lambda function. This will be passed ($index, &$item).

Info

return - The QueryPath object.
see - QueryPath::map()
see - QueryPath::each()
see - QueryPath::filterCallback()
see - QueryPath::filterLambda()
access - public

Method emptyElement (line 3006)

QueryPath emptyElement( )

Empty everything within the specified element.

A valid selector.

Info

return - The QueryPath object with the newly emptied elements.
author - eabrand
see - QueryPath::removeChildren()
see - QueryPath::text()
since - 2.1
access - public

Method end (line 1796)

QueryPath end( )

Revert to the previous set of matches.

This will revert back to the last set of matches (before the last "destructive" set of operations). This undoes any change made to the set of matched objects. Functions like {@see find()} and {@see filter()} change the list of matched objects. The end() function will revert back to the last set of matched items.

Note that functions that modify the document, but do not change the list of matched objects, are not "destructive". Thus, calling append('something')->end() will not undo the append() call.

Only one level of changes is stored. Reverting beyond that will result in an empty set of matches. Example:

// The line below returns the same thing as qp(document, 'p');
qp(document, 'p')->find('div')->end();
// This returns an empty array:
qp(document, 'p')->end();
// This returns an empty array:
qp(document, 'p')->find('div')->find('span')->end()->end();

The last one returns an empty array because only one level of changes is stored.

Info

return - A QueryPath object reflecting the list of matches prior to the last destructive operation.
see - QueryPath::andSelf()
see - QueryPath::add()
access - public

Method eq (line 820)

QueryPath eq( $index $index)

Reduce the matched set to just one.

This will take a matched set and reduce it to just one item -- the item at the index specified. This is a destructive operation, and can be undone with end().

Parameters

$index $index: The index of the element to keep. The rest will be discarded.

Info

see - QueryPath::end()
see - QueryPath::is()
see - QueryPath::get()
access - public

Method even (line 3030)

QueryPath even( )

Get the even elements, so counter-intuitively 1, 3, 5, etc.

Info

return - A QueryPath wrapping all of the children.
author - eabrand
see - QueryPath::prev()
see - QueryPath::removeChildren()
see - QueryPath::next()
see - QueryPath::parents()
see - QueryPath::parent()
since - 2.1
access - public

Method filter (line 861)

QueryPath filter( string $selector)

Filter a list down to only elements that match the selector.

Use this, for example, to find all elements with a class, or with certain children.

Parameters

string $selector: The selector to use as a filter.

Info

return - The QueryPath with non-matching items filtered out.
see - QueryPath::is()
see - QueryPath::find()
see - QueryPath::map()
see - QueryPath::filterLambda()
see - QueryPath::filterCallback()
access - public

Method filterCallback (line 927)

QueryPath filterCallback( $callback. $callback)

Filter based on a callback function.

A callback may be any of the following:

a function: 'my_func'.
an object/method combo: $obj, 'myMethod'
a class/method combo: 'MyClass', 'myMethod'

Note that classes are passed in strings. Objects are not.

Each callback is passed to arguments:

$index: The index position of the object in the array.
$item: The item to be operated upon.

Parameters

$callback. $callback: A callback either as a string (function) or an array (object, method OR classname, method).

Info

return - Query path object augmented according to the function.
see - QueryPath::find()
see - QueryPath::is()
see - QueryPath::map()
see - QueryPath::filter()
see - QueryPath::filterLambda()
access - public

Method filterLambda (line 893)

QueryPath filterLambda( $fn, string $function)

Filter based on a lambda function.

The function string will be executed as if it were the body of a function. It is passed two arguments:

$index: The index of the item.
$item: The current Element.

If the function returns boolean FALSE, the item will be removed from the list of elements. Otherwise it will be kept.

Example:

qp('li')->filterLambda('qp($item)->attr("id") == "test"');

The above would filter down the list to only an item whose ID is 'text'.

Parameters

string $function: Inline lambda function in a string.
$fn:

Info

see - QueryPath::filterCallback()
see - QueryPath::filter()
see - mapLambda()
see - QueryPath::map()
access - public

Method find (line 506)

QueryPath find( string $selector)

Given a CSS Selector, find matching items.

Parameters

string $selector: CSS 3 Selector

Info

see - QueryPath::filter()
see - QueryPath::is()
todo - If a find() returns zero matches, then a subsequent find() will also return zero matches, even if that find has a selector like :root. The reason for this is that the QueryPathCssEventHandler does not set the root of the document tree if it cannot find any elements from which to determine what the root is. The workaround is to use top() to select the root element again.
access - public

Method first (line 3080)

QueryPath first( )

Get the first matching element.

Info

return - A QueryPath wrapping all of the children.
author - eabrand
see - QueryPath::next()
see - QueryPath::prev()
since - 2.1
access - public

Method firstChild (line 3104)

QueryPath firstChild( )

Get the first child of the matching element.

Info

return - A QueryPath wrapping all of the children.
author - eabrand
see - QueryPath::next()
see - QueryPath::prev()
since - 2.1
access - public

Method get (line 652)

mixed get( [int $index = NULL], [boolean $asObject = FALSE])

Get one or all elements from this object.

When called with no paramaters, this returns all objects wrapped by the QueryPath. Typically, these are DOMElement objects (unless you have used map(), xpath(), or other methods that can select non-elements).

When called with an index, it will return the item in the QueryPath with that index number.

Calling this method does not change the QueryPath (e.g. it is non-destructive).

You can use qp()->get() to iterate over all elements matched. You can also iterate over qp() itself (QueryPath implementations must be Traversable). In the later case, though, each item will be wrapped in a QueryPath object. To learn more about iterating in QueryPath, see examples/techniques.php.

Parameters

int $index: If specified, then only this index value will be returned. If this index is out of bounds, a NULL will be returned.
boolean $asObject: If this is TRUE, an SplObjectStorage object will be returned instead of an array. This is the preferred method for extensions to use.

Info

return - If an index is passed, one element will be returned. If no index is present, an array of all matches will be returned.
see - QueryPath::eq()
see - SplObjectStorage
access - public

Method getIterator (line 3636)

Iterable getIterator( )

Implementation of:

IteratorAggregate::getIterator

Get an iterator for the matches in this object.

Info

return - Returns an iterator.
access - public

Method getOptions (line 459)

array getOptions( )

Get the effective options for the current QueryPath object.

This returns an associative array of all of the options as set for the current QueryPath object. This includes default options, options directly passed in via qp() or the constructor, an options set in the QueryPathOptions object.

The order of merging options is this:

Options passed in using qp() are highest priority, and will override other options.
Options set with QueryPathOptions will override default options, but can be overridden by options passed into qp().
Default options will be used when no overrides are present.

This function will return the options currently used, with the above option overriding having been calculated already.

Info

return - An associative array of options, calculated from defaults and overridden options.
see - qp()
see - QueryPathOptions::merge()
see - QueryPathOptions::set()
since - 2.0
access - public

Method has (line 2973)

void has( $contained)

Test to see if the current QueryPath object contains $contained.

Parameters

$contained:

Info

author - eabrand
since - 2.1
access - public

Method hasAttr (line 726)

boolean hasAttr( string $attrName)

Check to see if the given attribute is present.

This returns TRUE if <em>all</em> selected items have the attribute, or FALSE if at least one item does not have the attribute.

Parameters

string $attrName: The attribute name.

Info

return - TRUE if all matches have the attribute, FALSE otherwise.
see - QueryPath::hasClass()
see - QueryPath::attr()
since - 2.0
access - public

Method hasClass (line 2796)

boolean hasClass( string $class)

Returns TRUE if any of the elements in the QueryPath have the specified class.

Parameters

string $class: The name of the class.

Info

return - TRUE if the class exists in one or more of the elements, FALSE otherwise.
see - QueryPath::addClass()
see - QueryPath::removeClass()
access - public

Method html (line 2079)

mixed html( [string $markup = NULL])

Set or get the markup for an element.

If $markup is set, then the giving markup will be injected into each item in the set. All other children of that node will be deleted, and this new code will be the only child or children. The markup MUST BE WELL FORMED.

If no markup is given, this will return a string representing the child markup of the first node.

Important: This differs from jQuery's html() function. This function returns the current node and all of its children. jQuery returns only the children. This means you do not need to do things like this:

$qp->parent()->html()

By default, this is HTML 4.01, not XHTML. Use xml() for XHTML.

Parameters

string $markup: The text to insert.

Info

return - A string if no markup was passed, or a QueryPath if markup was passed.
see - QueryPath::contents()
see - QueryPath::text()
see - QueryPath::xml()
access - public

Method index (line 984)

mixed index( DOMElement $subject)

Get an item's index.

Given a DOMElement, get the index from the matches. This is the converse of get().

Parameters

DOMElement $subject: The item to match.

Info

return - The index as an integer (if found), or boolean FALSE. Since 0 is a valid index, you should use strong equality (===) to test..
see - QueryPath::get()
see - QueryPath::is()
access - public

Method innerHTML (line 2144)

string innerHTML( )

Fetch the HTML contents INSIDE of the first QueryPath item.

This behaves the way jQuery's <code>html()</code> function behaves.

This gets all children of the first match in QueryPath.

Consider this fragment:

<div>
test <p>foo</p> test
</div>

We can retrieve just the contents of this code by doing something like this:

qp($xml, 'div')->innerHTML();

This would return the following:

test <p>foo</p> test

Info

return - Returns a string representation of the child nodes of the first matched element.
see - QueryPath::html()
see - QueryPath::innerXHTML()
see - QueryPath::innerXML()
since - 2.0
access - public

Method innerXHTML (line 2161)

string innerXHTML( )

Fetch child (inner) nodes of the first match.

This will return the children of the present match. For an example, see innerHTML().

Info

return - Returns a string of XHTML that represents the children of the present node.
see - QueryPath::innerHTML()
see - QueryPath::innerXML()
since - 2.0
access - public

Method innerXML (line 2198)

string innerXML( )

Fetch child (inner) nodes of the first match.

This will return the children of the present match. For an example, see innerHTML().

Info

return - Returns a string of XHTML that represents the children of the present node.
see - QueryPath::innerHTML()
see - QueryPath::innerXHTML()
since - 2.0
access - public

Method insertAfter (line 1335)

QueryPath insertAfter( QueryPath $dest)

Insert the contents of the current QueryPath after the nodes in the destination QueryPath object.

Parameters

QueryPath $dest: Destination object where the current elements will be deposited.

Info

return - The present QueryPath, unaltered. Only the destination object is altered.
see - QueryPath::after()
see - QueryPath::append()
see - QueryPath::insertBefore()
throws - QueryPathException Thrown if $data is an unsupported object type.
access - public

Method insertBefore (line 1317)

QueryPath insertBefore( QueryPath $dest)

Insert the current elements into the destination document.

The items are inserted before each element in the given QueryPath document. That is, they will be siblings with the current elements.

Parameters

QueryPath $dest: Destination QueryPath document.

Info

return - The current QueryPath object, unaltered. Only the destination QueryPath object is altered.
see - QueryPath::before()
see - QueryPath::appendTo()
see - QueryPath::insertAfter()
throws - QueryPathException Thrown if $data is an unsupported object type.
access - public

Method is (line 837)

boolean is( string $selector)

Given a selector, this checks to see if the current set has one or more matches.

Unlike jQuery's version, this supports full selectors (not just simple ones).

Parameters

string $selector: The selector to search for.

Info

return - TRUE if one or more elements match. FALSE if no match is found.
see - QueryPath::get()
see - QueryPath::eq()
access - public

Method isXMLish (line 3319)

void isXMLish( $string)

Determine whether a given string looks like XML or not.

Basically, this scans a portion of the supplied string, checking to see if it has a tag-like structure. It is possible to "confuse" this, which may subsequently result in parse errors, but in the vast majority of cases, this method serves as a valid inicator of whether or not the content looks like XML.

Things that are intentional excluded:

plain text with no markup.
strings that look like filesystem paths.

Subclasses SHOULD NOT OVERRIDE THIS. Altering it may be altering core assumptions about how things work. Instead, classes should override the constructor and pass in only one of the parsed types that this class expects.

Parameters

$string:

Info

access - protected

Method last (line 3134)

QueryPath last( )

Get the last matching element.

Info

return - A QueryPath wrapping all of the children.
author - eabrand
see - QueryPath::next()
see - QueryPath::prev()
since - 2.1
access - public

Method lastChild (line 3161)

QueryPath lastChild( )

Get the last child of the matching element.

Info

return - A QueryPath wrapping all of the children.
author - eabrand
see - QueryPath::next()
see - QueryPath::prev()
since - 2.1
access - public

Method map (line 1023)

QueryPath map( callback $callback)

Run a function on each item in a set.

The mapping callback can return anything. Whatever it returns will be stored as a match in the set, though. This means that afer a map call, there is no guarantee that the elements in the set will behave correctly with other QueryPath functions.

Callback rules:

If the callback returns NULL, the item will be removed from the array.
If the callback returns an array, the entire array will be stored in the results.
If the callback returns anything else, it will be appended to the array of matches.

Parameters

callback $callback: The function or callback to use. The callback will be passed two params:
- $index: The index position in the list of items wrapped by this object.
- $item: The current item.

Info

return - The QueryPath object wrapping a list of whatever values were returned by each run of the callback.
see - QueryPath::find()
see - QueryPath::filter()
see - QueryPath::get()
access - public

Method next (line 2552)

QueryPath next( [string $selector = NULL])

Get the next sibling of each element in the QueryPath.

If a selector is provided, the next matching sibling will be returned.

Parameters

string $selector: A CSS3 selector.

Info

return - The QueryPath object.
see - QueryPath::parent()
see - QueryPath::parents()
see - QueryPath::nextAll()
see - QueryPath::contents()
see - QueryPath::children()
see - QueryPath::prev()
access - public

Method nextAll (line 2590)

QueryPath nextAll( [string $selector = NULL])

Get all siblings after an element.

For each element in the QueryPath, get all siblings that appear after it. If a selector is passed in, then only siblings that match the selector will be included.

Parameters

string $selector: A valid CSS 3 selector.

Info

return - The QueryPath object, now containing the matching siblings.
see - QueryPath::siblings()
see - QueryPath::next()
see - QueryPath::children()
see - QueryPath::prevAll()
access - public

Method nextUntil (line 3198)

QueryPath nextUntil( [string $selector = NULL])

Get all siblings after an element until the selector is reached.

For each element in the QueryPath, get all siblings that appear after it. If a selector is passed in, then only siblings that match the selector will be included.

Parameters

string $selector: A valid CSS 3 selector.

Info

return - The QueryPath object, now containing the matching siblings.
author - eabrand
see - QueryPath::next()
see - QueryPath::siblings()
see - QueryPath::children()
see - QueryPath::prevAll()
since - 2.1
access - public

Method not (line 950)

QueryPath not( string $selector)

Filter a list to contain only items that do NOT match.

Parameters

string $selector: A selector to use as a negation filter. If the filter is matched, the element will be removed from the list.

Info

return - The QueryPath object with matching items filtered out.
see - QueryPath::find()
access - public

Method odd (line 3057)

QueryPath odd( )

Get the odd elements, so counter-intuitively 0, 2, 4, etc.

Info

return - A QueryPath wrapping all of the children.
author - eabrand
see - QueryPath::prev()
see - QueryPath::removeChildren()
see - QueryPath::next()
see - QueryPath::parents()
see - QueryPath::parent()
since - 2.1
access - public

Method parent (line 1999)

QueryPath parent( [string $selector = NULL])

Get the immediate parent of each element in the QueryPath.

If a selector is passed, this will return the nearest matching parent for each element in the QueryPath.

Parameters

string $selector: A valid CSS3 selector.

Info

return - A QueryPath object wrapping the matching parents.
see - QueryPath::parents()
see - QueryPath::siblings()
see - QueryPath::children()
access - public

Method parents (line 2035)

QueryPath parents( [string $selector = NULL])

Get all ancestors of each element in the QueryPath.

If a selector is present, only matching ancestors will be retrieved.

Parameters

string $selector: A valid CSS 3 Selector.

Info

return - A QueryPath object containing the matching ancestors.
see - QueryPath::children()
see - QueryPath::siblings()
see - QueryPath::parent()
access - public

Method parentsUntil (line 3273)

QueryPath parentsUntil( [string $selector = NULL])

Get all ancestors of each element in the QueryPath until the selector is reached.

If a selector is present, only matching ancestors will be retrieved.

Parameters

string $selector: A valid CSS 3 Selector.

Info

return - A QueryPath object containing the matching ancestors.
author - eabrand
see - QueryPath::parent()
see - QueryPath::children()
see - QueryPath::siblings()
since - 2.1
access - public

Method peers (line 2688)

void peers( [ $selector = NULL])

Parameters

$selector:

Info

deprecated - Use siblings().
access - public

Method prepareInsert (line 1612)

mixed prepareInsert( mixed $item)

Prepare an item for insertion into a DOM.

This handles a variety of boilerplate tasks that need doing before an indeterminate object can be inserted into a DOM tree.

If item is a string, this is converted into a document fragment and returned.
If item is a QueryPath, then the first item is retrieved and this call function is called recursivel.
If the item is a DOMNode, it is imported into the current DOM if necessary.
If the item is a SimpleXMLElement, it is converted into a DOM node and then imported.

Parameters

mixed $item: Item to prepare for insert.

Info

return - Returns the prepared item.
throws - QueryPathException Thrown if the object passed in is not of a supprted object type.
access - protected

Method prepend (line 1239)

QueryPath prepend( $data, mixed $prependage)

Insert the given markup as the first child.

The markup will be inserted into each match in the set.

Parameters

mixed $prependage: This can be either a string (the usual case), or a DOM Element.
$data:

Info

see - QueryPath::prependTo()
see - QueryPath::append()
see - QueryPath::after()
see - QueryPath::before()
throws - QueryPathException Thrown if $data is an unsupported object type.
access - public

Method prependTo (line 1271)

QueryPath prependTo( QueryPath $dest)

Take all nodes in the current object and prepend them to the children nodes of each matched node in the passed-in QueryPath object.

This will iterate through each item in the current QueryPath object and add each item to the beginning of the children of each element in the passed-in QueryPath object.

Parameters

QueryPath $dest: The destination QueryPath object.

Info

return - The original QueryPath, unmodified. NOT the destination QueryPath.
see - QueryPath::appendTo()
see - QueryPath::insertBefore()
see - QueryPath::prepend()
see - QueryPath::insertAfter()
throws - QueryPathException Thrown if $data is an unsupported object type.
access - public

Method prev (line 2627)

QueryPath prev( [string $selector = NULL])

Get the next sibling before each element in the QueryPath.

For each element in the QueryPath, this retrieves the previous sibling (if any). If a selector is supplied, it retrieves the first matching sibling (if any is found).

Parameters

string $selector: A valid CSS 3 selector.

Info

return - A QueryPath object, now containing any previous siblings that have been found.
see - QueryPath::children()
see - QueryPath::prevAll()
see - QueryPath::siblings()
see - QueryPath::next()
access - public

Method prevAll (line 2665)

QueryPath prevAll( [string $selector = NULL])

Get the previous siblings for each element in the QueryPath.

For each element in the QueryPath, get all previous siblings. If a selector is provided, only matching siblings will be retrieved.

Parameters

string $selector: A valid CSS 3 selector.

Info

return - The QueryPath object, now wrapping previous sibling elements.
see - QueryPath::children()
see - QueryPath::contents()
see - QueryPath::siblings()
see - QueryPath::prev()
see - QueryPath::nextAll()
access - public

Method prevUntil (line 3241)

QueryPath prevUntil( [string $selector = NULL])

Get the previous siblings for each element in the QueryPath until the selector is reached.

For each element in the QueryPath, get all previous siblings. If a selector is provided, only matching siblings will be retrieved.

Parameters

string $selector: A valid CSS 3 selector.

Info

return - The QueryPath object, now wrapping previous sibling elements.
author - eabrand
see - QueryPath::children()
see - QueryPath::prev()
see - QueryPath::contents()
see - QueryPath::siblings()
see - QueryPath::nextAll()
since - 2.1
access - public

Method remove (line 1688)

QueryPath remove( [string $selector = NULL])

Remove any items from the list if they match the selector.

In other words, each item that matches the selector will be remove from the DOM document. The returned QueryPath wraps the list of removed elements.

If no selector is specified, this will remove all current matches from the document.

Parameters

string $selector: A CSS Selector.

Info

return - The Query path wrapping a list of removed items.
see - QueryPath::removeChildren()
see - QueryPath::replaceWith()
see - QueryPath::replaceAll()
access - public

Method removeAttr (line 798)

QueryPath removeAttr( string $name)

Remove the named attribute from all elements in the current QueryPath.

This will remove any attribute with the given name. It will do this on each item currently wrapped by QueryPath.

As is the case in jQuery, this operation is not considered destructive.

Parameters

string $name: Name of the parameter to remove.

Info

return - The QueryPath object with the same elements.
see - QueryPath::attr()
access - public

Method removeChildren (line 1840)

QueryPath removeChildren( )

Remove all child nodes.

This is equivalent to jQuery's empty() function. (However, empty() is a PHP built-in, and cannot be used as a method name.)

Info

return - The QueryPath object with the child nodes removed.
see - QueryPath::remove()
see - QueryPath::replaceAll()
see - QueryPath::replaceWith()
access - public

Method removeClass (line 2768)

QueryPath removeClass( string $class)

Remove the named class from any element in the QueryPath that has it.

This may result in the entire class attribute being removed. If there are other items in the class attribute, though, they will not be removed.

Example: Consider this XML:

<element class="first second"/>

Executing this fragment of code will remove only the 'first' class:

qp(document, 'element')->removeClass('first');

The resulting XML will be:

<element class="second"/>

To remove the entire 'class' attribute, you should use {@see removeAttr()}.

Parameters

string $class: The class name to remove.

Info

return - The modified QueryPath object.
see - QueryPath::hasClass()
see - QueryPath::addClass()
see - QueryPath::attr()
access - public

Method replaceAll (line 1726)

QueryPath replaceAll( string $selector, $document)

This replaces everything that matches the selector with the first value in the current list.

This is the reverse of replaceWith.

Unlike jQuery, QueryPath cannot assume a default document. Consequently, you must specify the intended destination document. If it is omitted, the present document is assumed to be tthe document. However, that can result in undefined behavior if the selector and the replacement are not sufficiently distinct.

Parameters

string $selector: The selector.
DOMDocument $document: The destination document.

Info

return - The QueryPath wrapping the modified document.
see - QueryPath::replaceWith()
see - QueryPath::remove()
deprecated - Due to the fact that this is not a particularly friendly method, and that it can be easily replicated using {@see replaceWith()}, it is to be considered deprecated.
access - public

Method replaceWith (line 1382)

QueryPath replaceWith( mixed $new)

Replace the existing element(s) in the list with a new one.

Parameters

mixed $new: A DOMElement or XML in a string. This will replace all elements currently wrapped in the QueryPath object.

Info

return - The QueryPath object wrapping the items that were removed. This remains consistent with the jQuery API.
see - QueryPath::remove()
see - QueryPath::replaceAll()
see - QueryPath::append()
see - QueryPath::after()
see - QueryPath::before()
see - QueryPath::prepend()
access - public

Method setMatches (line 3389)

void setMatches( $matches, [ $unique = TRUE])

EXPERT: Be very, very careful using this.

A utility function for setting the current set of matches. It makes sure the last matches buffer is set (for end() and andSelf()).

Parameters

$matches:
$unique:

Info

since - 2.0
access - public

Method siblings (line 1930)

QueryPath siblings( [string $selector = NULL])

Get a list of siblings for elements currently wrapped by this object.

This will compile a list of every sibling of every element in the current list of elements.

Note that if two siblings are present in the QueryPath object to begin with, then both will be returned in the matched set, since they are siblings of each other. In other words,if the matches contain a and b, and a and b are siblings of each other, than running siblings will return a set that contains both a and b.

Parameters

string $selector: If the optional selector is provided, siblings will be filtered through this expression.

Info

return - The QueryPath containing the matched siblings.
see - QueryPath::parents()
see - QueryPath::contents()
see - QueryPath::parent()
see - QueryPath::children()
access - public

Method size (line 616)

int size( )

Get the number of elements currently wrapped by this object.

Note that there is no length property on this object.

Info

return - Number of items in the object.
access - public

Method slice (line 1071)

QueryPath slice( integer $start, [ $end = 0], integer $count)

Narrow the items in this object down to only a slice of the starting items.

Parameters

integer $start: Where in the list of matches to begin the slice.
integer $count: The number of items to include in the slice. If nothing is specified, the all remaining matches (from $start onward) will be included in the sliced list.
$end:

Info

see - array_slice()
access - public

Method tag (line 1667)

string tag( )

The tag name of the first element in the list.

This returns the tag name of the first element in the list of matches. If the list is empty, an empty string will be used.

Info

return - The tag name of the first element in the list.
see - QueryPath::replaceAll()
see - QueryPath::replaceWith()
access - public

Method text (line 2266)

mixed text( [string $text = NULL])

Get or set the text contents of a node.

Parameters

string $text: If this is not NULL, this value will be set as the text of the node. It will replace any existing content.

Info

return - A QueryPath if $text is set, or the text content if no text is passed in as a pram.
see - QueryPath::contents()
see - QueryPath::xml()
see - QueryPath::html()
access - public

Method textImplode (line 2238)

string textImplode( [ $sep = ', '], [ $filterEmpties = TRUE], string $separator)

Retrieve the text of each match and concatenate them with the given separator.

This has the effect of looping through all children, retrieving their text content, and then concatenating the text with a separator.

Parameters

string $separator: The string used to separate text items. The default is a comma followed by a space.
$sep:
$filterEmpties:

Info

return - The text contents, concatenated together with the given separator between every pair of items.
see - implode()
see - QueryPath::text()
since - 2.0
access - public

Method top (line 483)

QueryPath top( [string $selector = NULL])

Select the root element of the document.

This sets the current match to the document's root element. For practical purposes, this is the same as:

qp($someDoc)->find(':root');

However, since it doesn't invoke a parser, it has less overhead. It also works in cases where the QueryPath has been reduced to zero elements (a case that is not handled by find(':root') because there is no element whose root can be found).

Parameters

string $selector: A selector. If this is supplied, QueryPath will navigate to the document root and then run the query. (Added in QueryPath 2.0 Beta 2)

Info

return - The QueryPath object, wrapping the root element (document element) for the current document.
access - public

Method val (line 2297)

mixed val( [string $value = NULL])

Set or get the value of an element's 'value' attribute.

The 'value' attribute is common in HTML form elements. This is a convenience function for accessing the values. Since this is not common task on the server side, this method may be removed in future releases. (It is currently provided for jQuery compatibility.)

If a value is provided in the params, then the value will be set for all matches. If no params are given, then the value of the first matched element will be returned. This may be NULL.

Parameters

string $value:

Info

return - Returns a QueryPath if a string was passed in, and a string if no string was passed in. In the later case, an error will produce NULL.
see - QueryPath::attr()
deprecated - Just use attr(). There's no reason to use this on the server.
access - public

Method wrap (line 1407)

QueryPath wrap( mixed $markup)

Wrap each element inside of the given markup.

Markup is usually a string, but it can also be a DOMNode, a document fragment, a SimpleXMLElement, or another QueryPath object (in which case the first item in the list will be used.)

Parameters

mixed $markup: Markup that will wrap each element in the current list.

Info

return - The QueryPath object with the wrapping changes made.
see - QueryPath::wrapAll()
see - QueryPath::wrapInner()
access - public

Method wrapAll (line 1455)

QueryPath wrapAll( string $markup)

Wrap all elements inside of the given markup.

So all elements will be grouped together under this single marked up item. This works by first determining the parent element of the first item in the list. It then moves all of the matching elements under the wrapper and inserts the wrapper where that first element was found. (This is in accordance with the way jQuery works.)

Markup is usually XML in a string, but it can also be a DOMNode, a document fragment, a SimpleXMLElement, or another QueryPath object (in which case the first item in the list will be used.)

Parameters

string $markup: Markup that will wrap all elements in the current list.

Info

return - The QueryPath object with the wrapping changes made.
see - QueryPath::wrap()
see - QueryPath::wrapInner()
access - public

Method wrapInner (line 1494)

QueryPath wrapInner( string $markup)

Wrap the child elements of each item in the list with the given markup.

Markup is usually a string, but it can also be a DOMNode, a document fragment, a SimpleXMLElement, or another QueryPath object (in which case the first item in the list will be used.)

Parameters

string $markup: Markup that will wrap children of each element in the current list.

Info

return - The QueryPath object with the wrapping changes made.
see - QueryPath::wrap()
see - QueryPath::wrapAll()
access - public

Method writeHTML (line 2474)

QueryPath writeHTML( [string $path = NULL])

Writes HTML to output.

HTML is formatted as HTML 4.01, without strict XML unary tags. This is for legacy HTML content. Modern XHTML should be written using toXHTML().

Write the document to stdout (usually the client) or to a file.

Parameters

string $path: The path to the file into which the XML should be written. if this is NULL, data will be written to STDOUT, which is usually sent to the remote browser.

Info

return - The QueryPath object, unmodified.
see - QueryPath::html()
see - QueryPath::innerHTML()
throws - Exception In the event that a file cannot be written, an Exception will be thrown.
access - public

Method writeXHTML (line 2516)

QueryPath writeXHTML( [string $path = NULL])

Write an XHTML file to output.

Typically, you should use this instead of writeHTML().

Currently, this functions identically to toXML() except that it always uses closing tags (e.g. always

<script></script>

, never

<script/>

). It will write the file as well-formed XML. No XHTML schema validation is done.

Parameters

string $path: The filename of the file to write to.

Info

return - Returns the QueryPath, unmodified.
see - QueryPath::xhtml()
see - QueryPath::writeXML()
see - QueryPath::innerXHTML()
see - QueryPath::writeHTML()
see - QueryPath::xml()
since - 2.0
throws - Exception In the event that the output file cannot be written, an exception is thrown.
access - public

Method writeXML (line 2438)

QueryPath writeXML( [string $path = NULL], [int $options = NULL])

Send the XML document to the client.

Write the document to a file path, if given, or to stdout (usually the client).

This prints the entire document.

Parameters

string $path: The path to the file into which the XML should be written. if this is NULL, data will be written to STDOUT, which is usually sent to the remote browser.
int $options: (As of QueryPath 2.1) Pass libxml options to the saving mechanism.

Info

return - The QueryPath object, unmodified.
see - QueryPath::xml()
see - QueryPath::writeXHTML()
see - QueryPath::innerXML()
throws - Exception In the event that a file cannot be written, an Exception will be thrown.
access - public

Method xhtml (line 2323)

mixed xhtml( [string $markup = NULL])

Set or get XHTML markup for an element or elements.

This differs from html() in that it processes (and produces) strictly XML 1.0 compliant markup.

Like xml() and html(), this functions as both a setter and a getter.

This is a convenience function for fetching HTML in XML format. It does no processing of the markup (such as schema validation).

Parameters

string $markup: A string containing XML data.

Info

return - If markup is passed in, a QueryPath is returned. If no markup is passed in, XML representing the first matched element is returned.
see - QueryPath::html()
see - QueryPath::innerXHTML()
access - public

Method xml (line 2381)

mixed xml( [string $markup = NULL])

Set or get the XML markup for an element or elements.

Like html(), this functions in both a setter and a getter mode.

In setter mode, the string passed in will be parsed and then appended to the elements wrapped by this QueryPath object.When in setter mode, this parses the XML using the DOMFragment parser. For that reason, an XML declaration is not necessary.

In getter mode, the first element wrapped by this QueryPath object will be converted to an XML string and returned.

Parameters

string $markup: A string containing XML data.

Info

return - If markup is passed in, a QueryPath is returned. If no markup is passed in, XML representing the first matched element is returned.
see - QueryPath::innerXML()
see - content()
see - QueryPath::text()
see - QueryPath::xhtml()
see - QueryPath::html()
access - public

Method xpath (line 595)

QueryPath xpath( string $query)

Execute an XPath query and store the results in the QueryPath.

Most methods in this class support CSS 3 Selectors. Sometimes, though, XPath provides a finer-grained query language. Use this to execute XPath queries.

Beware, though. QueryPath works best on DOM Elements, but an XPath query can return other nodes, strings, and values. These may not work with other QueryPath functions (though you will be able to access the values with get()).

Parameters

string $query: An XPath query.

Info

return - A QueryPath object wrapping the results of the query.
see - QueryPath::find()
access - public

Method __call (line 3601)

void __call( $name, $arguments)

Call extension methods.

This function is used to invoke extension methods. It searches the registered extenstensions for a matching function name. If one is found, it is executed with the arguments in the $arguments array.

Parameters

$name:
$arguments:

Info

throws - QueryPathException An expcetion is thrown if a non-existent method is called.
access - public

Method __clone (line 2903)

void __clone( )

Clone the QueryPath.

This makes a deep clone of the elements inside of the QueryPath.

This clones only the QueryPathImpl, not all of the decorators. The clone operator in PHP should handle the cloning of the decorators.

Class QueryPath

Description

The Query Path object is the primary tool in this library.

Class Variables

$document = NULL (line 318)

Data type : mixed

The base DOMDocument.

$last = array() (line 333)

Data type : mixed

The last array of matches.

$matches = array() (line 329)

Data type : mixed

The array of matches.

Class Constants

DEFAULT_PARSER_FLAGS = NULL (line 310)

Default parser flags.

HTML_STUB = '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <title>Untitled</title> </head> <body></body> </html>' (line 269)

This is a stub HTML 4.01 document.

VERSION = '2.1-Alpha1' (line 256)

The version string for this version of QueryPath.

This is a stub XHTML document.

Method Detail

Constructor __construct (line 351)

QueryPath __construct( [mixed $document = NULL], [string $string = NULL], [array $options = array()])

Constructor.

Parameters

Info

Method add (line 1755)

QueryPath add( string $selector)

Add more elements to the current set of matches.

Parameters

Info

Method addClass (line 2724)

QueryPath addClass( string $class)

Add a class to all elements in the current QueryPath.

Parameters

Info

Method after (line 1355)

QueryPath after( mixed $data)

Insert the given data after each element in the current QueryPath object.

Parameters

Info

Method andSelf (line 1819)

QueryPath andSelf( )

Combine the current and previous set of matched objects.

Info

Method append (line 1171)

QueryPath append( mixed $data)

Insert the given markup as the last child.

Parameters

Info

Method appendTo (line 1220)

QueryPath appendTo( QueryPath $dest, QueryPath $destination)

Append the current elements to the destination passed into the function.

Parameters

Info

Method attach (line 2962)

QueryPath attach( QueryPath $dest)

Attach any items from the list if they match the selector.

Parameters

Info

Method attr (line 687)

mixed attr( mixed $name, [string $value = NULL])

Get/set an attribute.

Parameters

Info

Method before (line 1292)

QueryPath before( mixed $data)

Insert the given data before each element in the current set of matches.

Parameters

Info

Method branch (line 2869)

QueryPath branch( [string $selector = NULL])

Branch the base QueryPath into another one with the same matches.

Parameters

Info

Method children (line 1864)

QueryPath children( [string $selector = NULL])

Get the children of the elements in the QueryPath object.

Parameters

HTML_STUB = '<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Untitled</title>
</head>
<body></body>
</html>' (line 269)