QueryPath\DOMQuery::prepareInsert()

Complexity

Conditions	11
Paths	14

Size

Total Lines	56
Code Lines	29

Duplication

Lines	0
Ratio	0 %

Importance

Changes

0

1 Method

Rating	Name	Duplication	Size	Complexity
A	DOMQuery::removeChildren()	0	9	3

<?php
/**
 * @file
 * This houses the class formerly called QueryPath.
 *
 * As of QueryPath 3.0.0, the class was renamed QueryPath::DOMQuery. This
 * was done for a few reasons:
 * - The library has been refactored, and it made more sense to call the top
 *   level class QueryPath. This is not the top level class.
 * - There have been requests for a JSONQuery class, which would be the
 *   natural complement of DOMQuery.
 */

namespace QueryPath;

use QueryPath\CSS\DOMTraverser;
use \QueryPath\CSS\QueryPathEventHandler;
use \Masterminds\HTML5;


/**
 * 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.
 *
 * @see     qp()
 * @see     QueryPath.php
 * @ingroup querypath_core
 */
class DOMQuery extends DOM
{

    /**
     * The last array of matches.
     */
    protected $last = []; // Last set of matches.
    private $ext = []; // Extensions array.

    /**
     * The number of current matches.
     *
     * @see count()
     */
    public $length = 0;

    /**
     * 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 {@link qp()} or the constructor,
     * an options set in the QueryPath::Options object.
     *
     * The order of merging options is this:
     *  - Options passed in using qp() are highest priority, and will
     *    override other options.
     *  - Options set with QueryPath::Options 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.
     *
     * @return array
     *  An associative array of options, calculated from defaults and overridden
     *  options.
     * @see   qp()
     * @see   QueryPath::Options::set()
     * @see   QueryPath::Options::merge()
     * @since 2.0
     */
    public function getOptions(): array
    {
        return $this->options;
    }

    /**
     * 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:
     *
     * @code
     * qp($someDoc)->find(':root');
     * @endcode
     * 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).
     *
     * @param 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)
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object, wrapping the root element (document element)
     *  for the current document.
     */
    public function top($selector = NULL): DOMQuery
    {
        return $this->inst($this->document->documentElement, $selector, $this->options);
    }

    /**
     * Given a CSS Selector, find matching items.
     *
     * @param string $selector
     *   CSS 3 Selector
     * @return \QueryPath\DOMQuery
     * @see  filter()
     * @see  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 {@link QueryPathEventHandler} 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
     *   {@link top()} to select the root element again.
     * @throws CSS\ParseException
     */
    public function find($selector): DOMQuery
    {
        $query = new DOMTraverser($this->matches);

It seems like $this->matches can also be of type array; however, parameter $splos of QueryPath\CSS\DOMTraverser::__construct() does only seem to accept SPLObjectStorage, maybe add an additional type check?

        $query->find($selector);
        return $this->inst($query->matches(), NULL, $this->options);
    }

    /**
     * @param $selector
     * @return $this
     * @throws CSS\ParseException
     */
    public function findInPlace($selector)
    {
        $query = new DOMTraverser($this->matches);

It seems like $this->matches can also be of type array; however, parameter $splos of QueryPath\CSS\DOMTraverser::__construct() does only seem to accept SPLObjectStorage, maybe add an additional type check?

        $query->find($selector);
        $this->setMatches($query->matches());

        return $this;
    }

