Return one node per match from firstChild()

CHANGELOG.md

@@ -28,6 +28,7 @@ QueryPath Changelog
 - Fix the `:text` pseudo-class so it matches jQuery: it selects `input` elements whose `type` attribute is absent or is `text` (case-insensitively). It never indicated, and still does not indicate, whether a node is a text node
 - `find('*')` now matches the nodes in the match set as well as their descendants, so that a selector can be tested against an element already in hand
 - Fix `QPXML::createElement()` throwing "Undefined namespace" for a prefixed element name whose prefix is declared on the matched element or an ancestor below the document element. The prefix is now resolved against the namespaces in scope on the first matched element (issue #94)
+- **Behaviour change.** `firstChild()` now returns the first child element of every matched element, as `lastChild()` already did, instead of only that of the first matched element (issue #78). Matches with no child elements contribute nothing. Use `firstChild()->first()` for the previous result
 - Fix `detach($selector)` ignoring its selector and detaching the current match set instead (issue #76). It now detaches only the matches of `$selector`, as `remove($selector)` does, and leaves the current match set in the document
 - `writeHTML5()` now returns the `DOMQuery` like the other `write*()` methods, and throws `QueryPath\IOException` instead of a `TypeError` when the file cannot be written (issue #80)
 - Fix `QueryPath\ParseException` and `QueryPath\IOException` losing the PHP warning they were raised from (issue #91). The message was the error number, as in `2 (/path/to/src/DOMQuery.php: 1343)`, and the code was always `0`. The message now carries the warning text and the code is the PHP error level (for example `E_WARNING`), so code that matches on the old message text will need updating

src/Helpers/QueryFilters.php

@@ -457,11 +457,11 @@ public function first(): Query
 	}
 
 	/**
-	 * Get the first child of the matching element.
+	 * Get the first child element of each matching element.
 	 *
 	 *
 	 * @return DOMQuery
-	 *  A DOMQuery wrapping all of the children.
+	 *  A DOMQuery wrapping the first child element of each match.
 	 * @throws ParseException
 	 * @see    prev()
 	 * @since  2.1
@@ -470,20 +470,14 @@ public function first(): Query
 	 */
 	public function firstChild(): Query
 	{
-		// 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->offsetSet($c);
-					$flag = true;
 					break;
 				}
 			}
-			if ($flag) {
-				break;
-			}
 		}
 
 		return $this->inst($found, null);
@@ -516,11 +510,11 @@ public function last(): Query
 	}
 
 	/**
-	 * Get the last child of the matching element.
+	 * Get the last child element of each matching element.
 	 *
 	 *
 	 * @return DOMQuery
-	 *  A DOMQuery wrapping all of the children.
+	 *  A DOMQuery wrapping the last child element of each match.
 	 * @throws ParseException
 	 * @see    prev()
 	 * @since  2.1

tests/QueryPath/DOMQueryTest.php

@@ -2228,6 +2228,13 @@ public function testFirstChild()
 		$this->assertEquals("Hello", qp($file, '#inner-one')->firstChild()->text());
 	}
 
+	public function testFirstChildReturnsOneChildPerMatch()
+	{
+		$xml = '<?xml version="1.0"?><root><p/><p>text only</p><p>text <i>a</i><i>b</i></p><p><!-- c --><i>c</i></p></root>';
+
+		$this->assertSame('a,c', qp($xml, 'p')->firstChild()->textImplode(','));
+	}
+
 	public function testLast()
 	{
 		$file = DATA_FILE;