The HttpFoundation Component

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 sub-set 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 its 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;

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 takes 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:

// the query string is '?foo=bar'

$request->query->get('foo');
// returns bar

$request->query->get('bar');
// returns null

$request->query->get('bar', 'bar');
// returns 'bar'

When PHP imports the request query, it handles request parameters like foo[bar]=bar 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. But sometimes, you might want to get the value for the “original” parameter name: foo[bar]. This is possible with all the ParameterBag getters like get() via the third argument:

// the query string is '?foo[bar]=bar'

$request->query->get('foo');
// returns array('bar' => 'bar')

$request->query->get('foo[bar]');
// returns null

$request->query->get('foo[bar]', null, true);
// returns 'bar'

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. For information on how this is used in the Symfony framework, see the Symfony book.

Finally, the raw data sent with the request body can be accessed using getContent():

$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:

// 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:

$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():

$request->overrideGlobals();

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.

2.4 新版功能: The getEncodings() method was introduced in Symfony 2.4.

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:

use SymfonyComponentHttpFoundationAcceptHeader;

$accept = AcceptHeader::fromString($request->headers->get('Accept'));
if ($accept->has('text/html')) {
    $item = $accept->get('text/html');
    $charset = $item->getAttribute('charset', 'utf-8');
    $quality = $item->getQuality();
}

// Accept header items are sorted by descending quality
$accepts = 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:

use SymfonyComponentHttpFoundationRequest;

Request::setFactory(function (
    array $query = array(),
    array $request = array(),
    array $attributes = array(),
    array $cookies = array(),
    array $files = array(),
    array $server = array(),
    $content = null
) {
    return SpecialRequest::create(
        $query,
        $request,
        $attributes,
        $cookies,
        $files,
        $server,
        $content
    );
});

$request = Request::createFromGlobals();

Sending the Response¶

Before sending the Response, you can ensure that it is compliant with the HTTP specification by calling the prepare() method:

$response->prepare($request);

Sending the response to the client is then as simple as calling send():

$response->send();

Setting Cookies¶

The response cookies can be manipulated through the headers public attribute:

use SymfonyComponentHttpFoundationCookie;

$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:

$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:

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:

use SymfonyComponentHttpFoundationRedirectResponse;

$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:

use SymfonyComponentHttpFoundationStreamedResponse;

$response = new StreamedResponse();
$response->setCallback(function () {
    echo 'Hello World';
    flush();
    sleep(2);
    echo 'Hello World';
    flush();
});
$response->send();

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:

use SymfonyComponentHttpFoundationResponseHeaderBag;

$d = $response->headers->makeDisposition(
    ResponseHeaderBag::DISPOSITION_ATTACHMENT,
    'foo.pdf'
);

$response->headers->set('Content-Disposition', $d);

Alternatively, if you are serving a static file, you can use a BinaryFileResponse:

use SymfonyComponentHttpFoundationBinaryFileResponse;

$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:

BinaryFileResponse::trustXSendfileTypeHeader();

You can still set the Content-Type of the sent file, or change its Content-Disposition:

$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.

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:

use SymfonyComponentHttpFoundationResponse;

$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:

use SymfonyComponentHttpFoundationJsonResponse;

$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.

JSONP Callback¶

If you’re using JSONP, you can set the callback function that the data should be passed to:

$response->setCallback('handleResponse');

In this case, the Content-Type header will be text/javascript and the response content will look like this:

handleResponse({'data': 123});