Skip to content

How to find HTML elements by class with DOM Crawler

Symfony's DomCrawler component lets you locate nodes in an HTML document using CSS selectors.

OUTPUT FORMATSHTMLJSONMarkdown

To target elements that share a class, pass a selector such as .mb-[33px] to the Crawler's filter() method. The result is a node list you can loop over and read text from. This guide shows the full PHP workflow, from fetching a page with Guzzle to printing each matched element's text.

The basic workflow

The pattern has four steps. First, create an HTTP client and retrieve the page body. Second, construct a Crawler from the HTML string. Third, call filter() with a CSS selector that includes the class name. Fourth, iterate the returned nodes and read their textContent. The protected code module code0001 contains the exact PHP sample, including the Guzzle client setup and the class selector. Guzzle is not bundled with DomCrawler, so install it separately before running the example.

Checklist before you run the selector

Use this quick check to avoid the common failure points:

  • Confirm the class name in the selector matches the HTML exactly, including case and special characters.
  • If the class contains brackets or other CSS-significant characters, escape them in the selector as the sample does.
  • Verify that Guzzle is installed and that the request returned a successful response body.
  • Remember that filter() returns a Crawler node list, not a single element; loop over it even when you expect one match.
  • Read textContent only after confirming the node list is not empty.

No match versus empty text

Two outcomes look similar but mean different things. If filter() returns zero nodes, the selector did not match any element in the parsed HTML; check the class spelling, the page source, and whether the content was loaded dynamically. If nodes are returned but textContent is blank, the element exists but contains no text, or its text lives in child nodes you have not read. Distinguishing these cases prevents you from rewriting a working selector when the real problem is empty markup.

Inputs and outputs at a glance

The Crawler constructor accepts the HTML string returned by the HTTP client. The filter() method accepts a CSS selector string that includes the class name. The returned value is a node list; each node exposes textContent for the element's text. The sample in code0001 uses a Guzzle GET request to load the page, then filters for the class mb-[33px] and prints each match.

Frequently asked questions

What selector syntax does filter() accept for classes?

Pass a CSS selector string that begins with a dot, such as .mb-[33px]. The dot tells the selector to match elements whose class attribute contains that name. Standard CSS selector rules apply, including escaping for special characters.

Do I need Guzzle to use DOM Crawler?

No. DomCrawler can parse any HTML string you already have. The sample uses Guzzle only to fetch the page over HTTP. If you obtain HTML another way, you can skip Guzzle and pass the string directly to the Crawler constructor.

How do I handle multiple elements with the same class?

filter() returns a node list. Use a foreach loop to visit each node and read its textContent. The sample in code0001 demonstrates this pattern.