The HttpFoundation Component
Warning: You are browsing the documentation for Symfony 2.x, which is no longer maintained.
Read the updated version of this page for Symfony 7.1 (the current stable version).
The HttpFoundation component defines an object-oriented layer for the HTTP specification.
In PHP, the request is represented by some global variables ($_GET
,
$_POST
, $_FILES
, $_COOKIE
, $_SESSION
, ...) and the response is
generated by some functions (echo
, header()
, setcookie()
, ...).
The Symfony HttpFoundation component replaces these default PHP global variables and functions by an object-oriented layer.
Installation
1
$ composer require symfony/http-foundation
Alternatively, you can clone the https://github.com/symfony/http-foundation repository.
Note
If you install this component outside of a Symfony application, you must
require the vendor/autoload.php
file in your code to enable the class
autoloading mechanism provided by Composer. Read
this article for more details.
See also
This article explains how to use the HttpFoundation features as an independent component in any PHP application. In Symfony applications everything is already configured and ready to use. Read the Controller article to learn about how to use these features when creating controllers.
Request
The most common way to create a request is to base it on the current PHP global variables with createFromGlobals():
1 2 3
use Symfony\Component\HttpFoundation\Request;
$request = Request::createFromGlobals();
which is almost equivalent to the more verbose, but also more flexible, __construct() call:
1 2 3 4 5 6 7 8
$request = new Request(
$_GET,
$_POST,
array(),
$_COOKIE,
$_FILES,
$_SERVER
);
Accessing Request Data
A Request object holds information about the client request. This information can be accessed via several public properties:
request
: equivalent of$_POST
;query
: equivalent of$_GET
($request->query->get('name')
);cookies
: equivalent of$_COOKIE
;attributes
: no equivalent - used by your app to store other data (see below);files
: equivalent of$_FILES
;server
: equivalent of$_SERVER
;headers
: mostly equivalent to a subset of$_SERVER
($request->headers->get('User-Agent')
).
Each property is a ParameterBag instance (or a sub-class of), which is a data holder class:
request
: ParameterBag;query
: ParameterBag;cookies
: ParameterBag;attributes
: ParameterBag;files
: FileBag;server
: ServerBag;headers
: HeaderBag.
All ParameterBag instances have methods to retrieve and update their data:
- all()
- Returns the parameters.
- keys()
- Returns the parameter keys.
- replace()
- Replaces the current parameters by a new set.
- add()
- Adds parameters.
- get()
- Returns a parameter by name.
- set()
- Sets a parameter by name.
- has()
-
Returns
true
if the parameter is defined. - remove()
- Removes a parameter.
The ParameterBag instance also has some methods to filter the input values:
- getAlpha()
- Returns the alphabetic characters of the parameter value;
- getAlnum()
- Returns the alphabetic characters and digits of the parameter value;
- getBoolean()
-
Returns the parameter value converted to boolean;
2.6
The
getBoolean()
method was introduced in Symfony 2.6. - getDigits()
- Returns the digits of the parameter value;
- getInt()
- Returns the parameter value converted to integer;
- filter()
- Filters the parameter by using the PHP filter_var function.
All getters take up to three arguments: the first one is the parameter name and the second one is the default value to return if the parameter does not exist:
1 2 3 4 5 6 7 8 9 10
// the query string is '?foo=bar'
$request->query->get('foo');
// returns 'bar'
$request->query->get('bar');
// returns null
$request->query->get('bar', 'baz');
// returns 'baz'
When PHP imports the request query, it handles request parameters like
foo[bar]=baz
in a special way as it creates an array. So you can get the
foo
parameter and you will get back an array with a bar
element:
1 2 3 4 5 6 7 8 9 10
// the query string is '?foo[bar]=baz'
$request->query->get('foo');
// returns array('bar' => 'baz')
$request->query->get('foo[bar]');
// returns null
$request->query->get('foo')['bar'];
// returns 'baz'
Thanks to the public attributes
property, you can store additional data
in the request, which is also an instance of
ParameterBag. This is mostly used
to attach information that belongs to the Request and that needs to be
accessed from many different points in your application.
Finally, the raw data sent with the request body can be accessed using getContent():
1
$content = $request->getContent();
For instance, this may be useful to process a JSON string sent to the application by a remote service using the HTTP POST method.
Identifying a Request
In your application, you need a way to identify a request; most of the time, this is done via the "path info" of the request, which can be accessed via the getPathInfo() method:
1 2 3
// for a request to http://example.com/blog/index.php/post/hello-world
// the path info is "/post/hello-world"
$request->getPathInfo();
Simulating a Request
Instead of creating a request based on the PHP globals, you can also simulate a request:
1 2 3 4 5
$request = Request::create(
'/hello-world',
'GET',
array('name' => 'Fabien')
);
The create() method creates a request based on a URI, a method and some parameters (the query parameters or the request ones depending on the HTTP method); and of course, you can also override all other variables as well (by default, Symfony creates sensible defaults for all the PHP global variables).
Based on such a request, you can override the PHP global variables via overrideGlobals():
1
$request->overrideGlobals();
Tip
You can also duplicate an existing request via duplicate() or change a bunch of parameters with a single call to initialize().
Accessing the Session
If you have a session attached to the request, you can access it via the getSession() method; the hasPreviousSession() method tells you if the request contains a session which was started in one of the previous requests.
Accessing Accept-*
Headers Data
You can easily access basic data extracted from Accept-*
headers
by using the following methods:
- getAcceptableContentTypes()
- Returns the list of accepted content types ordered by descending quality.
- getLanguages()
- Returns the list of accepted languages ordered by descending quality.
- getCharsets()
- Returns the list of accepted charsets ordered by descending quality.
- getEncodings()
- Returns the list of accepted encodings ordered by descending quality.
If you need to get full access to parsed data from Accept
, Accept-Language
,
Accept-Charset
or Accept-Encoding
, you can use
AcceptHeader utility class:
1 2 3 4 5 6 7 8 9 10 11 12
use Symfony\Component\HttpFoundation\AcceptHeader;
$acceptHeader = AcceptHeader::fromString($request->headers->get('Accept'));
if ($acceptHeader->has('text/html')) {
$item = $acceptHeader->get('text/html');
$charset = $item->getAttribute('charset', 'utf-8');
$quality = $item->getQuality();
}
// Accept header items are sorted by descending quality
$acceptHeaders = AcceptHeader::fromString($request->headers->get('Accept'))
->all();
Accessing other Data
The Request
class has many other methods that you can use to access the
request information. Have a look at
the Request API
for more information about them.
Overriding the Request
The Request
class should not be overridden as it is a data object that
represents an HTTP message. But when moving from a legacy system, adding
methods or changing some default behavior might help. In that case, register a
PHP callable that is able to create an instance of your Request
class:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
use AppBundle\Http\SpecialRequest;
use Symfony\Component\HttpFoundation\Request;
Request::setFactory(function (
array $query = array(),
array $request = array(),
array $attributes = array(),
array $cookies = array(),
array $files = array(),
array $server = array(),
$content = null
) {
return new SpecialRequest(
$query,
$request,
$attributes,
$cookies,
$files,
$server,
$content
);
});
$request = Request::createFromGlobals();
Response
A Response object holds all the information that needs to be sent back to the client from a given request. The constructor takes up to three arguments: the response content, the status code, and an array of HTTP headers:
1 2 3 4 5 6 7
use Symfony\Component\HttpFoundation\Response;
$response = new Response(
'Content',
Response::HTTP_OK,
array('content-type' => 'text/html')
);
This information can also be manipulated after the Response object creation:
1 2 3 4 5 6
$response->setContent('Hello World');
// the headers public attribute is a ResponseHeaderBag
$response->headers->set('Content-Type', 'text/plain');
$response->setStatusCode(Response::HTTP_NOT_FOUND);
When setting the Content-Type
of the Response, you can set the charset,
but it is better to set it via the
setCharset() method:
1
$response->setCharset('ISO-8859-1');
Note that by default, Symfony assumes that your Responses are encoded in UTF-8.
Sending the Response
Before sending the Response, you can optionally call the
prepare() method to fix any
incompatibility with the HTTP specification (e.g. a wrong Content-Type
header):
1
$response->prepare($request);
Sending the response to the client is then as simple as calling send():
1
$response->send();
Setting Cookies
The response cookies can be manipulated through the headers
public
attribute:
1 2 3
use Symfony\Component\HttpFoundation\Cookie;
$response->headers->setCookie(new Cookie('foo', 'bar'));
The setCookie() method takes an instance of Cookie as an argument.
You can clear a cookie via the clearCookie() method.
Managing the HTTP Cache
The Response class has a rich set of methods to manipulate the HTTP headers related to the cache:
- setPublic();
- setPrivate();
- expire();
- setExpires();
- setMaxAge();
- setSharedMaxAge();
- setTtl();
- setClientTtl();
- setLastModified();
- setEtag();
- setVary();
The setCache() method can be used to set the most commonly used cache information in one method call:
1 2 3 4 5 6 7 8
$response->setCache(array(
'etag' => 'abcdef',
'last_modified' => new \DateTime(),
'max_age' => 600,
's_maxage' => 600,
'private' => false,
'public' => true,
));
To check if the Response validators (ETag
, Last-Modified
) match a
conditional value specified in the client Request, use the
isNotModified()
method:
1 2 3
if ($response->isNotModified($request)) {
$response->send();
}
If the Response is not modified, it sets the status code to 304 and removes the actual response content.
Redirecting the User
To redirect the client to another URL, you can use the RedirectResponse class:
1 2 3
use Symfony\Component\HttpFoundation\RedirectResponse;
$response = new RedirectResponse('http://example.com/');
Streaming a Response
The StreamedResponse class allows you to stream the Response back to the client. The response content is represented by a PHP callable instead of a string:
1 2 3 4 5 6 7 8 9 10 11
use Symfony\Component\HttpFoundation\StreamedResponse;
$response = new StreamedResponse();
$response->setCallback(function () {
var_dump('Hello World');
flush();
sleep(2);
var_dump('Hello World');
flush();
});
$response->send();
Note
The flush()
function does not flush buffering. If ob_start()
has
been called before or the output_buffering
php.ini
option is enabled,
you must call ob_flush()
before flush()
.
Additionally, PHP isn't the only layer that can buffer output. Your web server might also buffer based on its configuration. Some servers, such as Nginx, let you disable buffering at the config level or by adding a special HTTP header in the response:
1 2
// disables FastCGI buffering in Nginx only for this response
$response->headers->set('X-Accel-Buffering', 'no')
Serving Files
When sending a file, you must add a Content-Disposition
header to your
response. While creating this header for basic file downloads is easy, using
non-ASCII filenames is more involving. The
makeDisposition()
abstracts the hard work behind a simple API:
1 2 3 4 5 6 7 8 9 10 11 12
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\ResponseHeaderBag;
$fileContent = ...; // the generated file content
$response = new Response($fileContent);
$disposition = $response->headers->makeDisposition(
ResponseHeaderBag::DISPOSITION_ATTACHMENT,
'foo.pdf'
);
$response->headers->set('Content-Disposition', $disposition);
Alternatively, if you are serving a static file, you can use a BinaryFileResponse:
1 2 3 4
use Symfony\Component\HttpFoundation\BinaryFileResponse;
$file = 'path/to/file.txt';
$response = new BinaryFileResponse($file);
The BinaryFileResponse
will automatically handle Range
and
If-Range
headers from the request. It also supports X-Sendfile
(see for Nginx and Apache). To make use of it, you need to determine
whether or not the X-Sendfile-Type
header should be trusted and call
trustXSendfileTypeHeader()
if it should:
1
BinaryFileResponse::trustXSendfileTypeHeader();
With the BinaryFileResponse
, you can still set the Content-Type
of the sent file,
or change its Content-Disposition
:
1 2 3 4 5 6
// ...
$response->headers->set('Content-Type', 'text/plain');
$response->setContentDisposition(
ResponseHeaderBag::DISPOSITION_ATTACHMENT,
'filename.txt'
);
It is possible to delete the file after the request is sent with the
deleteFileAfterSend() method.
Please note that this will not work when the X-Sendfile
header is set.
Note
If you just created the file during this same request, the file may be sent
without any content. This may be due to cached file stats that return zero for
the size of the file. To fix this issue, call clearstatcache(true, $file)
with the path to the binary file.
Creating a JSON Response
Any type of response can be created via the Response class by setting the right content and headers. A JSON response might look like this:
1 2 3 4 5 6 7
use Symfony\Component\HttpFoundation\Response;
$response = new Response();
$response->setContent(json_encode(array(
'data' => 123,
)));
$response->headers->set('Content-Type', 'application/json');
There is also a helpful JsonResponse class, which can make this even easier:
1 2 3 4 5 6
use Symfony\Component\HttpFoundation\JsonResponse;
$response = new JsonResponse();
$response->setData(array(
'data' => 123,
));
This encodes your array of data to JSON and sets the Content-Type
header
to application/json
.
Caution
To avoid XSSI JSON Hijacking, you should pass an associative array
as the outer-most array to JsonResponse
and not an indexed array so
that the final result is an object (e.g. {"object": "not inside an array"}
)
instead of an array (e.g. [{"object": "inside an array"}]
). Read
the OWASP guidelines for more information.
Only methods that respond to GET requests are vulnerable to XSSI 'JSON Hijacking'. Methods responding to POST requests only remain unaffected.
JSONP Callback
If you're using JSONP, you can set the callback function that the data should be passed to:
1
$response->setCallback('handleResponse');
In this case, the Content-Type
header will be text/javascript
and
the response content will look like this:
1
handleResponse({'data': 123});
Session
The session information is in its own document: Session Management.
Learn More
- Configuring Sessions and Save Handlers
- Integrating with Legacy Sessions
- Testing with Sessions
- Session Management
- Trusting Proxies
- Controller
- How to Manually Validate a CSRF Token in a Controller
- How to Customize Error Pages
- How to Forward Requests to another Controller
- How to Define Controllers as Services
- How to Create a SOAP Web Service in a Symfony Controller
- How to Upload Files
- Avoid Starting Sessions for Anonymous Users
- Limit Session Metadata Writes
- Making the Locale "Sticky" during a User's Session
- Bridge a legacy Application with Symfony Sessions
- Session Proxy Examples
- Configuring the Directory where Session Files are Saved
- Cache Invalidation
- Varying the Response for HTTP Cache
- Working with Edge Side Includes
- HTTP Cache Expiration
- Caching Pages that Contain CSRF Protected Forms
- HTTP Cache Validation
- How to Use Varnish to Speed up my Website