Skip to content

Commit 685dfda

Browse files
xabbuhxabbuh
committed
feature #6072 Add browserkit component documentation (yamiko, yamiko-ninja, robert Parker, javiereguiluz)
This PR was merged into the 2.3 branch. Discussion ---------- Add browserkit component documentation | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes | Applies to | all | Fixed tickets | - This PR tries to finish the fantastic work made by @yamiko-ninja in #4312. Please review it so I can improve/finish it and we can merge it before year's end. Thanks! Commits ------- 3f0858f Fixed a syntax issue c9093a8 Implemented changes suggested by Wouter e7056a8 Fixed a reference 5aec7c4 Minor fixes fd35c93 Fixed a syntax issue 883c062 Finished the first version of the BrowserKit doc 03ea5a5 fix title underline a1df783 spelling and formating ea3fd71 Adding documentation for cookies 6b6e23a added docs on histroy a3d158e added form submissions and moved creating a client to top 74cfecd more outlines, fixed link, added more about creating a client dda78ba added a link snippit 94bb3bf fixed spelling 6997c4f make a basic request b3d9eb3 added links to index and map files f0f8a50 added links with info about clients and packagist link 1e5ca13 added in sections that I apln to fill out 9c007e9 syntax fix 645d50d fixed a few mistakes 93d7258 added introduction
2 parents 2a6dc36 + 3f0858f commit 685dfda

File tree

4 files changed

+239
-0
lines changed

4 files changed

+239
-0
lines changed

‎components/browser_kit/index.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
BrowserKit
2+
==========
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
introduction

