Symfony CssSelector

The Symfony CssSelector component translates CSS selectors into equivalent XPath 1.0 expressions, so you can query HTML and XML documents using the familiar, concise CSS syntax instead of writing verbose XPath by hand. It is the piece that lets tools like Symfony’s DomCrawler and many web-scraping and testing libraries accept selectors such as “div.article > p” and run them against a DOM.

A port of Python’s cssselect library, the component parses a CSS selector into an abstract syntax tree and compiles it to XPath, supporting a broad range of selector features including combinators, attribute selectors, and pseudo-classes. It is dependency-light, well tested, and maintained as part of the Symfony ecosystem.

What You Get

• A CssSelectorConverter class that turns a CSS selector string into an XPath expression
• Support for combinators (descendant, child, adjacent, and general sibling)
• Attribute selectors, class and ID selectors, and a wide set of pseudo-classes
• An HTML mode and an XML mode for correct namespace and case handling
• A clean parser/translator architecture that can be extended with custom pseudo-class handlers
• A stable, well-tested component backed by the Symfony project

Common Use Cases

• Powering DOM querying in web scrapers and crawlers with CSS selectors
• Locating elements in functional and acceptance tests of web pages
• Extracting data from HTML or XML feeds using concise selector strings
• Building higher-level DOM traversal APIs on top of PHP’s DOMXPath

Under The Hood

Architecture - The component is split into a CSS layer and an XPath layer. A tokenizer and Parser build an AST of Node objects (ElementNode, ClassNode, AttributeNode, CombinedSelectorNode, and so on) from a selector string; a set of Translator classes then walk that AST and emit XPath, with HtmlExtension and XmlExtension supplying node/combination/pseudo-class handlers. The public CssSelectorConverter class wires these together and exposes a single toXPath() method.

Tech Stack - Pure PHP (92% of the codebase, with HTML test fixtures) targeting modern PHP versions, using PSR-4 autoloading under the Symfony\Component\CssSelector namespace. It has essentially no runtime dependencies beyond the PHP standard library and integrates with PHP’s native DOMXPath.

Code Quality - As a long-standing Symfony component it carries an extensive PHPUnit test suite, strict coding standards enforced via CI, and a decade-plus of maintenance across 88 contributors and 100+ tagged releases. Error handling surfaces parse problems through dedicated exception types (SyntaxErrorException, ExpressionErrorException).

API Design - The primary API is intentionally minimal: instantiate CssSelectorConverter (optionally in HTML or XML mode) and call toXPath() with a selector. Advanced users can register custom extensions, but the common path requires almost no boilerplate and reads naturally.