[jakejackson1]

Collapses #67, #69 and #71 into one branch. They were three PRs because there was one agent per issue, but they are one defect at three layers. Those PRs are closed in favour of this one.

Fixes #51. Fixes #62. Also fixes the filter() bug that had no issue.

The defect

is(), filter() and the selector-filtered traversal methods asked "does this node contain a match?" where jQuery asks "is this node a match?". Each ran a descendant search against the candidate, so anything matching below it kept it:

html5qp('<p><span>foo</span></p>', 'p')->is('span');   // true  — expected false
qp($xml, 'Demographics > Age > Name')->parents('Demographics');
// <Demographics>, <AmplifyReturn>, <ns1:AmplifyResponse>  — expected just <Demographics>
qp($file, 'inner')->filter('li')->count();             // 2     — expected 0

has() does exactly what these used to do and is unchanged. Anyone who depends on the old behaviour can switch to it.

The fix

The test is extracted into QueryPath\Helpers\NodeMatcher, so every call path shares it. A matcher is built once per call with new NodeMatcher($selector):

• $matcher->filter($nodes) / matching($nodes) / matchesAny($nodes) evaluate a whole set in one pass. filter(), children(), not(), is(), siblings(), nextAll(), prevAll() and parents() use these. A per-node pass cannot evaluate a selector describing a position within the set (:first, :eq(n), :odd), because each node is the only member of its own one-element set.
• $matcher->matches($node) answers the per-node question for the walk-and-stop methods (closest(), parent(), next(), prev(), nextUntil(), prevUntil(), parentsUntil()), memoizing each answer for the duration of the call.

It builds DOMTraverser in "initialized" mode, which takes the supplied nodes as the candidates instead of seeding them with a descendant search. The only engine change is that DOMTraverser::resolveSubject() drops non-element nodes from a caller-supplied set, so is() no longer fatals on a set holding text nodes (Call to undefined method DOMText::getElementsByTagName()).

It also leaves the scope node at its default. Passing a candidate as the scope node made every candidate match :scope, so the selector silently stopped filtering:

qp($xml, 'c')->parents(':scope')     // before: b, a, root   after: root
find('div')->children(':scope')      // before: 3            after: 0

parents()/parentsUntil() now return reverse document order with duplicates removed, per the jQuery spec quoted in #62.

The old per-node path also rebuilt a DOMQuery for every visited node. On a 1,000-item list, nextUntil() drops from about 1,000 ms to 26 ms.

Breaking changes

Method	Before	After
is($sel)	true if a descendant matched	true if a set member matches
filter($sel)	kept elements containing a match	keeps elements that match
parents(), parentsUntil(), closest(), parent(), next*(), prev*(), siblings(), not()	selector matched containment	selector matches the element
parents(), parentsUntil() ordering	grouped by starting element	reverse document order, deduplicated

The author's comment on filter()

filter() had carried this comment since 2009:

// Seems like this should be right... but it fails unit
// tests. Need to compare to jQuery.
// $query = new \QueryPath\CSS\DOMTraverser($tmp, TRUE, $m);

It fails exactly one test, DOMQueryTest::testFilter, whose two meaningful assertions both pin the containment result. That test is rebaselined here, and two tests are added: one pins the filter()/has() difference so the has() replacement stays covered, and one covers set-level evaluation. No other existing test encoded the old behaviour.

Interaction with merged work

Rebased onto current main, which now includes #70 (positional pseudo-classes, #66), #50 (:text), #106 (not() with SplObjectStorage) and #122 (nested pseudo-class arguments). It merges cleanly. The not() fix from #106 is kept, and its SplObjectStorage branch now shares the selector branch's loop. #70's caveat that children('li:first') returned every li child no longer applies, since filtering is now set-level. Issue49Test passes unchanged.

Follow-ups (out of scope)

• Consolidate the sibling and ancestor traversal loops in QueryFilters into one helper #115: consolidate the traversal loops
• Move "match these nodes against a selector" into DOMTraverser instead of NodeMatcher #116: move node matching into DOMTraverser (would also let NodeMatcher parse once per call)
• prevAll(), closest() and other traversals don't return results in jQuery's order #117: prevAll()/closest() ordering vs jQuery
• Positional selectors in closest(), next() and the *Until() methods see a one-element set #118: positional selectors in the walk-and-stop methods

