`
+ article to learn about how to use it when creating Symfony tests.
+
+The :class:`Symfony\\Component\\DomCrawler\\Crawler` class provides methods
+to query and manipulate HTML and XML documents.
+
+An instance of the Crawler represents a set of :phpclass:`DOMElement` objects,
+which are nodes that can be traversed as follows::
+
+ use Symfony\Component\DomCrawler\Crawler;
+
+ $html = <<<'HTML'
+
+
+
+ Hello World!
+ Hello Crawler!
+
+
+ HTML;
+
+ $crawler = new Crawler($html);
+
+ foreach ($crawler as $domElement) {
+ var_dump($domElement->nodeName);
+ }
+
+Specialized :class:`Symfony\\Component\\DomCrawler\\Link`,
+:class:`Symfony\\Component\\DomCrawler\\Image` and
+:class:`Symfony\\Component\\DomCrawler\\Form` classes are useful for
+interacting with html links, images and forms as you traverse through the HTML
+tree.
+
+.. note::
+
+ The DomCrawler will attempt to automatically fix your HTML to match the
+ official specification. For example, if you nest a ```` tag inside
+ another ``
`` tag, it will be moved to be a sibling of the parent tag.
+ This is expected and is part of the HTML5 spec. But if you're getting
+ unexpected behavior, this could be a cause. And while the DomCrawler
+ isn't meant to dump content, you can see the "fixed" version of your HTML
+ by :ref:`dumping it `.
+
+Node Filtering
+~~~~~~~~~~~~~~
+
+Using XPath expressions, you can select specific nodes within the document::
+
+ $crawler = $crawler->filterXPath('descendant-or-self::body/p');
+
+.. tip::
+
+ ``DOMXPath::query`` is used internally to actually perform an XPath query.
+
+If you prefer CSS selectors over XPath, install :doc:`/components/css_selector`.
+It allows you to use jQuery-like selectors::
+
+ $crawler = $crawler->filter('body > p');
+
+An anonymous function can be used to filter with more complex criteria::
+
+ use Symfony\Component\DomCrawler\Crawler;
+ // ...
+
+ $crawler = $crawler
+ ->filter('body > p')
+ ->reduce(function (Crawler $node, $i): bool {
+ // filters every other node
+ return ($i % 2) === 0;
+ });
+
+To remove a node, the anonymous function must return ``false``.
+
+.. note::
+
+ All filter methods return a new :class:`Symfony\\Component\\DomCrawler\\Crawler`
+ instance with the filtered content. To check if the filter actually
+ found something, use ``$crawler->count() > 0`` on this new crawler.
+
+Both the :method:`Symfony\\Component\\DomCrawler\\Crawler::filterXPath` and
+:method:`Symfony\\Component\\DomCrawler\\Crawler::filter` methods work with
+XML namespaces, which can be either automatically discovered or registered
+explicitly.
+
+Consider the XML below:
+
+.. code-block:: xml
+
+
+
+ tag:youtube.com,2008:video:kgZRZmEc9j4
+
+
+
+ Chordates - CrashCourse Biology #24
+ widescreen
+
+
+
+This can be filtered with the ``Crawler`` without needing to register namespace
+aliases both with :method:`Symfony\\Component\\DomCrawler\\Crawler::filterXPath`::
+
+ $crawler = $crawler->filterXPath('//default:entry/media:group//yt:aspectRatio');
+
+and :method:`Symfony\\Component\\DomCrawler\\Crawler::filter`::
+
+ $crawler = $crawler->filter('default|entry media|group yt|aspectRatio');
+
+.. note::
+
+ The default namespace is registered with a prefix "default". It can be
+ changed with the
+ :method:`Symfony\\Component\\DomCrawler\\Crawler::setDefaultNamespacePrefix`
+ method.
+
+ The default namespace is removed when loading the content if it's the only
+ namespace in the document. It's done to simplify the XPath queries.
+
+Namespaces can be explicitly registered with the
+:method:`Symfony\\Component\\DomCrawler\\Crawler::registerNamespace` method::
+
+ $crawler->registerNamespace('m', 'http://search.yahoo.com/mrss/');
+ $crawler = $crawler->filterXPath('//m:group//yt:aspectRatio');
+
+Verify if the current node matches a selector::
+
+ $crawler->matches('p.lorem');
+
+Node Traversing
+~~~~~~~~~~~~~~~
+
+Access node by its position on the list::
+
+ $crawler->filter('body > p')->eq(0);
+
+Get the first or last node of the current selection::
+
+ $crawler->filter('body > p')->first();
+ $crawler->filter('body > p')->last();
+
+Get the nodes of the same level as the current selection::
+
+ $crawler->filter('body > p')->siblings();
+
+Get the same level nodes after or before the current selection::
+
+ $crawler->filter('body > p')->nextAll();
+ $crawler->filter('body > p')->previousAll();
+
+Get all the child or ancestor nodes::
+
+ $crawler->filter('body')->children();
+ $crawler->filter('body > p')->ancestors();
+
+Get all the direct child nodes matching a CSS selector::
+
+ $crawler->filter('body')->children('p.lorem');
+
+Get the first parent (heading toward the document root) of the element that matches the provided selector::
+
+ $crawler->closest('p.lorem');
+
+.. note::
+
+ All the traversal methods return a new :class:`Symfony\\Component\\DomCrawler\\Crawler`
+ instance.
+
+Accessing Node Values
+~~~~~~~~~~~~~~~~~~~~~
+
+Access the node name (HTML tag name) of the first node of the current selection (e.g. "p" or "div")::
+
+ // returns the node name (HTML tag name) of the first child element under
+ $tag = $crawler->filterXPath('//body/*')->nodeName();
+
+Access the value of the first node of the current selection::
+
+ // if the node does not exist, calling to text() will result in an exception
+ $message = $crawler->filterXPath('//body/p')->text();
+
+ // avoid the exception passing an argument that text() returns when node does not exist
+ $message = $crawler->filterXPath('//body/p')->text('Default text content');
+
+ // by default, text() trims whitespace characters, including the internal ones
+ // (e.g. " foo\n bar baz \n " is returned as "foo bar baz")
+ // pass FALSE as the second argument to return the original text unchanged
+ $crawler->filterXPath('//body/p')->text('Default text content', false);
+
+ // innerText() is similar to text() but returns only text that is a direct
+ // descendant of the current node, excluding text from child nodes
+ $text = $crawler->filterXPath('//body/p')->innerText();
+ // if content is Foo Bar
or Bar Foo
+ // innerText() returns 'Foo' in both cases; and text() returns 'Foo Bar' and 'Bar Foo' respectively
+
+ // if there are multiple text nodes, between other child nodes, like
+ // Foo Bar Baz
+ // innerText() returns only the first text node 'Foo'
+
+ // like text(), innerText() also trims whitespace characters by default,
+ // but you can get the unchanged text by passing FALSE as argument
+ $text = $crawler->filterXPath('//body/p')->innerText(false);
+
+Access the attribute value of the first node of the current selection::
+
+ $class = $crawler->filterXPath('//body/p')->attr('class');
+
+.. tip::
+
+ You can define the default value to use if the node or attribute is empty
+ by using the second argument of the ``attr()`` method::
+
+ $class = $crawler->filterXPath('//body/p')->attr('class', 'my-default-class');
+
+Extract attribute and/or node values from the list of nodes::
+
+ $attributes = $crawler
+ ->filterXpath('//body/p')
+ ->extract(['_name', '_text', 'class'])
+ ;
+
+.. note::
+
+ Special attribute ``_text`` represents a node value, while ``_name``
+ represents the element name (the HTML tag name).
+
+Call an anonymous function on each node of the list::
+
+ use Symfony\Component\DomCrawler\Crawler;
+ // ...
+
+ $nodeValues = $crawler->filter('p')->each(function (Crawler $node, $i): string {
+ return $node->text();
+ });
+
+The anonymous function receives the node (as a Crawler) and the position as arguments.
+The result is an array of values returned by the anonymous function calls.
+
+When using nested crawler, beware that ``filterXPath()`` is evaluated in the
+context of the crawler::
+
+ $crawler->filterXPath('parent')->each(function (Crawler $parentCrawler, $i): void {
+ // DON'T DO THIS: direct child can not be found
+ $subCrawler = $parentCrawler->filterXPath('sub-tag/sub-child-tag');
+
+ // DO THIS: specify the parent tag too
+ $subCrawler = $parentCrawler->filterXPath('parent/sub-tag/sub-child-tag');
+ $subCrawler = $parentCrawler->filterXPath('node()/sub-tag/sub-child-tag');
+ });
+
+Adding the Content
+~~~~~~~~~~~~~~~~~~
+
+The crawler supports multiple ways of adding the content, but they are mutually
+exclusive, so you can only use one of them to add content (e.g. if you pass the
+content to the ``Crawler`` constructor, you can't call ``addContent()`` later)::
+
+ $crawler = new Crawler('');
+
+ $crawler->addHtmlContent('
');
+ $crawler->addXmlContent('
+
+
+This practice is no longer recommended unless the web application is extremely
+simple. Hardcoding URLs can be a disadvantage because:
+
+* **Templates get verbose**: you have to write the full path for each
+ asset. When using the Asset component, you can group assets in packages to
+ avoid repeating the common part of their path;
+* **Versioning is difficult**: it has to be custom managed for each
+ application. Adding a version (e.g. ``main.css?v=5``) to the asset URLs
+ is essential for some applications because it allows you to control how
+ the assets are cached. The Asset component allows you to define different
+ versioning strategies for each package;
+* **Moving assets' location** is cumbersome and error-prone: it requires you to
+ carefully update the URLs of all assets included in all templates. The Asset
+ component allows to move assets effortlessly just by changing the base path
+ value associated with the package of assets;
+* **It's nearly impossible to use multiple CDNs**: this technique requires
+ you to change the URL of the asset randomly for each request. The Asset component
+ provides out-of-the-box support for any number of multiple CDNs, both regular
+ (``http://``) and secure (``https://``).
+
+Installation
+------------
+
+.. code-block:: terminal
+
+ $ composer require symfony/asset
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+.. _asset-packages:
+
+Asset Packages
+~~~~~~~~~~~~~~
+
+The Asset component manages assets through packages. A package groups all the
+assets which share the same properties: versioning strategy, base path, CDN hosts,
+etc. In the following basic example, a package is created to manage assets without
+any versioning::
+
+ use Symfony\Component\Asset\Package;
+ use Symfony\Component\Asset\VersionStrategy\EmptyVersionStrategy;
+
+ $package = new Package(new EmptyVersionStrategy());
+
+ // Absolute path
+ echo $package->getUrl('/image.png');
+ // result: /image.png
+
+ // Relative path
+ echo $package->getUrl('image.png');
+ // result: image.png
+
+Packages implement :class:`Symfony\\Component\\Asset\\PackageInterface`,
+which defines the following two methods:
+
+:method:`Symfony\\Component\\Asset\\PackageInterface::getVersion`
+ Returns the asset version for an asset.
+
+:method:`Symfony\\Component\\Asset\\PackageInterface::getUrl`
+ Returns an absolute or root-relative public path.
+
+With a package, you can:
+
+A) :ref:`version the assets