Создание клиента

Компонент предоставляет только абстрактного клиента, и не предоставляет готового к использованию бэк-энда для уровня HTTP. Чтобы создать вашего собственного клиента, вам нужно расширить класс AbstractBrowser и реализовать метод doRequest(). Этот метод принимает запрос и должен вернуть ответ:

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)
    {
        // ... преобразовать запрос в ответ

        return new Response($content, $status, $headers);
    }
}

Для простой реализации браузера, основанного на слое HTTP, посмотрите на HttpBrowser, предоставленный этим компонентом . Для реализации, основанной на HttpKernelInterface, посмотрите на HttpClientKernel, предоставленный компонентом HttpKernel.

Как делать запросы

Используйте метод request(), чтобы делать HTTP запросы. Первые два аргумента - HTTP метод и запрошенный URL:

1
2
3
4

use Acme\Client;

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

Значение, возвращённое методом request() - это экземпляр класса Crawler, предоставленный DomCrawler component, который разрешает программный доступ и траверсирование HTML элементов.

Метод jsonRequest(), который определяет те же аргументы, что и метод request(), является ярлыком для преобразования параметров запроса в JSON-строку и установки необходимых HTTP-заголовков:

1
2
3
4
5

use Acme\Client;

$client = new Client();
// это зашифровывает параметры как JSON, и устанавливает необходимые заголовки CONTENT_TYPE и HTTP_ACCEPT
$crawler = $client->jsonRequest('GET', '/', ['some_parameter' => 'some_value']);

Метод xmlHttpRequest(), который определяет те же аргументы, что и метод request(), является ярлыков для создания AJAX-запросов:

1
2
3
4
5

use Acme\Client;

$client = new Client();
// необходимый заголовок HTTP_X_REQUESTED_WITH добавляется автоматически
$crawler = $client->xmlHttpRequest('GET', '/');

Нажатие ссылок

AbstractBrowser способен симулировать нажатие на ссылки. Передайте содержимое текста ссылки, а клиент выполнит необходимый запрос HTTP GET, чтобы симулировать нажатие на ссылку:

1
2
3
4
5
6

use Acme\Client;

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

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

Если вам нужен объект Link, который предоставляет доступ к свойствам ссылки (например, $link->getMethod(), $link->getUri()), используйте этот другой метод:

1
2
3
4

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

Отправка форм

AbstractBrowser также способен отправлять формы. Для начала, выберите форму, используя любую ее кнопку, а затем переопределите любое из ее свойств (метод, значение поля и др.), до ее отправки:

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

// найти форму с кнопкой 'Log in' и отправить ее
// 'Log in' может быть текстовым содержанием, id, значением или именем <button> или <input type="submit">
$client->submitForm('Log in');

// второй необязательный аргумент позволяет вам переопределять значения полей формы по умолчанию
$client->submitForm('Log in', [
    'login' => 'my_user',
    'password' => 'my_pass',
    // чтобы загрузить файл, значение должно быть абсолютным путем файла
    'file' => __FILE__,
]);

// вы можете также переопределить другие опции формы
$client->submitForm(
    'Log in',
    ['login' => 'my_user', 'password' => 'my_pass'],
    // переопределить HTTP-метод формы по умолчанию
    'PUT',
    // переопределить некоторые параметры $_SERVER (например, HTTP-заголовки)
    ['HTTP_ACCEPT_LANGUAGE' => 'es']
);

Если вам нужен объект Form, который предоставляет доступ к свойствам формы (например, $form->getUri(), $form->getValues(), $form->getFields()), используйте этот другой метод:

1
2
3
4
5
6
7
8
9

// ...

// выбрать форму и заполнить какие-то значения
$form = $crawler->selectButton('Log in')->form();
$form['login'] = 'symfonyfan';
$form['password'] = 'anypass';

// отправить эту форму
$crawler = $client->submit($form);

Обработка пользовательских заголовков

Необязательные HTTP-заголовки, переданные методу request(), следуют формату запросу FastCGI (верхний регистр, нижние подчеркивания вместо дефисов и префикс HTTP_). До сохранения этих заголовков в запрос, они переводятся в нижний регистр, HTTP_ убирается, а нижние подчеркивания преобразуются в дефисы.

Если вы делаете запрос к приложению, которое имеет специальные правила о регистре или пунктуации заголовков, переопределите метод getHeaders(), который должен возвращать ассоциированный массив заголовков:

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;
}

Извлечение куки

Реализация AbstractBrowser отображает cookie (если они есть) через класс CookieJar, который позволяет вам хранить и извлекать любой cookie во время выполнения запросов с клиентом:

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;

// Сделать запрос
$client = new Client();
$crawler = $client->request('GET', '/');

// Получить cookie Jar
$cookieJar = $client->getCookieJar();

// Получить куки по имени
$cookie = $cookieJar->get('name_of_the_cookie');

// Получить данные куки
$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();

Закольцовывание через куки

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

// Получить cookie Jar
$cookieJar = $client->getCookieJar();

// Получить массив со всеми куки
$cookies = $cookieJar->all();
foreach ($cookies as $cookie) {
    // ...
}

// Получить все значения
$values = $cookieJar->allValues('http://symfony.com');
foreach ($values as $value) {
    // ...
}

// Получить все сырые значения
$rawValues = $cookieJar->allRawValues('http://symfony.com');
foreach ($rawValues as $rawValue) {
    // ...
}

Установка Куки

Вы также можете создавать куки и добавлять их в cookie jar, которая может быть внедрена в конструктор клиента:

1
2
3
4
5
6
7
8
9
10

use Acme\Client;

// создайте куки и добавьте в cookie jar
$cookie = new Cookie('flavor', 'chocolate', strtotime('+1 day'));
$cookieJar = new CookieJar();
$cookieJar->set($cookie);

// создайте клиента и установите куки
$client = new Client(array(), null, $cookieJar);
// ...

Работа с HTTP-ответами

При использовании компонента BrowserKit, вам может понадобиться работать с ответами запросов, которые вы сделали. Чтобы сделать это, вызовите метод getResponse() объекта HttpBrowser. Этот метод возвращает последний ответ, полученный браузером:

1
2
3
4

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

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

Если вы делаете запросы, которые приводят к JSON-ответу, вы можете использовать метод toArray(), чтобы превратить документ JSON в массив PHP, без необходимости ясного вызова json_decode():

1
2
3
4
5

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

$browser->request('GET', 'https://api.foo.com');
$response = $browser->getResponse()->toArray();
// $response - это PHP-массив расшифрованного содержания JSON