Skip to content

Commit 0b6b65e

Browse files
weaverryanweaverryan
committed
Merge remote-tracking branch 'origin/2.0'
2 parents a1982ae + 27a4e01 commit 0b6b65e

File tree

6 files changed

+383
-6
lines changed

6 files changed

+383
-6
lines changed

‎components/console.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -273,9 +273,9 @@ console.
273273
Getting Services from the Service Container
274274
-------------------------------------------
275275

276-
By using :class:`Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand`
276+
By using :class:`Symfony\\Bundle\\FrameworkBundle\\Command\\ContainerAwareCommand`
277277
as the base class for the command (instead of the more basic
278-
:class:`Symfony\Component\Console\Command\Command`), you have access to the
278+
:class:`Symfony\\Component\\Console\\Command\\Command`), you have access to the
279279
service container. In other words, you have access to any configured service.
280280
For example, you could easily extend the task to be translatable::
281281

‎components/finder.rst

+3-1
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,9 @@ directories::
3131
print $file->getRealpath()."\n";
3232
}
3333

34-
The ``$file`` is an instance of :phpclass:`SplFileInfo`.
34+
The ``$file`` is an instance of :class:`Symfony\\Component\\Finder\\SplFileInfo`
35+
which extends :phpclass:`SplFileInfo` to provide methods to work with relative
36+
paths.
3537

3638
The above code prints the names of all the files in the current directory
3739
recursively. The Finder class uses a fluent interface, so all methods return

‎components/http_foundation.rst

