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

Inheritance diagram for QueryPath:

Public Member Functions
	__construct ($document=NULL, $string=NULL, $options=array())
	Constructor.
	getOptions ()
	Get the effective options for the current QueryPath object.
	top ($selector=NULL)
	Select the root element of the document.
	find ($selector)
	Given a CSS Selector, find matching items.
	xpath ($query, $options=array())
	Execute an XPath query and store the results in the QueryPath.
	size ()
	Get the number of elements currently wrapped by this object.
	count ()
	Get the number of elements currently wrapped by this object.
	get ($index=NULL, $asObject=FALSE)
	Get one or all elements from this object.
	document ()
	Get the DOMDocument that we currently work with.
	xinclude ()
	On an XML document, load all XIncludes.
	toArray ()
	Get all current elements wrapped in an array.
	attr ($name=NULL, $value=NULL)
	Get/set an attribute.
	hasAttr ($attrName)
	Check to see if the given attribute is present.
	css ($name=NULL, $value= '')
	Set/get a CSS value for the current element(s).
	dataURL ($attr, $data=NULL, $mime= 'application/octet-stream', $context=NULL)
	Insert or retrieve a Data URL.
	removeAttr ($name)
	Remove the named attribute from all elements in the current QueryPath.
	eq ($index)
	Reduce the matched set to just one.
	is ($selector)
	Given a selector, this checks to see if the current set has one or more matches.
	filter ($selector)
	Filter a list down to only elements that match the selector.
	filterLambda ($fn)
	Filter based on a lambda function.
	filterPreg ($regex)
	Use regular expressions to filter based on the text content of matched elements.
	filterCallback ($callback)
	Filter based on a callback function.
	not ($selector)
	Filter a list to contain only items that do NOT match.
	index ($subject)
	Get an item's index.
	map ($callback)
	Run a function on each item in a set.
	slice ($start, $length=0)
	Narrow the items in this object down to only a slice of the starting items.
	each ($callback)
	Run a callback on each item in the list of items.
	eachLambda ($lambda)
	An each() iterator that takes a lambda function.
	append ($data)
	Insert the given markup as the last child.
	appendTo (QueryPath $dest)
	Append the current elements to the destination passed into the function.
	prepend ($data)
	Insert the given markup as the first child.
	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.
	before ($data)
	Insert the given data before each element in the current set of matches.
	insertBefore (QueryPath $dest)
	Insert the current elements into the destination document.
	insertAfter (QueryPath $dest)
	Insert the contents of the current QueryPath after the nodes in the destination QueryPath object.
	after ($data)
	Insert the given data after each element in the current QueryPath object.
	replaceWith ($new)
	Replace the existing element(s) in the list with a new one.
	unwrap ()
	Remove the parent element from the selected node or nodes.
	wrap ($markup)
	Wrap each element inside of the given markup.
	wrapAll ($markup)
	Wrap all elements inside of the given markup.
	wrapInner ($markup)
	Wrap the child elements of each item in the list with the given markup.
	deepest ()
	Reduce the set of matches to the deepest child node in the tree.
	tag ()
	The tag name of the first element in the list.
	remove ($selector=NULL)
	Remove any items from the list if they match the selector.
	replaceAll ($selector, DOMDocument $document)
	This replaces everything that matches the selector with the first value in the current list.
	add ($selector)
	Add more elements to the current set of matches.
	end ()
	Revert to the previous set of matches.
	andSelf ()
	Combine the current and previous set of matched objects.
	removeChildren ()
	Remove all child nodes.
	children ($selector=NULL)
	Get the children of the elements in the QueryPath object.
	contents ()
	Get all child nodes (not just elements) of all items in the matched set.
	siblings ($selector=NULL)
	Get a list of siblings for elements currently wrapped by this object.
	closest ($selector)
	Find the closest element matching the selector.
	parent ($selector=NULL)
	Get the immediate parent of each element in the QueryPath.
	parents ($selector=NULL)
	Get all ancestors of each element in the QueryPath.
	html ($markup=NULL)
	Set or get the markup for an element.
	innerHTML ()
	Fetch the HTML contents INSIDE of the first QueryPath item.
	innerXHTML ()
	Fetch child (inner) nodes of the first match.
	innerXML ()
	Fetch child (inner) nodes of the first match.
	textImplode ($sep= ', ', $filterEmpties=TRUE)
	Retrieve the text of each match and concatenate them with the given separator.
	childrenText ($separator= ' ')
	Get the text contents from just child elements.
	text ($text=NULL)
	Get or set the text contents of a node.
	textBefore ($text=NULL)
	Get or set the text before each selected item.
	textAfter ($text=NULL)
	val ($value=NULL)
	Set or get the value of an element's 'value' attribute.
	xhtml ($markup=NULL)
	Set or get XHTML markup for an element or elements.
	xml ($markup=NULL)
	Set or get the XML markup for an element or elements.
	writeXML ($path=NULL, $options=NULL)
	Send the XML document to the client.
	writeHTML ($path=NULL)
	Writes HTML to output.
	writeXHTML ($path=NULL)
	Write an XHTML file to output.
	next ($selector=NULL)
	Get the next sibling of each element in the QueryPath.
	nextAll ($selector=NULL)
	Get all siblings after an element.
	prev ($selector=NULL)
	Get the next sibling before each element in the QueryPath.
	prevAll ($selector=NULL)
	Get the previous siblings for each element in the QueryPath.
	peers ($selector=NULL)
	addClass ($class)
	Add a class to all elements in the current QueryPath.
	removeClass ($class)
	Remove the named class from any element in the QueryPath that has it.
	hasClass ($class)
	Returns TRUE if any of the elements in the QueryPath have the specified class.
	branch ($selector=NULL)
	Branch the base QueryPath into another one with the same matches.
	cloneAll ()
	Perform a deep clone of each node in the QueryPath.
	__clone ()
	Clone the QueryPath.
	detach ($selector=NULL)
	Detach any items from the list if they match the selector.
	attach (QueryPath $dest)
	Attach any items from the list if they match the selector.
	has ($contained)
	Reduce the elements matched by QueryPath to only those which contain the given item.
	emptyElement ()
	Empty everything within the specified element.
	even ()
	Get the even elements, so counter-intuitively 1, 3, 5, etc.
	odd ()
	Get the odd elements, so counter-intuitively 0, 2, 4, etc.
	first ()
	Get the first matching element.
	firstChild ()
	Get the first child of the matching element.
	last ()
	Get the last matching element.
	lastChild ()
	Get the last child of the matching element.
	nextUntil ($selector=NULL)
	Get all siblings after an element until the selector is reached.
	prevUntil ($selector=NULL)
	Get the previous siblings for each element in the QueryPath until the selector is reached.
	parentsUntil ($selector=NULL)
	Get all ancestors of each element in the QueryPath until the selector is reached.
	setMatches ($matches, $unique=TRUE)
	EXPERT: Be very, very careful using this.
	__call ($name, $arguments)
	Call extension methods.
	getIterator ()
	Dynamically generate certain properties.
