Skip to content

Commit cf9ce3d

Browse files
xabbuhxabbuh
committed
Merge branch '2.8' into 3.0
* 2.8: (26 commits) removed duplicate lines Updated "Learn more from the Cookbook" section [#6072] some tweaks [Cookbook][Console] change API doc class name Improvement to the apache/mod_php configuration example Fixed a syntax issue Implemented changes suggested by Wouter Fixed a reference Minor fixes Fixed a syntax issue Finished the first version of the BrowserKit doc fix title underline spelling and formating Adding documentation for cookies added docs on histroy added form submissions and moved creating a client to top more outlines, fixed link, added more about creating a client added a link snippit fixed spelling make a basic request ...
2 parents b986eb1 + a447862 commit cf9ce3d

File tree

8 files changed

+273
-21
lines changed

8 files changed

+273
-21
lines changed

‎book/routing.rst

+7
Original file line numberDiff line numberDiff line change
@@ -1598,5 +1598,12 @@ Learn more from the Cookbook
15981598
----------------------------
15991599

16001600
* :doc:`/cookbook/routing/scheme`
1601+
* :doc:`/cookbook/routing/slash_in_parameter`
1602+
* :doc:`/cookbook/routing/redirect_in_config`
1603+
* :doc:`/cookbook/routing/method_parameters`
1604+
* :doc:`/cookbook/routing/service_container_parameters`
1605+
* :doc:`/cookbook/routing/custom_route_loader`
1606+
* :doc:`/cookbook/routing/redirect_trailing_slash`
1607+
* :doc:`/cookbook/routing/extra_information`
16011608

16021609
.. _`FOSJsRoutingBundle`: https://github.com/FriendsOfSymfony/FOSJsRoutingBundle

‎components/browser_kit/index.rst

+7
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

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

‎components/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ The Components
66

77
using_components
88
asset/index
9+
browser_kit/index
910
class_loader/index
1011
config/index
1112
console/index

‎components/map.rst.inc

+4
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44

55
* :doc:`/components/asset/introduction`
66

7+
* :doc:`/components/browser_kit/index`
8+
9+
* :doc:`/components/browser_kit/introduction`
10+
711
* :doc:`/components/class_loader/index`
812

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

‎cookbook/configuration/web_server_configuration.rst

+8
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,14 @@ and increase web server performance:
9393
# Options FollowSymlinks
9494
# </Directory>
9595
96+
# optionally disable the RewriteEngine for the asset directories
97+
# which will allow apache to simply reply with a 404 when files are
98+
# not found instead of passing the request into the full symfony stack
99+
<Directory /var/www/project/web/bundles>
100+
<IfModule mod_rewrite.c>
101+
RewriteEngine Off
102+
</IfModule>
103+
</Directory>
96104
ErrorLog /var/log/apache2/project_error.log
97105
CustomLog /var/log/apache2/project_access.log combined
98106
</VirtualHost>

0 commit comments

Comments
 (0)