# Technical Documentation: symfony/dom-crawler

> ℹ️ **Provenance:** In-Tree Documentation (3 Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/symfony/dom-crawler) · Recency: Active (< 180 days)

## File: README.md

DomCrawler Component
====================

The DomCrawler component eases DOM navigation for HTML and XML documents.

Sponsor
-------

This package is looking for a [backer][1].

Help Symfony by [sponsoring][3] its development!

Resources
---------

 * [Documentation](https://symfony.com/doc/current/components/dom_crawler.html)
 * [Contributing](https://symfony.com/doc/current/contributing/index.html)
 * [Report issues](https://github.com/symfony/symfony/issues) and
   [send Pull Requests](https://github.com/symfony/symfony/pulls)
   in the [main Symfony repository](https://github.com/symfony/symfony)

[1]: https://symfony.com/backers
[3]: https://symfony.com/sponsor

---

## File: CHANGELOG.md

CHANGELOG
=========

8.2
---

 * Add `ChoiceFormField::selectByText()` to select an option by its visible text content
 * Make `ChoiceFormField::disableValidation()` part of the supported public API

8.1
---

 * Make `ChoiceFormField::addChoice()` part of the supported public API
 * Always set `LIBXML_NONET` in `Crawler::addXmlContent()` so external entities cannot trigger network requests

8.0
---

 * Remove argument `$useHtml5Parser` of `Crawler`'s constructor; the native HTML5 parser is used unconditionally

7.4
---

 * Disabling HTML5 parsing is deprecated; Symfony 8 will unconditionally use the native HTML5 parser

7.0
---

 * Add argument `$normalizeWhitespace` to `Crawler::innerText()`
 * Add argument `$default` to `Crawler::attr()`

6.4
---

 * Add `CrawlerAnySelectorTextContains` test constraint
 * Add `CrawlerAnySelectorTextSame` test constraint
 * Add argument `$default` to `Crawler::attr()`

6.3
---

 * Add `$useHtml5Parser` argument to `Crawler`
 * Add `CrawlerSelectorCount` test constraint
 * Add argument `$normalizeWhitespace` to `Crawler::innerText()`
 * Make `Crawler::innerText()` return the first non-empty text

6.0
---

 * Remove `Crawler::parents()` method, use `ancestors()` instead

5.4
---

 * Add `Crawler::innerText` method.

5.3
---

 * The `parents()` method is deprecated. Use `ancestors()` instead.
 * Marked the `containsOption()`, `availableOptionValues()`, and `disableValidation()` methods of the
   `ChoiceFormField` class as internal

5.1.0
-----

 * Added an internal cache layer on top of the CssSelectorConverter
 * Added `UriResolver` to resolve an URI according to a base URI

5.0.0
-----

 * Added argument `$selector` to `Crawler::children()`
 * Added argument `$default` to `Crawler::text()` and `html()`

4.4.0
-----

 * Added `Form::getName()` method.
 * Added `Crawler::matches()` method.
 * Added `Crawler::closest()` method.
 * Added `Crawler::outerHtml()` method.
 * Added an argument to the `Crawler::text()` method to opt-in normalizing whitespaces.

4.3.0
-----

 * Added PHPUnit constraints: `CrawlerSelectorAttributeValueSame`, `CrawlerSelectorExists`, `CrawlerSelectorTextContains`
   and `CrawlerSelectorTextSame`
 * Added return of element name (`_name`) in `extract()` method.
 * Added ability to return a default value in `text()` and `html()` instead of throwing an exception when node is empty.
 * When available, the [html5-php library](https://github.com/Masterminds/html5-php) is used to
   parse HTML added to a Crawler for better support of HTML5 tags.

4.2.0
-----

 * The `$currentUri` constructor argument of the `AbstractUriElement`, `Link` and
   `Image` classes is now optional.
 * The `Crawler::children()` method will have a new `$selector` argument in version 5.0,
   not defining it is deprecated.

3.1.0
-----

 * All the URI parsing logic have been abstracted in the `AbstractUriElement` class.
   The `Link` class is now a child of `AbstractUriElement`.
 * Added an `Image` class to crawl images and parse their `src` attribute,
   and `selectImage`, `image`, `images` methods in the `Crawler` (the image version of the equivalent `link` methods).

2.5.0
-----

 * [BC BREAK] The default value for checkbox and radio inputs without a value attribute have changed
   from '1' to 'on' to match the HTML specification.
 * [BC BREAK] The typehints on the `Link`, `Form` and `FormField` classes have been changed from
   `\DOMNode` to `DOMElement`. Using any other type of `DOMNode` was triggering fatal errors in previous
   versions. Code extending these classes will need to update the typehints when overwriting these methods.

2.4.0
-----

 * `Crawler::addXmlContent()` removes the default document namespace again if it's an only namespace.
 * added support for automatic discovery and explicit registration of document
   namespaces for `Crawler::filterXPath()` and `Crawler::filter()`
 * improved content type guessing in `Crawler::addContent()`
 * [BC BREAK] `Crawler::addXmlContent()` no longer removes the default document
   namespace

2.3.0
-----

 * added Crawler::html()
 * [BC BREAK] Crawler::each() and Crawler::reduce() now return Crawler instances instead of DomElement instances
 * added schema relative URL support to links
 * added support for HTML5 'form' attribute

2.2.0
-----

 * added a way to set raw path to the file in FileFormField - necessary for
   simulating HTTP requests

2.1.0
-----

 * added support for the HTTP PATCH method
 * refactored the Form class internals to support multi-dimensional fields
   (the public API is backward compatible)
 * added a way to get parsing errors for Crawler::addHtmlContent() and
   Crawler::addXmlContent() via libxml functions
 * added support for submitting a form without a submit button

---

## File: composer.json

{
    "name": "symfony/dom-crawler",
    "type": "library",
    "description": "Eases DOM navigation for HTML and XML documents",
    "keywords": [],
    "homepage": "https://symfony.com",
    "license": "MIT",
    "authors": [
        {
            "name": "Fabien Potencier",
            "email": "fabien@symfony.com"
        },
        {
            "name": "Symfony Community",
            "homepage": "https://symfony.com/contributors"
        }
    ],
    "require": {
        "php": ">=8.4.1",
        "symfony/polyfill-ctype": "^1.8",
        "symfony/polyfill-mbstring": "^1.0"
    },
    "require-dev": {
        "symfony/css-selector": "^7.4|^8.0"
    },
    "autoload": {
        "psr-4": { "Symfony\\Component\\DomCrawler\\": "" },
        "exclude-from-classmap": [
            "/Tests/"
        ]
    },
    "minimum-stability": "dev"
}

--- METRICS ---
- Files Extracted: 3
- Estimated Token Budget: ~1626 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/symfony/dom-crawler