diff --git a/components/browser_kit/index.rst b/components/browser_kit/index.rst new file mode 100644 index 00000000000..692b45d63f3 --- /dev/null +++ b/components/browser_kit/index.rst @@ -0,0 +1,7 @@ +BrowserKit +========== + +.. toctree:: + :maxdepth: 2 + + introduction diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst new file mode 100644 index 00000000000..b07009ff15a --- /dev/null +++ b/components/browser_kit/introduction.rst @@ -0,0 +1,227 @@ +.. index:: + single: BrowserKit + single: Components; BrowserKit + +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. + +Installation +------------ + +You can install the component in two different ways: + +* :doc:`Install it via Composer ` + (``symfony/browser-kit`` on `Packagist`_); +* Use the official Git repository (https://github.com/symfony/BrowserKit). + +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 abstract ``Client`` class and +implement the :method:`Symfony\\Component\\BrowserKit\\Client::doRequest` 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 an HTTP layer, have a look +at `Goutte`_. For an implementation based on ``HttpKernelInterface``, have a +look at the Client provided by the :doc:`HttpKernel component `. + +Making Requests +~~~~~~~~~~~~~~~ + +Use the :method:`Symfony\\Component\\BrowserKit\\Client::request` method to make +any HTTP request. The first two arguments are for the HTTP method and the +requested URL:: + + use Acme\Client; + + $client = new Client(); + $crawler = $client->request('GET', 'http://symfony.com'); + +The value returned by the ``request()`` method is an instance of the +:class:`Symfony\\Component\\DomCrawler\\Crawler` class, provided by the +:doc:`DomCrawler component `, and which allows +accessing and traversing HTML elements programmatically. + +Clicking Links +~~~~~~~~~~~~~~ + +The ``Crawler`` object is capable of simulating link clicks. First, pass the +text content of the link to the ``selectLink()`` method, which returns you a +``Link`` object. Then, pass this object to the ``click()`` method, which makes +the needed HTTP GET request to simulate the link click:: + + use Acme\Client; + + $client = new Client(); + $crawler = $client->request('GET', 'http://symfony.com'); + $link = $crawler->selectLink('Go elsewhere...')->link(); + $client->click($link); + +Submitting Forms +~~~~~~~~~~~~~~~~ + +The ``Crawler`` object is also capable of selecting forms. First, select any of +the form's buttons with the ``selectButton()`` method. Then, use the ``form()`` +method to select the form which the button belongs to. + +After selecting the form, fill in its data and send it using the ``submit()`` +method (which makes the needed HTTP POST request to submit the form contents):: + + 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 +------- + +Retrieving Cookies +~~~~~~~~~~~~~~~~~~ + +The ``Crawler`` object exposes cookies (if any) through a +:class:`Symfony\\Component\\BrowserKit\\CookieJar`, which allows you to store and +retrieve any cookie while making requests with the client:: + + 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 + $cookie = $cookieJar->get('name_of_the_cookie'); + + // Get cookie data + $name = $cookie->getName(); + $value = $cookie->getValue(); + $raw = $cookie->getRawValue(); + $secure = $cookie->isSecure(); + $isHttpOnly = $cookie->isHttpOnly(); + $isExpired = $cookie->isExpired(); + $expires = $cookie->getExpiresTime(); + $path = $cookie->getPath(); + $domain = $cookie->getDomain(); + +.. note:: + + These methods only return cookies that have not expired. + +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) { + // ... + } + +Setting Cookies +~~~~~~~~~~~~~~~ + +You can also create cookies and add them to a cookie jar that can be injected +into the client constructor:: + + use Acme\Client; + + // create cookies and add to cookie jar + $cookieJar = new Cookie('flavor', 'chocolate', strtotime('+1 day')); + + // 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:: + + use Acme\Client; + + // make a real request to an external site + $client = new Client(); + $client->request('GET', 'http://symfony.com'); + + // 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:: + + use Acme\Client; + + // make a real request to an external site + $client = new Client(); + $client->request('GET', 'http://symfony.com'); + + // delete history + $client->restart(); + +.. _`Packagist`: https://packagist.org/packages/symfony/browser-kit +.. _`Goutte`: https://github.com/fabpot/Goutte diff --git a/components/index.rst b/components/index.rst index 739b9e84f9c..780b33b2c9e 100644 --- a/components/index.rst +++ b/components/index.rst @@ -5,6 +5,7 @@ The Components :hidden: using_components + browser_kit/index class_loader/index config/index console/index diff --git a/components/map.rst.inc b/components/map.rst.inc index 38bf2e07748..b69b347373f 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -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`