The BrowserKit Component ¶

The BrowserKit component simulates the behavior of a web browser, allowing you to make requests, click on links and submit forms programmatically.
BrowserKit コンポーネントは、Web ブラウザーの動作をシミュレートし、要求を作成し、リンクをクリックし、フォームをプログラムで送信できるようにします。

Installation ¶

    
                        $ composer require symfony/browser-kit

Note

ノート

If you install this component outside of a Symfony application, you must require the vendor/autoload.php file in your code to enable the class autoloading mechanism provided by Composer. Read this article for more details.

このコンポーネントを Symfony アプリケーションの外部にインストールする場合は、Composer が提供するクラス自動ロードメカニズムを有効にするために、コード内に vendor/autoload.php ファイルを必要とする必要があります。詳細については、この記事をお読みください。

Basic Usage ¶

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:

このコンポーネントは抽象クライアントのみを提供し、HTTP レイヤーですぐに使用できるバックエンドは提供しません。独自のクライアントを作成するには、AbstractBrowser クラスを拡張し、doRequest() メソッドを実装する必要があります。このメソッドはリクエストを受け入れ、レスポンスを返す必要があります。

    
                        namespace Acme;

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

class Client extends AbstractBrowser
{
    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 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.

HTTP レイヤーに基づくブラウザーの簡単な実装については、このコンポーネントによって提供される HttpBrowser を参照してください。 HttpKernelInterface に基づく実装については、HttpKernel コンポーネントによって提供される HttpClientKernel を参照してください。

Making Requests ¶

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

request() メソッドを使用して HTTP リクエストを作成します。最初の 2 つの引数は、HTTP メソッドと requestedURL です。

    
                        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.

request() メソッドによって返される値は、DomCrawler コンポーネントによって提供される Crawler クラスのインスタンスであり、プログラムによって HTML 要素にアクセスして走査することができます。

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:

request() メソッドと同じ引数を定義する jsonRequest() メソッドは、リクエストパラメータを JSON 文字列に変換し、必要な HTTP ヘッダーを設定するためのショートカットです。

    
                        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:

request() メソッドと同じ引数を定義する xmlHttpRequest() メソッドは、AJAX リクエストを作成するためのショートカットです。

    
                        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:

AbstractBrowser は、リンクのクリックをシミュレートできます。リンクのテキストコンテンツを渡すと、クライアントは必要な HTTP GET リクエストを実行して、リンクのクリックをシミュレートします。

    
                        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:

リンクプロパティへのアクセスを提供する Link オブジェクトが必要な場合 (例: $link->getMethod()、$link->getUri())、次の別のメソッドを使用します。

    
                        // ...
$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:

AbstractBrowser は、フォームを送信することもできます。まず、いずれかのボタンを使用してフォームを選択し、送信する前にそのプロパティ (メソッド、フィールド値など) をオーバーライドします。

    
        
                
                
                        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:

フォームプロパティ (例: $form->getUri()、$form->getValues()、$form->getFields()) へのアクセスを提供する Form オブジェクトが必要な場合は、次の別のメソッドを使用します。

    
                        // ...

// 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.

request() メソッドに渡されるオプションの HTTP ヘッダーは、FastCGIrequest 形式に従います (大文字、ダッシュの代わりにアンダースコアを使用し、HTTP_ のプレフィックスを付けます)。これらのヘッダーをリクエストに保存する前に、HTTP_stripped で小文字にし、アンダースコアをダッシュに変換します。 .

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:

ヘッダーの大文字化または句読点に関する特別なルールを持つアプリケーションにリクエストを送信する場合は、ヘッダーの連想配列を返す必要がある getHeaders() メソッドをオーバーライドします。

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

Cookies ¶

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:

AbstractBrowser 実装は、CookieJar を介して Cookie (存在する場合) を公開します。これにより、クライアントでリクエストを行う際に、任意の Cookie を保存および取得できます。

    
        
                
                
                        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

ノート

These methods only return cookies that have not expired.

これらのメソッドは、有効期限が切れていない Cookie のみを返します。

Looping Through Cookies ¶

    
        
                
                
                        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:

また、Cookie を作成して、クライアントコンストラクターに挿入できる Cookie jar に追加することもできます。

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

History ¶

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

クライアントはすべてのリクエストを保存し、履歴を前後に移動できるようにします。

    
                        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 restart() method. This will also delete all the cookies:

restart() メソッドを使用して、クライアントの履歴を削除できます。これにより、すべての Cookie も削除されます。

    
                        use Acme\Client;

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

// reset the client (history and cookies are cleared too)
$client->restart();

Making External HTTP Requests ¶

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

これまで、この記事のすべての例は、独自のアプリケーションに対して内部要求を行っていることを前提としています。ただし、外部の Web サイトやアプリケーションに対して HTTP 要求を行う場合は、まったく同じ例を実行できます。

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

まず、HttpClient コンポーネントをインストールして構成します。次に、HttpBrowser を使用して、外部 HTTP 要求を行うクライアントを作成します。

    
                        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 a dedicated web crawler or scraper such as Goutte:

この記事に示されている方法のいずれかを使用して、情報を抽出したり、リンクをクリックしたり、フォームを送信したりできます。これは、Goutte などの専用の Web クローラーまたはスクレーパーを使用する必要がなくなったことを意味します。

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

Tip

ヒント

You can also use HTTP client options like ciphers, auth_basic and query. They have to be passed as the default options argument to the client which is used by the HTTP browser.

ciphers、auth_basic、query などの HTTP クライアントオプションを使用することもできます。これらは、HTTP ブラウザーで使用されるクライアントにデフォルトのオプション引数として渡す必要があります。

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:

BrowserKit コンポーネントを使用する場合、作成したリクエストの応答を処理する必要がある場合があります。これを行うには、HttpBrowser オブジェクトの getResponse() メソッドを呼び出します。このメソッドは、ブラウザーが最後に受信した応答を返します。

    
                        $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:

JSON レスポンスを返すリクエストを作成している場合、明示的に json_decode() を呼び出さなくても、toArray() メソッドを使用して JSON ドキュメントを PHP 配列に変換できます。

    
                        $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

6.1

The toArray() method was introduced in Symfony 6.1.

toArray() メソッドは Symfony 6.1 で導入されました。

Learn more ¶

Testing
テスト
The CssSelector Component
CssSelector コンポーネント
The DomCrawler Component
DomCrawler コンポーネント