Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 0ca6251

Browse filesBrowse files
fabpotfabpot
committed
added doc for the HttpFoundation component (there is some missing things but that's a good start)
1 parent 3814b8e commit 0ca6251
Copy full SHA for 0ca6251

File tree

Expand file treeCollapse file tree

2 files changed

+367
-0
lines changed
Filter options
Expand file treeCollapse file tree

2 files changed

+367
-0
lines changed

‎components/http_foundation.rst

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

‎components/index.rst

Copy file name to clipboardExpand all lines: components/index.rst
+1Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,6 @@ The Components
88
console
99
css_selector
1010
finder
11+
http_foundation
1112
process
1213
yaml

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.