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..e2a8f5ecffe --- /dev/null +++ b/components/browser_kit/introduction.rst @@ -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 ` (``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. + +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; + + 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 \ No newline at end of file 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 572f19352d8..f25975d6853 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`