Static Public Member Functions
static	encodeDataURL ($data, $mime= 'application/octet-stream', $context=NULL)
	A static function for transforming data into a Data URL.
Public Attributes
const	VERSION = '2.1.1'
	The version string for this version of QueryPath.
const	HTML_STUB
	This is a stub HTML 4.01 document.
const	XHTML_STUB
	This is a stub XHTML document.
const	DEFAULT_PARSER_FLAGS = NULL
	Default parser flags.
const	JS_CSS_ESCAPE_CDATA = '\\1'
const	JS_CSS_ESCAPE_CDATA_CCOMMENT = '/* \\1 */'
const	JS_CSS_ESCAPE_CDATA_DOUBLESLASH = '// \\1'
const	JS_CSS_ESCAPE_NONE = ''
	$length = 0
	The number of current matches.
Protected Member Functions
	deepestNode (DOMNode $ele, $depth=0, $current=NULL, &$deepest=NULL)
	A depth-checking function.
	prepareInsert ($item)
	Prepare an item for insertion into a DOM.
	isXMLish ($string)
	Determine whether a given string looks like XML or not.
Protected Attributes
	$document = NULL
	The base DOMDocument.
	$matches = array()
	The array of matches.
	$last = array()
	The last array of matches.

Detailed Description

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 also:: qp(); QueryPath.php

Constructor & Destructor Documentation

