symfony/browser-kit

The Symfony BrowserKit component simulates the behavior of a web browser at the HTTP/HTML level: it tracks a browsing history, manages a cookie jar across requests, follows redirects, and lets calling code click on Crawler-located links and submit forms without a real browser or JavaScript engine. It’s most commonly used as the driving engine behind Symfony’s functional test client, but ships as a standalone component usable in any PHP project.

BrowserKit itself is transport-agnostic — AbstractBrowser defines the browsing simulation logic (history, cookies, form/link interaction) while leaving the actual HTTP request execution to a subclass. HttpBrowser is the concrete implementation that performs real HTTP requests via Symfony’s HttpClient component, but applications can also plug BrowserKit into a test double that dispatches directly into an in-process kernel (as Symfony’s functional testing does) for fast, no-network integration tests.

What You Get

• AbstractBrowser (692 lines) implementing history tracking, cookie jar management, redirect following, and form/link interaction over an abstract request cycle
• HttpBrowser, a concrete implementation that performs real HTTP requests via Symfony’s HttpClient component
• CookieJar and Cookie classes for RFC-compliant cookie storage and matching across requests
• History for back/forward navigation tracking across a browsing session
• Integration with DomCrawler so returned pages can be queried and their forms/links interacted with using CSS selectors or XPath

Common Use Cases

• Driving Symfony’s functional test client (KernelBrowser) to test controllers end-to-end without a real HTTP server
• Writing browser-simulation scripts that log in, navigate, and submit forms against a real website via HttpBrowser
• Building lightweight web scrapers that need cookie/session persistence across multiple requests
• Testing multi-step form flows (wizards, checkout processes) by simulating sequential form submissions

Under The Hood

Architecture — AbstractBrowser is the core state machine: it holds a CookieJar, a History, and the current Crawler-wrapped response, and exposes methods like request(), click(), submit(), and back()/forward() that operate against that state. It’s deliberately abstract over the actual request mechanism — subclasses implement doRequest() to perform the real work, which is what lets Symfony’s test kernel client and the standalone HttpBrowser share identical browsing-simulation logic while differing only in how a request is dispatched (in-process kernel call vs. real network I/O via HttpClient). Cookie/CookieJar implement cookie expiration, domain/path matching, and persistence rules close to what a real browser does, so multi-request flows behave correctly across redirects and subdomains. Tech Stack — PHP 8.4.1+, PSR-4 autoloaded flat under Symfony\Component\BrowserKit, with a single hard dependency on symfony/dom-crawler for parsing/querying returned HTML; HttpBrowser’s real-request capability pulls in symfony/http-client as a dev/optional dependency. Like other Symfony components, it’s split from the monorepo at github.com/symfony/symfony into this read-only mirror. Code Quality — Compact and mature: the core AbstractBrowser class (692 lines) has been stable for years as the shared foundation for both Symfony’s own functional testing and standalone browser simulation, with a dedicated Tests/ directory (excluded from the autoload classmap) covering cookie handling, form submission, and history navigation edge cases. API Design — The API mirrors how a person uses a browser: request() to load a page, click($crawler->selectLink('...')->link()) to follow a link, submit($form) to post a form — keeping test code and scraping scripts readable and close to the user-facing interaction being simulated.