Skip to content

Commit 7cfbb2f

Browse files
xabbuhxabbuh
committed
Merge branch '2.3' into 2.7
* 2.3: (24 commits) removed duplicate lines Updated "Learn more from the Cookbook" section [#6072] some tweaks 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 added links to index and map files added links with info about clients and packagist link ... Conflicts: components/index.rst components/map.rst.inc
2 parents 11f1564 + 45797b3 commit 7cfbb2f

File tree

6 files changed

+247
-3
lines changed

6 files changed

+247
-3
lines changed

‎book/routing.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1606,5 +1606,12 @@ Learn more from the Cookbook
16061606
----------------------------
16071607

16081608
* :doc:`/cookbook/routing/scheme`
1609+
* :doc:`/cookbook/routing/slash_in_parameter`
1610+
* :doc:`/cookbook/routing/redirect_in_config`
1611+
* :doc:`/cookbook/routing/method_parameters`
1612+
* :doc:`/cookbook/routing/service_container_parameters`
1613+
* :doc:`/cookbook/routing/custom_route_loader`
1614+
* :doc:`/cookbook/routing/redirect_trailing_slash`
1615+
* :doc:`/cookbook/routing/extra_information`
16091616

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

‎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: 228 additions & 0 deletions
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

Lines changed: 1 addition & 0 deletions
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

Lines changed: 4 additions & 0 deletions
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/email/gmail.rst

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -120,9 +120,6 @@ If your application uses ``tls`` encryption or ``oauth`` authentication, you
120120
must override the default options by defining the ``encryption`` and ``auth_mode``
121121
parameters.
122122

123-
If you are using 2-Step-Verification, you must `generate an App password`_ and
124-
use this as your ``mailer_password`` value.
125-
126123
If your Gmail account uses 2-Step-Verification, you must `generate an App password`_
127124
and use it as the value of the ``mailer_password`` parameter. You must also ensure
128125
that you `allow less secure apps to access your Gmail account`_.

0 commit comments

Comments
 (0)