Skip to content

[DomCrawler] Add more details about some methods #21034

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: 6.4
Choose a base branch
from
Open

[DomCrawler] Add more details about some methods #21034

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f692b02
[DomCrawler] Add more details about some methods
javiereguiluz Jun 2, 2025
58ef2f9
Add a missing trailing dot
javiereguiluz Jun 3, 2025
449fd99
-
javiereguiluz Jun 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 15 additions & 11 deletions testing/dom_crawler.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,27 +21,29 @@ selects the last one on the page, and then selects its immediate ancestor elemen
Many other methods are also available:

``filter('h1.title')``
Nodes that match the CSS selector.
Selects nodes that match the given CSS selector (which must be supported by
Symfony's :doc:`CSS Selector component </components/css_selector>`).
``filterXpath('h1')``
Nodes that match the XPath expression.
Selects nodes matching the given `XPath expression`_.
``eq(1)``
Node for the specified index.
Selects the node at the given index (``0`` is the first node).
``first()``
First node.
Selects the first node (equivalent to ``eq(0)``).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Using Selects in all those descriptions is confusing to me. We have different kinds of methods in this lists:

  • methods creating a Crawler containing only a subset of the nodes of the current Crawler instance (eq and all its shorcuts, but also reduce which actually filters the current instance and slice)
  • methods returning a new Crawler with a different selection (which also includes the filter and filterXpath methods, despite their name, as they are doing a mix of matching the existing nodes or finding their descendants)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are right, but this doc is in testing/dom_crawler (we also have components/dom_crawler) so this is probably an internal detail not relevant in this page. 🤔

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, if you improve the documentation of available methods to make it easier to know what they do (without going to another page), it is relevant to make it clear what they do IMO. Otherwise, you could remove the list and make them go to components/dom_crawler to get the proper explanation.

``last()``
Last node.
Selects the last node.
``siblings()``
Siblings.
Selects all sibling nodes (nodes with the same parent, excluding the current node).
``nextAll()``
All following siblings.
Selects all following siblings (same parent, after the current node).
``previousAll()``
All preceding siblings.
Selects all preceding siblings (same parent, before the current node).
``ancestors()``
Returns the ancestor nodes.
Selects all ancestor nodes (parents, grandparents, etc., up to the ``<html>``
element).
``children()``
Returns children nodes.
Selects all direct child nodes of the current node.
``reduce($lambda)``
Nodes for which the callable does not return false.
Filters the nodes using a callback; keeps only those for which it returns ``true``.

Since each of these methods returns a new ``Crawler`` instance, you can
narrow down your node selection by chaining the method calls::
Expand Down Expand Up @@ -91,3 +93,5 @@ The Crawler can extract information from the nodes::
$data = $crawler->each(function ($node, int $i): string {
return $node->attr('href');
});

.. _`XPath expression`: https://developer.mozilla.org/en-US/docs/Web/XML/XPath