From 93d72584480e99a2a56d1cc7265e24e235422a06 Mon Sep 17 00:00:00 2001 From: yamiko Date: Thu, 9 Oct 2014 11:17:59 -0700 Subject: [PATCH 01/21] added introduction --- components/browser_kit/index.rst | 7 +++++++ components/browser_kit/introduction.rst | 18 ++++++++++++++++++ 2 files changed, 25 insertions(+) create mode 100644 components/browser_kit/index.rst create mode 100644 components/browser_kit/introduction.rst diff --git a/components/browser_kit/index.rst b/components/browser_kit/index.rst new file mode 100644 index 00000000000..624a0aeb12f --- /dev/null +++ b/components/browser_kit/index.rst @@ -0,0 +1,7 @@ +Browser Kit +==== + +.. toctree:: + :maxdepth: 2 + + introduction diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst new file mode 100644 index 00000000000..495c979108a --- /dev/null +++ b/components/browser_kit/introduction.rst @@ -0,0 +1,18 @@ +.. index:: + single: Yaml + single: Components; Yaml + +The Browser Kit Component +========================= + + The Browser Kit component simulates the behavior of a web browser. + +The Browser Kit component allows you to make web request, click on links and submit forms. + +Installation +------------ + +You can install the component in 2 different ways: + +* :doc:`Install it via Composer ` (``symfony/browser-kit`` on `Packagist`_); +* Use the official Git repository (https://github.com/symfony/BrowserKit). From 645d50dcea9c4c05adaeb5d300bfb68e129498ec Mon Sep 17 00:00:00 2001 From: yamiko Date: Fri, 10 Oct 2014 09:54:20 -0700 Subject: [PATCH 02/21] fixed a few mistakes --- components/browser_kit/index.rst | 4 ++-- components/browser_kit/introduction.rst | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/components/browser_kit/index.rst b/components/browser_kit/index.rst index 624a0aeb12f..692b45d63f3 100644 --- a/components/browser_kit/index.rst +++ b/components/browser_kit/index.rst @@ -1,5 +1,5 @@ -Browser Kit -==== +BrowserKit +========== .. toctree:: :maxdepth: 2 diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index 495c979108a..32dc1db9750 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -1,13 +1,13 @@ .. index:: - single: Yaml - single: Components; Yaml + single: BrowserKit + single: Components; BrowserKit -The Browser Kit Component +The BrowserKit Component ========================= - The Browser Kit component simulates the behavior of a web browser. + The BrowserKit component simulates the behavior of a web browser. -The Browser Kit component allows you to make web request, click on links and submit forms. +The BrowserKit component allows you to make web request, click on links and submit forms. Installation ------------ @@ -15,4 +15,4 @@ Installation You can install the component in 2 different ways: * :doc:`Install it via Composer ` (``symfony/browser-kit`` on `Packagist`_); -* Use the official Git repository (https://github.com/symfony/BrowserKit). +* Use the official Git repository (https://github.com/symfony/BrowserKit). \ No newline at end of file From 9c007e99ebafde72b267653fdc2ac6e90f3668b9 Mon Sep 17 00:00:00 2001 From: yamiko Date: Fri, 10 Oct 2014 11:31:38 -0700 Subject: [PATCH 03/21] syntax fix --- components/browser_kit/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index 32dc1db9750..b3f221c3ae8 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -3,7 +3,7 @@ single: Components; BrowserKit The BrowserKit Component -========================= +======================== The BrowserKit component simulates the behavior of a web browser. From 1e5ca139886e469f8c7cc564061cba5b11193498 Mon Sep 17 00:00:00 2001 From: yamiko Date: Fri, 10 Oct 2014 11:48:04 -0700 Subject: [PATCH 04/21] added in sections that I apln to fill out --- components/browser_kit/introduction.rst | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index b3f221c3ae8..a5326bfb71c 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -15,4 +15,22 @@ Installation You can install the component in 2 different ways: * :doc:`Install it via Composer ` (``symfony/browser-kit`` on `Packagist`_); -* Use the official Git repository (https://github.com/symfony/BrowserKit). \ No newline at end of file +* Use the official Git repository (https://github.com/symfony/BrowserKit). + +Usage +----- + +.. note:: + The component only provide an abstract client and does not provide any "default" backend for the HTTP layer. + +Making Request +~~~~~~~~~~~~~~ + +Clicking Links +~~~~~~~~~~~~~~ + +Submiting Forms +~~~~~~~~~~~~~~~~ + +Creating a Client +----------------- \ No newline at end of file From f0f8a50bc62b9c46592aec27a79c9b88b07a22ac Mon Sep 17 00:00:00 2001 From: yamiko Date: Fri, 10 Oct 2014 14:00:26 -0700 Subject: [PATCH 05/21] added links with info about clients and packagist link --- components/browser_kit/introduction.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index a5326bfb71c..024e4dc8b24 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -33,4 +33,11 @@ Submiting Forms ~~~~~~~~~~~~~~~~ Creating a Client ------------------ \ No newline at end of file +----------------- + +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`. + +.. _Packagist: https://packagist.org/packages/symfony/event-dispatcher +.. _Goutte: https://github.com/fabpot/Goutte \ No newline at end of file From b3d9eb3f3a6f5c7dbc3413e75c4612f338683176 Mon Sep 17 00:00:00 2001 From: yamiko Date: Fri, 10 Oct 2014 14:09:56 -0700 Subject: [PATCH 06/21] added links to index and map files --- components/index.rst | 1 + components/map.rst.inc | 4 ++++ 2 files changed, 5 insertions(+) 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` From 6997c4fb18011bb249cf5957669ffda0e066ec83 Mon Sep 17 00:00:00 2001 From: yamiko Date: Fri, 10 Oct 2014 14:40:11 -0700 Subject: [PATCH 07/21] make a basic request --- components/browser_kit/introduction.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index 024e4dc8b24..bcf4a8f6fee 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -26,6 +26,16 @@ Usage Making Request ~~~~~~~~~~~~~~ +To make a request you use the client's request method. +The first two arguments are for the HTTP method and the request url. + +.. code-block:: php + + use ACME\Client; + + $client = new Client(); + $response = $client->request('GET', 'http://symfony.com'); + Clicking Links ~~~~~~~~~~~~~~ From 94bb3bf8881acdc7cab51a080e6b673aa0d1f7b9 Mon Sep 17 00:00:00 2001 From: yamiko Date: Fri, 10 Oct 2014 14:42:30 -0700 Subject: [PATCH 08/21] fixed spelling --- components/browser_kit/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index bcf4a8f6fee..7edc304c30e 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -21,7 +21,7 @@ Usage ----- .. note:: - The component only provide an abstract client and does not provide any "default" backend for the HTTP layer. + The component only provides an abstract client and does not provide any "default" backend for the HTTP layer. Making Request ~~~~~~~~~~~~~~ From dda78bad952a3a0d5090eaae891c2c73726773e6 Mon Sep 17 00:00:00 2001 From: yamiko Date: Fri, 10 Oct 2014 15:03:05 -0700 Subject: [PATCH 09/21] added a link snippit --- components/browser_kit/introduction.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index 7edc304c30e..f3d150d97c8 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -28,17 +28,29 @@ Making Request 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(); - $response = $client->request('GET', 'http://symfony.com'); + $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 ~~~~~~~~~~~~~~~~ From 74cfecda84582e7df1580a6e7ba779a1650c36d6 Mon Sep 17 00:00:00 2001 From: yamiko Date: Mon, 13 Oct 2014 09:40:20 -0700 Subject: [PATCH 10/21] more outlines, fixed link, added more about creating a client --- components/browser_kit/introduction.rst | 35 ++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index f3d150d97c8..c4f27a7e30b 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -17,8 +17,8 @@ You can install the component in 2 different ways: * :doc:`Install it via Composer ` (``symfony/browser-kit`` on `Packagist`_); * Use the official Git repository (https://github.com/symfony/BrowserKit). -Usage ------ +Basic Usage +----------- .. note:: The component only provides an abstract client and does not provide any "default" backend for the HTTP layer. @@ -40,7 +40,7 @@ The request method will return a crawler object. Clicking Links ~~~~~~~~~~~~~~ -select a link with the crawler and pass it to the click method to click on the link. +Select a link with the crawler and pass it to the click method to click on the link. .. code-block:: php @@ -54,12 +54,39 @@ select a link with the crawler and pass it to the click method to click on the l Submiting Forms ~~~~~~~~~~~~~~~~ + +Cookies +------- + +History +------- + +Insulated Request +----------------- + Creating a Client ----------------- +To create your own client you must extend the abstract client class and implement the doRequest method. +This method accepts a request 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`. -.. _Packagist: https://packagist.org/packages/symfony/event-dispatcher +.. _Packagist: https://packagist.org/packages/symfony/browser-kit .. _Goutte: https://github.com/fabpot/Goutte \ No newline at end of file From a3d158e92d6ccb57a914775c791cd2162daa3708 Mon Sep 17 00:00:00 2001 From: "Robert M. Parker" Date: Sat, 23 May 2015 10:55:22 -0700 Subject: [PATCH 11/21] added form submissions and moved creating a client to top --- components/browser_kit/introduction.rst | 67 ++++++++++++++++--------- 1 file changed, 42 insertions(+), 25 deletions(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index c4f27a7e30b..45b2c6247c2 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -23,6 +23,32 @@ 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 request 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 Request ~~~~~~~~~~~~~~ @@ -52,8 +78,23 @@ Select a link with the crawler and pass it to the click method to click on the l $client->click($link); Submiting Forms -~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~ + +.. 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 ------- @@ -64,29 +105,5 @@ History Insulated Request ----------------- -Creating a Client ------------------ - -To create your own client you must extend the abstract client class and implement the doRequest method. -This method accepts a request 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`. - .. _Packagist: https://packagist.org/packages/symfony/browser-kit .. _Goutte: https://github.com/fabpot/Goutte \ No newline at end of file From 6b6e23af0e1928012e7224a64cc5b791a5a9aebe Mon Sep 17 00:00:00 2001 From: "Robert M. Parker" Date: Sat, 23 May 2015 11:20:57 -0700 Subject: [PATCH 12/21] added docs on histroy --- components/browser_kit/introduction.rst | 36 +++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index 45b2c6247c2..322219054e9 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -80,6 +80,9 @@ Select a link with the crawler and pass it to the click method to click on the l 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; @@ -102,6 +105,39 @@ Cookies History ------- +The client stores all your request 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 clients 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(); + Insulated Request ----------------- From ea3fd71234a5fe3aae1f380ccb4c4ee7e47a091a Mon Sep 17 00:00:00 2001 From: robert Parker Date: Tue, 27 Oct 2015 20:21:57 -0700 Subject: [PATCH 13/21] Adding documentation for cookies --- components/browser_kit/introduction.rst | 92 ++++++++++++++++++++++++- 1 file changed, 90 insertions(+), 2 deletions(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index 322219054e9..710b0bf65fd 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -102,6 +102,96 @@ You can get the form object by using the crawler to select the button and runnin 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 ------- @@ -138,8 +228,6 @@ You can restart the clients history with the restart method. This will also clea // restart history $client->restart(); -Insulated Request ------------------ .. _Packagist: https://packagist.org/packages/symfony/browser-kit .. _Goutte: https://github.com/fabpot/Goutte \ No newline at end of file From a1df783f0d47d4ccae07eb250308e9f13ec87aad Mon Sep 17 00:00:00 2001 From: "Robert M. Parker" Date: Thu, 19 Nov 2015 01:34:29 -0800 Subject: [PATCH 14/21] spelling and formating --- components/browser_kit/introduction.rst | 31 ++++++++++++++----------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index 710b0bf65fd..4af1366d3d7 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -7,12 +7,12 @@ The BrowserKit Component The BrowserKit component simulates the behavior of a web browser. -The BrowserKit component allows you to make web request, click on links and submit forms. +The BrowserKit component allows you to make web requests, click on links and submit forms. Installation ------------ -You can install the component in 2 different ways: +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). @@ -21,13 +21,14 @@ 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 request and should return a response. +This method accepts a requests and should return a response. .. code-block:: php @@ -36,8 +37,10 @@ This method accepts a request and should return a response. use Symfony\Component\BrowserKit\Client as BaseClient; use Symfony\Component\BrowserKit\Response; - class Client extends BaseClient { - protected function doRequest($request) { + class Client extends BaseClient + { + protected function doRequest($request) + { // convert request into a response // ... return new Response($content, $status, $headers); @@ -46,14 +49,14 @@ This method accepts a request and should return a response. 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`. +For an implementation based on ``HttpKernelInterface``, have a look at the Client provided by the :doc:`/components/http_kernel/introduction`. -Making Request +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. +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 @@ -66,7 +69,7 @@ The request method will return a crawler object. Clicking Links ~~~~~~~~~~~~~~ -Select a link with the crawler and pass it to the click method to click on the link. +Select a link with the crawler and pass it to the click_ method to click on the link. .. code-block:: php @@ -195,7 +198,7 @@ You can define create cookies and add them to a cookie jar that can be injected History ------- -The client stores all your request allowing you to go back and forward in your history. +The client stores all your requests allowing you to go back and forward in your history. .. code-block:: php @@ -215,7 +218,7 @@ The client stores all your request allowing you to go back and forward in your h // go forward to documentation page $doc_crawler = $client->forward(); -You can restart the clients history with the restart method. This will also clear out the CookieJar. +You can restart the client's history with the restart method. This will also clear out the CookieJar. .. code-block:: php @@ -230,4 +233,6 @@ You can restart the clients history with the restart method. This will also clea .. _Packagist: https://packagist.org/packages/symfony/browser-kit -.. _Goutte: https://github.com/fabpot/Goutte \ No newline at end of file +.. _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 From 03ea5a59d7e87b5b972cfb5e8e1e125be7c8856c Mon Sep 17 00:00:00 2001 From: "Robert M. Parker" Date: Thu, 19 Nov 2015 01:37:27 -0800 Subject: [PATCH 15/21] fix title underline --- components/browser_kit/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index 4af1366d3d7..e2a8f5ecffe 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -53,7 +53,7 @@ For an implementation based on ``HttpKernelInterface``, have a look at the Clien 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. From 883c0624a9775080da264be2d7f41bc7b77b32de Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Dec 2015 16:08:10 +0100 Subject: [PATCH 16/21] Finished the first version of the BrowserKit doc --- components/browser_kit/introduction.rst | 141 ++++++++++++------------ 1 file changed, 68 insertions(+), 73 deletions(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index e2a8f5ecffe..fdc361406f4 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -5,90 +5,91 @@ 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. + 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`_); +* :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. +The component only provides an abstract client and does not provide any backend +ready to use for the HTTP layer. -.. code-block:: php +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; + namespace Acme; use Symfony\Component\BrowserKit\Client as BaseClient; use Symfony\Component\BrowserKit\Response; - class Client extends BaseClient + class Client extends BaseClient { - protected function doRequest($request) + 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`. - +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. +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:: -.. code-block:: php - - use ACME\Client; + 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, which allows accessing +and traversing HTML elements programmatically. + Clicking Links ~~~~~~~~~~~~~~ -Select a link with the crawler and pass it to the click_ method to click on the link. +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:: -.. code-block:: php - - use ACME\Client; + use Acme\Client; $client = new Client(); $crawler = $client->request('GET', 'http://symfony.com'); $link = $crawler->selectLink('Go elsewhere...')->link(); $client->click($link); -Submiting Forms -~~~~~~~~~~~~~~~ +Submitting 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. +The ``Crawler`` object is also capable of simulating form submissions. First, +select the form via any of its buttons (thanks to the ``selectButton()`` and +``form()`` methods). Then, fill in the form data to send and use the ``submit()`` +method to make the needed HTTP POST request to submit the form:: -.. code-block:: php - - use ACME\Client; + use Acme\Client; // make a real request to an external site $client = new Client(); @@ -105,14 +106,14 @@ You can get the form object by using the crawler to select the button and runnin Cookies ------- -Retreiving Cookies -~~~~~~~~~~~~~~~~~~ - -The Crawler has a cookieJar which is a container for storing and recieving cookies. +Retrieving Cookies +~~~~~~~~~~~~~~~~~~ -.. code-block:: php +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; + use Acme\Client; // Make a request $client = new Client(); @@ -122,25 +123,28 @@ The Crawler has a cookieJar which is a container for storing and recieving cooki $cookieJar = $crawler->getCookieJar(); // Get a cookie by name - $flavor = $cookieJar->get('flavor'); + $cookie = $cookieJar->get('name_of_the_cookie'); // 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(); + $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; + use Acme\Client; // Make a request $client = new Client(); @@ -151,7 +155,7 @@ Looping Through Cookies // Get array with all cookies $cookies = $cookieJar->all(); - foreach($cookies as $cookie) + foreach($cookies as $cookie) { // ... } @@ -170,17 +174,13 @@ Looping Through Cookies // ... } -.. 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. +You can also create cookies and add them to a cookie jar that can be injected +into the client constructor:: -.. code-block:: php - - use ACME\Client; + use Acme\Client; // create cookies and add to cookie jar $expires = new \DateTime(); @@ -198,11 +198,10 @@ You can define create cookies and add them to a cookie jar that can be injected History ------- -The client stores all your requests allowing you to go back and forward in your history. - -.. code-block:: php +The client stores all your requests allowing you to go back and forward in your +history:: - use ACME\Client; + use Acme\Client; // make a real request to an external site $client = new Client(); @@ -218,21 +217,17 @@ The client stores all your requests allowing you to go back and forward in your // 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. +You can delete the client's history with the ``restart()`` method. This will +also delete all the cookies:: -.. code-block:: php - - use ACME\Client; + use Acme\Client; // make a real request to an external site $client = new Client(); $home_crawler = $client->request('GET', 'http://symfony.com'); - // restart history + // delete 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 From fd35c9304429d85190bdf23e799a7efb82200a72 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Dec 2015 16:15:31 +0100 Subject: [PATCH 17/21] Fixed a syntax issue --- components/browser_kit/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index fdc361406f4..6a47f651e87 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -110,7 +110,7 @@ Retrieving Cookies ~~~~~~~~~~~~~~~~~~ The ``Crawler`` object exposes cookies (if any) through a -:class:`Symfony\Component\BrowserKit\CookieJar`, which allows you to store and +:class:`Symfony\\Component\\BrowserKit\\CookieJar`, which allows you to store and retrieve any cookie while making requests with the client:: use Acme\Client; From 5aec7c486caf5f209d69f884e74cc820aaec21f1 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Dec 2015 16:21:22 +0100 Subject: [PATCH 18/21] Minor fixes --- components/browser_kit/introduction.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index 6a47f651e87..684a85c1358 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -26,7 +26,7 @@ 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 +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:: @@ -39,8 +39,7 @@ This method accepts a request and should return a response:: { protected function doRequest($request) { - // convert request into a response - // ... + // ... convert request into a response return new Response($content, $status, $headers); } From e7056a80610de64b3523a78310300817e6d5924a Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Dec 2015 16:22:11 +0100 Subject: [PATCH 19/21] Fixed a reference --- components/browser_kit/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index 684a85c1358..e31bc6d639a 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -47,7 +47,7 @@ This method accepts a request and should return a response:: 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`. +look at the Client provided by the :doc:`HttpKernel component `. Making Requests ~~~~~~~~~~~~~~~ From c9093a862285470bcb59ff64baadfd6b3e72e9c3 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Dec 2015 16:37:50 +0100 Subject: [PATCH 20/21] Implemented changes suggested by Wouter --- components/browser_kit/introduction.rst | 65 ++++++++++++------------- 1 file changed, 30 insertions(+), 35 deletions(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index e31bc6d639a..0177db8857d 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -62,8 +62,9 @@ requested URL:: $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, which allows accessing -and traversing HTML elements programmatically. +:class:`Symfony\\Component\\DomCrawler\\Crawler` class, provided by the +:doc:`DomCrawler component `_, and which allows +accessing and traversing HTML elements programmatically. Clicking Links ~~~~~~~~~~~~~~ @@ -83,10 +84,12 @@ the needed HTTP GET request to simulate the link click:: Submitting Forms ~~~~~~~~~~~~~~~~ -The ``Crawler`` object is also capable of simulating form submissions. First, -select the form via any of its buttons (thanks to the ``selectButton()`` and -``form()`` methods). Then, fill in the form data to send and use the ``submit()`` -method to make the needed HTTP POST request to submit the form:: +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; @@ -125,17 +128,18 @@ retrieve any cookie while making requests with the client:: $cookie = $cookieJar->get('name_of_the_cookie'); // Get cookie data - $name = $cookie->getName(); - $value = $cookie->getValue(); - $raw = $cookie->getRawValue(); - $secure = $cookie->isSecure(); + $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(); + $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 @@ -154,22 +158,19 @@ Looping Through Cookies // Get array with all cookies $cookies = $cookieJar->all(); - foreach($cookies as $cookie) - { + foreach ($cookies as $cookie) { // ... } // Get all values $values = $cookieJar->allValues('http://symfony.com'); - foreach($values as $value) - { + foreach ($values as $value) { // ... } // Get all raw values $rawValues = $cookieJar->allRawValues('http://symfony.com'); - foreach($rawValues as $rawValue) - { + foreach ($rawValues as $rawValue) { // ... } @@ -182,13 +183,7 @@ into the client constructor:: 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() - ); + $cookieJar = new Cookie('flavor', 'chocolate', strtotime('+1 day')); // create a client and set the cookies $client = new Client(array(), array(), $cookieJar); @@ -204,17 +199,17 @@ history:: // make a real request to an external site $client = new Client(); - $home_crawler = $client->request('GET', 'http://symfony.com'); + $client->request('GET', 'http://symfony.com'); // select and click on a link - $doc_link = $crawler->selectLink('Documentation')->link(); - $doc_crawler = $client->click($link); + $link = $crawler->selectLink('Documentation')->link(); + $client->click($link); // go back to home page - $home_crawler = $client->back(); + $crawler = $client->back(); // go forward to documentation page - $doc_crawler = $client->forward(); + $crawler = $client->forward(); You can delete the client's history with the ``restart()`` method. This will also delete all the cookies:: @@ -223,10 +218,10 @@ also delete all the cookies:: // make a real request to an external site $client = new Client(); - $home_crawler = $client->request('GET', 'http://symfony.com'); + $client->request('GET', 'http://symfony.com'); // delete history $client->restart(); -.. _Packagist: https://packagist.org/packages/symfony/browser-kit -.. _Goutte: https://github.com/fabpot/Goutte +.. _`Packagist`: https://packagist.org/packages/symfony/browser-kit +.. _`Goutte`: https://github.com/fabpot/Goutte From 3f0858f62d6f6aad9fcb6d7adc1140c8c03ec737 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 23 Dec 2015 17:12:50 +0100 Subject: [PATCH 21/21] Fixed a syntax issue --- components/browser_kit/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/browser_kit/introduction.rst b/components/browser_kit/introduction.rst index 0177db8857d..b07009ff15a 100644 --- a/components/browser_kit/introduction.rst +++ b/components/browser_kit/introduction.rst @@ -63,7 +63,7 @@ requested URL:: 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 +:doc:`DomCrawler component `, and which allows accessing and traversing HTML elements programmatically. Clicking Links