Verification

• vendor/bin/phpunit: 548 tests, 1653 assertions, 0 failures (1 skipped)
• composer run lint and composer run lint:min-php: clean, PHP 7.1+
• New tests: tests/Issues/Issue51Test.php, tests/Issues/Issue62Test.php, and additions to DOMQueryTest, including a ParseException case for every changed method and for filter(''), is('') and not('')

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 98.92473% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 91.07%. Comparing base (6ae6acf) to head (f8196cf).
⚠️ Report is 10 commits behind head on main.

Files with missing lines	Patch %	Lines
src/Helpers/NodeMatcher.php	95.65%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main      #72      +/-   ##
============================================
+ Coverage     90.69%   91.07%   +0.38%     
- Complexity     1424     1433       +9     
============================================
  Files            25       26       +1     
  Lines          3170     3172       +2     
============================================
+ Hits           2875     2889      +14     
+ Misses          295      283      -12     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jakejackson1]

Note from #50: this PR should delete the wildcard self-match, and NodeMatcher's element filter is load-bearing

Three things found while rebasing and reviewing #50, verified against a trial merge of the two branches.

1. Delete #50's wildcard self-match once this lands.

#50 makes DOMTraverser::initialMatchOnElement() attach the node itself when the element selector is the
wildcard, so that $input->is(':text') can be true for the input itself. That is a workaround for is()/filter()
being built on find() — exactly what this PR fixes properly with NodeMatcher. Its changelog entry says as much.

I merged the two branches locally and deleted the hunk. All 421 tests / 1358 assertions pass with it gone,
including #50's own is(':text') assertions — NodeMatcher::matchesNode() covers everything it was standing in for.

It is worth deleting rather than leaving, because it is not confined to a literal find('*'): a null element
normalises to *, so every attribute-only and pseudo-only selector routes through it. Measured on the merged
branches, best of 9 on a 16,882-node document:

query	hunk present	hunk removed	result set
find('td')->find('*')	32.21 ms	22.70 ms (−30%)	14400 → 7200
find('td')->find('[href]')	30.23 ms	22.71 ms (−25%)	2400 → 2400 (identical)
find('td')->find(':text')	41.19 ms	27.96 ms (−32%)	2400 → 2400 (identical)
find('tr')->find('em')	9.16 ms	9.20 ms (unchanged)	2400 → 2400 (identical)

Retained memory for find('td')->find('*') drops from 5.11 MB to 4.64 MB. The last row confirms named-element
selectors were never affected. Removing it also restores jQuery's descendant-only find('*'), which is what #73 wants.

2. NodeMatcher's instanceof DOMElement filter must not be removed as redundant.

NodeMatcher::filter() screens non-elements before building the traverser:

foreach ($nodes as $node) {
    if ($node instanceof DOMElement) {
        $candidates->offsetSet($node);
    }
}

That looks like it duplicates the guards #50 adds to initialMatchOnID() / initialMatchOnClasses() /
initialMatchOnElement(). It does not. Those guards live in initialMatch(), and
DOMTraverser::resolveSubject() skips initialMatch() entirely when $initialized is true — which is the
mode NodeMatcher uses:

if ($index === 0 && $this->initialized) {
    $candidates = $this->matches;      // no initialMatch(), so no guard
} else {
    $candidates = $this->initialMatch($selectorGroup[$index], $this->matches);
}

I confirmed this by switching QueryFilters::filter() to initialized mode without an element filter:

TypeError: QueryPath\CSS\DOMTraverser::matchesSimpleSelector(): Argument #1 ($node)
           must be of type DOMElement, DOMText given

That is issue #49's crash coming back. The two filters guard two different paths and both are needed.

3. This branch needs a rebase onto main before it merges.

It predates #70, so its Util.php re-adds sortDocumentOrder(), documentOrderPath(), siblingOffset() and
comparePaths(), which main now already has. A straight merge fails with
Cannot redeclare QueryPath\CSS\DOMTraverser\Util::sortDocumentOrder(). #70's copies are the supersets, so the
resolution is to drop this branch's versions and keep main's. The other conflicts are just the use block and
the CHANGELOG unreleased section.