[DomCrawler] Add a way to filter direct children #28221

Einenlum · 2018-08-17T18:01:06Z

Q	A
Branch?	master
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	#28171
License	MIT
Doc PR	-

The Dom-Crawler component only has a filter() method (to filter the node and all its children) and a children() method to return direct children.
There is currently no way to easily filter (thanks to a selector) the direct children of a node, like jQuery allows so (with a selector passed to the .children([selector]) method).

This PR adds a way to optionally filter direct children thanks to a CSS selector. Here is an example of the usage:

$html = <<<'HTML'
<html>
    <body>
        <div id="foo">
            <p class="lorem" id="p1"></p>
            <p class="lorem" id="p2"></p>
            <div id="nested">
                <p class="lorem" id="p3"></p>
            </div>
        </div>
    </body>
</html>
HTML;

$crawler = new Crawler($html);
$foo = $crawler->filter('#foo');

$foo->children() // will select `#p1`, `#p2` and `#nested`
$foo->children('p') // will select `#p1` and `p2`
$foo->children('.lorem') // will select `#p1` and `p2`

This PR adds only an optional parameter and adds no BC break.

nicolas-grekas

thanks, here are some comments.

nicolas-grekas · 2018-08-19T09:27:15Z

src/Symfony/Component/DomCrawler/Crawler.php

     */
-    public function children()
+    public function children($selector = null)


Actually, this is a BC break: child classes overriding this method would break with this change.
What we do in these situations is fetching the argument using \func_get_arg(), see e.g. the Finder::sortByName() method.
public function children(/* string $selector = null */) should be the new signature

nicolas-grekas · 2018-08-19T09:28:38Z

src/Symfony/Component/DomCrawler/Crawler.php

@@ -1148,4 +1154,20 @@ private function createSubCrawler($nodes)

        return $crawler;
    }
+
+    /**
+     * @param bool $html Whether HTML support should be enabled. Disable it for XML documents


this argument should be removed: read $this->isHtml instead.

nicolas-grekas · 2018-08-19T09:28:52Z

src/Symfony/Component/DomCrawler/Crawler.php

+    /**
+     * @param bool $html Whether HTML support should be enabled. Disable it for XML documents
+     *
+     * @return CssSelectorConverter A CssSelectorConverter instance


should be removed and replaced by a real return type on the method

nicolas-grekas · 2018-08-19T09:29:07Z

src/Symfony/Component/DomCrawler/Crawler.php

+     *
+     * @return CssSelectorConverter A CssSelectorConverter instance
+     *
+     * @throws \RuntimeException if the CssSelector Component is not available


uppercase "If" (same in other places)

Einenlum · 2018-08-19T14:53:30Z

Thank you very much for your feedbacks @nicolas-grekas :).
I fixed your comments.
A test is broken on 7.2 on Travis, but it seems it's not related to this PR (link).

nicolas-grekas

(with minor comments)

nicolas-grekas · 2018-08-19T15:58:38Z

src/Symfony/Component/DomCrawler/Crawler.php

@@ -501,16 +501,28 @@ public function parents()
    /**
     * Returns the children nodes of the current selection.
     *
+     * @param $selector string|null An optional CSS selector to filter children


swap needed: @param string|null $selector

nicolas-grekas · 2018-08-19T15:59:20Z

src/Symfony/Component/DomCrawler/Crawler.php

        if (!$this->nodes) {
            throw new \InvalidArgumentException('The current node list is empty.');
        }

+        if ($selector) {


if (null !== $selector) {?

nicolas-grekas · 2018-08-19T15:59:48Z

src/Symfony/Component/DomCrawler/Crawler.php

@@ -1148,4 +1156,16 @@ private function createSubCrawler($nodes)

        return $crawler;
    }
+
+    /**
+     * @throws \RuntimeException if the CssSelector Component is not available


uppercase If

Einenlum · 2018-08-19T16:34:05Z

Thanks @nicolas-grekas :). Fixed.

stof · 2018-08-20T10:09:57Z

src/Symfony/Component/DomCrawler/Crawler.php

+            $converter = $this->createCssSelectorConverter($this->isHtml);
+            $xpath = $converter->toXPath($selector, 'child::*/');
+
+            return $this->filterXPath($xpath);


this could be made much more efficient by using child:: as prefix when converting CSS and then using filterRelativeXPath instead of going through relativize to modify the XPath again

Einenlum · 2018-08-20T13:39:01Z

@stof Thank you for your feedback. I fixed it.

stof · 2018-08-20T13:46:34Z

src/Symfony/Component/DomCrawler/Crawler.php

     */
-    public function children()
+    public function children(/* string $selector = null */)


@nicolas-grekas shouldn't we also detect cases where getclass($this) !== __CLASS__ (plus the special handling of common mock libraries) to trigger a deprecation warning if they don't have the argument in the child class ? Otherwise, we don't have a continous migration path.

Looking at the source, we forgot such deprecations in many places.
Maybe merge as is (the continuous upgrade path would be just not adding this argument in v5)
and fix all the code base at once next?

