Warning: You are browsing the documentation for Symfony 4.1, which is no longer maintained.

Read the updated version of this page for Symfony 5.3 (the current stable version).

The DomCrawler Component

The DomCrawler Component

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


While possible, the DomCrawler component is not designed for manipulation of the DOM or re-dumping HTML/XML.


$ composer require symfony/dom-crawler

Alternatively, you can clone the https://github.com/symfony/dom-crawler repository.


If you install this component outside of a Symfony application, you must require the vendor/autoload.php file in your code to enable the class autoloading mechanism provided by Composer. Read this article for more details.


See also

This article explains how to use the DomCrawler features as an independent component in any PHP application. Read the Symfony Functional Tests article to learn about how to use it when creating Symfony tests.

The Symfony\Component\DomCrawler\Crawler class provides methods to query and manipulate HTML and XML documents.

An instance of the Crawler represents a set of DOMElement objects, which are basically nodes that you can traverse easily:

use Symfony\Component\DomCrawler\Crawler;

$html = <<<'HTML'
<!DOCTYPE html>
        <p class="message">Hello World!</p>
        <p>Hello Crawler!</p>

$crawler = new Crawler($html);

foreach ($crawler as $domElement) {

Specialized Symfony\Component\DomCrawler\Link, Symfony\Component\DomCrawler\Image and Symfony\Component\DomCrawler\Form classes are useful for interacting with html links, images and forms as you traverse through the HTML tree.


The DomCrawler will attempt to automatically fix your HTML to match the official specification. For example, if you nest a <p> tag inside another <p> 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 dumping it.

Node Filtering

Using XPath expressions, you can select specific nodes within the document:

$crawler = $crawler->filterXPath('descendant-or-self::body/p');


DOMXPath::query is used internally to actually perform an XPath query.

If you prefer CSS selectors over XPath, install the CssSelector component. It allows you to use jQuery-like selectors to traverse:

$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) {
        // filters every other node
        return ($i % 2) == 0;

To remove a node the anonymous function must return false.


All filter methods return a new Symfony\Component\DomCrawler\Crawler instance with filtered content.

Both the filterXPath() and filter() methods work with XML namespaces, which can be either automatically discovered or registered explicitly.

Consider the XML below:

<?xml version="1.0" encoding="UTF-8"?>
    <yt:accessControl action="comment" permission="allowed"/>
    <yt:accessControl action="videoRespond" permission="moderated"/>
        <media:title type="plain">Chordates - CrashCourse Biology #24</media:title>

This can be filtered with the Crawler without needing to register namespace aliases both with filterXPath():

$crawler = $crawler->filterXPath('//default:entry/media:group//yt:aspectRatio');

and filter():

$crawler = $crawler->filter('default|entry media|group yt|aspectRatio');


The default namespace is registered with a prefix “default”. It can be changed with the 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 registerNamespace() method:

$crawler->registerNamespace('m', 'http://search.yahoo.com/mrss/');
$crawler = $crawler->filterXPath('//m:group//yt:aspectRatio');

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 parent nodes:

$crawler->filter('body > p')->parents();


All the traversal methods return a new Symfony\Component\DomCrawler\Crawler instance.

Accessing Node Values

Access the node name (HTML tag name) of the first node of the current selection (eg. “p” or “div”):

// returns the node name (HTML tag name) of the first child element under <body>
$tag = $crawler->filterXPath('//body/*')->nodeName();

Access the value of the first node of the current selection:

$message = $crawler->filterXPath('//body/p')->text();

Access the attribute value of the first node of the current selection:

$class = $crawler->filterXPath('//body/p')->attr('class');

Extract attribute and/or node values from the list of nodes:

$attributes = $crawler
    ->extract(['_text', 'class'])


Special attribute _text represents a node value.

Call an anonymous function on each node of the list:

use Symfony\Component\DomCrawler\Crawler;
// ...

$nodeValues = $crawler->filter('p')->each(function (Crawler $node, $i) {
    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.

Adding the Content

The crawler supports multiple ways of adding the content:

$crawler = new Crawler('<html><body /></html>');

$crawler->addHtmlContent('<html><body /></html>');
$crawler->addXmlContent('<root><node /></root>');

$crawler->addContent('<html><body /></html>');
$crawler->addContent('<root><node /></root>', 'text/xml');

$crawler->add('<html><body /></html>');
$crawler->add('<root><node /></root>');


The addHtmlContent() and addXmlContent() methods default to UTF-8 encoding but you can change this behavior with their second optional argument.

The addContent() method guesses the best charset according to the given contents and defaults to ISO-8859-1 in case no charset can be guessed.

As the Crawler’s implementation is based on the DOM extension, it is also able to interact with native DOMDocument, DOMNodeList and DOMNode objects:

$domDocument = new \DOMDocument();
$domDocument->loadXml('<root><node /><node /></root>');
$nodeList = $domDocument->getElementsByTagName('node');
$node = $domDocument->getElementsByTagName('node')->item(0);


Expression Evaluation

The evaluate() method evaluates the given XPath expression. The return value depends on the XPath expression. If the expression evaluates to a scalar value (e.g. HTML attributes), an array of results will be returned. If the expression evaluates to a DOM document, a new Crawler instance will be returned.

This behavior is best illustrated with examples:

use Symfony\Component\DomCrawler\Crawler;

$html = '<html>
    <span id="article-100" class="article">Article 1</span>
    <span id="article-101" class="article">Article 2</span>
    <span id="article-102" class="article">Article 3</span>

$crawler = new Crawler();

$crawler->filterXPath('//span[contains(@id, "article-")]')->evaluate('substring-after(@id, "-")');
/* array:3 [
     0 => "100"
     1 => "101"
     2 => "102"

$crawler->evaluate('substring-after(//span[contains(@id, "article-")]/@id, "-")');
/* array:1 [
     0 => "100"

/* array:3 [
     0 => 1.0
     1 => 1.0
     2 => 1.0

/* array:1 [
     0 => 3.0

// A Symfony\Component\DomCrawler\Crawler instance


To find an image by its alt attribute, use the selectImage method on an existing crawler. This returns a Crawler instance with just the selected image(s). Calling image() gives you a special Symfony\Component\DomCrawler\Image object:

$imagesCrawler = $crawler->selectImage('Kitten');
$image = $imagesCrawler->image();

// or do this all at once
$image = $crawler->selectImage('Kitten')->image();

The Symfony\Component\DomCrawler\Image object has the same getUri() method as Symfony\Component\DomCrawler\Link.


Special treatment is also given to forms. A selectButton() method is available on the Crawler which returns another Crawler that matches <button> or <input type="submit"> or <input type="button"> elements (or an <img> element inside them). The string given as argument is looked for in the id, alt, name, and value attributes and the text content of those elements.

This method is especially useful because you can use it to return a Symfony\Component\DomCrawler\Form object that represents the form that the button lives in:

// button example: <button id="my-super-button" type="submit">My super button</button>

// you can get button by its label
$form = $crawler->selectButton('My super button')->form();

// or by button id (#my-super-button) if the button doesn't have a label
$form = $crawler->selectButton('my-super-button')->form();

// or you can filter the whole form, for example a form has a class attribute: <form class="form-vertical" method="POST">

// or "fill" the form fields with data
$form = $crawler->selectButton('my-super-button')->form([
    'name' => 'Ryan',

The Symfony\Component\DomCrawler\Form object has lots of very useful methods for working with forms:

$uri = $form->getUri();

$method = $form->getMethod();

The getUri() method does more than just return the action attribute of the form. If the form method is GET, then it mimics the browser’s behavior and returns the action attribute followed by a query string of all of the form’s values.


The optional formaction and formmethod button attributes are supported. The getUri() and getMethod() methods take into account those attributes to always return the right action and method depending on the button used to get the form.

You can virtually set and get values on the form:

// sets values on the form internally
    'registration[username]' => 'symfonyfan',
    'registration[terms]'    => 1,

// gets back an array of values - in the "flat" array like above
$values = $form->getValues();

// returns the values like PHP would see them,
// where "registration" is its own array
$values = $form->getPhpValues();

To work with multi-dimensional fields:

    <input name="multi[]" />
    <input name="multi[]" />
    <input name="multi[dimensional]" />

Pass an array of values:

// sets a single field
$form->setValues(['multi' => ['value']]);

// sets multiple fields at once
$form->setValues(['multi' => [
    1             => 'value',
    'dimensional' => 'an other value',

This is great, but it gets better! The Form object allows you to interact with your form like a browser, selecting radio values, ticking checkboxes, and uploading files:


// checks or unchecks a checkbox

// selects an option

// selects many options from a "multiple" select
$form['registration[interests]']->select(['symfony', 'cookies']);

// fakes a file upload

Using the Form Data

What’s the point of doing all of this? If you’re testing internally, you can grab the information off of your form as if it had just been submitted by using the PHP values:

$values = $form->getPhpValues();
$files = $form->getPhpFiles();

If you’re using an external HTTP client, you can use the form to grab all of the information you need to create a POST request for the form:

$uri = $form->getUri();
$method = $form->getMethod();
$values = $form->getValues();
$files = $form->getFiles();

// now use some HTTP client and post using this information

One great example of an integrated system that uses all of this is Goutte. Goutte understands the Symfony Crawler object and can use it to submit forms directly:

use Goutte\Client;

// makes a real request to an external site
$client = new Client();
$crawler = $client->request('GET', 'https://github.com/login');

// select the form and fill in some values
$form = $crawler->selectButton('Sign in')->form();
$form['login'] = 'symfonyfan';
$form['password'] = 'anypass';

// submits the given form
$crawler = $client->submit($form);

Selecting Invalid Choice Values

By default, choice fields (select, radio) have internal validation activated to prevent you from setting invalid values. If you want to be able to set invalid values, you can use the disableValidation() method on either the whole form or specific field(s):

// disables validation for a specific field
$form['country']->disableValidation()->select('Invalid value');

// disables validation for the whole form
$form['country']->select('Invalid value');

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.