+375
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,375 @@
1+
.. index::
2+
single: HTTP
3+
single: HttpFoundation
4+
5+
The HttpFoundation Component
6+
============================
7+
8+
The HttpFoundation Component defines an object-oriented layer for the HTTP
9+
specification.
10+
11+
In PHP, the request is represented by some global variables (``$_GET``,
12+
``$_POST``, ``$_FILE``, ``$_COOKIE``, ``$_SESSION``...) and the response is
13+
generated by some functions (``echo``, ``header``, ``setcookie``, ...).
14+
15+
The Symfony2 HttpFoundation component replaces these default PHP global
16+
variables and functions by an Object-Oriented layer.
17+
18+
Installation
19+
------------
20+
21+
You can install the component in many different ways:
22+
23+
* Use the official Git repository (https://github.com/symfony/HttpFoundation);
24+
* Install it via PEAR ( `pear.symfony.com/HttpFoundation`);
25+
* Install it via Composer (`symfony/http-foundation` on Packagist).
26+
27+
Request
28+
-------
29+
30+
The most common way to create request is to base it on the current PHP global
31+
variables with
32+
:method:`Symfony\\Component\\HttpFoundation\\Request::createFromGlobals`::
33+
34+
use Symfony\Component\HttpFoundation\Request;
35+
36+
$request = Request::createFromGlobals();
37+
38+
which is almost equivalent to the more verbose, but also more flexible,
39+
:method:`Symfony\\Component\\HttpFoundation\\Request::__construct` call::
40+
41+
$request = new Request($_GET, $_POST, array(), $_COOKIE, $_FILES, $_SERVER);
42+
43+
Accessing Request Data
44+
~~~~~~~~~~~~~~~~~~~~~~
45+
46+
A Request object holds information about the client request. This information
47+
can be accessed via several public properties:
48+
49+
* ``request``: equivalent of ``$_POST``;
50+
51+
* ``query``: equivalent of ``$_GET`` (``$request->query->get('name')``);
52+
53+
* ``cookies``: equivalent of ``$_COOKIE``;
54+
55+
* ``files``: equivalent of ``$_FILE``;
56+
57+
* ``server``: equivalent of ``$_SERVER``;
58+
59+
* ``headers``: mostly equivalent to a sub-set of ``$_SERVER``
60+
(``$request->headers->get('Content-Type')``).
61+
62+
Each property is a :class:`Symfony\\Component\\HttpFoundation\\ParameterBag`
63+
instance (or a sub-class of), which is a data holder class:
64+
65+
* ``request``: :class:`Symfony\\Component\\HttpFoundation\\ParameterBag`;
66+
67+
* ``query``: :class:`Symfony\\Component\\HttpFoundation\\ParameterBag`;
68+
69+
* ``cookies``: :class:`Symfony\\Component\\HttpFoundation\\ParameterBag`;
70+
71+
* ``files``: :class:`Symfony\\Component\\HttpFoundation\\FileBag`;
72+
73+
* ``server``: :class:`Symfony\\Component\\HttpFoundation\\ServerBag`;
74+
75+
* ``headers``: :class:`Symfony\\Component\\HttpFoundation\\HeaderBag`.
76+
77+
All :class:`Symfony\\Component\\HttpFoundation\\ParameterBag` instances have
78+
methods to retrieve and update its data:
79+
80+
* :method:`Symfony\\Component\\HttpFoundation\\ParameterBag::all`: Returns
81+
the parameters;
82+
83+
* :method:`Symfony\\Component\\HttpFoundation\\ParameterBag::keys`: Returns
84+
the parameter keys;
85+
86+
* :method:`Symfony\\Component\\HttpFoundation\\ParameterBag::replace`:
87+
Replaces the current parameters by a new set;
88+
89+
* :method:`Symfony\\Component\\HttpFoundation\\ParameterBag::add`: Adds
90+
parameters;
91+
92+
* :method:`Symfony\\Component\\HttpFoundation\\ParameterBag::get`: Returns a
93+
parameter by name;
94+
95+
* :method:`Symfony\\Component\\HttpFoundation\\ParameterBag::set`: Sets a
96+
parameter by name;
97+
98+
* :method:`Symfony\\Component\\HttpFoundation\\ParameterBag::has`: Returns
99+
true if the parameter is defined;
100+
101+
* :method:`Symfony\\Component\\HttpFoundation\\ParameterBag::remove`: Removes
102+
a parameter.
103+
104+
The :class:`Symfony\\Component\\HttpFoundation\\ParameterBag` instance also
105+
has some methods to filter the input values:
106+
107+
* :method:`Symfony\\Component\\HttpFoundation\\Request::getAlpha`: Returns
108+
the alphabetic characters of the parameter value;
109+
110+
* :method:`Symfony\\Component\\HttpFoundation\\Request::getAlnum`: Returns
111+
the alphabetic characters and digits of the parameter value;
112+
113+
* :method:`Symfony\\Component\\HttpFoundation\\Request::getDigits`: Returns
114+
the digits of the parameter value;
115+
116+
* :method:`Symfony\\Component\\HttpFoundation\\Request::getInt`: Returns the
117+
parameter value converted to integer;
118+
119+
* :method:`Symfony\\Component\\HttpFoundation\\Request::filter`: Filters the
120+
parameter by using the PHP ``filter_var()`` function.
121+
122+
All getters takes up to three arguments: the first one is the parameter name
123+
and the second one is the default value to return if the parameter does not
124+
exist::
125+
126+
// the query string is '?foo=bar'
127+
128+
$request->query->get('foo');
129+
// returns bar
130+
131+
$request->query->get('bar');
132+
// returns null
133+
134+
$request->query->get('bar', 'bar');
135+
// returns 'bar'
136+
137+
138+
When PHP imports the request query, it handles request parameters like
139+
``foo[bar]=bar`` in a special way as it creates an array. So you can get the
140+
``foo`` parameter and you will get back an array with a ``bar`` element. But
141+
sometimes, you might want to get the value for the "original" parameter name:
142+
``foo[bar]``. This is possible with all the `ParameterBag` getters like
143+
:method:`Symfony\\Component\\HttpFoundation\\Request::get` via the third
144+
argument::
145+
146+
// the query string is '?foo[bar]=bar'
147+
148+
$request->query->get('foo');
149+
// returns array('bar' => 'bar')
150+
151+
$request->query->get('foo[bar]');
152+
// returns null
153+
154+
$request->query->get('foo[bar]', null, true);
155+
// returns 'bar'
156+
157+
Last, but not the least, you can also store additional data in the request,
158+
thanks to the ``attributes`` public property, which is also an instance of
159+
:class:`Symfony\\Component\\HttpFoundation\\ParameterBag`. This is mostly used
160+
to attach information that belongs to the Request and that needs to be
161+
accessed from many different points in your application.
162+
163+
Identifying a Request
164+
~~~~~~~~~~~~~~~~~~~~~
165+
166+
In your application, you need a way to identify a request; most of the time,
167+
this is done via the "path info" of the request, which can be accessed via the
168+
:method:`Symfony\\Component\\HttpFoundation\\Request::getPathInfo` method::
169+
170+
// for a request to http://example.com/blog/index.php/post/hello-world
171+
// the path info is "/post/hello-world"
172+
$request->getPathInfo();
173+
174+
Simulating a Request
175+
~~~~~~~~~~~~~~~~~~~~
176+
177+
Instead of creating a Request based on the PHP globals, you can also simulate
178+
a Request::
179+
180+
$request = Request::create('/hello-world', 'GET', array('name' => 'Fabien'));
181+
182+
The :method:`Symfony\\Component\\HttpFoundation\\Request::create` method
183+
creates a request based on a path info, a method and some parameters (the
184+
query parameters or the request ones depending on the HTTP method); and of
185+
course, you an also override all other variables as well (by default, Symfony
186+
creates sensible defaults for all the PHP global variables).
187+
188+
Based on such a request, you can override the PHP global variables via
189+
:method:`Symfony\\Component\\HttpFoundation\\Request::overrideGlobals`::
190+
191+
$request->overrideGlobals();
192+
193+
.. tip::
194+
195+
You can also duplicate an existing query via
196+
:method:`Symfony\\Component\\HttpFoundation\\Request::duplicate` or
197+
change a bunch of parameters with a single call to
198+
:method:`Symfony\\Component\\HttpFoundation\\Request::initialize`.
199+
200+
Accessing the Session
201+
~~~~~~~~~~~~~~~~~~~~~
202+
203+
If you have a session attached to the Request, you can access it via the
204+
:method:`Symfony\\Component\\HttpFoundation\\Request::getSession` method;
205+
the
206+
:method:`Symfony\\Component\\HttpFoundation\\Request::hasPreviousSession`
207+
method tells you if the request contains a Session which was started in one of
208+
the previous requests.
209+
210+
Accessing other Data
211+
~~~~~~~~~~~~~~~~~~~~
212+
213+
The Request class has many other methods that you can use to access the
214+
request information. Have a look at the API for more information about them.
215+
216+
Response
217+
--------
218+
219+
A :class:`Symfony\\Component\\HttpFoundation\\Response` object holds all the
220+
information that needs to be sent back to the client from a given request. The
221+
constructor takes up to three arguments: the response content, the status
222+
code, and an array of HTTP headers::
223+
224+
use Symfony\Component\HttpFoundation\Response;
225+
226+
$response = new Response('Content', 200, array('content-type' => 'text/html'));
227+
228+
These information can also be manipulated after the Response object creation::
229+
230+
$response->setContent('Hello World');
231+
232+
// the headers public attribute is a ResponseHeaderBag
233+
$response->headers->set('Content-Type', 'text/plain');
234+
235+
$response->setStatusCode(404);
236+
237+
When setting the ``Content-Type`` of the Response, you can set the charset,
238+
but it is better to set it via the
239+
:method:`Symfony\\Component\\HttpFoundation\\Response::setCharset` method::
240+
241+
$response->setCharset('ISO-8859-1');
242+
243+
Note that by default, Symfony assumes that your Responses are encoded in
244+
UTF-8.
245+
246+
Sending the Response
247+
~~~~~~~~~~~~~~~~~~~~
248+
249+
Before sending the Response, you can ensure that it is compliant with the HTTP
250+
specification by calling the
251+
:method:`Symfony\\Component\\HttpFoundation\\Response::prepare` method::
252+
253+
$response->prepare($request);
254+
255+
Sending the response to the client is then as simple as calling
256+
:method:`Symfony\\Component\\HttpFoundation\\Response::send`::
257+
258+
$response->send();
259+
260+
Setting Cookies
261+
~~~~~~~~~~~~~~~
262+
263+
The response cookies can be manipulated though the ``headers`` public
264+
attribute::
265+
266+
use Symfony\Component\HttpFoundation\Cookie;
267+
268+
$response->headers->setCookie(new Cookie('foo', 'bar'));
269+
270+
The
271+
:method:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag::setCookie`
272+
method takes an instance of
273+
:class:`Symfony\\Component\\HttpFoundation\\Cookie` as an argument.
274+
275+
You can clear a cookie via the
276+
:method:`Symfony\\Component\\HttpFoundation\\Response::clearCookie` method.
277+
278+
Managing the HTTP Cache
279+
~~~~~~~~~~~~~~~~~~~~~~~
280+
281+
The :class:`Symfony\\Component\\HttpFoundation\\Response` class has a rich set
282+
of methods to manipulate the HTTP headers related to the cache:
283+
284+
* :method:`Symfony\\Component\\HttpFoundation\\Response::setPublic`;
285+
* :method:`Symfony\\Component\\HttpFoundation\\Response::setPrivate`;
286+
* :method:`Symfony\\Component\\HttpFoundation\\Response::expire`;
287+
* :method:`Symfony\\Component\\HttpFoundation\\Response::setExpires`;
288+
* :method:`Symfony\\Component\\HttpFoundation\\Response::setMaxAge`;
289+
* :method:`Symfony\\Component\\HttpFoundation\\Response::setSharedMaxAge`;
290+
* :method:`Symfony\\Component\\HttpFoundation\\Response::setTtl`;
291+
* :method:`Symfony\\Component\\HttpFoundation\\Response::setClientTtl`;
292+
* :method:`Symfony\\Component\\HttpFoundation\\Response::setLastModified`;
293+
* :method:`Symfony\\Component\\HttpFoundation\\Response::setEtag`;
294+
* :method:`Symfony\\Component\\HttpFoundation\\Response::setVary`;
295+
296+
The :method:`Symfony\\Component\\HttpFoundation\\Response::setCache` method
297+
can be used to set the most commonly used cache information in one method
298+
call::
299+
300+
$response->setCache(array(
301+
'etag' => 'abcdef',
302+
'last_modified' => new \DateTime(),
303+
'max_age' => 600,
304+
's_maxage' => 600,
305+
'private' => false,
306+
'public' => true,
307+
));
308+
309+
To check if the Response validators (``ETag``, ``Last-Modified``) match a
310+
conditional value specified in the client Request, use the
311+
:method:`Symfony\\Component\\HttpFoundation\\Response::isNotModified`
312+
method::
313+
314+
if ($response->isNotModified($request)) {
315+
$response->send();
316+
}
317+
318+
If the Response is not modified, it sets the status code to 304 and remove the
319+
actual response content.
320+
321+
Redirecting the User
322+
~~~~~~~~~~~~~~~~~~~~
323+
324+
To redirect the client to another URL, you can use the
325+
:class:`Symfony\\Component\\HttpFoundation\\RedirectResponse` class::
326+
327+
use Symfony\Component\HttpFoundation\RedirectResponse;
328+
329+
$response = new RedirectResponse('http://example.com/');
330+
331+
Streaming a Response
332+
~~~~~~~~~~~~~~~~~~~~
333+
334+
.. versionadded:: 2.1
335+
Support for streamed responses was added in Symfony 2.1.
336+
337+
The :class:`Symfony\\Component\\HttpFoundation\\StreamedResponse` class allows
338+
you to stream the Response back to the client. The response content is
339+
represented by a PHP callable instead of a string::
340+
341+
use Symfony\Component\HttpFoundation\StreamedResponse;
342+
343+
$response = new StreamedResponse();
344+
$response->setCallback(function () {
345+
echo 'Hello World';
346+
flush();
347+
sleep(2);
348+
echo 'Hello World';
349+
flush();
350+
});
351+
$response->send();
352+
353+
Downloading Files
354+
~~~~~~~~~~~~~~~~~
355+
356+
.. versionadded:: 2.1
357+
The ``makeDisposition`` method was added in Symfony 2.1.
358+
359+
When uploading a file, you must add a ``Content-Disposition`` header to your
360+
response. While creating this header for basic file downloads is easy, using
361+
non-ASCII filenames is more involving. The
362+
:method:`:Symfony\\Component\\HttpFoundation\\Response:makeDisposition`
363+
abstracts the hard work behind a simple API::
364+
365+
use Symfony\\Component\\HttpFoundation\\ResponseHeaderBag;
366+
367+
$d = $response->headers->makeDisposition(ResponseHeaderBag::DISPOSITION_ATTACHMENT, 'foo.pdf');
368+
369+
$response->headers->set('Content-Disposition', $d);
370+
371+
Session
372+
-------
373+
374+
TBD -- This part has not been written yet as it will probably be refactored
375+
soon in Symfony 2.1.

0 commit comments

Comments
 (0)