nicolas-grekas · 2018-08-24T10:00:24Z

Thank you @Einenlum.

…nlum) This PR was squashed before being merged into the 4.2-dev branch (closes #28221). Discussion ---------- [DomCrawler] Add a way to filter direct children | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #28171 | License | MIT | Doc PR | - The Dom-Crawler component only has a `filter()` method (to filter the node and all its children) and a `children()` method to return direct children. **There is currently no way to easily filter (thanks to a selector) the direct children of a node, like jQuery allows so (with a selector passed to the `.children([selector])` method).** **This PR adds a way to optionally filter direct children thanks to a CSS selector**. Here is an example of the usage: ```php $html = <<<'HTML' <html> <body> <div id="foo"> <p class="lorem" id="p1"></p> <p class="lorem" id="p2"></p> <div id="nested"> <p class="lorem" id="p3"></p> </div> </div> </body> </html> HTML; $crawler = new Crawler($html); $foo = $crawler->filter('#foo'); $foo->children() // will select `#p1`, `#p2` and `#nested` $foo->children('p') // will select `#p1` and `p2` $foo->children('.lorem') // will select `#p1` and `p2` ``` This PR adds only an optional parameter and adds no BC break. Commits ------- f634afd [DomCrawler] Add a way to filter direct children

Einenlum · 2018-08-24T10:05:46Z

Thank you very much @nicolas-grekas! :)

javiereguiluz · 2018-09-07T14:52:49Z

@Einenlum thanks for this feature! We've created symfony/symfony-docs#10288 to not forget about documenting this new feature. It'd be great if you could provide the docs for it. If you need any help doing that, ask us in the Symfony Docs repository. Thanks!

Einenlum · 2018-09-07T15:43:42Z

@javiereguiluz Thank you for your comment. I will create a PR on Symfony Docs in the following days, no problem!

carsonbot added Status: Needs Review DomCrawler Feature labels Aug 17, 2018

Einenlum force-pushed the feature/dom-crawler-filter-children branch from 0bc09b8 to 8c9e3c7 Compare August 18, 2018 21:29

nicolas-grekas added this to the next milestone Aug 19, 2018

nicolas-grekas reviewed Aug 19, 2018

View reviewed changes

carsonbot removed the Status: Needs Review label Aug 19, 2018

nicolas-grekas approved these changes Aug 19, 2018

View reviewed changes

carsonbot added the Status: Reviewed label Aug 19, 2018

jakzal approved these changes Aug 20, 2018

View reviewed changes

stof requested changes Aug 20, 2018

View reviewed changes

carsonbot added Status: Needs Work and removed Status: Reviewed labels Aug 20, 2018

stof reviewed Aug 20, 2018

View reviewed changes

[DomCrawler] Add a way to filter direct children

f634afd

nicolas-grekas force-pushed the feature/dom-crawler-filter-children branch from 6f303ec to f634afd Compare August 24, 2018 10:00

nicolas-grekas merged commit f634afd into symfony:master Aug 24, 2018

Einenlum deleted the feature/dom-crawler-filter-children branch August 24, 2018 10:05

javiereguiluz mentioned this pull request Sep 7, 2018

[DomCrawler] Add a way to filter direct children symfony/symfony-docs#10288

Closed

nicolas-grekas modified the milestones: next, 4.2 Nov 1, 2018

fabpot mentioned this pull request Nov 3, 2018

Release v4.2.0-BETA1 #29072

Closed

fabpot mentioned this pull request Nov 3, 2018

Release v4.2.0-BETA1 #29073

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DomCrawler] Add a way to filter direct children #28221

[DomCrawler] Add a way to filter direct children #28221

Einenlum commented Aug 17, 2018

nicolas-grekas left a comment

nicolas-grekas Aug 19, 2018

nicolas-grekas Aug 19, 2018

nicolas-grekas Aug 19, 2018

nicolas-grekas Aug 19, 2018

Einenlum commented Aug 19, 2018

nicolas-grekas left a comment

nicolas-grekas Aug 19, 2018

nicolas-grekas Aug 19, 2018

nicolas-grekas Aug 19, 2018

Einenlum commented Aug 19, 2018

stof Aug 20, 2018

Einenlum commented Aug 20, 2018

stof Aug 20, 2018

nicolas-grekas Aug 20, 2018

nicolas-grekas commented Aug 24, 2018

Einenlum commented Aug 24, 2018

javiereguiluz commented Sep 7, 2018

Einenlum commented Sep 7, 2018

[DomCrawler] Add a way to filter direct children #28221

[DomCrawler] Add a way to filter direct children #28221

Conversation

Einenlum commented Aug 17, 2018

nicolas-grekas left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Einenlum commented Aug 19, 2018

nicolas-grekas left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Einenlum commented Aug 19, 2018

Choose a reason for hiding this comment

Einenlum commented Aug 20, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nicolas-grekas commented Aug 24, 2018

Einenlum commented Aug 24, 2018

javiereguiluz commented Sep 7, 2018

Einenlum commented Sep 7, 2018