The BrowserKit Component

In Symfony versions prior to 4.3, the BrowserKit component could only makeinternal requests to your application. Starting from Symfony 4.3, thiscomponent can also make HTTP requests to any public sitewhen using it in combination with the .

Note

If you install this component outside of a Symfony application, you mustrequire the file in your code to enable the classautoloading mechanism provided by Composer. Readthis article for more details.

Basic Usage

This article explains how to use the BrowserKit features as an independentcomponent in any PHP application. Read the Symfony Functional Testsarticle to learn about how to use it in Symfony applications.

The component only provides an abstract client and does not provide any backendready to use for the HTTP layer.

To create your own client, you must extend the abstract Client class andimplement the method.This method accepts a request and should return a response:

namespace Acme;
 
use Symfony\Component\BrowserKit\Client as BaseClient;
use Symfony\Component\BrowserKit\Response;
 
class Client extends BaseClient
{
    protected function doRequest($request)
    {
        // ... convert request into a response
 
        return new Response($content, $status, $headers);
    }
}

For a simple implementation of a browser based on the HTTP layer, have a lookat Goutte. For an implementation based on HttpKernelInterface, havea look at the provided bythe HttpKernel component.

Making Requests

Use the request() method tomake HTTP requests. The first two arguments are the HTTP method and the requestedURL:

use Acme\Client;
 
$client = new Client();
$crawler = $client->request('GET', '/');

The value returned by the request() method is an instance of the class, provided by the, which allows accessingand traversing HTML elements programmatically.

use Acme\Client;
 
$client = new Client();
// the required HTTP_X_REQUESTED_WITH header is added automatically
$crawler = $client->xmlHttpRequest('GET', '/');

The Client object is capable of simulating link clicks. Pass the textcontent of the link and the client will perform the needed HTTP GET request tosimulate the link click:

use Acme\Client;
 
$client = new Client();
$client->request('GET', '/product/123');
 
$crawler = $client->clickLink('Go elsewhere...');

If you need the Link object thatprovides access to the link properties (e.g. $link->getMethod(),$link->getUri()), use this other method:

Submitting Forms

The object is also capable of submitting forms. First, select theform using any of its buttons and then override any of its properties (method,field values, etc.) before submitting it:

use Acme\Client;
 
$client = new Client();
$crawler = $client->request('GET', 'https://github.com/login');
 
// find the form with the 'Log in' button and submit it
// 'Log in' can be the text content, id, value or name of a <button> or <input type="submit">
$client->submitForm('Log in');
 
// the second optional argument lets you override the default form field values
$client->submitForm('Log in', [
    'password' => 'my_pass',
    // to upload a file, the value must be the absolute file path
    'file' => __FILE__,
]);
 
// you can override other form options too
$client->submitForm(
    'Log in',
    ['login' => 'my_user', 'password' => 'my_pass'],
    // override the default form HTTP method
    'PUT',
    // override some $_SERVER parameters (e.g. HTTP headers)
    ['HTTP_ACCEPT_LANGUAGE' => 'es']
);

If you need the Form object thatprovides access to the form properties (e.g. $form->getUri(),$form->getValues(), $form->getFields()), use this other method:

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

The Client implementation exposes cookies (if any) through a, which allows you to store andretrieve any cookie while making requests with the client:

use Acme\Client;
 
// Make a request
$client = new Client();
$crawler = $client->request('GET', '/');
 
// Get the cookie Jar
$cookieJar = $client->getCookieJar();
 
// Get a cookie by name
$cookie = $cookieJar->get('name_of_the_cookie');
 
// Get cookie data
$name       = $cookie->getName();
$value      = $cookie->getValue();
$rawValue   = $cookie->getRawValue();
$isSecure   = $cookie->isSecure();
$isHttpOnly = $cookie->isHttpOnly();
$isExpired  = $cookie->isExpired();
$expires    = $cookie->getExpiresTime();
$path       = $cookie->getPath();
$domain     = $cookie->getDomain();
$sameSite   = $cookie->getSameSite();

Note

Looping Through Cookies

use Acme\Client;
 
// Make a request
$client = new Client();
$crawler = $client->request('GET', '/');
 
// Get the cookie Jar
 
// Get array with all cookies
$cookies = $cookieJar->all();
foreach ($cookies as $cookie) {
    // ...
}
 
// Get all values
$values = $cookieJar->allValues('http://symfony.com');
foreach ($values as $value) {
    // ...
}
 
// Get all raw values
$rawValues = $cookieJar->allRawValues('http://symfony.com');
foreach ($rawValues as $rawValue) {
    // ...
}

You can also create cookies and add them to a cookie jar that can be injectedinto the client constructor:

History

The client stores all your requests allowing you to go back and forward in yourhistory:

use Acme\Client;
 
$client = new Client();
$client->request('GET', '/');
 
// select and click on a link
$link = $crawler->selectLink('Documentation')->link();
$client->click($link);
 
// go back to home page
$crawler = $client->back();
 
// go forward to documentation page
$crawler = $client->forward();

You can delete the client's history with the method. This willalso delete all the cookies:

use Acme\Client;
 
$client = new Client();
$client->request('GET', '/');
 
// reset the client (history and cookies are cleared too)
$client->restart();

So far, all the examples in this article have assumed that you are makinginternal requests to your own application. However, you can run the exact sameexamples when making HTTP requests to external web sites and applications.

First, install and configure the HttpClient component.Then, use the to createthe client that will make the external HTTP requests:

use Symfony\Component\BrowserKit\HttpBrowser;
use Symfony\Component\HttpClient\HttpClient;
 
$browser = new HttpBrowser(HttpClient::create());

You can now use any of the methods shown in this article to extract information,click links, submit forms, etc. This means that you no longer need to use adedicated web crawler or scraper such as Goutte:

$browser = new HttpBrowser(HttpClient::create());
 
$browser->request('GET', 'https://github.com');
$browser->clickLink('Sign in');
$browser->submitForm('Sign in', ['login' => '...', 'password' => '...']);
$openPullRequests = trim($browser->clickLink('Pull requests')->filter(
    '.table-list-header-toggle a:nth-child(1)'
)->text());

Learn more

• Testing