The BrowserKit Component

Creating a Client

The component only provides an abstract client and does not provide any backend ready to use for the HTTP layer. To create your own client, you must extend the AbstractBrowser class and implement the doRequest() method. This method accepts a request and should return a response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

namespace Acme;

use Symfony\Component\BrowserKit\AbstractBrowser;
use Symfony\Component\BrowserKit\Response;

class Client extends AbstractBrowser
{
    protected function doRequest($request): Response
    {
        // ... 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 look at the HttpBrowser provided by this component. For an implementation based on HttpKernelInterface, have a look at the HttpClientKernel provided by the HttpKernel component.

Making Requests

Use the request() method to make HTTP requests. The first two arguments are the HTTP method and the requested URL:

1
2
3
4

use Acme\Client;

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

The value returned by the request() method is an instance of the Crawler class, provided by the DomCrawler component, which allows accessing and traversing HTML elements programmatically.

The jsonRequest() method, which defines the same arguments as the request() method, is a shortcut to convert the request parameters into a JSON string and set the needed HTTP headers:

1
2
3
4
5

use Acme\Client;

$client = new Client();
// this encodes parameters as JSON and sets the required CONTENT_TYPE and HTTP_ACCEPT headers
$crawler = $client->jsonRequest('GET', '/', ['some_parameter' => 'some_value']);

The xmlHttpRequest() method, which defines the same arguments as the request() method, is a shortcut to make AJAX requests:

1
2
3
4
5

use Acme\Client;

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

Clicking Links

The AbstractBrowser is capable of simulating link clicks. Pass the text content of the link and the client will perform the needed HTTP GET request to simulate the link click:

1
2
3
4
5
6

use Acme\Client;

$client = new Client();
$client->request('GET', '/product/123');

$crawler = $client->clickLink('Go elsewhere...');

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

1
2
3
4

// ...
$crawler = $client->request('GET', '/product/123');
$link = $crawler->selectLink('Go elsewhere...')->link();
$client->click($link);

Submitting Forms

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

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', [
    'login' => 'my_user',
    '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 that provides access to the form properties (e.g. $form->getUri(), $form->getValues(), $form->getFields()), use this other method:

1
2
3
4
5
6
7
8
9

// ...

// 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);

Custom Header Handling

The optional HTTP headers passed to the request() method follow the FastCGI request format (uppercase, underscores instead of dashes and prefixed with HTTP_). Before saving those headers to the request, they are lower-cased, with HTTP_ stripped, and underscores converted into dashes.

If you're making a request to an application that has special rules about header capitalization or punctuation, override the getHeaders() method, which must return an associative array of headers:

1
2
3
4
5
6
7
8
9

protected function getHeaders(Request $request): array
{
    $headers = parent::getHeaders($request);
    if (isset($request->getServer()['api_key'])) {
        $headers['api_key'] = $request->getServer()['api_key'];
    }

    return $headers;
}

Retrieving Cookies

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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();

Looping Through Cookies

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

use Acme\Client;

// Make a request
$client = new Client();
$crawler = $client->request('GET', '/');

// Get the cookie Jar
$cookieJar = $client->getCookieJar();

// 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) {
    // ...
}

Setting Cookies

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

1
2
3
4
5
6
7
8
9
10

use Acme\Client;

// create cookies and add to cookie jar
$cookie = new Cookie('flavor', 'chocolate', strtotime('+1 day'));
$cookieJar = new CookieJar();
$cookieJar->set($cookie);

// create a client and set the cookies
$client = new Client([], null, $cookieJar);
// ...

Sending Cookies

Requests can include cookies. To do so, use the serverParameters argument of the request() method to set the Cookie header value:

1
2
3
4
5
6

$client->request('GET', '/', [], [], [
    'HTTP_COOKIE' => new Cookie('flavor', 'chocolate', strtotime('+1 day')),

    // you can also pass the cookie contents as a string
    'HTTP_COOKIE' => 'flavor=chocolate; expires=Sat, 11 Feb 2023 12:18:13 GMT; Max-Age=86400; path=/'
]);

Dealing with HTTP responses

When using the BrowserKit component, you may need to deal with responses of the requests you made. To do so, call the getResponse() method of the HttpBrowser object. This method returns the last response the browser received:

1
2
3
4

$browser = new HttpBrowser(HttpClient::create());

$browser->request('GET', 'https://foo.com');
$response = $browser->getResponse();

If you're making requests that result in a JSON response, you may use the toArray() method to turn the JSON document into a PHP array without having to call json_decode() explicitly:

1
2
3
4
5

$browser = new HttpBrowser(HttpClient::create());

$browser->request('GET', 'https://api.foo.com');
$response = $browser->getResponse()->toArray();
// $response is a PHP array of the decoded JSON contents