Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add browserkit component documentation #4312

Closed
wants to merge 15 commits into from
7 changes: 7 additions & 0 deletions components/browser_kit/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
BrowserKit
==========

.. toctree::
:maxdepth: 2

introduction
238 changes: 238 additions & 0 deletions components/browser_kit/introduction.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,238 @@
.. index::
single: BrowserKit
single: Components; BrowserKit

The BrowserKit Component
========================

The BrowserKit component simulates the behavior of a web browser.

The BrowserKit component allows you to make web requests, click on links and submit forms.

Installation
------------

You can install the component in two different ways:

* :doc:`Install it via Composer </components/using_components>` (``symfony/browser-kit`` on `Packagist`_);
* Use the official Git repository (https://github.com/symfony/BrowserKit).

Basic Usage
-----------

.. note::

The component only provides an abstract client and does not provide any "default" backend for the HTTP layer.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There should be a blank line between the directive and its contents.


Creating a Client
-----------------

To create your own client you must extend the abstract client class and implement the doRequest method.
This method accepts a requests and should return a response.

.. code-block:: php

namespace ACME;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should be AppBundle

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, we are in the components section here. It should not use framework things like bundles


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 an HTTP layer, have a look at Goutte_.

For an implementation based on ``HttpKernelInterface``, have a look at the Client provided by the :doc:`/components/http_kernel/introduction`.


Making Requests
~~~~~~~~~~~~~~~

To make a request you use the client's request_ method.
The first two arguments are for the HTTP method and the request URL.
The request method will return a crawler object.

.. code-block:: php

use ACME\Client;

$client = new Client();
$crawler = $client->request('GET', 'http://symfony.com');

Clicking Links
~~~~~~~~~~~~~~

Select a link with the crawler and pass it to the click_ method to click on the link.

.. code-block:: php

use ACME\Client;

$client = new Client();
$crawler = $client->request('GET', 'http://symfony.com');
$link = $crawler->selectLink('Go elsewhere...')->link();
$client->click($link);

Submiting Forms
~~~~~~~~~~~~~~~

You can submit forms with the submit method which takes a form object.
You can get the form object by using the crawler to select the button and running the form method.

.. code-block:: php

use ACME\Client;

// make a real request to an external site
$client = new Client();
$crawler = $client->request('GET', 'https://github.com/login');

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

Cookies
-------

Retreiving Cookies
~~~~~~~~~~~~~~~~~~

The Crawler has a cookieJar which is a container for storing and recieving cookies.

.. code-block:: php

use ACME\Client;

// Make a request
$client = new Client();
$crawler = $client->request('GET', 'http://symfony.com');

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

// Get a cookie by name
$flavor = $cookieJar->get('flavor');

// Get cookie data
$name = $flavor->getName();
$value = $flavor->getValue();
$raw = $flavor->getRawValue();
$secure = $flavor->isSecure();
$isHttpOnly = $flavor->isHttpOnly();
$isExpired = $flavor->isExpired();
$expires = $flavor->getExpiresTime();
$path = $flavor->getPath();
$domain = $flavor->getDomain();

Looping Through Cookies
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: php

use ACME\Client;

// Make a request
$client = new Client();
$crawler = $client->request('GET', 'http://symfony.com');

// Get the cookie Jar
$cookieJar = $crawler->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)
{
// ...
}

.. note::
These cookie jar methods only return cookies that have not expired.

Setting Cookies
~~~~~~~~~~~~~~~

You can define create cookies and add them to a cookie jar that can be injected it into the client constructor.

.. code-block:: php

use ACME\Client;

// create cookies and add to cookie jar
$expires = new \DateTime();
$expires->add(new \DateInterval('P1D'));
$cookie = new Cookie(
'flavor',
'chocolate chip',
$now->getTimestamp()
);

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

History
-------

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

.. code-block:: php

use ACME\Client;

// make a real request to an external site
$client = new Client();
$home_crawler = $client->request('GET', 'http://symfony.com');

// select and click on a link
$doc_link = $crawler->selectLink('Documentation')->link();
$doc_crawler = $client->click($link);

// go back to home page
$home_crawler = $client->back();

// go forward to documentation page
$doc_crawler = $client->forward();

You can restart the client's history with the restart method. This will also clear out the CookieJar.

.. code-block:: php

use ACME\Client;

// make a real request to an external site
$client = new Client();
$home_crawler = $client->request('GET', 'http://symfony.com');

// restart history
$client->restart();


.. _Packagist: https://packagist.org/packages/symfony/browser-kit
.. _Goutte: https://github.com/fabpot/Goutte
.. _request: http://api.symfony.com/2.3/Symfony/Component/BrowserKit/Client.html#method_request
.. _click: http://api.symfony.com/2.3/Symfony/Component/BrowserKit/Client.html#method_click
1 change: 1 addition & 0 deletions components/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ The Components
:hidden:

using_components
browser_kit/index
class_loader/index
config/index
console/index
Expand Down
4 changes: 4 additions & 0 deletions components/map.rst.inc
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
* :doc:`/components/using_components`

* :doc:`/components/browser_kit/index`

* :doc:`/components/browser_kit/introduction`

* :doc:`/components/class_loader/index`

* :doc:`/components/class_loader/introduction`
Expand Down