__construct	(	$	document = `NULL`,
		$	string = `NULL`,
		$	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.

See also:: qp()

Definition at line 396 of file QueryPath.php.

References get(), DEFAULT_PARSER_FLAGS, $document, document(), setMatches(), isXMLish(), and find().

Member Function Documentation

__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.

Exceptions:

QueryPathException An exception is thrown if a non-existent method is called.

Definition at line 4164 of file QueryPath.php.

References QueryPathExtensionRegistry\$useRegistry, QueryPathExtensionRegistry\getExtensions(), QueryPathExtensionRegistry\hasMethod(), and QueryPathExtensionRegistry\getMethodClass().

__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.

Definition at line 3439 of file QueryPath.php.

References cloneAll().

add ( $ 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.

Returns:: QueryPath The QueryPath object with the newly added elements.

See also:: append(); after(); andSelf(); end()

Definition at line 2181 of file QueryPath.php.

References last(), qp(), document(), and $selector.

addClass ( $ 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.

Returns:: QueryPath Returns the QueryPath object.

See also:: css(); attr(); removeClass(); hasClass()

Definition at line 3257 of file QueryPath.php.

after ( $ 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.

Returns:: QueryPath The QueryPath object (with the items inserted).

See also:: before(); append()

Exceptions:

QueryPathException Thrown if $data is an unsupported object type.

Definition at line 1707 of file QueryPath.php.

References $data, and prepareInsert().

Referenced by insertAfter(), and textAfter().

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.

See also:: end();

Returns:: QueryPath A QueryPath object with the results of the last two "destructive" operations.

See also:: add(); end()

Definition at line 2248 of file QueryPath.php.

References $last, and last().

append ( $ 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.

Returns:: QueryPath The QueryPath object.

See also:: appendTo(); prepend()

Exceptions:

QueryPathException Thrown if $data is an unsupported object type.

Definition at line 1520 of file QueryPath.php.

References $data, prepareInsert(), document(), and setMatches().

Referenced by appendTo(), html(), xml(), and attach().

appendTo ( QueryPath $ dest )

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 $dest A QueryPath object that will be appended to.

Returns:: QueryPath The original QueryPath, unaltered. Only the destination QueryPath will be modified.

See also:: append(); prependTo()

Exceptions:

QueryPathException Thrown if $data is an unsupported object type.

Definition at line 1569 of file QueryPath.php.

References append().

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.

Returns:: QueryPath The Query path wrapping a list of removed items.

See also:: replaceAll(); replaceWith(); removeChildren()

Since:: 2.1

Author:: eabrand

Definition at line 3498 of file QueryPath.php.

References last(), and append().

attr	(	$	name = `NULL`,
		$	value = `NULL`
	)

Get/set an attribute.

If no parameters are specified, this returns an associative array of all name/value pairs.
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).

Returns:: mixed If this was a setter request, return the QueryPath object. If this was an access request (getter), return the string value.

See also:: removeAttr(); tag(); hasAttr(); hasClass()

Definition at line 842 of file QueryPath.php.

Referenced by css(), dataURL(), and val().

before ( $ data )

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

This will take the give data (XML or HTML) and put it before each of the items that the QueryPath object currently contains. Contrast this with after().

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()).

Returns:: QueryPath Returns the QueryPath with the new modifications. The list of elements currently selected will remain the same.

See also:: insertBefore(); after(); append(); prepend()

Exceptions:

QueryPathException Thrown if $data is an unsupported object type.

Definition at line 1644 of file QueryPath.php.

References $data, and prepareInsert().

Referenced by insertBefore(), and textBefore().

branch ( $ 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.)

Returns:: QueryPath A copy of the QueryPath object that points to the same set of elements that the original QueryPath was pointing to.

Since:: 1.1

See also:: cloneAll(); find()

Definition at line 3405 of file QueryPath.php.

References qp(), and $selector.

Referenced by childrenText(), and has().

children ( $ 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.

Returns:: QueryPath A QueryPath wrapping all of the children.

See also:: removeChildren(); parent(); parents(); next(); prev()

Definition at line 2293 of file QueryPath.php.

References $c, $selector, setMatches(), and filter().

childrenText ( $ separator = ' ' )

Get the text contents from just child elements.

This is a specialized variant of textImplode() that implodes text for just the child elements of the current element.

Parameters:

string $separator The separator that will be inserted between found text content.

Returns:: string The concatenated values of all children.

Definition at line 2702 of file QueryPath.php.

References branch().

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.

See also:: qp()

Returns:: QueryPath

Definition at line 3424 of file QueryPath.php.

References setMatches().

Referenced by __clone().

closest ( $ 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.

Returns:: QueryPath The set of matches.

Since:: 2.0

Definition at line 2393 of file QueryPath.php.

References qp(), is(), $selector, and setMatches().

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.

Returns:: QueryPath A QueryPath object wrapping all child nodes for all elements in the QueryPath object.

See also:: find(); text(); html(); innerHTML(); xml(); innerXML()

Definition at line 2327 of file QueryPath.php.

References $c, and setMatches().

count ( )

Get the number of elements currently wrapped by this object.

Since QueryPath is Countable, the PHP count() function can also be used on a QueryPath.

 <?php
  count(qp($xml, 'div'));
 ?>

Returns:: int The number of matches in the QueryPath.

Definition at line 735 of file QueryPath.php.

Referenced by is(), and removeClass().

css	(	$	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

As of QueryPath 2.1, existing style attributes will be merged with new attributes. (In previous versions of QueryPath, a call to css() overwrite the existing style values).

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.
string	$value	The value to set. This is only set if $name is a string.

Returns:: QueryPath

Definition at line 943 of file QueryPath.php.

References attr().

dataURL	(	$	attr,
		$	data = `NULL`,
		$	mime = `'application/octet-stream'`,
		$	context = `NULL`
	)

Insert or retrieve a Data URL.

When called with just $attr, it will fetch the result, attempt to decode it, and return an array with the MIME type and the application data.

When called with both $attr and $data, it will inject the data into all selected elements So

 $qp->dataURL('src', file_get_contents('my.png'), 'image/png')

will inject the given PNG image into the selected elements.

The current implementation only knows how to encode and decode Base 64 data.

Note that this is known *not* to work on IE 6, but should render fine in other browsers.

Parameters:

string	$attr	The name of the attribute.
mixed	$data	The contents to inject as the data. The value can be any one of the following: A URL: If this is given, then the subsystem will read the content from that URL. THIS MUST BE A FULL URL, not a relative path. A string of data: If this is given, then the subsystem will encode the string. A stream or file handle: If this is given, the stream's contents will be encoded and inserted as data. (Note that we make the assumption here that you would never want to set data to be a URL. If this is an incorrect assumption, file a bug.)
string	$mime	The MIME type of the document.
resource	$context	A valid context. Use this only if you need to pass a stream context. This is only necessary if $data is a URL. (See stream_context_create()).

Returns:: If this is called as a setter, this will return a QueryPath object. Otherwise, it will attempt to fetch data out of the attribute and return that.

See also:: http://en.wikipedia.org/wiki/Data:_URL; attr()

Since:: 2.1

Definition at line 1023 of file QueryPath.php.

References $data, attr(), $matches, and encodeDataURL().

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.

Returns:: QueryPath The QueryPath wrapping the single deepest node.

Definition at line 1953 of file QueryPath.php.

References deepestNode(), and setMatches().

deepestNode	(	DOMNode $	ele,
		$	depth = `0`,
		$	current = `NULL`,
		&$	deepest = `NULL`
	)		`[protected]`

A depth-checking function.

Typically, it only needs to be invoked with the first parameter. The rest are used for recursion.

See also:: deepest();

Parameters:

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

Returns:: array Returns an array of DOM nodes.

Definition at line 1991 of file QueryPath.php.

Referenced by wrap(), wrapAll(), wrapInner(), and deepest().

detach ( $ 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.

Returns:: QueryPath The Query path wrapping a list of removed items.

See also:: replaceAll(); replaceWith(); removeChildren()

Since:: 2.1

Author:: eabrand

Definition at line 3466 of file QueryPath.php.

References $selector, find(), last(), and setMatches().

document ( )

Get the DOMDocument that we currently work with.

This returns the current DOMDocument. Any changes made to this document will be accessible to QueryPath, as both will share access to the same object.

Returns:: DOMDocument

Definition at line 792 of file QueryPath.php.

Referenced by __construct(), top(), find(), xpath(), xinclude(), append(), prepareInsert(), replaceAll(), add(), html(), innerXHTML(), innerXML(), text(), textBefore(), textAfter(), xhtml(), xml(), writeXML(), and writeHTML().

each ( $ callback )

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

Rules of the callback:

A callback is passed two variables: $index and $item. (There is no special treatment of $this, as there is in jQuery.)
- You will want to pass $item by reference if it is not an object (DOMNodes are all objects).
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.

Returns:: QueryPath The QueryPath.

See also:: eachLambda(); filter(); map()

Definition at line 1463 of file QueryPath.php.

References $i.

eachLambda ( $ lambda )

An each() iterator that takes a lambda function.

Parameters:

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

Returns:: QueryPath The QueryPath object.

See also:: each(); filterLambda(); filterCallback(); map()

Definition at line 1488 of file QueryPath.php.

emptyElement ( )

Empty everything within the specified element.

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

Returns:: QueryPath The QueryPath object with the newly emptied elements.

See also:: removeChildren()

Since:: 2.1

Author:: eabrand

Deprecated:: The removeChildren() function is the preferred method.

Definition at line 3567 of file QueryPath.php.

References removeChildren().

static encodeDataURL	(	$	data,
		$	mime = `'application/octet-stream'`,
		$	context = `NULL`
	)		`[static]`

A static function for transforming data into a Data URL.

This can be used to create Data URLs for injection into CSS, JavaScript, or other non-XML/HTML content. If you are working with QP objects, you may want to use dataURL() instead.

Parameters:

mixed	$data	The contents to inject as the data. The value can be any one of the following: A URL: If this is given, then the subsystem will read the content from that URL. THIS MUST BE A FULL URL, not a relative path. A string of data: If this is given, then the subsystem will encode the string. A stream or file handle: If this is given, the stream's contents will be encoded and inserted as data. (Note that we make the assumption here that you would never want to set data to be a URL. If this is an incorrect assumption, file a bug.)
string	$mime	The MIME type of the document.
resource	$context	A valid context. Use this only if you need to pass a stream context. This is only necessary if $data is a URL. (See stream_context_create()).

Returns:: An encoded data URL.

Definition at line 505 of file QueryPath.php.

References $data.

Referenced by dataURL(), and QueryPathTest\testEncodeDataURL().

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 find() and 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.

Returns:: QueryPath A QueryPath object reflecting the list of matches prior to the last destructive operation.

See also:: andSelf(); add()

Definition at line 2223 of file QueryPath.php.

References last().

eq ( $ 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 The index of the element to keep. The rest will be discarded.

Returns:: QueryPath

See also:: get(); is(); end()

Definition at line 1091 of file QueryPath.php.

References setMatches().

even ( )

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

Returns:: QueryPath A QueryPath wrapping all of the children.

See also:: removeChildren(); parent(); parents(); next(); prev()

Since:: 2.1

Author:: eabrand

Definition at line 3587 of file QueryPath.php.

References setMatches().

filter ( $ 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.

Returns:: QueryPath The QueryPath with non-matching items filtered out.

See also:: filterLambda(); filterCallback(); map(); find(); is()

Definition at line 1158 of file QueryPath.php.

References qp(), is(), $selector, and setMatches().

Referenced by children(), and siblings().

filterCallback ( $ 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.

If the callback function returns FALSE, the item will be removed from the set of matches. Otherwise the item will be considered a match and left alone.

Parameters:

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

Returns:: QueryPath Query path object augmented according to the function.

See also:: filter(); filterLambda(); map(); is(); find()

Definition at line 1275 of file QueryPath.php.

References $i, and setMatches().

filterLambda ( $ fn )

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 $fn Inline lambda function in a string.

Returns:: QueryPath

See also:: filter(); map(); mapLambda(); filterCallback()

Definition at line 1190 of file QueryPath.php.

References $i, and setMatches().

filterPreg ( $ regex )

Use regular expressions to filter based on the text content of matched elements.

Only items that match the given regular expression will be kept. All others will be removed.

The regular expression is run against the text content (the PCDATA) of the elements. This is a way of filtering elements based on their content.

Example:

  <?xml version="1.0"?>
  <div>Hello <i>World</i></div>

  <?php
    // This will be 1.
    qp($xml, 'div')->filterPreg('/World/')->size();
  ?>

The return value above will be 1 because the text content of ($xml, 'div') is World.

Compare this to the behavior of the :contains() CSS3 pseudo-class.

Parameters:

string $regex A regular expression.

Returns:: QueryPath

See also:: filter(); filterCallback(); preg_match()

Definition at line 1235 of file QueryPath.php.

References setMatches().

find ( $ selector )

Given a CSS Selector, find matching items.

Parameters:

string $selector CSS 3 Selector

Returns:: QueryPath

See also:: filter(); 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.

Definition at line 591 of file QueryPath.php.

References $selector, document(), setMatches(), and $i.

Referenced by __construct(), top(), and detach().

first ( )

Get the first matching element.

Returns:: QueryPath A QueryPath wrapping all of the children.

See also:: next(); prev()

Since:: 2.1

Author:: eabrand

Definition at line 3637 of file QueryPath.php.

References setMatches().

firstChild ( )

Get the first child of the matching element.

Returns:: QueryPath A QueryPath wrapping all of the children.

See also:: next(); prev()

Since:: 2.1

Author:: eabrand

Definition at line 3661 of file QueryPath.php.

References $c, and setMatches().

get	(	$	index = `NULL`,
		$	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.

Returns:: mixed If an index is passed, one element will be returned. If no index is present, an array of all matches will be returned.

See also:: eq(); SplObjectStorage

Definition at line 771 of file QueryPath.php.

References size(), and $matches.

Referenced by __construct().

getIterator ( )

Dynamically generate certain properties.

This is used primarily to increase jQuery compatibility by providing property-like behaviors.

Currently defined properties:

length: Alias of size(). Get an iterator for the matches in this object.
Returns:
Iterable Returns an iterator.

Definition at line 4219 of file QueryPath.php.

References $i.

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.

Returns:: array An associative array of options, calculated from defaults and overridden options.

See also:: qp(); QueryPathOptions::set(); QueryPathOptions::merge()

Since:: 2.0

Definition at line 544 of file QueryPath.php.

has ( $ contained )

Reduce the elements matched by QueryPath to only those which contain the given item.

There are two ways in which this is different from jQuery's implementation:

We allow ANY DOMNode, not just DOMElements. That means this will work on processor instructions, text nodes, comments, etc.
Unlike jQuery, this implementation of has() follows QueryPath standard behavior and modifies the existing object. It does not create a brand new object.

Parameters:

mixed

$contained

If $contained is a CSS selector (e.g. '#foo'), this will test to see if the current QueryPath has any elements that contain items that match the selector.
If $contained is a DOMNode, then this will test to see if THE EXACT DOMNode exists in the currently matched elements. (Note that you cannot match across DOM trees, even if it is the same document.)

Since:: 2.1

Author:: eabrand

Todo:: It would be trivially easy to add support for iterating over an array or Iterable of DOMNodes.

Definition at line 3522 of file QueryPath.php.

References branch(), and setMatches().

hasAttr ( $ attrName )

Check to see if the given attribute is present.

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

Parameters:

string $attrName The attribute name.

Returns:: boolean TRUE if all matches have the attribute, FALSE otherwise.

Since:: 2.0

See also:: attr(); hasClass()

Definition at line 896 of file QueryPath.php.

hasClass ( $ class )

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

Parameters:

string $class The name of the class.

Returns:: boolean TRUE if the class exists in one or more of the elements, FALSE otherwise.

See also:: addClass(); removeClass()

Definition at line 3329 of file QueryPath.php.

html ( $ 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.

Returns:: mixed A string if no markup was passed, or a QueryPath if markup was passed.

See also:: xml(); text(); contents()

Definition at line 2509 of file QueryPath.php.

References QueryPathEntities\replaceAllEntities(), $doc, document(), removeChildren(), append(), $length, and size().

index ( $ 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.

Returns:: mixed The index as an integer (if found), or boolean FALSE. Since 0 is a valid index, you should use strong equality (===) to test..

See also:: get(); is()

Definition at line 1332 of file QueryPath.php.

References $i.

innerHTML ( )

Fetch the HTML contents INSIDE of the first QueryPath item.

This behaves the way jQuery's () 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:

foo test

Returns:: string Returns a string representation of the child nodes of the first matched element.

See also:: html(); innerXML(); innerXHTML()

Since:: 2.0

Definition at line 2579 of file QueryPath.php.

References innerXML().

innerXHTML ( )

Fetch child (inner) nodes of the first match.

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

See also:: innerHTML(); innerXML()

Returns:: string Returns a string of XHTML that represents the children of the present node.

Since:: 2.0

Definition at line 2596 of file QueryPath.php.

References $length, size(), and document().

innerXML ( )

Fetch child (inner) nodes of the first match.

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

See also:: innerHTML(); innerXHTML()

Returns:: string Returns a string of XHTML that represents the children of the present node.

Since:: 2.0

Definition at line 2633 of file QueryPath.php.

References $length, size(), and document().

Referenced by innerHTML().

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.

Returns:: QueryPath The present QueryPath, unaltered. Only the destination object is altered.

See also:: after(); insertBefore(); append()

Exceptions:

QueryPathException Thrown if $data is an unsupported object type.

Definition at line 1687 of file QueryPath.php.

References after().

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.

Returns:: QueryPath The current QueryPath object, unaltered. Only the destination QueryPath object is altered.

See also:: before(); insertAfter(); appendTo()

Exceptions:

QueryPathException Thrown if $data is an unsupported object type.

Definition at line 1669 of file QueryPath.php.

References before().

is ( $ 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. As of QueryPath 2.1.1, this also supports passing a DOMNode object.

Returns:: boolean TRUE if one or more elements match. FALSE if no match is found.

See also:: get(); eq()

Definition at line 1109 of file QueryPath.php.

References $selector, and count().

Referenced by filter(), not(), closest(), parent(), parents(), next(), nextAll(), prev(), prevAll(), peers(), nextUntil(), prevUntil(), and parentsUntil().

isXMLish ( $ string ) [protected]

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.

Definition at line 3873 of file QueryPath.php.

Referenced by __construct(), and XMLishMock\exposedIsXMLish().

last ( )

Get the last matching element.

Returns:: QueryPath A QueryPath wrapping all of the children.

See also:: next(); prev()

Since:: 2.1

Author:: eabrand

Definition at line 3691 of file QueryPath.php.

References setMatches().

Referenced by add(), end(), andSelf(), detach(), attach(), and setMatches().

lastChild ( )

Get the last child of the matching element.

Returns:: QueryPath A QueryPath wrapping all of the children.

See also:: next(); prev()

Since:: 2.1

Author:: eabrand

Definition at line 3718 of file QueryPath.php.

References $c, and setMatches().

map ( $ 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.

Returns:: QueryPath The QueryPath object wrapping a list of whatever values were returned by each run of the callback.

See also:: QueryPath::get(); filter(); find()

Definition at line 1371 of file QueryPath.php.

References $i, $c, and setMatches().

next ( $ 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.

Returns:: QueryPath The QueryPath object.

See also:: nextAll(); prev(); children(); contents(); parent(); parents()

Definition at line 3085 of file QueryPath.php.

References $selector, qp(), is(), and setMatches().

nextAll ( $ 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.

Returns:: QueryPath The QueryPath object, now containing the matching siblings.

See also:: next(); prevAll(); children(); siblings()

Definition at line 3123 of file QueryPath.php.

References $selector, qp(), is(), and setMatches().

nextUntil ( $ 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.

Returns:: QueryPath The QueryPath object, now containing the matching siblings.

See also:: next(); prevAll(); children(); siblings()

Since:: 2.1

Author:: eabrand

Definition at line 3755 of file QueryPath.php.

References $selector, qp(), is(), and setMatches().

not ( $ 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.

Returns:: QueryPath The QueryPath object with matching items filtered out.

See also:: find()

Definition at line 1298 of file QueryPath.php.

References $selector, qp(), is(), and setMatches().

odd ( )

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

Returns:: QueryPath A QueryPath wrapping all of the children.

See also:: removeChildren(); parent(); parents(); next(); prev()

Since:: 2.1

Author:: eabrand

Definition at line 3614 of file QueryPath.php.

References setMatches().

parent ( $ 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.

Returns:: QueryPath A QueryPath object wrapping the matching parents.

See also:: children(); siblings(); parents()

Definition at line 2429 of file QueryPath.php.

References $selector, qp(), is(), and setMatches().

parents ( $ selector = NULL )

Get all ancestors of each element in the QueryPath.

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

See also:: parent()

Parameters:

string $selector A valid CSS 3 Selector.

Returns:: QueryPath A QueryPath object containing the matching ancestors.

See also:: siblings(); children()

Definition at line 2465 of file QueryPath.php.

References $selector, qp(), is(), and setMatches().

parentsUntil ( $ 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.

See also:: parent()

Parameters:

string $selector A valid CSS 3 Selector.

Returns:: QueryPath A QueryPath object containing the matching ancestors.

See also:: siblings(); children()

Since:: 2.1

Author:: eabrand

Definition at line 3830 of file QueryPath.php.

References $selector, qp(), is(), and setMatches().

peers ( $ selector = NULL )

Deprecated:: Use siblings().

Definition at line 3221 of file QueryPath.php.

References $selector, qp(), is(), and setMatches().

prepareInsert ( $ item ) [protected]

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.

Returns:: mixed Returns the prepared item.

Exceptions:

QueryPathException Thrown if the object passed in is not of a supprted object type.

Definition at line 2031 of file QueryPath.php.

References QueryPathEntities\replaceAllEntities(), and document().

Referenced by append(), prepend(), before(), after(), replaceWith(), wrap(), wrapAll(), and wrapInner().

prepend ( $ data )

Insert the given markup as the first child.

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

Parameters:

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

Returns:: QueryPath

See also:: append(); before(); after(); prependTo()

Exceptions:

QueryPathException Thrown if $data is an unsupported object type.

Definition at line 1588 of file QueryPath.php.

References $data, and prepareInsert().

Referenced by prependTo().

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.

See also:: insertBefore(); insertAfter(); prepend(); appendTo()

Parameters:

QueryPath $dest The destination QueryPath object.

Returns:: QueryPath The original QueryPath, unmodified. NOT the destination QueryPath.

Exceptions:

QueryPathException Thrown if $data is an unsupported object type.

Definition at line 1620 of file QueryPath.php.

References prepend().

prev ( $ 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.

Returns:: QueryPath A QueryPath object, now containing any previous siblings that have been found.

See also:: prevAll(); next(); siblings(); children()

Definition at line 3160 of file QueryPath.php.

References $selector, qp(), is(), and setMatches().

prevAll ( $ 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.

Returns:: QueryPath The QueryPath object, now wrapping previous sibling elements.

See also:: prev(); nextAll(); siblings(); contents(); children()

Definition at line 3198 of file QueryPath.php.

References $selector, qp(), is(), and setMatches().

prevUntil ( $ 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.

Returns:: QueryPath The QueryPath object, now wrapping previous sibling elements.

See also:: prev(); nextAll(); siblings(); contents(); children()

Since:: 2.1

Author:: eabrand

Definition at line 3798 of file QueryPath.php.

References $selector, qp(), is(), and setMatches().

remove ( $ 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.

Returns:: QueryPath The Query path wrapping a list of removed items.

See also:: replaceAll(); replaceWith(); removeChildren()

Definition at line 2107 of file QueryPath.php.

References $selector, and $matches.

removeAttr ( $ 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.

Returns:: QueryPath The QueryPath object with the same elements.

See also:: attr()

Definition at line 1069 of file QueryPath.php.

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.)

Returns:: QueryPath The QueryPath object with the child nodes removed.

See also:: replaceWith(); replaceAll(); remove()

Definition at line 2269 of file QueryPath.php.

Referenced by html(), text(), xml(), and emptyElement().

removeClass ( $ 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 also:: removeAttr()}.

Parameters:

string $class The class name to remove.

Returns:: QueryPath The modified QueryPath object.

See also:: attr(); addClass(); hasClass()

Definition at line 3301 of file QueryPath.php.

References count().

replaceAll	(	$	selector,
		DOMDocument $	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.

Returns:: QueryPath The QueryPath wrapping the modified document.

Deprecated:: Due to the fact that this is not a particularly friendly method, and that it can be easily replicated using {

See also:: replaceWith()}, it is to be considered deprecated.; remove(); replaceWith()

Definition at line 2152 of file QueryPath.php.

References size(), document(), $c, $selector, and qp().

replaceWith ( $ 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.

Returns:: QueryPath The QueryPath object wrapping the items that were removed. This remains consistent with the jQuery API.

See also:: append(); prepend(); before(); after(); remove(); replaceAll()

Definition at line 1734 of file QueryPath.php.

References $data, prepareInsert(), and setMatches().

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()).

Since:: 2.0

Definition at line 3949 of file QueryPath.php.

References last(), and $matches.

Referenced by __construct(), top(), find(), xpath(), eq(), filter(), filterLambda(), filterPreg(), filterCallback(), not(), map(), slice(), append(), replaceWith(), deepest(), children(), contents(), siblings(), closest(), parent(), parents(), next(), nextAll(), prev(), prevAll(), peers(), cloneAll(), detach(), has(), even(), odd(), first(), firstChild(), last(), lastChild(), nextUntil(), prevUntil(), and parentsUntil().

siblings ( $ 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.

Returns:: QueryPath The QueryPath containing the matched siblings.

See also:: contents(); children(); parent(); parents()

Definition at line 2360 of file QueryPath.php.

References $selector, setMatches(), and filter().

size ( )

Get the number of elements currently wrapped by this object.

Note that there is no length property on this object.

Returns:: int Number of items in the object.

Deprecated:: QueryPath now implements Countable, so use count().

Definition at line 716 of file QueryPath.php.

Referenced by get(), slice(), tag(), replaceAll(), html(), innerXHTML(), innerXML(), xhtml(), and xml().

slice	(	$	start,
		$	length = `0`
	)

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	$length	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.

Returns:: QueryPath

See also:: array_slice()

Definition at line 1419 of file QueryPath.php.

References $length, size(), setMatches(), and $i.

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.

See also:: replaceAll(); replaceWith()

Returns:: string The tag name of the first element in the list.

Definition at line 2086 of file QueryPath.php.

References size().

text ( $ 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.

Returns:: mixed A QueryPath if $text is set, or the text content if no text is passed in as a pram.

See also:: html(); xml(); contents()

Definition at line 2718 of file QueryPath.php.

References removeChildren(), and document().

textAfter ( $ text = NULL )

Definition at line 2772 of file QueryPath.php.

References document(), and after().

textBefore ( $ text = NULL )

Get or set the text before each selected item.

If $text is passed in, the text is inserted before each currently selected item.

If no text is given, this will return the concatenated text after each selected element.

 <?php
 $xml = '<?xml version="1.0"?><root>Foo<a>Bar</a><b/></root>';
 
 // This will return 'Foo'
 qp($xml, 'a')->textBefore();

 // This will insert 'Baz' right before <b/>.
 qp($xml, 'b')->textBefore('Baz');
 ?>

Parameters:

string $text If this is set, it will be inserted before each node in the current set of selected items.

Returns:: mixed Returns the QueryPath object if $text was set, and returns a string (possibly empty) if no param is passed.

Definition at line 2756 of file QueryPath.php.

References document(), before(), and $p.

textImplode	(	$	sep = `'`,
		'	,
		$	filterEmpties = `TRUE`
	)

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	$sep	The string used to separate text items. The default is a comma followed by a space.
boolean	$filterEmpties	If this is true, empty items will be ignored.

Returns:: string The text contents, concatenated together with the given separator between every pair of items.

See also:: implode(); text()

Since:: 2.0

Definition at line 2675 of file QueryPath.php.

toArray ( )

Get all current elements wrapped in an array.

Compatibility function for jQuery 1.4, but identical to calling get() with no parameters.

Returns:: array An array of DOMNodes (typically DOMElements).

Definition at line 814 of file QueryPath.php.

top ( $ 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)

Returns:: QueryPath The QueryPath object, wrapping the root element (document element) for the current document.

Definition at line 568 of file QueryPath.php.

References setMatches(), document(), $selector, and find().

unwrap ( )

Remove the parent element from the selected node or nodes.

This takes the given list of nodes and "unwraps" them, moving them out of their parent node, and then deleting the parent node.

For example, consider this:

   <root><wrapper><content/></wrapper></root>

Now we can run this code:

   qp($xml, 'content')->unwrap();

This will result in:

   <root><content/></root>

This is the opposite of wrap().

The root element cannot be unwrapped. It has no parents. If you attempt to use unwrap on a root element, this will throw a QueryPathException. (You can, however, "Unwrap" a child that is a direct descendant of the root element. This will remove the root element, and replace the child as the root element. Be careful, though. You cannot set more than one child as a root element.)

Returns:: QueryPath The QueryPath object, with the same element(s) selected.

Exceptions:

QueryPathException An exception is thrown if one attempts to unwrap a root element.

See also:: wrap()

Since:: 2.1

Author:: mbutcher

Definition at line 1783 of file QueryPath.php.

val ( $ 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.

Deprecated:: Just use attr(). There's no reason to use this on the server.

See also:: attr()

Parameters:

string $value

Returns:: mixed 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.

Definition at line 2807 of file QueryPath.php.

References attr().

wrap ( $ 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.

Returns:: QueryPath The QueryPath object with the wrapping changes made.

See also:: wrapAll(); wrapInner()

Definition at line 1826 of file QueryPath.php.

References $data, prepareInsert(), and deepestNode().

wrapAll ( $ 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.

Returns:: QueryPath The QueryPath object with the wrapping changes made.

See also:: wrap(); wrapInner()

Definition at line 1874 of file QueryPath.php.

References $data, prepareInsert(), and deepestNode().

wrapInner ( $ 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.

Returns:: QueryPath The QueryPath object with the wrapping changes made.

See also:: wrap(); wrapAll()

Definition at line 1913 of file QueryPath.php.

References $data, prepareInsert(), and deepestNode().

writeHTML ( $ 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.

Returns:: QueryPath The QueryPath object, unmodified.

See also:: html(); innerHTML()

Exceptions:

Exception In the event that a file cannot be written, an Exception will be thrown.

Definition at line 3007 of file QueryPath.php.

References $path, print, and document().

writeXHTML ( $ 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.

See also:: writeXML(); xml(); writeHTML(); innerXHTML(); xhtml()

Parameters:

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

Returns:: QueryPath Returns the QueryPath, unmodified.

Exceptions:

Exception In the event that the output file cannot be written, an exception is thrown.

Since:: 2.0

Definition at line 3049 of file QueryPath.php.

References writeXML(), and $path.

writeXML	(	$	path = `NULL`,
		$	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.

Returns:: QueryPath The QueryPath object, unmodified.

See also:: xml(); innerXML(); writeXHTML()

Exceptions:

Exception In the event that a file cannot be written, an Exception will be thrown.

Definition at line 2971 of file QueryPath.php.

References $path, print, and document().

Referenced by writeXHTML().

xhtml ( $ 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.

Returns:: mixed If markup is passed in, a QueryPath is returned. If no markup is passed in, XML representing the first matched element is returned.

See also:: html(); innerXHTML()

Definition at line 2833 of file QueryPath.php.

References xml(), $length, size(), and document().

xinclude ( )

On an XML document, load all XIncludes.

Returns:: QueryPath

Definition at line 801 of file QueryPath.php.

References document().

xml ( $ 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.

Returns:: mixed If markup is passed in, a QueryPath is returned. If no markup is passed in, XML representing the first matched element is returned.

See also:: xhtml(); html(); text(); content(); innerXML()

Definition at line 2914 of file QueryPath.php.

References QueryPathEntities\replaceAllEntities(), $doc, document(), removeChildren(), append(), $length, and size().

Referenced by xhtml().

xpath	(	$	query,
		$	options = `array()`
	)

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.
array	$options	Currently supported options are: 'namespace_prefix': And XML namespace prefix to be used as the default. Used in conjunction with 'namespace_uri' 'namespace_uri': The URI to be used as the default namespace URI. Used with 'namespace_prefix'

Returns:: QueryPath A QueryPath object wrapping the results of the query.

See also:: find()

Author:: M Butcher; Xavier Prud'homme

Definition at line 688 of file QueryPath.php.

References document(), $i, and setMatches().

Member Data Documentation

$document = NULL [protected]

The base DOMDocument.

Definition at line 356 of file QueryPath.php.

Referenced by __construct().

$last = array() [protected]

The last array of matches.

Definition at line 372 of file QueryPath.php.

Referenced by andSelf().

$length = 0

The number of current matches.

See also:: count()

Definition at line 380 of file QueryPath.php.

Referenced by slice(), html(), innerXHTML(), innerXML(), xhtml(), and xml().

$matches = array() [protected]

The array of matches.

Definition at line 368 of file QueryPath.php.

Referenced by get(), dataURL(), remove(), and setMatches().

const DEFAULT_PARSER_FLAGS = NULL

Default parser flags.

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

Since:: 2.0

Definition at line 343 of file QueryPath.php.

Referenced by __construct().

const HTML_STUB

Initial value:

 '<!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>'

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()).

Definition at line 302 of file QueryPath.php.

Referenced by QPDBTest\testQueryInto(), QPDBTest\testQueryChains(), QPListTests\testAppendList(), QPListTests\testAppendTable(), QPTPLTest\testTplRecursion(), QPTPLTest\testTplTraversable(), QueryPathTest\testQueryPathHtmlConstructors(), QueryPathTest\testNext(), QueryPathTest\testBranch(), QueryPathTest\testStub(), and QueryPathTest\testIterator().

const JS_CSS_ESCAPE_CDATA = '\\1'

Definition at line 345 of file QueryPath.php.

const JS_CSS_ESCAPE_CDATA_CCOMMENT = '/* \\1 */'

Definition at line 346 of file QueryPath.php.

const JS_CSS_ESCAPE_CDATA_DOUBLESLASH = '// \\1'

Definition at line 347 of file QueryPath.php.

const JS_CSS_ESCAPE_NONE = ''

Definition at line 348 of file QueryPath.php.

const VERSION = '2.1.1'

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

Definition at line 289 of file QueryPath.php.

const XHTML_STUB

Initial value:

 '<?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>'

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

Definition at line 327 of file QueryPath.php.

The documentation for this class was generated from the following file:

src/QueryPath/QueryPath.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation