DEFAULT_PARSER_FLAGS
DEFAULT_PARSER_FLAGS
Default parser flags.
These are flags that will be used if no global or local flags override them.
The DOMQuery object is the primary tool in this library.
To create a new DOMQuery, use QueryPath::with() or 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: DOMQuery uses DOM classes internally, and those do not serialize well at all. In addition, DOMQuery may contain many extensions, and there is no guarantee that extensions can serialize. The moral of the story: Don't serialize DOMQuery.
__construct(mixed $document = NULL, string $string = NULL, array $options = array())
Constructor.
Typically, a new DOMQuery is created by QueryPath::with(), QueryPath::withHTML(), qp(), or htmlqp().
| mixed | $document | A document-like object. |
| string | $string | A CSS 3 Selector |
| array | $options | An associative array of options. |
getOptions() : array
Get the effective options for the current DOMQuery object.
This returns an associative array of all of the options as set for the current DOMQuery object. This includes default options, options directly passed in via qp() or the constructor, an options set in the QueryPath::Options object.
The order of merging options is this:
This function will return the options currently used, with the above option overriding having been calculated already.
An associative array of options, calculated from defaults and overridden options.
top(string $selector = NULL) : \QueryPath\DOMQuery
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:
| 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) |
The DOMQuery object, wrapping the root element (document element) for the current document.
find(string $selector) : \QueryPath\DOMQuery
Given a CSS Selector, find matching items.
| string | $selector | CSS 3 Selector |
xpath(string $query, array $options = array()) : \QueryPath\DOMQuery
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. DOMQuery 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()).
| string | $query | An XPath query. |
| array | $options | Currently supported options are:
|
A DOMQuery object wrapping the results of the query.
get(integer $index = NULL, boolean $asObject = FALSE) : mixed
Get one or all elements from this object.
When called with no paramaters, this returns all objects wrapped by the DOMQuery. 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 DOMQuery with that index number.
Calling this method does not change the DOMQuery (e.g. it is non-destructive).
You can use qp()->get() to iterate over all elements matched. You can also iterate over qp() itself (DOMQuery implementations must be Traversable). In the later case, though, each item will be wrapped in a DOMQuery object. To learn more about iterating in QueryPath, see \examples/techniques.php.
| integer | $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. |
If an index is passed, one element will be returned. If no index is present, an array of all matches will be returned.
xinclude() : \QueryPath\DOMQuery
On an XML document, load all XIncludes.
attr(mixed $name = NULL, string $value = NULL) : mixed
Get/set an attribute.
When an attribute value is retrieved, only the attribute value of the FIRST match is returned.
| 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). |
If this was a setter request, return the DOMQuery object. If this was an access request (getter), return the string value.
hasAttr(string $attrName) : boolean
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.
| string | $attrName | The attribute name. |
TRUE if all matches have the attribute, FALSE otherwise.
css(mixed $name = NULL, string $value = '') : \QueryPath\DOMQuery
Set/get a CSS value for the current element(s).
This sets the CSS value for each element in the DOMQuery object. It does this by setting (or getting) the style attribute (without a namespace).
For example, consider this code:
| 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. |
dataURL(string $attr, mixed $data = NULL, string $mime = 'application/octet-stream', resource $context = NULL) : \QueryPath\DOMQuery|string
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 @code$qp->dataURL('src', file_get_contents('my.png'), 'image/png')@endcode 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.
| 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:
|
| 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 {@link stream_context_create()}). |
If this is called as a setter, this will return a DOMQuery object. Otherwise, it will attempt to fetch data out of the attribute and return that.
removeAttr(string $name) : \QueryPath\DOMQuery
Remove the named attribute from all elements in the current DOMQuery.
This will remove any attribute with the given name. It will do this on each item currently wrapped by DOMQuery.
As is the case in jQuery, this operation is not considered destructive.
| string | $name | Name of the parameter to remove. |
The DOMQuery object with the same elements.
eq( $index) : \QueryPath\DOMQuery
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().
| $index | The index of the element to keep. The rest will be discarded. |
is(string $selector) : boolean
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).
| string | $selector | The selector to search for. As of QueryPath 2.1.1, this also supports passing a DOMNode object. |
TRUE if one or more elements match. FALSE if no match is found.
filter(string $selector) : \QueryPath\DOMQuery
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.
| string | $selector | The selector to use as a filter. |
The DOMQuery with non-matching items filtered out.
sort(callback $comparator, boolean $modifyDOM = FALSE) : \QueryPath\DOMQuery
Sort the contents of the QueryPath object.
By default, this does not change the order of the elements in the DOM. Instead, it just sorts the internal list. However, if TRUE is passed in as the second parameter then QueryPath will re-order the DOM, too.
| callback | $comparator | A callback. This will be called during sorting to compare two DOMNode objects. |
| boolean | $modifyDOM | If this is TRUE, the sorted results will be inserted back into the DOM at the position of the original first element. |
This object.
filterLambda(string $fn) : \QueryPath\DOMQuery
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:
Example:
| string | $fn | Inline lambda function in a string. |
filterPreg(string $regex) : \QueryPath\DOMQuery
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:
| string | $regex | A regular expression. |
filterCallback( $callback) : \QueryPath\DOMQuery
Filter based on a callback function.
A callback may be any of the following:
Each callback is passed to arguments:
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.
| $callback |
Query path object augmented according to the function.
not(string $selector) : \QueryPath\DOMQuery
Filter a list to contain only items that do NOT match.
| string | $selector | A selector to use as a negation filter. If the filter is matched, the element will be removed from the list. |
The DOMQuery object with matching items filtered out.
index(\QueryPath\DOMElement $subject) : mixed
Get an item's index.
Given a DOMElement, get the index from the matches. This is the converse of \get().
| \QueryPath\DOMElement | $subject | The item to match. |
The index as an integer (if found), or boolean FALSE. Since 0 is a valid index, you should use strong equality (===) to test..
map(callback $callback) : \QueryPath\DOMQuery
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 DOMQuery functions.
Callback rules:
| callback | $callback | The function or callback to use. The callback will be passed two params:
|
The DOMQuery object wrapping a list of whatever values were returned by each run of the callback.
slice(integer $start, integer $length) : \QueryPath\DOMQuery
Narrow the items in this object down to only a slice of the starting items.
| 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. |
each(callback $callback) : \QueryPath\DOMQuery
Run a callback on each item in the list of items.
Rules of the callback:
| callback | $callback | The callback to run. |
The DOMQuery.
eachLambda(string $lambda) : \QueryPath\DOMQuery
An each() iterator that takes a lambda function.
| string | $lambda | The lambda function. This will be passed ($index, &$item). |
The DOMQuery object.
append(mixed $data) : \QueryPath\DOMQuery
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.
| mixed | $data | This can be either a string (the usual case), or a DOM Element. |
Thrown if $data is an unsupported object type.
The DOMQuery object.
appendTo(\QueryPath\DOMQuery $dest) : \QueryPath\DOMQuery
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.
| \QueryPath\DOMQuery | $dest | A DOMQuery object that will be appended to. |
Thrown if $data is an unsupported object type.
The original DOMQuery, unaltered. Only the destination DOMQuery will be modified.
prepend(mixed $data) : \QueryPath\DOMQuery
Insert the given markup as the first child.
The markup will be inserted into each match in the set.
| mixed | $data | This can be either a string (the usual case), or a DOM Element. |
Thrown if $data is an unsupported object type.
prependTo(\QueryPath\DOMQuery $dest) : \QueryPath\DOMQuery
Take all nodes in the current object and prepend them to the children nodes of each matched node in the passed-in DOMQuery object.
This will iterate through each item in the current DOMQuery object and add each item to the beginning of the children of each element in the passed-in DOMQuery object.
| \QueryPath\DOMQuery | $dest | The destination DOMQuery object. |
Thrown if $data is an unsupported object type.
The original DOMQuery, unmodified. NOT the destination DOMQuery.
before(mixed $data) : \QueryPath\DOMQuery
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 DOMQuery object currently contains. Contrast this with after().
| mixed | $data | The data to be inserted. This can be XML in a string, a DomFragment, a DOMElement, or the other usual suspects. (See {@link qp()}). |
Thrown if $data is an unsupported object type.
Returns the DOMQuery with the new modifications. The list of elements currently selected will remain the same.
insertBefore(\QueryPath\DOMQuery $dest) : \QueryPath\DOMQuery
Insert the current elements into the destination document.
The items are inserted before each element in the given DOMQuery document. That is, they will be siblings with the current elements.
| \QueryPath\DOMQuery | $dest | Destination DOMQuery document. |
Thrown if $data is an unsupported object type.
The current DOMQuery object, unaltered. Only the destination DOMQuery object is altered.
insertAfter(\QueryPath\DOMQuery $dest) : \QueryPath\DOMQuery
Insert the contents of the current DOMQuery after the nodes in the destination DOMQuery object.
| \QueryPath\DOMQuery | $dest | Destination object where the current elements will be deposited. |
Thrown if $data is an unsupported object type.
The present DOMQuery, unaltered. Only the destination object is altered.
after(mixed $data) : \QueryPath\DOMQuery
Insert the given data after each element in the current DOMQuery 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.
| mixed | $data | The data to be appended. |
Thrown if $data is an unsupported object type.
The DOMQuery object (with the items inserted).
replaceWith(mixed $new) : \QueryPath\DOMQuery
Replace the existing element(s) in the list with a new one.
| mixed | $new | A DOMElement or XML in a string. This will replace all elements currently wrapped in the DOMQuery object. |
The DOMQuery object wrapping the items that were removed. This remains consistent with the jQuery API.
unwrap() : \QueryPath\DOMQuery
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:
An exception is thrown if one attempts to unwrap a root element.
The DOMQuery object, with the same element(s) selected.
wrap(mixed $markup) : \QueryPath\DOMQuery
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 DOMNode object (in which case the first item in the list will be used.)
| mixed | $markup | Markup that will wrap each element in the current list. |
The DOMQuery object with the wrapping changes made.
wrapAll(string $markup) : \QueryPath\DOMQuery
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 DOMNode object (in which case the first item in the list will be used.)
| string | $markup | Markup that will wrap all elements in the current list. |
The DOMQuery object with the wrapping changes made.
wrapInner(string $markup) : \QueryPath\DOMQuery
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 DOMNode object (in which case the first item in the list will be used.)
| string | $markup | Markup that will wrap children of each element in the current list. |
The DOMQuery object with the wrapping changes made.
deepest() : \QueryPath\DOMQuery
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.
The DOMQuery wrapping the single deepest node.
remove(string $selector = NULL) : \QueryPath\DOMQuery
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 DOMQuery wraps the list of removed elements.
If no selector is specified, this will remove all current matches from the document.
| string | $selector | A CSS Selector. |
The Query path wrapping a list of removed items.
replaceAll(string $selector, \QueryPath\DOMDocument $document) : \QueryPath\DOMQuery
This replaces everything that matches the selector with the first value in the current list.
This is the reverse of replaceWith.
Unlike jQuery, DOMQuery 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.
| string | $selector | The selector. |
| \QueryPath\DOMDocument | $document | The destination document. |
The DOMQuery wrapping the modified document.
add(string $selector) : \QueryPath\DOMQuery
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.
| string | $selector | A valid selector. |
The DOMQuery object with the newly added elements.
end() : \QueryPath\DOMQuery
Revert to the previous set of matches.
DEPRECATED Do not use.
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:
A DOMNode object reflecting the list of matches prior to the last destructive operation.
andSelf() : \QueryPath\DOMQuery
Combine the current and previous set of matched objects.
Example:
A DOMNode object with the results of the last two "destructive" operations.
removeChildren() : \QueryPath\DOMQuery
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.)
The DOMQuery object with the child nodes removed.
children(string $selector = NULL) : \QueryPath\DOMQuery
Get the children of the elements in the DOMQuery object.
If a selector is provided, the list of children will be filtered through the selector.
| string | $selector | A valid selector. |
A DOMQuery wrapping all of the children.
contents() : \QueryPath\DOMQuery
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.
A DOMNode object wrapping all child nodes for all elements in the DOMNode object.
siblings(string $selector = NULL) : \QueryPath\DOMQuery
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 DOMQuery 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.
| string | $selector | If the optional selector is provided, siblings will be filtered through this expression. |
The DOMQuery containing the matched siblings.
closest(string $selector) : \QueryPath\DOMQuery
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.
| string | $selector | A CSS Selector to match. |
The set of matches.
parent(string $selector = NULL) : \QueryPath\DOMQuery
Get the immediate parent of each element in the DOMQuery.
If a selector is passed, this will return the nearest matching parent for each element in the DOMQuery.
| string | $selector | A valid CSS3 selector. |
A DOMNode object wrapping the matching parents.
parents(string $selector = NULL) : \QueryPath\DOMQuery
Get all ancestors of each element in the DOMQuery.
If a selector is present, only matching ancestors will be retrieved.
| string | $selector | A valid CSS 3 Selector. |
A DOMNode object containing the matching ancestors.
html(string $markup = NULL) : mixed
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:
| string | $markup | The text to insert. |
A string if no markup was passed, or a DOMQuery if markup was passed.
innerHTML() : string
Fetch the HTML contents INSIDE of the first DOMQuery item.
This behaves the way jQuery's @codehtml()@endcode function behaves.
This gets all children of the first match in DOMQuery.
Consider this fragment:
Returns a string representation of the child nodes of the first matched element.
textImplode(string $sep = ', ', boolean $filterEmpties = TRUE) : string
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.
| 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. |
The text contents, concatenated together with the given separator between every pair of items.
childrenText(string $separator = ' ') : string
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.
| string | $separator | The separator that will be inserted between found text content. |
The concatenated values of all children.
text(string $text = NULL) : mixed
Get or set the text contents of a node.
| string | $text | If this is not NULL, this value will be set as the text of the node. It will replace any existing content. |
A DOMQuery if $text is set, or the text content if no text is passed in as a pram.
textBefore(string $text = NULL) : mixed
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.
| string | $text | If this is set, it will be inserted before each node in the current set of selected items. |
Returns the DOMQuery object if $text was set, and returns a string (possibly empty) if no param is passed.
val(string $value = NULL) : mixed
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.
| string | $value |
Returns a DOMQuery if a string was passed in, and a string if no string was passed in. In the later case, an error will produce NULL.
xhtml(string $markup = NULL) : mixed
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).
| string | $markup | A string containing XML data. |
If markup is passed in, a DOMQuery is returned. If no markup is passed in, XML representing the first matched element is returned.
xml(string $markup = NULL) : mixed
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 DOMNode 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 DOMNode object will be converted to an XML string and returned.
| string | $markup | A string containing XML data. |
If markup is passed in, a DOMQuery is returned. If no markup is passed in, XML representing the first matched element is returned.
writeXML(string $path = NULL, integer $options = NULL) : \QueryPath\DOMQuery
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.
| 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. |
| integer | $options | (As of QueryPath 2.1) Pass libxml options to the saving mechanism. |
In the event that a file cannot be written, an Exception will be thrown.
The DOMQuery object, unmodified.
writeHTML(string $path = NULL) : \QueryPath\DOMQuery
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.
| 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. |
In the event that a file cannot be written, an Exception will be thrown.
The DOMQuery object, unmodified.
writeXHTML(string $path = NULL) : \QueryPath\DOMQuery
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 @code@endcode, never @code@endcode). It will write the file as well-formed XML. No XHTML schema validation is done.
| string | $path | The filename of the file to write to. |
In the event that the output file cannot be written, an exception is thrown.
Returns the DOMQuery, unmodified.
next(string $selector = NULL) : \QueryPath\DOMQuery
Get the next sibling of each element in the DOMQuery.
If a selector is provided, the next matching sibling will be returned.
| string | $selector | A CSS3 selector. |
The DOMQuery object.
nextAll(string $selector = NULL) : \QueryPath\DOMQuery
Get all siblings after an element.
For each element in the DOMQuery, get all siblings that appear after it. If a selector is passed in, then only siblings that match the selector will be included.
| string | $selector | A valid CSS 3 selector. |
The DOMQuery object, now containing the matching siblings.
prev(string $selector = NULL) : \QueryPath\DOMQuery
Get the next sibling before each element in the DOMQuery.
For each element in the DOMQuery, this retrieves the previous sibling (if any). If a selector is supplied, it retrieves the first matching sibling (if any is found).
| string | $selector | A valid CSS 3 selector. |
A DOMNode object, now containing any previous siblings that have been found.
prevAll(string $selector = NULL) : \QueryPath\DOMQuery
Get the previous siblings for each element in the DOMQuery.
For each element in the DOMQuery, get all previous siblings. If a selector is provided, only matching siblings will be retrieved.
| string | $selector | A valid CSS 3 selector. |
The DOMQuery object, now wrapping previous sibling elements.
addClass(string $class) : \QueryPath\DOMQuery
Add a class to all elements in the current DOMQuery.
This searchers for a class attribute on each item wrapped by the current DOMNode 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.
| string | $class | The name of the class. |
Returns the DOMQuery object.
removeClass(string $class = false) : \QueryPath\DOMQuery
Remove the named class from any element in the DOMQuery 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:
| string | $class | The class name to remove. |
The modified DOMNode object.
branch(string $selector = NULL) : \QueryPath\DOMQuery
Branch the base DOMQuery into another one with the same matches.
This function makes a copy of the DOMQuery object, but keeps the new copy (initially) pointed at the same matches. This object can then be queried without changing the original DOMQuery. However, changes to the elements inside of this DOMQuery will show up in the DOMQuery from which it is branched.
Compare this operation with \cloneAll(). The cloneAll() call takes the current DOMNode object and makes a copy of all of its matches. You continue to operate on the same DOMNode object, but the elements inside of the DOMQuery are copies of those before the call to cloneAll().
This, on the other hand, copies the DOMQuery, 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:
| string | $selector | If a selector is passed in, an additional {@link find()} will be executed on the branch before it is returned. (Added in QueryPath 2.0.) |
A copy of the DOMQuery object that points to the same set of elements that the original DOMQuery was pointing to.
cloneAll() : \QueryPath\DOMQuery
Perform a deep clone of each node in the DOMQuery.
detach(string $selector = NULL) : \QueryPath\DOMQuery
Detach any items from the list if they match the selector.
In other words, each item that matches the selector will be removed from the DOM document. The returned DOMQuery wraps the list of removed elements.
If no selector is specified, this will remove all current matches from the document.
| string | $selector | A CSS Selector. |
The Query path wrapping a list of removed items.
attach(\QueryPath\DOMQuery $dest) : \QueryPath\DOMQuery
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.
| \QueryPath\DOMQuery | $dest | A DOMQuery Selector. |
The Query path wrapping a list of removed items.
has(mixed $contained)
Reduce the elements matched by DOMQuery to only those which contain the given item.
There are two ways in which this is different from jQuery's implementation:
| mixed | $contained |
|
emptyElement() : \QueryPath\DOMQuery
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.
The DOMQuery object with the newly emptied elements.
even() : \QueryPath\DOMQuery
Get the even elements, so counter-intuitively 1, 3, 5, etc.
A DOMQuery wrapping all of the children.
odd() : \QueryPath\DOMQuery
Get the odd elements, so counter-intuitively 0, 2, 4, etc.
A DOMQuery wrapping all of the children.
first() : \QueryPath\DOMQuery
Get the first matching element.
A DOMQuery wrapping all of the children.
firstChild() : \QueryPath\DOMQuery
Get the first child of the matching element.
A DOMQuery wrapping all of the children.
last() : \QueryPath\DOMQuery
Get the last matching element.
A DOMQuery wrapping all of the children.
lastChild() : \QueryPath\DOMQuery
Get the last child of the matching element.
A DOMQuery wrapping all of the children.
nextUntil(string $selector = NULL) : \QueryPath\DOMQuery
Get all siblings after an element until the selector is reached.
For each element in the DOMQuery, get all siblings that appear after it. If a selector is passed in, then only siblings that match the selector will be included.
| string | $selector | A valid CSS 3 selector. |
The DOMQuery object, now containing the matching siblings.
prevUntil(string $selector = NULL) : \QueryPath\DOMQuery
Get the previous siblings for each element in the DOMQuery until the selector is reached.
For each element in the DOMQuery, get all previous siblings. If a selector is provided, only matching siblings will be retrieved.
| string | $selector | A valid CSS 3 selector. |
The DOMQuery object, now wrapping previous sibling elements.
parentsUntil(string $selector = NULL) : \QueryPath\DOMQuery
Get all ancestors of each element in the DOMQuery until the selector is reached.
If a selector is present, only matching ancestors will be retrieved.
| string | $selector | A valid CSS 3 Selector. |
A DOMNode object containing the matching ancestors.
__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.
| $name | ||
| $arguments |
An exception is thrown if a non-existent method is called.
deepestNode(\QueryPath\DOMNode $ele, integer $depth, mixed $current = NULL, \QueryPath\DOMNode $deepest = NULL) : array
A depth-checking function. Typically, it only needs to be invoked with the first parameter. The rest are used for recursion.
| \QueryPath\DOMNode | $ele | The element. |
| integer | $depth | The depth guage |
| mixed | $current | The current set. |
| \QueryPath\DOMNode | $deepest | A reference to the current deepest node. |
Returns an array of DOM nodes.
prepareInsert(mixed $item) : mixed
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.
| mixed | $item | Item to prepare for insert. |
Thrown if the object passed in is not of a supprted object type.
Returns the prepared item.
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:
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.
| $string |
parseXMLFile(string $filename, integer $flags = NULL, resource $context = NULL)
Parse an XML or HTML file.
This attempts to autodetect the type of file, and then parse it.
| string | $filename | The file name to parse. |
| integer | $flags | The OR-combined flags accepted by the DOM parser. See the PHP documentation for DOM or for libxml. |
| resource | $context | The stream context for the file IO. If this is set, then an alternate parsing path is followed: The file is loaded by PHP's stream-aware IO facilities, read entirely into memory, and then handed off to {@link parseXMLString()}. On large files, this can have a performance impact. |
Thrown when a file cannot be loaded or parsed.