    /**
     * 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 {@link get()}).
     *
     * @param string $query
     *      An XPath query.
     * @param 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'
     * @return \QueryPath\DOMQuery
     *      A DOMQuery object wrapping the results of the query.
     * @see    find()
     * @author M Butcher
     * @author Xavier Prud'homme
     */
    public function xpath($query, $options = [])
    {
        $xpath = new \DOMXPath($this->document);

        // Register a default namespace.
        if (!empty($options['namespace_prefix']) && !empty($options['namespace_uri'])) {
            $xpath->registerNamespace($options['namespace_prefix'], $options['namespace_uri']);
        }

        $found = new \SplObjectStorage();
        foreach ($this->matches as $item) {
            $nl = $xpath->query($query, $item);
            if ($nl->length > 0) {
                for ($i = 0; $i < $nl->length; ++$i) {
                    $found->attach($nl->item($i));
                }
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * Get the number of elements currently wrapped by this object.
     *
     * Note that there is no length property on this object.
     *
     * @return int
     *  Number of items in the object.
     * @deprecated QueryPath now implements Countable, so use count().
     */
    public function size()
    {
        return $this->matches->count();

The method count() does not exist on Traversable. It seems like you code against a sub-type of Traversable such as DOMNodeList or Yaf_Config_Simple or Yaf\Session or Threaded or MockeryTest_InterfaceWithTraversable or SimpleXMLElement or DOMNamedNodeMap or Thread or Yaf_Session or Yaf\Config\Simple or Yaf\Config\Ini or Worker or Yaf_Config_Ini or Stackable or MongoGridFSCursor or ResourceBundle or PharIo\Manifest\AuthorCollection or QueryPath\CSS\Selector or QueryPath\DOM or QueryPathImpl or PharIo\Manifest\BundledComponentCollection or SebastianBergmann\CodeCoverage\Node\Directory or ArrayObject or PHPUnit\Framework\TestSuite or PharIo\Manifest\RequirementCollection or SplDoublyLinkedList or HttpMessage or HttpRequestPool or Yaf_Config_Simple or SplFixedArray or SplObjectStorage or Yaf\Session or SQLiteResult or Imagick or TheSeer\Tokenizer\TokenCollection or Yaf_Session or SplPriorityQueue or Yaf\Config\Simple or Yaf\Config\Ini or MongoCursor or Yaf_Config_Ini or SplHeap or MongoGridFSCursor or CachingIterator or PHP_Token_Stream or Phar or ArrayIterator or GlobIterator or Phar or Phar or RecursiveCachingIterator or RecursiveArrayIterator or SimpleXMLIterator or Phar.

    }

    /**
     * Get the number of elements currently wrapped by this object.
     *
     * Since DOMQuery is Countable, the PHP count() function can also
     * be used on a DOMQuery.
     *
     * @code
     * <?php
     *  count(qp($xml, 'div'));
     * ?>
     * @endcode
     *
     * @return int
     *  The number of matches in the DOMQuery.
     */
    public function count(): int
    {
        return $this->matches->count();
    }

    /**
     * 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 {@link examples/techniques.php}.
     *
     * @param int $index
     *   If specified, then only this index value will be returned. If this
     *   index is out of bounds, a NULL will be returned.
     * @param 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.
     * @return 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 eq()
     * @see SplObjectStorage
     */
    public function get($index = NULL, $asObject = false)
    {
        if ($index !== NULL) {
            return ($this->count() > $index) ? $this->getNthMatch($index) : NULL;
        }
        // Retain support for legacy.
        if (!$asObject) {
            $matches = [];
            foreach ($this->matches as $m) {
                $matches[] = $m;
            }

            return $matches;
        }

        return $this->matches;
    }

    /**
     * Get the namespace of the current element.
     *
     * If QP is currently pointed to a list of elements, this will get the
     * namespace of the first element.
     */
    public function ns()
    {
        return $this->get(0)->namespaceURI;
    }

    /**
     * Get the DOMDocument that we currently work with.
     *
     * This returns the current DOMDocument. Any changes made to this document will be
     * accessible to DOMQuery, as both will share access to the same object.
     *
     * @return DOMDocument

The type QueryPath\DOMDocument was not found. Did you mean DOMDocument? If so, make sure to prefix the type with \.

     */
    public function document()
    {
        return $this->document;
    }

    /**
     * On an XML document, load all XIncludes.
     *
     * @return \QueryPath\DOMQuery
     */
    public function xinclude()
    {
        $this->document->xinclude();

        return $this;
    }

    /**
     * Get all current elements wrapped in an array.
     * Compatibility function for jQuery 1.4, but identical to calling {@link get()}
     * with no parameters.
     *
     * @return array
     *  An array of DOMNodes (typically DOMElements).
     */
    public function toArray()
    {
        return $this->get();
    }

    /**
     * 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.
     *
     * @param mixed $name
     *   The name of the attribute or an associative array of name/value pairs.
     * @param string $value
     *   A value (used only when setting an individual property).
     * @return mixed
     *   If this was a setter request, return the DOMQuery object. If this was
     *   an access request (getter), return the string value.
     * @see removeAttr()
     * @see tag()
     * @see hasAttr()
     * @see hasClass()
     */
    public function attr($name = NULL, $value = NULL)
    {

        // Default case: Return all attributes as an assoc array.
        if (is_null($name)) {
            if ($this->matches->count() == 0) {
                return NULL;
            }
            $ele = $this->getFirstMatch();
            $buffer = [];

            // This does not appear to be part of the DOM
            // spec. Nor is it documented. But it works.
            foreach ($ele->attributes as $name => $attrNode) {
                $buffer[$name] = $attrNode->value;
            }

            return $buffer;
        }

        // multi-setter
        if (is_array($name)) {
            foreach ($name as $k => $v) {
                foreach ($this->matches as $m) {
                    $m->setAttribute($k, $v);
                }
            }

            return $this;
        }
        // setter
        if (isset($value)) {
            foreach ($this->matches as $m) {
                $m->setAttribute($name, $value);
            }

            return $this;
        }

        //getter
        if ($this->matches->count() == 0) {
            return NULL;
        }

        // Special node type handler:
        if ($name == 'nodeType') {
            return $this->getFirstMatch()->nodeType;
        }

        // Always return first match's attr.
        return $this->getFirstMatch()->getAttribute($name);
    }

    /**
     * Check to see if the given attribute is present.
     *
     * This returns TRUE if <em>all</em> selected items have the attribute, or
     * FALSE if at least one item does not have the attribute.
     *
     * @param string $attrName
     *  The attribute name.
     * @return boolean
     *  TRUE if all matches have the attribute, FALSE otherwise.
     * @since 2.0
     * @see   attr()
     * @see   hasClass()
     */
    public function hasAttr($attrName)
    {
        foreach ($this->matches as $match) {
            if (!$match->hasAttribute($attrName)) {
                return false;
            }
        }

        return true;
    }

    /**
     * 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:
     *
     * @code
     * <?php
     * qp(HTML_STUB, 'body')->css('background-color','red')->html();
     * ?>
     * @endcode
     * This will return the following HTML:
     * @code
     * <body style="background-color: red"/>
     * @endcode
     *
     * If no parameters are passed into this function, then the current style
     * element will be returned unparsed. Example:
     * @code
     * <?php
     * qp(HTML_STUB, 'body')->css('background-color','red')->css();
     * ?>
     * @endcode
     * This will return the following:
     * @code
     * background-color: red
     * @endcode
     *
     * 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).
     *
     * @param 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.
     * @param string $value
     *  The value to set. This is only set if $name is a string.
     * @return \QueryPath\DOMQuery
     */
    public function css($name = NULL, $value = '')
    {
        if (empty($name)) {
            return $this->attr('style');
        }

        // Get any existing CSS.
        $css = [];
        foreach ($this->matches as $match) {
            $style = $match->getAttribute('style');
            if (!empty($style)) {
                // XXX: Is this sufficient?
                $style_array = explode(';', $style);
                foreach ($style_array as $item) {
                    $item = trim($item);

                    // Skip empty attributes.
                    if (strlen($item) == 0) {
                        continue;
                    }

                    list($css_att, $css_val) = explode(':', $item, 2);
                    $css[$css_att] = trim($css_val);
                }
            }
        }

        if (is_array($name)) {
            // Use array_merge instead of + to preserve order.
            $css = array_merge($css, $name);
        } else {
            $css[$name] = $value;
        }

        // Collapse CSS into a string.
        $format = '%s: %s;';
        $css_string = '';
        foreach ($css as $n => $v) {
            $css_string .= sprintf($format, $n, trim($v));
        }

        $this->attr('style', $css_string);

        return $this;
    }

    /**
     * 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.
     *
     * @param string $attr
     *    The name of the attribute.
     * @param 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.)
     * @param string $mime
     *    The MIME type of the document.
     * @param 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()}).
     * @return \QueryPath\DOMQuery|string
     *    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.
     * @see   http://en.wikipedia.org/wiki/Data:_URL
     * @see   attr()
     * @since 2.1
     */
    public function dataURL($attr, $data = NULL, $mime = 'application/octet-stream', $context = NULL)
    {
        if (is_null($data)) {
            // Attempt to fetch the data
            $data = $this->attr($attr);
            if (empty($data) || is_array($data) || strpos($data, 'data:') !== 0) {

It seems like $data can also be of type QueryPath\DOMQuery; however, parameter $haystack of strpos() does only seem to accept string, maybe add an additional type check?

                return;
            }

            // So 1 and 2 should be MIME types, and 3 should be the base64-encoded data.
            $regex = '/^data:([a-zA-Z0-9]+)\/([a-zA-Z0-9]+);base64,(.*)$/';
            $matches = [];
            preg_match($regex, $data, $matches);

It seems like $data can also be of type QueryPath\DOMQuery; however, parameter $subject of preg_match() does only seem to accept string, maybe add an additional type check?

            if (!empty($matches)) {
                $result = [
                    'mime' => $matches[1] . '/' . $matches[2],
                    'data' => base64_decode($matches[3]),
                ];

                return $result;

The expression return $result returns the type array<string,string> which is incompatible with the documented return type QueryPath\DOMQuery|string.

            }
        } else {
            $attVal = QueryPath::encodeDataURL($data, $mime, $context);

            return $this->attr($attr, $attVal);
        }
    }

    /**
     * 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.
     *
     * @param string $name
     *  Name of the parameter to remove.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object with the same elements.
     * @see attr()
     */
    public function removeAttr($name)
    {
        foreach ($this->matches as $m) {
            //if ($m->hasAttribute($name))
            $m->removeAttribute($name);
        }

        return $this;
    }

    /**
     * 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 {@link end()}.
     *
     * @param $index
     *  The index of the element to keep. The rest will be
     *  discarded.
     * @return \QueryPath\DOMQuery
     * @see get()
     * @see is()
     * @see end()
     */
    public function eq($index)
    {
        return $this->inst($this->getNthMatch($index), NULL, $this->options);
        // XXX: Might there be a more efficient way of doing this?
        //$this->setMatches($this->getNthMatch($index));
        //return $this;
    }

    /**
     * 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).
     *
     * @param string $selector
     *   The selector to search for. As of QueryPath 2.1.1, this also supports passing a
     *   DOMNode object.
     * @return boolean
     *   TRUE if one or more elements match. FALSE if no match is found.
     * @see get()
     * @see eq()
     */
    public function is($selector)
    {

        if (is_object($selector)) {

The condition is_object($selector) is always false.

            if ($selector instanceof \DOMNode) {
                return count($this->matches) == 1 && $selector->isSameNode($this->get(0));
            } elseif ($selector instanceof \Traversable) {
                if (count($selector) != count($this->matches)) {
                    return false;
                }
                // Without $seen, there is an edge case here if $selector contains the same object
                // more than once, but the counts are equal. For example, [a, a, a, a] will
                // pass an is() on [a, b, c, d]. We use the $seen SPLOS to prevent this.
                $seen = new \SplObjectStorage();
                foreach ($selector as $item) {
                    if (!$this->matches->contains($item) || $seen->contains($item)) {
                        return false;
                    }
                    $seen->attach($item);
                }

                return true;
            }
            throw new \QueryPath\Exception('Cannot compare an object to a DOMQuery.');

            return false;

return false is not reachable.

        }

        // Testing based on Issue #70.
        //fprintf(STDOUT, __FUNCTION__  .' found %d', $this->find($selector)->count());
        return $this->branch($selector)->count() > 0;

        // Old version:
        //foreach ($this->matches as $m) {
        //$q = new \QueryPath\CSS\QueryPathEventHandler($m);
        //if ($q->find($selector)->getMatches()->count()) {
        //return TRUE;
        //}
        //}
        //return FALSE;
    }

    /**
     * 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.
     *
     * @param string $selector
     *   The selector to use as a filter.
     * @return \QueryPath\DOMQuery
     *   The DOMQuery with non-matching items filtered out.
     * @see filterLambda()
     * @see filterCallback()
     * @see map()
     * @see find()
     * @see is()
     */
    public function filter($selector)
    {

        $found = new \SplObjectStorage();
        $tmp = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            $tmp->attach($m);
            // Seems like this should be right... but it fails unit
            // tests. Need to compare to jQuery.
            // $query = new \QueryPath\CSS\DOMTraverser($tmp, TRUE, $m);
            $query = new DOMTraverser($tmp);
            $query->find($selector);
            if (count($query->matches())) {
                $found->attach($m);
            }
            $tmp->detach($m);
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @attention
     * DOM re-ordering is done by finding the location of the original first
     * item in the list, and then placing the sorted list at that location.
     *
     * The argument $compartor is a callback, such as a function name or a
     * closure. The callback receives two DOMNode objects, which you can use
     * as DOMNodes, or wrap in QueryPath objects.
     *
     * A simple callback:
     * @code
     * <?php
     * $comp = function (\DOMNode $a, \DOMNode $b) {
     *   if ($a->textContent == $b->textContent) {
     *     return 0;
     *   }
     *   return $a->textContent > $b->textContent ? 1 : -1;
     * };
     * $qp = QueryPath::with($xml, $selector)->sort($comp);
     * ?>
     * @endcode
     *
     * The above sorts the matches into lexical order using the text of each node.
     * If you would prefer to work with QueryPath objects instead of DOMNode
     * objects, you may prefer something like this:
     *
     * @code
     * <?php
     * $comp = function (\DOMNode $a, \DOMNode $b) {
     *   $qpa = qp($a);
     *   $qpb = qp($b);
     *
     *   if ($qpa->text() == $qpb->text()) {
     *     return 0;
     *   }
     *   return $qpa->text()> $qpb->text()? 1 : -1;
     * };
     *
     * $qp = QueryPath::with($xml, $selector)->sort($comp);
     * ?>
     * @endcode
     *
     * @param callback $comparator
     *   A callback. This will be called during sorting to compare two DOMNode
     *   objects.
     * @param boolean $modifyDOM
     *   If this is TRUE, the sorted results will be inserted back into
     *   the DOM at the position of the original first element.
     * @return \QueryPath\DOMQuery
     *   This object.
     */
    public function sort($comparator, $modifyDOM = false)
    {
        // Sort as an array.
        $list = iterator_to_array($this->matches);

It seems like $this->matches can also be of type array; however, parameter $iterator of iterator_to_array() does only seem to accept Traversable, maybe add an additional type check?

        if (empty($list)) {
            return $this;
        }

        $oldFirst = $list[0];

        usort($list, $comparator);

        // Copy back into SplObjectStorage.
        $found = new \SplObjectStorage();
        foreach ($list as $node) {
            $found->attach($node);
        }
        //$this->setMatches($found);


        // Do DOM modifications only if necessary.
        if ($modifyDOM) {
            $placeholder = $oldFirst->ownerDocument->createElement('_PLACEHOLDER_');
            $placeholder = $oldFirst->parentNode->insertBefore($placeholder, $oldFirst);
            $len = count($list);
            for ($i = 0; $i < $len; ++$i) {
                $node = $list[$i];
                $node = $node->parentNode->removeChild($node);
                $placeholder->parentNode->insertBefore($node, $placeholder);
            }
            $placeholder->parentNode->removeChild($placeholder);
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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:
     *
     * @code
     * qp('li')->filterLambda('qp($item)->attr("id") == "test"');
     * @endcode
     *
     * The above would filter down the list to only an item whose ID is
     * 'text'.
     *
     * @param string $fn
     *  Inline lambda function in a string.
     * @return \QueryPath\DOMQuery
     * @see filter()
     * @see map()
     * @see mapLambda()
     * @see filterCallback()
     */
    public function filterLambda($fn)
    {
        $function = create_function('$index, $item', $fn);

The function create_function() has been deprecated: 7.2

        $found = new \SplObjectStorage();
        $i = 0;
        foreach ($this->matches as $item) {
            if ($function($i++, $item) !== false) {
                $found->attach($item);
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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 <i>text content</i> (the PCDATA) of the
     * elements. This is a way of filtering elements based on their content.
     *
     * Example:
     *
     * @code
     *  <?xml version="1.0"?>
     *  <div>Hello <i>World</i></div>
     * @endcode
     *
     * @code
     *  <?php
     *    // This will be 1.
     *    qp($xml, 'div')->filterPreg('/World/')->size();
     *  ?>
     * @endcode
     *
     * The return value above will be 1 because the text content of @codeqp($xml, 'div')@endcode is
     * @codeHello World@endcode.
     *
     * Compare this to the behavior of the <em>:contains()</em> CSS3 pseudo-class.
     *
     * @param string $regex
     *  A regular expression.
     * @return \QueryPath\DOMQuery
     * @see       filter()
     * @see       filterCallback()
     * @see       preg_match()
     */
    public function filterPreg($regex)
    {

        $found = new \SplObjectStorage();

        foreach ($this->matches as $item) {
            if (preg_match($regex, $item->textContent) > 0) {
                $found->attach($item);
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @param callback $callback .
     *                           A callback either as a string (function) or an array (object, method OR
     *                           classname, method).
     * @return \QueryPath\DOMQuery
     *                           Query path object augmented according to the function.
     * @see filter()
     * @see filterLambda()
     * @see map()
     * @see is()
     * @see find()
     */
    public function filterCallback($callback)
    {
        $found = new \SplObjectStorage();
        $i = 0;
        if (is_callable($callback)) {
            foreach ($this->matches as $item) {
                if (call_user_func($callback, $i++, $item) !== false) {
                    $found->attach($item);
                }
            }
        } else {
            throw new \QueryPath\Exception('The specified callback is not callable.');
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * Filter a list to contain only items that do NOT match.
     *
     * @param string $selector
     *  A selector to use as a negation filter. If the filter is matched, the
     *  element will be removed from the list.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object with matching items filtered out.
     * @see find()
     */
    public function not($selector)
    {
        $found = new \SplObjectStorage();
        if ($selector instanceof \DOMElement) {

$selector is never a sub-type of DOMElement.

            foreach ($this->matches as $m) {
                if ($m !== $selector) {
                    $found->attach($m);
                }
            }
        } elseif (is_array($selector)) {

The condition is_array($selector) is always false.

            foreach ($this->matches as $m) {
                if (!in_array($m, $selector, true)) {
                    $found->attach($m);
                }
            }
        } elseif ($selector instanceof \SplObjectStorage) {

$selector is never a sub-type of SplObjectStorage.

            foreach ($this->matches as $m) {
                if ($selector->contains($m)) {
                    $found->attach($m);
                }
            }
        } else {
            foreach ($this->matches as $m) {
                if (!QueryPath::with($m, NULL, $this->options)->is($selector)) {
                    $found->attach($m);
                }
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * Get an item's index.
     *
     * Given a DOMElement, get the index from the matches. This is the
     * converse of {@link get()}.
     *
     * @param DOMElement $subject

The type QueryPath\DOMElement was not found. Did you mean DOMElement? If so, make sure to prefix the type with \.

     *  The item to match.
     *
     * @return 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 get()
     * @see is()
     */
    public function index($subject)
    {

        $i = 0;
        foreach ($this->matches as $m) {
            if ($m === $subject) {
                return $i;
            }
            ++$i;
        }

        return false;
    }

    /**
     * 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:
     * - 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.
     *
     * @param 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.
     *
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object wrapping a list of whatever values were returned
     *  by each run of the callback.
     *
     * @see DOMQuery::get()
     * @see filter()
     * @see find()
     */
    public function map($callback)
    {
        $found = new \SplObjectStorage();

        if (is_callable($callback)) {
            $i = 0;
            foreach ($this->matches as $item) {
                $c = call_user_func($callback, $i, $item);
                if (isset($c)) {
                    if (is_array($c) || $c instanceof \Iterable) {
                        foreach ($c as $retval) {
                            if (!is_object($retval)) {
                                $tmp = new \stdClass();
                                $tmp->textContent = $retval;
                                $retval = $tmp;
                            }
                            $found->attach($retval);
                        }
                    } else {
                        if (!is_object($c)) {
                            $tmp = new \stdClass();
                            $tmp->textContent = $c;
                            $c = $tmp;
                        }
                        $found->attach($c);
                    }
                }
                ++$i;
            }
        } else {
            throw new \QueryPath\Exception('Callback is not callable.');
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * Narrow the items in this object down to only a slice of the starting items.
     *
     * @param integer $start
     *  Where in the list of matches to begin the slice.
     * @param 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.
     * @return \QueryPath\DOMQuery
     * @see array_slice()
     */
    public function slice($start, $length = 0)
    {
        $end = $length;
        $found = new \SplObjectStorage();
        if ($start >= $this->size()) {

The function QueryPath\DOMQuery::size() has been deprecated: QueryPath now implements Countable, so use count().

            return $this->inst($found, NULL, $this->options);
        }

        $i = $j = 0;
        foreach ($this->matches as $m) {
            if ($i >= $start) {
                if ($end > 0 && $j >= $end) {
                    break;
                }
                $found->attach($m);
                ++$j;
            }
            ++$i;
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @param callback $callback
     *  The callback to run.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery.
     * @see eachLambda()
     * @see filter()
     * @see map()
     */
    public function each($callback)
    {
        if (is_callable($callback)) {
            $i = 0;
            foreach ($this->matches as $item) {
                if (call_user_func($callback, $i, $item) === false) {
                    return $this;
                }
                ++$i;
            }
        } else {
            throw new \QueryPath\Exception('Callback is not callable.');
        }

        return $this;
    }

    /**
     * An each() iterator that takes a lambda function.
     *
     * @deprecated
     *   Since PHP 5.3 supports anonymous functions -- REAL Lambdas -- this
     *   method is not necessary and should be avoided.
     * @param string $lambda
     *  The lambda function. This will be passed ($index, &$item).
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object.
     * @see each()
     * @see filterLambda()
     * @see filterCallback()
     * @see map()
     */
    public function eachLambda($lambda)
    {
        $index = 0;
        foreach ($this->matches as $item) {
            $fn = create_function('$index, &$item', $lambda);

The function create_function() has been deprecated: 7.2

            if ($fn($index, $item) === false) {
                return $this;
            }
            ++$index;
        }

        return $this;
    }

    /**
     * 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.
     *
     * @param mixed $data
     *  This can be either a string (the usual case), or a DOM Element.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object.
     * @see appendTo()
     * @see prepend()
     * @throws QueryPath::Exception
     *  Thrown if $data is an unsupported object type.
     */
    public function append($data)
    {
        $data = $this->prepareInsert($data);
        if (isset($data)) {
            if (empty($this->document->documentElement) && $this->matches->count() == 0) {
                // Then we assume we are writing to the doc root
                $this->document->appendChild($data);
                $found = new \SplObjectStorage();
                $found->attach($this->document->documentElement);
                $this->setMatches($found);
            } else {
                // You can only append in item once. So in cases where we
                // need to append multiple times, we have to clone the node.
                foreach ($this->matches as $m) {
                    // DOMDocumentFragments are even more troublesome, as they don't
                    // always clone correctly. So we have to clone their children.
                    if ($data instanceof \DOMDocumentFragment) {
                        foreach ($data->childNodes as $n) {
                            $m->appendChild($n->cloneNode(true));
                        }
                    } else {
                        // Otherwise a standard clone will do.
                        $m->appendChild($data->cloneNode(true));
                    }

                }
            }

        }

        return $this;
    }

    /**
     * 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.
     *
     * @param DOMQuery $dest
     *  A DOMQuery object that will be appended to.
     * @return \QueryPath\DOMQuery
     *  The original DOMQuery, unaltered. Only the destination DOMQuery will
     *  be modified.
     * @see append()
     * @see prependTo()
     * @throws QueryPath::Exception
     *  Thrown if $data is an unsupported object type.
     */
    public function appendTo(DOMQuery $dest)
    {
        foreach ($this->matches as $m) {
            $dest->append($m);
        }

        return $this;
    }

    /**
     * Insert the given markup as the first child.
     *
     * The markup will be inserted into each match in the set.
     *
     * @param mixed $data
     *  This can be either a string (the usual case), or a DOM Element.
     * @return \QueryPath\DOMQuery
     * @see append()
     * @see before()
     * @see after()
     * @see prependTo()
     * @throws QueryPath::Exception
     *  Thrown if $data is an unsupported object type.
     */
    public function prepend($data)
    {
        $data = $this->prepareInsert($data);
        if (isset($data)) {
            foreach ($this->matches as $m) {
                $ins = $data->cloneNode(true);
                if ($m->hasChildNodes()) {
                    $m->insertBefore($ins, $m->childNodes->item(0));
                } else {
                    $m->appendChild($ins);
                }
            }
        }

        return $this;
    }

    /**
     * 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.
     *
     * @see insertBefore()
     * @see insertAfter()
     * @see prepend()
     * @see appendTo()
     * @param DOMQuery $dest
     *  The destination DOMQuery object.
     * @return \QueryPath\DOMQuery
     *  The original DOMQuery, unmodified. NOT the destination DOMQuery.
     * @throws QueryPath::Exception
     *  Thrown if $data is an unsupported object type.
     */
    public function prependTo(DOMQuery $dest)
    {
        foreach ($this->matches as $m) {
            $dest->prepend($m);
        }

        return $this;
    }

    /**
     * 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().
     *
     * @param 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()}).
     * @return \QueryPath\DOMQuery
     *  Returns the DOMQuery with the new modifications. The list of elements currently
     *  selected will remain the same.
     * @see insertBefore()
     * @see after()
     * @see append()
     * @see prepend()
     * @throws QueryPath::Exception
     *  Thrown if $data is an unsupported object type.
     */
    public function before($data)
    {
        $data = $this->prepareInsert($data);
        foreach ($this->matches as $m) {
            $ins = $data->cloneNode(true);
            $m->parentNode->insertBefore($ins, $m);
        }

        return $this;
    }

    /**
     * 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.
     *
     * @param DOMQuery $dest
     *  Destination DOMQuery document.
     * @return \QueryPath\DOMQuery
     *  The current DOMQuery object, unaltered. Only the destination DOMQuery
     *  object is altered.
     * @see before()
     * @see insertAfter()
     * @see appendTo()
     * @throws QueryPath::Exception
     *  Thrown if $data is an unsupported object type.
     */
    public function insertBefore(DOMQuery $dest)
    {
        foreach ($this->matches as $m) {
            $dest->before($m);
        }

        return $this;
    }

    /**
     * Insert the contents of the current DOMQuery after the nodes in the
     * destination DOMQuery object.
     *
     * @param DOMQuery $dest
     *  Destination object where the current elements will be deposited.
     * @return \QueryPath\DOMQuery
     *  The present DOMQuery, unaltered. Only the destination object is altered.
     * @see after()
     * @see insertBefore()
     * @see append()
     * @throws QueryPath::Exception
     *  Thrown if $data is an unsupported object type.
     */
    public function insertAfter(DOMQuery $dest)
    {
        foreach ($this->matches as $m) {
            $dest->after($m);
        }

        return $this;
    }

    /**
     * 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 {@link append()}, which inserts the data as children
     * of matched elements.
     *
     * @param mixed $data
     *  The data to be appended.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object (with the items inserted).
     * @see before()
     * @see append()
     * @throws QueryPath::Exception
     *  Thrown if $data is an unsupported object type.
     */
    public function after($data)
    {
        if (empty($data)) {
            return $this;
        }
        $data = $this->prepareInsert($data);
        foreach ($this->matches as $m) {
            $ins = $data->cloneNode(true);
            if (isset($m->nextSibling)) {
                $m->parentNode->insertBefore($ins, $m->nextSibling);
            } else {
                $m->parentNode->appendChild($ins);
            }
        }

        return $this;
    }

    /**
     * Replace the existing element(s) in the list with a new one.
     *
     * @param mixed $new
     *  A DOMElement or XML in a string. This will replace all elements
     *  currently wrapped in the DOMQuery object.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object wrapping <b>the items that were removed</b>.
     *  This remains consistent with the jQuery API.
     * @see append()
     * @see prepend()
     * @see before()
     * @see after()
     * @see remove()
     * @see replaceAll()
     */
    public function replaceWith($new)
    {
        $data = $this->prepareInsert($new);
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            $parent = $m->parentNode;
            $parent->insertBefore($data->cloneNode(true), $m);
            $found->attach($parent->removeChild($m));
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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:
     *
     * @code
     *   <root><wrapper><content/></wrapper></root>
     * @endcode
     *
     * Now we can run this code:
     * @code
     *   qp($xml, 'content')->unwrap();
     * @endcode
     *
     * This will result in:
     *
     * @code
     *   <root><content/></root>
     * @endcode
     * This is the opposite of wrap().
     *
     * <b>The root element cannot be unwrapped.</b> It has no parents.
     * If you attempt to use unwrap on a root element, this will throw a
     * QueryPath::Exception. (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.)
     *
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object, with the same element(s) selected.
     * @throws QueryPath::Exception
     *  An exception is thrown if one attempts to unwrap a root element.
     * @see    wrap()
     * @since  2.1
     * @author mbutcher
     */
    public function unwrap()
    {

        // We do this in two loops in order to
        // capture the case where two matches are
        // under the same parent. Othwerwise we might
        // remove a match before we can move it.
        $parents = new \SplObjectStorage();
        foreach ($this->matches as $m) {

            // Cannot unwrap the root element.
            if ($m->isSameNode($m->ownerDocument->documentElement)) {
                throw new \QueryPath\Exception('Cannot unwrap the root element.');
            }

            // Move children to peer of parent.
            $parent = $m->parentNode;
            $old = $parent->removeChild($m);
            $parent->parentNode->insertBefore($old, $parent);
            $parents->attach($parent);
        }

        // Now that all the children are moved, we
        // remove all of the parents.
        foreach ($parents as $ele) {
            $ele->parentNode->removeChild($ele);
        }

        return $this;
    }

    /**
     * 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.)
     *
     * @param mixed $markup
     *  Markup that will wrap each element in the current list.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object with the wrapping changes made.
     * @see wrapAll()
     * @see wrapInner()
     */
    public function wrap($markup)
    {
        $data = $this->prepareInsert($markup);

        // If the markup passed in is empty, we don't do any wrapping.
        if (empty($data)) {
            return $this;
        }

        foreach ($this->matches as $m) {
            if ($data instanceof \DOMDocumentFragment) {
                $copy = $data->firstChild->cloneNode(true);
            } else {
                $copy = $data->cloneNode(true);
            }

            // XXX: Should be able to avoid doing this over and over.
            if ($copy->hasChildNodes()) {
                $deepest = $this->deepestNode($copy);
                // FIXME: Does this need a different data structure?
                $bottom = $deepest[0];
            } else {
                $bottom = $copy;
            }

            $parent = $m->parentNode;
            $parent->insertBefore($copy, $m);
            $m = $parent->removeChild($m);
            $bottom->appendChild($m);
            //$parent->appendChild($copy);
        }

        return $this;
    }

    /**
     * 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.)
     *
     * @param string $markup
     *  Markup that will wrap all elements in the current list.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object with the wrapping changes made.
     * @see wrap()
     * @see wrapInner()
     */
    public function wrapAll($markup)
    {
        if ($this->matches->count() === 0) {
            return;
        }

        $data = $this->prepareInsert($markup);

        if (empty($data)) {
            return $this;
        }

        if ($data instanceof \DOMDocumentFragment) {
            $data = $data->firstChild->cloneNode(true);
        } else {
            $data = $data->cloneNode(true);
        }

        if ($data->hasChildNodes()) {
            $deepest = $this->deepestNode($data);
            // FIXME: Does this need fixing?
            $bottom = $deepest[0];
        } else {
            $bottom = $data;
        }

        $first = $this->getFirstMatch();
        $parent = $first->parentNode;
        $parent->insertBefore($data, $first);
        foreach ($this->matches as $m) {
            $bottom->appendChild($m->parentNode->removeChild($m));
        }

        return $this;
    }

    /**
     * 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.)
     *
     * @param string $markup
     *  Markup that will wrap children of each element in the current list.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object with the wrapping changes made.
     * @see wrap()
     * @see wrapAll()
     */
    public function wrapInner($markup)
    {
        $data = $this->prepareInsert($markup);

        // No data? Short circuit.
        if (empty($data)) {
            return $this;
        }

        foreach ($this->matches as $m) {
            if ($data instanceof \DOMDocumentFragment) {
                $wrapper = $data->firstChild->cloneNode(true);
            } else {
                $wrapper = $data->cloneNode(true);
            }

            if ($wrapper->hasChildNodes()) {
                $deepest = $this->deepestNode($wrapper);
                // FIXME: ???
                $bottom = $deepest[0];
            } else {
                $bottom = $wrapper;
            }

            if ($m->hasChildNodes()) {
                while ($m->firstChild) {
                    $kid = $m->removeChild($m->firstChild);
                    $bottom->appendChild($kid);
                }
            }

            $m->appendChild($wrapper);
        }

        return $this;
    }

    /**
     * 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.
     *
     * @return \QueryPath\DOMQuery
     *  The DOMQuery wrapping the single deepest node.
     */
    public function deepest()
    {
        $deepest = 0;
        $winner = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            $local_deepest = 0;
            $local_ele = $this->deepestNode($m, 0, NULL, $local_deepest);

$local_deepest of type integer is incompatible with the type DOMNode expected by parameter $deepest of QueryPath\DOM::deepestNode().

            // Replace with the new deepest.
            if ($local_deepest > $deepest) {
                $winner = new \SplObjectStorage();
                foreach ($local_ele as $lele) {
                    $winner->attach($lele);
                }
                $deepest = $local_deepest;
            } // Augument with other equally deep elements.
            elseif ($local_deepest == $deepest) {
                foreach ($local_ele as $lele) {
                    $winner->attach($lele);
                }
            }
        }

        return $this->inst($winner, NULL, $this->options);
    }

    /**
     * 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 replaceAll()
     * @see replaceWith()
     * @return string
     *  The tag name of the first element in the list.
     */
    public function tag()
    {
        return ($this->size() > 0) ? $this->getFirstMatch()->tagName : '';

The function QueryPath\DOMQuery::size() has been deprecated: QueryPath now implements Countable, so use count().

    }

    /**
     * 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.
     *
     * @param string $selector
     *  A CSS Selector.
     * @return \QueryPath\DOMQuery
     *  The Query path wrapping a list of removed items.
     * @see replaceAll()
     * @see replaceWith()
     * @see removeChildren()
     */
    public function remove($selector = NULL)
    {
        if (!empty($selector)) {
            // Do a non-destructive find.
            $query = new QueryPathEventHandler($this->matches);
            $query->find($selector);
            $matches = $query->getMatches();
        } else {
            $matches = $this->matches;
        }

        $found = new \SplObjectStorage();
        foreach ($matches as $item) {
            // The item returned is (according to docs) different from
            // the one passed in, so we have to re-store it.
            $found->attach($item->parentNode->removeChild($item));
        }

        // Return a clone DOMQuery with just the removed items. If
        // no items are found, this will return an empty DOMQuery.
        return count($found) == 0 ? new static() : new static($found);
    }

    /**
     * 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.
     *
     * @param string $selector
     *  The selector.
     * @param DOMDocument $document
     *  The destination document.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery 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 replaceWith()}, it is to be
     *  considered deprecated.
     * @see        remove()
     * @see        replaceWith()
     */
    public function replaceAll($selector, \DOMDocument $document)
    {
        $replacement = $this->size() > 0 ? $this->getFirstMatch() : $this->document->createTextNode('');

The function QueryPath\DOMQuery::size() has been deprecated: QueryPath now implements Countable, so use count().

        $c = new QueryPathEventHandler($document);
        $c->find($selector);
        $temp = $c->getMatches();
        foreach ($temp as $item) {
            $node = $replacement->cloneNode();
            $node = $document->importNode($node);
            $item->parentNode->replaceChild($node, $item);
        }

        return QueryPath::with($document, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @param string $selector
     *  A valid selector.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object with the newly added elements.
     * @see append()
     * @see after()
     * @see andSelf()
     * @see end()
     */
    public function add($selector)
    {

        // This is destructive, so we need to set $last:
        $this->last = $this->matches;

        foreach (QueryPath::with($this->document, $selector, $this->options)->get() as $item) {
            $this->matches->attach($item);

The method attach() does not exist on Traversable. It seems like you code against a sub-type of Traversable such as QueryPathImpl or QueryPath\DOMQuery or HttpRequestPool or SplObjectStorage.

        }

        return $this;
    }

    /**
     * Revert to the previous set of matches.
     *
     * <b>DEPRECATED</b> 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:
     *
     * @code
     * // 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();
     * @endcode
     *
     * The last one returns an empty array because only one level of changes is stored.
     *
     * @return \QueryPath\DOMQuery
     *  A DOMNode object reflecting the list of matches prior to the last destructive
     *  operation.
     * @see        andSelf()
     * @see        add()
     * @deprecated This function will be removed.
     */
    public function end()
    {
        // Note that this does not use setMatches because it must set the previous
        // set of matches to empty array.
        $this->matches = $this->last;
        $this->last = new \SplObjectStorage();

        return $this;
    }

    /**
     * Combine the current and previous set of matched objects.
     *
     * Example:
     *
     * @code
     * qp(document, 'p')->find('div')->andSelf();
     * @endcode
     *
     * The code above will contain a list of all p elements and all div elements that
     * are beneath p elements.
     *
     * @see end();
     * @return \QueryPath\DOMQuery
     *  A DOMNode object with the results of the last two "destructive" operations.
     * @see add()
     * @see end()
     */
    public function andSelf()
    {
        // This is destructive, so we need to set $last:
        $last = $this->matches;

        foreach ($this->last as $item) {
            $this->matches->attach($item);
        }

        $this->last = $last;

        return $this;
    }

    /**
     * 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.)
     *
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object with the child nodes removed.
     * @see replaceWith()
     * @see replaceAll()
     * @see remove()
     */
    public function removeChildren()
    {
        foreach ($this->matches as $m) {
            while ($kid = $m->firstChild) {
                $m->removeChild($kid);
            }
        }

        return $this;
    }

    /**
     * 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.
     *
     * @param string $selector
     *  A valid selector.
     * @return \QueryPath\DOMQuery
     *  A DOMQuery wrapping all of the children.
     * @see removeChildren()
     * @see parent()
     * @see parents()
     * @see next()
     * @see prev()
     */
    public function children($selector = NULL)
    {
        $found = new \SplObjectStorage();
        $filter = strlen($selector) > 0;

        if ($filter) {
            $tmp = new \SplObjectStorage();
        }
        foreach ($this->matches as $m) {
            foreach ($m->childNodes as $c) {
                if ($c->nodeType == XML_ELEMENT_NODE) {
                    // This is basically an optimized filter() just for children().
                    if ($filter) {
                        $tmp->attach($c);

The variable $tmp does not seem to be defined for all execution paths leading up to this point.

                        $query = new DOMTraverser($tmp, true, $c);
                        $query->find($selector);
                        if (count($query->matches()) > 0) {
                            $found->attach($c);
                        }
                        $tmp->detach($c);

                    } // No filter. Just attach it.
                    else {
                        $found->attach($c);
                    }
                }
            }
        }
        $new = $this->inst($found, NULL, $this->options);

        return $new;
    }

    /**
     * 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.
     *
     * @return \QueryPath\DOMQuery
     *  A DOMNode object wrapping all child nodes for all elements in the
     *  DOMNode object.
     * @see find()
     * @see text()
     * @see html()
     * @see innerHTML()
     * @see xml()
     * @see innerXML()
     */
    public function contents()
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            if (empty($m->childNodes)) {
                continue;
            } // Issue #51
            foreach ($m->childNodes as $c) {
                $found->attach($c);
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @param string $selector
     *  If the optional selector is provided, siblings will be filtered through
     *  this expression.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery containing the matched siblings.
     * @see contents()
     * @see children()
     * @see parent()
     * @see parents()
     */
    public function siblings($selector = NULL)
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            $parent = $m->parentNode;
            foreach ($parent->childNodes as $n) {
                if ($n->nodeType == XML_ELEMENT_NODE && $n !== $m) {
                    $found->attach($n);
                }
            }
        }
        if (empty($selector)) {
            return $this->inst($found, NULL, $this->options);
        } else {
            return $this->inst($found, NULL, $this->options)->filter($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.
     *
     * @param string $selector
     *  A CSS Selector to match.
     * @return \QueryPath\DOMQuery
     *  The set of matches.
     * @since 2.0
     */
    public function closest($selector)
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {

            if (QueryPath::with($m, NULL, $this->options)->is($selector) > 0) {
                $found->attach($m);
            } else {
                while ($m->parentNode->nodeType !== XML_DOCUMENT_NODE) {
                    $m = $m->parentNode;
                    // Is there any case where parent node is not an element?
                    if ($m->nodeType === XML_ELEMENT_NODE && QueryPath::with($m, NULL,
                            $this->options)->is($selector) > 0) {
                        $found->attach($m);
                        break;
                    }
                }
            }

        }

        // XXX: Should this be an in-place modification?
        return $this->inst($found, NULL, $this->options);
        //$this->setMatches($found);
        //return $this;
    }

    /**
     * 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.
     *
     * @param string $selector
     *  A valid CSS3 selector.
     * @return \QueryPath\DOMQuery
     *  A DOMNode object wrapping the matching parents.
     * @see children()
     * @see siblings()
     * @see parents()
     */
    public function parent($selector = NULL)
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            while ($m->parentNode->nodeType !== XML_DOCUMENT_NODE) {
                $m = $m->parentNode;
                // Is there any case where parent node is not an element?
                if ($m->nodeType === XML_ELEMENT_NODE) {
                    if (!empty($selector)) {
                        if (QueryPath::with($m, NULL, $this->options)->is($selector) > 0) {
                            $found->attach($m);
                            break;
                        }
                    } else {
                        $found->attach($m);
                        break;
                    }
                }
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * Get all ancestors of each element in the DOMQuery.
     *
     * If a selector is present, only matching ancestors will be retrieved.
     *
     * @see parent()
     * @param string $selector
     *  A valid CSS 3 Selector.
     * @return \QueryPath\DOMQuery
     *  A DOMNode object containing the matching ancestors.
     * @see siblings()
     * @see children()
     */
    public function parents($selector = NULL)
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            while ($m->parentNode->nodeType !== XML_DOCUMENT_NODE) {
                $m = $m->parentNode;
                // Is there any case where parent node is not an element?
                if ($m->nodeType === XML_ELEMENT_NODE) {
                    if (!empty($selector)) {
                        if (QueryPath::with($m, NULL, $this->options)->is($selector) > 0) {
                            $found->attach($m);
                        }
                    } else {
                        $found->attach($m);
                    }
                }
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * <b>Important:</b> This differs from jQuery's html() function. This function
     * returns <i>the current node</i> and all of its children. jQuery returns only
     * the children. This means you do not need to do things like this:
     * @code$qp->parent()->html()@endcode.
     *
     * By default, this is HTML 4.01, not XHTML. Use {@link xml()} for XHTML.
     *
     * @param string $markup
     *  The text to insert.
     * @return mixed
     *  A string if no markup was passed, or a DOMQuery if markup was passed.
     * @see xml()
     * @see text()
     * @see contents()
     */
    public function html($markup = NULL)
    {
        if (isset($markup)) {

            if ($this->options['replace_entities']) {
                $markup = \QueryPath\Entities::replaceAllEntities($markup);
            }

            // Parse the HTML and insert it into the DOM
            //$doc = DOMDocument::loadHTML($markup);
            $doc = $this->document->createDocumentFragment();
            $doc->appendXML($markup);
            $this->removeChildren();
            $this->append($doc);

            return $this;
        }
        $length = $this->size();

The function QueryPath\DOMQuery::size() has been deprecated: QueryPath now implements Countable, so use count().

        if ($length == 0) {
            return NULL;
        }
        // Only return the first item -- that's what JQ does.
        $first = $this->getFirstMatch();

        // Catch cases where first item is not a legit DOM object.
        if (!($first instanceof \DOMNode)) {
            return NULL;
        }

        // Added by eabrand.
        if (!$first->ownerDocument->documentElement) {
            return NULL;
        }

        if ($first instanceof \DOMDocument || $first->isSameNode($first->ownerDocument->documentElement)) {
            return $this->document->saveHTML();
        }

        // saveHTML cannot take a node and serialize it.
        return $this->document->saveXML($first);
    }

    /**
     * Write the QueryPath document to HTML5.
     *
     * See html()
     *
     * @param null $markup

Are you sure the doc-type for parameter $markup is correct as it would always require null to be passed?

     * @return null|DOMQuery|string
     * @throws \QueryPath\QueryPath
     */
    public function html5($markup = NULL)
    {
        $html5 = new HTML5($this->options);

        // append HTML to existing
        if ($markup === NULL) {

            // Parse the HTML and insert it into the DOM
            $doc = $html5->loadHTMLFragment($markup);
            $this->removeChildren();
            $this->append($doc);

            return $this;
        }

        $length = $this->count();
        if ($length === 0) {
            return NULL;
        }
        // Only return the first item -- that's what JQ does.
        $first = $this->getFirstMatch();

        // Catch cases where first item is not a legit DOM object.
        if (!($first instanceof \DOMNode)) {
            return NULL;
        }

        // Added by eabrand.
        if (!$first->ownerDocument->documentElement) {
            return NULL;
        }

        if ($first instanceof \DOMDocument || $first->isSameNode($first->ownerDocument->documentElement)) {
            return $html5->saveHTML($this->document); //$this->document->saveHTML();
        }

        return $html5->saveHTML($first);
    }

    /**
     * Fetch the HTML contents INSIDE of the first DOMQuery item.
     *
     * <b>This behaves the way jQuery's @codehtml()@endcode function behaves.</b>
     *
     * This gets all children of the first match in DOMQuery.
     *
     * Consider this fragment:
     *
     * @code
     * <div>
     * test <p>foo</p> test
     * </div>
     * @endcode
     *
     * We can retrieve just the contents of this code by doing something like
     * this:
     * @code
     * qp($xml, 'div')->innerHTML();
     * @endcode
     *
     * This would return the following:
     * @codetest <p>foo</p> test@endcode
     *
     * @return string
     *  Returns a string representation of the child nodes of the first
     *  matched element.
     * @see   html()
     * @see   innerXML()
     * @see   innerXHTML()
     * @since 2.0
     */
    public function innerHTML()
    {
        return $this->innerXML();
    }

    /**
     * Fetch child (inner) nodes of the first match.
     *
     * This will return the children of the present match. For an example,
     * see {@link innerHTML()}.
     *
     * @see   innerHTML()
     * @see   innerXML()
     * @return string
     *  Returns a string of XHTML that represents the children of the present
     *  node.
     * @since 2.0
     */
    public function innerXHTML()
    {
        $length = $this->size();

The function QueryPath\DOMQuery::size() has been deprecated: QueryPath now implements Countable, so use count().

        if ($length == 0) {
            return NULL;
        }
        // Only return the first item -- that's what JQ does.
        $first = $this->getFirstMatch();

        // Catch cases where first item is not a legit DOM object.
        if (!($first instanceof \DOMNode)) {
            return NULL;
        } elseif (!$first->hasChildNodes()) {
            return '';
        }

        $buffer = '';
        foreach ($first->childNodes as $child) {
            $buffer .= $this->document->saveXML($child, LIBXML_NOEMPTYTAG);
        }

        return $buffer;
    }

    /**
     * Fetch child (inner) nodes of the first match.
     *
     * This will return the children of the present match. For an example,
     * see {@link innerHTML()}.
     *
     * @see   innerHTML()
     * @see   innerXHTML()
     * @return string
     *  Returns a string of XHTML that represents the children of the present
     *  node.
     * @since 2.0
     */
    public function innerXML()
    {
        $length = $this->size();

The function QueryPath\DOMQuery::size() has been deprecated: QueryPath now implements Countable, so use count().

        if ($length == 0) {
            return NULL;
        }
        // Only return the first item -- that's what JQ does.
        $first = $this->getFirstMatch();

        // Catch cases where first item is not a legit DOM object.
        if (!($first instanceof \DOMNode)) {
            return NULL;
        } elseif (!$first->hasChildNodes()) {
            return '';
        }

        $buffer = '';
        foreach ($first->childNodes as $child) {
            $buffer .= $this->document->saveXML($child);
        }

        return $buffer;
    }

    /**
     * Get child elements as an HTML5 string.
     *
     * TODO: This is a very simple alteration of innerXML. Do we need better
     * support?
     */
    public function innerHTML5()
    {
        $length = $this->size();

The function QueryPath\DOMQuery::size() has been deprecated: QueryPath now implements Countable, so use count().

        if ($length == 0) {
            return NULL;
        }
        // Only return the first item -- that's what JQ does.
        $first = $this->getFirstMatch();

        // Catch cases where first item is not a legit DOM object.
        if (!($first instanceof \DOMNode)) {
            return NULL;
        } elseif (!$first->hasChildNodes()) {
            return '';
        }

        $html5 = new HTML5($this->options);
        $buffer = '';
        foreach ($first->childNodes as $child) {
            $buffer .= $html5->saveHTML($child);
        }

        return $buffer;
    }

    /**
     * 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.
     *
     * @param string $sep
     *  The string used to separate text items. The default is a comma followed by a
     *  space.
     * @param boolean $filterEmpties
     *  If this is true, empty items will be ignored.
     * @return string
     *  The text contents, concatenated together with the given separator between
     *  every pair of items.
     * @see   implode()
     * @see   text()
     * @since 2.0
     */
    public function textImplode($sep = ', ', $filterEmpties = true)
    {
        $tmp = [];
        foreach ($this->matches as $m) {
            $txt = $m->textContent;
            $trimmed = trim($txt);
            // If filter empties out, then we only add items that have content.
            if ($filterEmpties) {
                if (strlen($trimmed) > 0) {
                    $tmp[] = $txt;
                }
            } // Else add all content, even if it's empty.
            else {
                $tmp[] = $txt;
            }
        }

        return implode($sep, $tmp);
    }

    /**
     * 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.
     *
     * @param string $separator
     *  The separator that will be inserted between found text content.
     * @return string
     *  The concatenated values of all children.
     */
    public function childrenText($separator = ' ')
    {
        // Branch makes it non-destructive.
        return $this->branch()->xpath('descendant::text()')->textImplode($separator);
    }

    /**
     * Get or set the text contents of a node.
     *
     * @param string $text
     *  If this is not NULL, this value will be set as the text of the node. It
     *  will replace any existing content.
     * @return mixed
     *  A DOMQuery if $text is set, or the text content if no text
     *  is passed in as a pram.
     * @see html()
     * @see xml()
     * @see contents()
     */
    public function text($text = NULL)
    {
        if (isset($text)) {
            $this->removeChildren();
            foreach ($this->matches as $m) {
                $m->appendChild($this->document->createTextNode($text));
            }

            return $this;
        }
        // Returns all text as one string:
        $buf = '';
        foreach ($this->matches as $m) {
            $buf .= $m->textContent;
        }

        return $buf;
    }

    /**
     * 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.
     *
     * @code
     * <?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');
     * ?>
     * @endcode
     *
     * @param string $text
     *  If this is set, it will be inserted before each node in the current set of
     *  selected items.
     * @return mixed
     *  Returns the DOMQuery object if $text was set, and returns a string (possibly empty)
     *  if no param is passed.
     */
    public function textBefore($text = NULL)
    {
        if (isset($text)) {
            $textNode = $this->document->createTextNode($text);

            return $this->before($textNode);
        }
        $buffer = '';
        foreach ($this->matches as $m) {
            $p = $m;
            while (isset($p->previousSibling) && $p->previousSibling->nodeType == XML_TEXT_NODE) {
                $p = $p->previousSibling;
                $buffer .= $p->textContent;
            }
        }

        return $buffer;
    }

    public function textAfter($text = NULL)
    {
        if (isset($text)) {
            $textNode = $this->document->createTextNode($text);

            return $this->after($textNode);
        }
        $buffer = '';
        foreach ($this->matches as $m) {
            $n = $m;
            while (isset($n->nextSibling) && $n->nextSibling->nodeType == XML_TEXT_NODE) {
                $n = $n->nextSibling;
                $buffer .= $n->textContent;
            }
        }

        return $buffer;
    }

    /**
     * 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        attr()
     * @param string $value
     * @return mixed
     *  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.
     */
    public function val($value = NULL)
    {
        if (isset($value)) {
            $this->attr('value', $value);

            return $this;
        }

        return $this->attr('value');
    }

    /**
     * Set or get XHTML markup for an element or elements.
     *
     * This differs from {@link html()} in that it processes (and produces)
     * strictly XML 1.0 compliant markup.
     *
     * Like {@link xml()} and {@link 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).
     *
     * @param string $markup
     *  A string containing XML data.
     * @return mixed
     *  If markup is passed in, a DOMQuery is returned. If no markup is passed
     *  in, XML representing the first matched element is returned.
     * @see html()
     * @see innerXHTML()
     */
    public function xhtml($markup = NULL)
    {

        // XXX: This is a minor reworking of the original xml() method.
        // This should be refactored, probably.
        // See http://github.com/technosophos/querypath/issues#issue/10

        $omit_xml_decl = $this->options['omit_xml_declaration'];
        if ($markup === true) {

The condition $markup === true is always false.

            // Basically, we handle the special case where we don't
            // want the XML declaration to be displayed.
            $omit_xml_decl = true;
        } elseif (isset($markup)) {
            return $this->xml($markup);
        }

        $length = $this->size();

The function QueryPath\DOMQuery::size() has been deprecated: QueryPath now implements Countable, so use count().

        if ($length == 0) {
            return NULL;
        }

        // Only return the first item -- that's what JQ does.
        $first = $this->getFirstMatch();
        // Catch cases where first item is not a legit DOM object.
        if (!($first instanceof \DOMNode)) {
            return NULL;
        }

        if ($first instanceof \DOMDocument || $first->isSameNode($first->ownerDocument->documentElement)) {

            // Has the unfortunate side-effect of stripping doctype.
            //$text = ($omit_xml_decl ? $this->document->saveXML($first->ownerDocument->documentElement, LIBXML_NOEMPTYTAG) : $this->document->saveXML(NULL, LIBXML_NOEMPTYTAG));
            $text = $this->document->saveXML(NULL, LIBXML_NOEMPTYTAG);
        } else {
            $text = $this->document->saveXML($first, LIBXML_NOEMPTYTAG);
        }

        // Issue #47: Using the old trick for removing the XML tag also removed the
        // doctype. So we remove it with a regex:
        if ($omit_xml_decl) {
            $text = preg_replace('/<\?xml\s[^>]*\?>/', '', $text);
        }

        // This is slightly lenient: It allows for cases where code incorrectly places content
        // inside of these supposedly unary elements.
        $unary = '/<(area|base|basefont|br|col|frame|hr|img|input|isindex|link|meta|param)(?(?=\s)([^>\/]+))><\/[^>]*>/i';
        $text = preg_replace($unary, '<\\1\\2 />', $text);

        // Experimental: Support for enclosing CDATA sections with comments to be both XML compat
        // and HTML 4/5 compat
        $cdata = '/(<!\[CDATA\[|\]\]>)/i';
        $replace = $this->options['escape_xhtml_js_css_sections'];
        $text = preg_replace($cdata, $replace, $text);

        return $text;
    }

    /**
     * Set or get the XML markup for an element or elements.
     *
     * Like {@link 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.
     *
     * @param string $markup
     *  A string containing XML data.
     * @return mixed
     *  If markup is passed in, a DOMQuery is returned. If no markup is passed
     *  in, XML representing the first matched element is returned.
     * @see xhtml()
     * @see html()
     * @see text()
     * @see content()
     * @see innerXML()
     */
    public function xml($markup = NULL)
    {
        $omit_xml_decl = $this->options['omit_xml_declaration'];
        if ($markup === true) {

The condition $markup === true is always false.

            // Basically, we handle the special case where we don't
            // want the XML declaration to be displayed.
            $omit_xml_decl = true;
        } elseif (isset($markup)) {
            if ($this->options['replace_entities']) {
                $markup = \QueryPath\Entities::replaceAllEntities($markup);
            }
            $doc = $this->document->createDocumentFragment();
            $doc->appendXML($markup);
            $this->removeChildren();
            $this->append($doc);

            return $this;
        }
        $length = $this->size();

The function QueryPath\DOMQuery::size() has been deprecated: QueryPath now implements Countable, so use count().

        if ($length == 0) {
            return NULL;
        }
        // Only return the first item -- that's what JQ does.
        $first = $this->getFirstMatch();

        // Catch cases where first item is not a legit DOM object.
        if (!($first instanceof \DOMNode)) {
            return NULL;
        }

        if ($first instanceof \DOMDocument || $first->isSameNode($first->ownerDocument->documentElement)) {

            return ($omit_xml_decl ? $this->document->saveXML($first->ownerDocument->documentElement) : $this->document->saveXML());
        }

        return $this->document->saveXML($first);
    }

    /**
     * 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.
     *
     * @param 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.
     * @param int $options
     *  (As of QueryPath 2.1) Pass libxml options to the saving mechanism.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object, unmodified.
     * @see xml()
     * @see innerXML()
     * @see writeXHTML()
     * @throws Exception
     *  In the event that a file cannot be written, an Exception will be thrown.
     */
    public function writeXML($path = NULL, $options = NULL)
    {
        if ($path == NULL) {

It seems like you are loosely comparing $path of type null|string against null; this is ambiguous if the string can be empty. Consider using a strict comparison === instead.

            print $this->document->saveXML(NULL, $options);
        } else {
            try {
                set_error_handler([IOException::class, 'initializeFromError']);
                $this->document->save($path, $options);
            } catch (Exception $e) {
                restore_error_handler();
                throw $e;
            }
            restore_error_handler();
        }

        return $this;
    }

    /**
     * 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 {@link toXHTML()}.
     *
     * Write the document to stdout (usually the client) or to a file.
     *
     * @param 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.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object, unmodified.
     * @see html()
     * @see innerHTML()
     * @throws Exception
     *  In the event that a file cannot be written, an Exception will be thrown.
     */
    public function writeHTML($path = NULL)
    {
        if ($path == NULL) {

It seems like you are loosely comparing $path of type null|string against null; this is ambiguous if the string can be empty. Consider using a strict comparison === instead.

            print $this->document->saveHTML();
        } else {
            try {
                set_error_handler(['\QueryPath\ParseException', 'initializeFromError']);
                $this->document->saveHTMLFile($path);
            } catch (Exception $e) {
                restore_error_handler();
                throw $e;
            }
            restore_error_handler();
        }

        return $this;
    }

    /**
     * Write the document to HTML5.
     *
     * This works the same as the other write* functions, but it encodes the output
     * as HTML5 with UTF-8.
     *
     * @see html5()
     * @see innerHTML5()
     * @throws Exception
     *  In the event that a file cannot be written, an Exception will be thrown.
     */
    public function writeHTML5($path = NULL)
    {
        $html5 = new HTML5();
        if ($path === NULL) {
            // Print the document to stdout.
            print $html5->saveHTML($this->document);

            return;
        }

        $html5->save($this->document, $path);
    }

    /**
     * Write an XHTML file to output.
     *
     * Typically, you should use this instead of {@link writeHTML()}.
     *
     * Currently, this functions identically to {@link toXML()} <i>except that</i>
     * it always uses closing tags (e.g. always @code<script></script>@endcode,
     * never @code<script/>@endcode). It will
     * write the file as well-formed XML. No XHTML schema validation is done.
     *
     * @see   writeXML()
     * @see   xml()
     * @see   writeHTML()
     * @see   innerXHTML()
     * @see   xhtml()
     * @param string $path
     *  The filename of the file to write to.
     * @return \QueryPath\DOMQuery
     *  Returns the DOMQuery, unmodified.
     * @throws Exception
     *  In the event that the output file cannot be written, an exception is
     *  thrown.
     * @since 2.0
     */
    public function writeXHTML($path = NULL)
    {
        return $this->writeXML($path, LIBXML_NOEMPTYTAG);
    }

    /**
     * Get the next sibling of each element in the DOMQuery.
     *
     * If a selector is provided, the next matching sibling will be returned.
     *
     * @param string $selector
     *  A CSS3 selector.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object.
     * @see nextAll()
     * @see prev()
     * @see children()
     * @see contents()
     * @see parent()
     * @see parents()
     */
    public function next($selector = NULL)
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            while (isset($m->nextSibling)) {
                $m = $m->nextSibling;
                if ($m->nodeType === XML_ELEMENT_NODE) {
                    if (!empty($selector)) {
                        if (QueryPath::with($m, NULL, $this->options)->is($selector) > 0) {
                            $found->attach($m);
                            break;
                        }
                    } else {
                        $found->attach($m);
                        break;
                    }
                }
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @param string $selector
     *  A valid CSS 3 selector.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object, now containing the matching siblings.
     * @see next()
     * @see prevAll()
     * @see children()
     * @see siblings()
     */
    public function nextAll($selector = NULL)
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            while (isset($m->nextSibling)) {
                $m = $m->nextSibling;
                if ($m->nodeType === XML_ELEMENT_NODE) {
                    if (!empty($selector)) {
                        if (QueryPath::with($m, NULL, $this->options)->is($selector) > 0) {
                            $found->attach($m);
                        }
                    } else {
                        $found->attach($m);
                    }
                }
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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).
     *
     * @param string $selector
     *  A valid CSS 3 selector.
     * @return \QueryPath\DOMQuery
     *  A DOMNode object, now containing any previous siblings that have been
     *  found.
     * @see prevAll()
     * @see next()
     * @see siblings()
     * @see children()
     */
    public function prev($selector = NULL)
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            while (isset($m->previousSibling)) {
                $m = $m->previousSibling;
                if ($m->nodeType === XML_ELEMENT_NODE) {
                    if (!empty($selector)) {
                        if (QueryPath::with($m, NULL, $this->options)->is($selector)) {
                            $found->attach($m);
                            break;
                        }
                    } else {
                        $found->attach($m);
                        break;
                    }
                }
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @param string $selector
     *  A valid CSS 3 selector.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object, now wrapping previous sibling elements.
     * @see prev()
     * @see nextAll()
     * @see siblings()
     * @see contents()
     * @see children()
     */
    public function prevAll($selector = NULL)
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            while (isset($m->previousSibling)) {
                $m = $m->previousSibling;
                if ($m->nodeType === XML_ELEMENT_NODE) {
                    if (!empty($selector)) {
                        if (QueryPath::with($m, NULL, $this->options)->is($selector)) {
                            $found->attach($m);
                        }
                    } else {
                        $found->attach($m);
                    }
                }
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @param string $class
     *  The name of the class.
     * @return \QueryPath\DOMQuery
     *  Returns the DOMQuery object.
     * @see css()
     * @see attr()
     * @see removeClass()
     * @see hasClass()
     */
    public function addClass($class)
    {
        foreach ($this->matches as $m) {
            if ($m->hasAttribute('class')) {
                $val = $m->getAttribute('class');
                $m->setAttribute('class', $val . ' ' . $class);
            } else {
                $m->setAttribute('class', $class);
            }
        }

        return $this;
    }

    /**
     * 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:
     *
     * @code
     * <element class="first second"/>
     * @endcode
     *
     * Executing this fragment of code will remove only the 'first' class:
     * @code
     * qp(document, 'element')->removeClass('first');
     * @endcode
     *
     * The resulting XML will be:
     * @code
     * <element class="second"/>
     * @endcode
     *
     * To remove the entire 'class' attribute, you should use {@see removeAttr()}.
     *
     * @param string $class
     *  The class name to remove.
     * @return \QueryPath\DOMQuery
     *  The modified DOMNode object.
     * @see attr()
     * @see addClass()
     * @see hasClass()
     */
    public function removeClass($class = false)
    {
        if (empty($class)) {
            foreach ($this->matches as $m) {
                $m->removeAttribute('class');
            }
        } else {
            $to_remove = array_filter(explode(' ', $class));
            foreach ($this->matches as $m) {
                if ($m->hasAttribute('class')) {
                    $vals = array_filter(explode(' ', $m->getAttribute('class')));
                    $buf = [];
                    foreach ($vals as $v) {
                        if (!in_array($v, $to_remove)) {
                            $buf[] = $v;
                        }
                    }
                    if (empty($buf)) {
                        $m->removeAttribute('class');
                    } else {
                        $m->setAttribute('class', implode(' ', $buf));
                    }
                }
            }
        }

        return $this;
    }

    /**
     * Returns TRUE if any of the elements in the DOMQuery have the specified class.
     *
     * @param string $class
     *  The name of the class.
     * @return boolean
     *  TRUE if the class exists in one or more of the elements, FALSE otherwise.
     * @see addClass()
     * @see removeClass()
     */
    public function hasClass($class)
    {
        foreach ($this->matches as $m) {
            if ($m->hasAttribute('class')) {
                $vals = explode(' ', $m->getAttribute('class'));
                if (in_array($class, $vals)) {
                    return true;
                }
            }
        }

        return false;
    }

    /**
     * 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 {@link 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 <i>the DOMQuery</i>, 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 {@link QPTPL}
     * for examples of this in practice).
     *
     * Example:
     *
     * @code
     * <?php
     * $qp = qp( QueryPath::HTML_STUB);
     * $branch = $qp->branch();
     * $branch->find('title')->text('Title');
     * $qp->find('body')->text('This is the body')->writeHTML;
     * ?>
     * @endcode
     *
     * Notice that in the code, each of the DOMQuery objects is doing its own
     * query. However, both are modifying the same document. The result of the above
     * would look something like this:
     *
     * @code
     * <!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>
     * @endcode
     *
     * 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 DOMNode objects.
     *
     * @param 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.)
     * @return \QueryPath\DOMQuery
     *  A copy of the DOMQuery object that points to the same set of elements that
     *  the original DOMQuery was pointing to.
     * @since 1.1
     * @see   cloneAll()
     * @see   find()
     */
    public function branch($selector = NULL)
    {
        $temp = QueryPath::with($this->matches, NULL, $this->options);
        //if (isset($selector)) $temp->find($selector);
        $temp->document = $this->document;
        if (isset($selector)) {
            $temp->findInPlace($selector);
        }

        return $temp;
    }

    protected function inst($matches, $selector, $options)

The parameter $options is not used and could be removed.

    {
        // https://en.wikipedia.org/wiki/Dolly_(sheep)
        $dolly = clone $this;
        $dolly->setMatches($matches);

        if (isset($selector)) {
            $dolly->findInPlace($selector);
        }

        return $dolly;
    }

    /**
     * Perform a deep clone of each node in the DOMQuery.
     *
     * @attention
     *   This is an in-place modification of the current QueryPath object.
     *
     * This does not clone the DOMQuery object, but instead clones the
     * list of nodes wrapped by the DOMQuery. 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 qp()
     * @return \QueryPath\DOMQuery
     */
    public function cloneAll()
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            $found->attach($m->cloneNode(true));
        }
        //return $this->inst($found, NULL, $this->options);
        $this->setMatches($found);

        return $this;
    }

    /**
     * Clone the DOMQuery.
     *
     * This makes a deep clone of the elements inside of the DOMQuery.
     *
     * This clones only the QueryPathImpl, not all of the decorators. The
     * clone operator in PHP should handle the cloning of the decorators.
     */
    public function __clone()
    {
        //XXX: Should we clone the document?

        // Make sure we clone the kids.
        $this->cloneAll();
    }

    /**
     * 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.
     *
     * @param string $selector
     *  A CSS Selector.
     * @return \QueryPath\DOMQuery
     *  The Query path wrapping a list of removed items.
     * @see    replaceAll()
     * @see    replaceWith()
     * @see    removeChildren()
     * @since  2.1
     * @author eabrand
     */
    public function detach($selector = NULL)
    {

        if (!empty($selector)) {
            $this->find($selector);
        }

        $found = new \SplObjectStorage();
        $this->last = $this->matches;
        foreach ($this->matches as $item) {
            // The item returned is (according to docs) different from
            // the one passed in, so we have to re-store it.
            $found->attach($item->parentNode->removeChild($item));
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @param DOMQuery $dest
     *  A DOMQuery Selector.
     * @return \QueryPath\DOMQuery
     *  The Query path wrapping a list of removed items.
     * @see    replaceAll()
     * @see    replaceWith()
     * @see    removeChildren()
     * @since  2.1
     * @author eabrand
     */
    public function attach(DOMQuery $dest)
    {
        foreach ($this->last as $m) {
            $dest->append($m);
        }

        return $this;
    }

    /**
     * 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:
     * - 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.
     *
     * @param mixed $contained
     *     - If $contained is a CSS selector (e.g. '#foo'), this will test to see
     *     if the current DOMQuery 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.
     */
    public function has($contained)
    {
        /*
    if (count($this->matches) == 0) {
      return false;
    }
     */
        $found = new \SplObjectStorage();

        // If it's a selector, we just get all of the DOMNodes that match the selector.
        $nodes = [];
        if (is_string($contained)) {
            // Get the list of nodes.
            $nodes = $this->branch($contained)->get();
        } elseif ($contained instanceof \DOMNode) {
            // Make a list with one node.
            $nodes = [$contained];
        }

        // Now we go through each of the nodes that we are testing. We want to find
        // ALL PARENTS that are in our existing DOMQuery matches. Those are the
        // ones we add to our new matches.
        foreach ($nodes as $original_node) {
            $node = $original_node;
            while (!empty($node)/* && $node != $node->ownerDocument*/) {
                if ($this->matches->contains($node)) {

The method contains() does not exist on Traversable. It seems like you code against a sub-type of Traversable such as QueryPathImpl or QueryPath\DOMQuery or SplObjectStorage.

                    $found->attach($node);
                }
                $node = $node->parentNode;
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object with the newly emptied elements.
     * @see        removeChildren()
     * @since      2.1
     * @author     eabrand
     * @deprecated The removeChildren() function is the preferred method.
     */
    public function emptyElement()
    {
        $this->removeChildren();

        return $this;
    }

    /**
     * Get the even elements, so counter-intuitively 1, 3, 5, etc.
     *
     *
     *
     * @return \QueryPath\DOMQuery
     *  A DOMQuery wrapping all of the children.
     * @see    removeChildren()
     * @see    parent()
     * @see    parents()
     * @see    next()
     * @see    prev()
     * @since  2.1
     * @author eabrand
     */
    public function even()
    {
        $found = new \SplObjectStorage();
        $even = false;
        foreach ($this->matches as $m) {
            if ($even && $m->nodeType == XML_ELEMENT_NODE) {
                $found->attach($m);
            }
            $even = ($even) ? false : true;
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * Get the odd elements, so counter-intuitively 0, 2, 4, etc.
     *
     *
     *
     * @return \QueryPath\DOMQuery
     *  A DOMQuery wrapping all of the children.
     * @see    removeChildren()
     * @see    parent()
     * @see    parents()
     * @see    next()
     * @see    prev()
     * @since  2.1
     * @author eabrand
     */
    public function odd()
    {
        $found = new \SplObjectStorage();
        $odd = true;
        foreach ($this->matches as $m) {
            if ($odd && $m->nodeType == XML_ELEMENT_NODE) {
                $found->attach($m);
            }
            $odd = ($odd) ? false : true;
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * Get the first matching element.
     *
     *
     * @return \QueryPath\DOMQuery
     *  A DOMQuery wrapping all of the children.
     * @see    next()
     * @see    prev()
     * @since  2.1
     * @author eabrand
     */
    public function first()
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            if ($m->nodeType == XML_ELEMENT_NODE) {
                $found->attach($m);
                break;
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * Get the first child of the matching element.
     *
     *
     * @return \QueryPath\DOMQuery
     *  A DOMQuery wrapping all of the children.
     * @see    next()
     * @see    prev()
     * @since  2.1
     * @author eabrand
     */
    public function firstChild()
    {
        // Could possibly use $m->firstChild http://theserverpages.com/php/manual/en/ref.dom.php
        $found = new \SplObjectStorage();
        $flag = false;
        foreach ($this->matches as $m) {
            foreach ($m->childNodes as $c) {
                if ($c->nodeType == XML_ELEMENT_NODE) {
                    $found->attach($c);
                    $flag = true;
                    break;
                }
            }
            if ($flag) {
                break;
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * Get the last matching element.
     *
     *
     * @return \QueryPath\DOMQuery
     *  A DOMQuery wrapping all of the children.
     * @see    next()
     * @see    prev()
     * @since  2.1
     * @author eabrand
     */
    public function last()
    {
        $found = new \SplObjectStorage();
        $item = NULL;
        foreach ($this->matches as $m) {
            if ($m->nodeType == XML_ELEMENT_NODE) {
                $item = $m;
            }
        }
        if ($item) {
            $found->attach($item);
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * Get the last child of the matching element.
     *
     *
     * @return \QueryPath\DOMQuery
     *  A DOMQuery wrapping all of the children.
     * @see    next()
     * @see    prev()
     * @since  2.1
     * @author eabrand
     */
    public function lastChild()
    {
        $found = new \SplObjectStorage();
        $item = NULL;
        foreach ($this->matches as $m) {
            foreach ($m->childNodes as $c) {
                if ($c->nodeType == XML_ELEMENT_NODE) {
                    $item = $c;
                }
            }
            if ($item) {
                $found->attach($item);
                $item = NULL;
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @param string $selector
     *  A valid CSS 3 selector.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object, now containing the matching siblings.
     * @see    next()
     * @see    prevAll()
     * @see    children()
     * @see    siblings()
     * @since  2.1
     * @author eabrand
     */
    public function nextUntil($selector = NULL)
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            while (isset($m->nextSibling)) {
                $m = $m->nextSibling;
                if ($m->nodeType === XML_ELEMENT_NODE) {
                    if (!empty($selector) && QueryPath::with($m, NULL, $this->options)->is($selector) > 0) {
                        break;
                    }
                    $found->attach($m);
                }
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @param string $selector
     *  A valid CSS 3 selector.
     * @return \QueryPath\DOMQuery
     *  The DOMQuery object, now wrapping previous sibling elements.
     * @see    prev()
     * @see    nextAll()
     * @see    siblings()
     * @see    contents()
     * @see    children()
     * @since  2.1
     * @author eabrand
     */
    public function prevUntil($selector = NULL)
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            while (isset($m->previousSibling)) {
                $m = $m->previousSibling;
                if ($m->nodeType === XML_ELEMENT_NODE) {
                    if (!empty($selector) && QueryPath::with($m, NULL, $this->options)->is($selector)) {
                        break;
                    }

                    $found->attach($m);
                }
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /**
     * 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.
     *
     * @see    parent()
     * @param string $selector
     *  A valid CSS 3 Selector.
     * @return \QueryPath\DOMQuery
     *  A DOMNode object containing the matching ancestors.
     * @see    siblings()
     * @see    children()
     * @since  2.1
     * @author eabrand
     */
    public function parentsUntil($selector = NULL)
    {
        $found = new \SplObjectStorage();
        foreach ($this->matches as $m) {
            while ($m->parentNode->nodeType !== XML_DOCUMENT_NODE) {
                $m = $m->parentNode;
                // Is there any case where parent node is not an element?
                if ($m->nodeType === XML_ELEMENT_NODE) {
                    if (!empty($selector)) {
                        if (QueryPath::with($m, NULL, $this->options)->is($selector) > 0) {
                            break;
                        } else {
                            $found->attach($m);
                        }
                    } else {
                        $found->attach($m);
                    }
                }
            }
        }

        return $this->inst($found, NULL, $this->options);
    }

    /////// INTERNAL FUNCTIONS ////////

    /**
     * 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.
     *
     * @throws QueryPath::Exception
     *  An exception is thrown if a non-existent method is called.
     */
    public function __call($name, $arguments)
    {

        if (!ExtensionRegistry::$useRegistry) {
            throw new \QueryPath\Exception("No method named $name found (Extensions disabled).");
        }

        // Loading of extensions is deferred until the first time a
        // non-core method is called. This makes constructing faster, but it
        // may make the first invocation of __call() slower (if there are
        // enough extensions.)
        //
        // The main reason for moving this out of the constructor is that most
        // new DOMQuery instances do not use extensions. Charging qp() calls
        // with the additional hit is not a good idea.
        //
        // Also, this will at least limit the number of circular references.
        if (empty($this->ext)) {
            // Load the registry
            $this->ext = ExtensionRegistry::getExtensions($this);
        }

        // Note that an empty ext registry indicates that extensions are disabled.
        if (!empty($this->ext) && ExtensionRegistry::hasMethod($name)) {
            $owner = ExtensionRegistry::getMethodClass($name);
            $method = new \ReflectionMethod($owner, $name);

            return $method->invokeArgs($this->ext[$owner], $arguments);
        }
        throw new \QueryPath\Exception("No method named $name found. Possibly missing an extension.");
    }

    /**
     * Get an iterator for the matches in this object.
     *
     * @return Iterable
     *  Returns an iterator.
     */
    public function getIterator()
    {
        $i = new QueryPathIterator($this->matches);

It seems like $this->matches can also be of type array; however, parameter $iterator of QueryPath\QueryPathIterator::__construct() does only seem to accept Traversable, maybe add an additional type check?

        $i->options = $this->options;

        return $i;
    }
}