‎components/browser_kit/introduction.rst

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
.. index::
2+
single: BrowserKit
3+
single: Components; BrowserKit
4+
5+
The BrowserKit Component
6+
========================
7+
8+
The BrowserKit component simulates the behavior of a web browser, allowing
9+
you to make requests, click on links and submit forms programmatically.
10+
11+
Installation
12+
------------
13+
14+
You can install the component in two different ways:
15+
16+
* :doc:`Install it via Composer </components/using_components>`
17+
(``symfony/browser-kit`` on `Packagist`_);
18+
* Use the official Git repository (https://github.com/symfony/BrowserKit).
19+
20+
Basic Usage
21+
-----------
22+
23+
Creating a Client
24+
~~~~~~~~~~~~~~~~~
25+
26+
The component only provides an abstract client and does not provide any backend
27+
ready to use for the HTTP layer.
28+
29+
To create your own client, you must extend the abstract ``Client`` class and
30+
implement the :method:`Symfony\\Component\\BrowserKit\\Client::doRequest` method.
31+
This method accepts a request and should return a response::
32+
33+
namespace Acme;
34+
35+
use Symfony\Component\BrowserKit\Client as BaseClient;
36+
use Symfony\Component\BrowserKit\Response;
37+
38+
class Client extends BaseClient
39+
{
40+
protected function doRequest($request)
41+
{
42+
// ... convert request into a response
43+
44+
return new Response($content, $status, $headers);
45+
}
46+
}
47+
48+
For a simple implementation of a browser based on an HTTP layer, have a look
49+
at `Goutte`_. For an implementation based on ``HttpKernelInterface``, have a
50+
look at the Client provided by the :doc:`HttpKernel component </components/http_kernel/introduction>`.
51+
52+
Making Requests
53+
~~~~~~~~~~~~~~~
54+
55+
Use the :method:`Symfony\\Component\\BrowserKit\\Client::request` method to make
56+
any HTTP request. The first two arguments are for the HTTP method and the
57+
requested URL::
58+
59+
use Acme\Client;
60+
61+
$client = new Client();
62+
$crawler = $client->request('GET', 'http://symfony.com');
63+
64+
The value returned by the ``request()`` method is an instance of the
65+
:class:`Symfony\\Component\\DomCrawler\\Crawler` class, provided by the
66+
:doc:`DomCrawler component </components/dom_crawler>`, and which allows
67+
accessing and traversing HTML elements programmatically.
68+
69+
Clicking Links
70+
~~~~~~~~~~~~~~
71+
72+
The ``Crawler`` object is capable of simulating link clicks. First, pass the
73+
text content of the link to the ``selectLink()`` method, which returns you a
74+
``Link`` object. Then, pass this object to the ``click()`` method, which makes
75+
the needed HTTP GET request to simulate the link click::
76+
77+
use Acme\Client;
78+
79+
$client = new Client();
80+
$crawler = $client->request('GET', 'http://symfony.com');
81+
$link = $crawler->selectLink('Go elsewhere...')->link();
82+
$client->click($link);
83+
84+
Submitting Forms
85+
~~~~~~~~~~~~~~~~
86+
87+
The ``Crawler`` object is also capable of selecting forms. First, select any of
88+
the form's buttons with the ``selectButton()`` method. Then, use the ``form()``
89+
method to select the form which the button belongs to.
90+
91+
After selecting the form, fill in its data and send it using the ``submit()``
92+
method (which makes the needed HTTP POST request to submit the form contents)::
93+
94+
use Acme\Client;
95+
96+
// make a real request to an external site
97+
$client = new Client();
98+
$crawler = $client->request('GET', 'https://github.com/login');
99+
100+
// select the form and fill in some values
101+
$form = $crawler->selectButton('Log in')->form();
102+
$form['login'] = 'symfonyfan';
103+
$form['password'] = 'anypass';
104+
105+
// submit that form
106+
$crawler = $client->submit($form);
107+
108+
Cookies
109+
-------
110+
111+
Retrieving Cookies
112+
~~~~~~~~~~~~~~~~~~
113+
114+
The ``Crawler`` object exposes cookies (if any) through a
115+
:class:`Symfony\\Component\\BrowserKit\\CookieJar`, which allows you to store and
116+
retrieve any cookie while making requests with the client::
117+
118+
use Acme\Client;
119+
120+
// Make a request
121+
$client = new Client();
122+
$crawler = $client->request('GET', 'http://symfony.com');
123+
124+
// Get the cookie Jar
125+
$cookieJar = $crawler->getCookieJar();
126+
127+
// Get a cookie by name
128+
$cookie = $cookieJar->get('name_of_the_cookie');
129+
130+
// Get cookie data
131+
$name = $cookie->getName();
132+
$value = $cookie->getValue();
133+
$raw = $cookie->getRawValue();
134+
$secure = $cookie->isSecure();
135+
$isHttpOnly = $cookie->isHttpOnly();
136+
$isExpired = $cookie->isExpired();
137+
$expires = $cookie->getExpiresTime();
138+
$path = $cookie->getPath();
139+
$domain = $cookie->getDomain();
140+
141+
.. note::
142+
143+
These methods only return cookies that have not expired.
144+
145+
Looping Through Cookies
146+
~~~~~~~~~~~~~~~~~~~~~~~
147+
148+
.. code-block:: php
149+
150+
use Acme\Client;
151+
152+
// Make a request
153+
$client = new Client();
154+
$crawler = $client->request('GET', 'http://symfony.com');
155+
156+
// Get the cookie Jar
157+
$cookieJar = $crawler->getCookieJar();
158+
159+
// Get array with all cookies
160+
$cookies = $cookieJar->all();
161+
foreach ($cookies as $cookie) {
162+
// ...
163+
}
164+
165+
// Get all values
166+
$values = $cookieJar->allValues('http://symfony.com');
167+
foreach ($values as $value) {
168+
// ...
169+
}
170+
171+
// Get all raw values
172+
$rawValues = $cookieJar->allRawValues('http://symfony.com');
173+
foreach ($rawValues as $rawValue) {
174+
// ...
175+
}
176+
177+
Setting Cookies
178+
~~~~~~~~~~~~~~~
179+
180+
You can also create cookies and add them to a cookie jar that can be injected
181+
into the client constructor::
182+
183+
use Acme\Client;
184+
185+
// create cookies and add to cookie jar
186+
$cookieJar = new Cookie('flavor', 'chocolate', strtotime('+1 day'));
187+
188+
// create a client and set the cookies
189+
$client = new Client(array(), array(), $cookieJar);
190+
// ...
191+
192+
History
193+
-------
194+
195+
The client stores all your requests allowing you to go back and forward in your
196+
history::
197+
198+
use Acme\Client;
199+
200+
// make a real request to an external site
201+
$client = new Client();
202+
$client->request('GET', 'http://symfony.com');
203+
204+
// select and click on a link
205+
$link = $crawler->selectLink('Documentation')->link();
206+
$client->click($link);
207+
208+
// go back to home page
209+
$crawler = $client->back();
210+
211+
// go forward to documentation page
212+
$crawler = $client->forward();
213+
214+
You can delete the client's history with the ``restart()`` method. This will
215+
also delete all the cookies::
216+
217+
use Acme\Client;
218+
219+
// make a real request to an external site
220+
$client = new Client();
221+
$client->request('GET', 'http://symfony.com');
222+
223+
// delete history
224+
$client->restart();
225+
226+
.. _`Packagist`: https://packagist.org/packages/symfony/browser-kit
227+
.. _`Goutte`: https://github.com/fabpot/Goutte

‎components/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ The Components
55
:hidden:
66

77
using_components
8+
browser_kit/index
89
class_loader/index
910
config/index
1011
console/index

‎components/map.rst.inc

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
* :doc:`/components/using_components`
22

3+
* :doc:`/components/browser_kit/index`
4+
5+
* :doc:`/components/browser_kit/introduction`
6+
37
* :doc:`/components/class_loader/index`
48

59
* :doc:`/components/class_loader/introduction`

0 commit comments

Comments
 (0)