Symfony2 API
Class

Symfony\Component\HttpFoundation\Request

class Request

Request represents an HTTP request.

The methods dealing with URL accept / return a raw path (% encoded): * getBasePath * getBaseUrl * getPathInfo * getRequestUri * getUri * getUriForPath

Constants

HEADER_CLIENT_IP

HEADER_CLIENT_HOST

HEADER_CLIENT_PROTO

HEADER_CLIENT_PORT

METHOD_HEAD

METHOD_GET

METHOD_POST

METHOD_PUT

METHOD_PATCH

METHOD_DELETE

METHOD_PURGE

METHOD_OPTIONS

METHOD_TRACE

METHOD_CONNECT

Properties

ParameterBag $attributes Custom parameters
ParameterBag $request Request body parameters ($_POST)
ParameterBag $query Query string parameters ($_GET)
ServerBag $server Server and execution environment parameters ($_SERVER)
FileBag $files Uploaded files ($_FILES)
ParameterBag $cookies Cookies ($_COOKIE)
HeaderBag $headers Headers (taken from the $_SERVER)

Methods

__construct(array $query = array(), array $request = array(), array $attributes = array(), array $cookies = array(), array $files = array(), array $server = array(), string $content = null)

Constructor.

initialize(array $query = array(), array $request = array(), array $attributes = array(), array $cookies = array(), array $files = array(), array $server = array(), string $content = null)

Sets the parameters for this request.

static Request createFromGlobals()

Creates a new request with values from PHP's super globals.

static Request create(string $uri, string $method = 'GET', array $parameters = array(), array $cookies = array(), array $files = array(), array $server = array(), string $content = null)

Creates a Request based on a given URI and configuration.

static  setFactory(callable|null $callable)

Sets a callable able to create a Request instance.

Request duplicate(array $query = null, array $request = null, array $attributes = null, array $cookies = null, array $files = null, array $server = null)

Clones a request and overrides some of its parameters.

__clone()

Clones the current request.

string __toString()

Returns the request as a string.

overrideGlobals()

Overrides the PHP global variables according to this request instance.

static  setTrustedProxies(array $proxies)

Sets a list of trusted proxies.

static array getTrustedProxies()

Gets the list of trusted proxies.

static  setTrustedHosts(array $hostPatterns)

Sets a list of trusted host patterns.

static array getTrustedHosts()

Gets the list of trusted host patterns.

static  setTrustedHeaderName(string $key, string $value)

Sets the name for trusted headers.

static string getTrustedHeaderName(string $key)

Gets the trusted proxy header name.

static string normalizeQueryString(string $qs)

Normalizes a query string.

static  enableHttpMethodParameterOverride()

Enables support for the _method request parameter to determine the intended HTTP method.

static bool getHttpMethodParameterOverride()

Checks whether support for the _method request parameter is enabled.

mixed get(string $key, mixed $default = null, bool $deep = false)

Gets a "parameter" value.

SessionInterface|null getSession()

Gets the Session.

bool hasPreviousSession()

Whether the request contains a Session which was started in one of the previous requests.

bool hasSession()

Whether the request contains a Session object.

setSession(SessionInterface $session)

Sets the Session.

array getClientIps()

Returns the client IP addresses.

string getClientIp()

Returns the client IP address.

string getScriptName()

Returns current script name.

string getPathInfo()

Returns the path being requested relative to the executed script.

string getBasePath()

Returns the root path from which this request is executed.

string getBaseUrl()

Returns the root URL from which this request is executed.

string getScheme()

Gets the request's scheme.

string getPort()

Returns the port on which the request is made.

string|null getUser()

Returns the user.

string|null getPassword()

Returns the password.

string getUserInfo()

Gets the user info.

string getHttpHost()

Returns the HTTP host being requested.

string getRequestUri()

Returns the requested URI (path and query string).

string getSchemeAndHttpHost()

Gets the scheme and HTTP host.

string getUri()

Generates a normalized URI (URL) for the Request.

string getUriForPath(string $path)

Generates a normalized URI for the given path.

string|null getQueryString()

Generates the normalized query string for the Request.

bool isSecure()

Checks whether the request is secure or not.

string getHost()

Returns the host name.

setMethod(string $method)

Sets the request method.

string getMethod()

Gets the request "intended" method.

string getRealMethod()

Gets the "real" request method.

string getMimeType(string $format)

Gets the mime type associated with the format.

string|null getFormat(string $mimeType)

Gets the format associated with the mime type.

setFormat(string $format, string|array $mimeTypes)

Associates a format with mime types.

string getRequestFormat(string $default = 'html')

Gets the request format.

setRequestFormat(string $format)

Sets the request format.

string|null getContentType()

Gets the format associated with the request.

setDefaultLocale(string $locale)

Sets the default locale.

string getDefaultLocale()

Get the default locale.

setLocale(string $locale)

Sets the locale.

string getLocale()

Get the locale.

bool isMethod(string $method)

Checks if the request method is of specified type.

bool isMethodSafe()

Checks whether the method is safe or not.

string|resource getContent(bool $asResource = false)

Returns the request body content.

array getETags()

Gets the Etags.

bool isNoCache()

string|null getPreferredLanguage(array $locales = null)

Returns the preferred language.

array getLanguages()

Gets a list of languages acceptable by the client browser.

array getCharsets()

Gets a list of charsets acceptable by the client browser.

array getEncodings()

Gets a list of encodings acceptable by the client browser.

array getAcceptableContentTypes()

Gets a list of content types acceptable by the client browser

bool isXmlHttpRequest()

Returns true if the request is a XMLHttpRequest.

Details

at line 230
public __construct(array $query = array(), array $request = array(), array $attributes = array(), array $cookies = array(), array $files = array(), array $server = array(), string $content = null)

Constructor.

Parameters

array $query The GET parameters
array $request The POST parameters
array $attributes The request attributes (parameters parsed from the PATH_INFO, ...)
array $cookies The COOKIE parameters
array $files The FILES parameters
array $server The SERVER parameters
string $content The raw body data

at line 250
public initialize(array $query = array(), array $request = array(), array $attributes = array(), array $cookies = array(), array $files = array(), array $server = array(), string $content = null)

Sets the parameters for this request.

This method also re-initializes all properties.

Parameters

array $query The GET parameters
array $request The POST parameters
array $attributes The request attributes (parameters parsed from the PATH_INFO, ...)
array $cookies The COOKIE parameters
array $files The FILES parameters
array $server The SERVER parameters
string $content The raw body data

at line 280
static public Request createFromGlobals()

Creates a new request with values from PHP's super globals.

Return Value

Request A new request

at line 312
static public Request create(string $uri, string $method = 'GET', array $parameters = array(), array $cookies = array(), array $files = array(), array $server = array(), string $content = null)

Creates a Request based on a given URI and configuration.

The information contained in the URI always take precedence over the other information (server and parameters).

Parameters

string $uri The URI
string $method The HTTP method
array $parameters The query (GET) or request (POST) parameters
array $cookies The request cookies ($_COOKIE)
array $files The request files ($_FILES)
array $server The server parameters ($_SERVER)
string $content The raw body data

Return Value

Request A Request instance

at line 413
static public setFactory(callable|null $callable)

Sets a callable able to create a Request instance.

This is mainly useful when you need to override the Request class to keep BC with an existing system. It should not be used for any other purpose.

Parameters

callable|null $callable A PHP callable

at line 432
public Request duplicate(array $query = null, array $request = null, array $attributes = null, array $cookies = null, array $files = null, array $server = null)

Clones a request and overrides some of its parameters.

Parameters

array $query The GET parameters
array $request The POST parameters
array $attributes The request attributes (parameters parsed from the PATH_INFO, ...)
array $cookies The COOKIE parameters
array $files The FILES parameters
array $server The SERVER parameters

Return Value

Request The duplicated request

at line 482
public __clone()

Clones the current request.

Note that the session is not cloned as duplicated requests are most of the time sub-requests of the main one.

at line 498
public string __toString()

Returns the request as a string.

Return Value

string The request

at line 514
public overrideGlobals()

Overrides the PHP global variables according to this request instance.

It overrides $GET, $POST, $REQUEST, $SERVER, $COOKIE. $FILES is never overridden, see rfc1867

at line 552
static public setTrustedProxies(array $proxies)

Sets a list of trusted proxies.

You should only list the reverse proxies that you manage directly.

Parameters

array $proxies A list of trusted proxies

at line 562
static public array getTrustedProxies()

Gets the list of trusted proxies.

Return Value

array An array of trusted proxies.

at line 574
static public setTrustedHosts(array $hostPatterns)

Sets a list of trusted host patterns.

You should only list the hosts you manage using regexs.

Parameters

array $hostPatterns A list of trusted host patterns

at line 588
static public array getTrustedHosts()

Gets the list of trusted host patterns.

Return Value

array An array of trusted host patterns.

at line 610
static public setTrustedHeaderName(string $key, string $value)

Sets the name for trusted headers.

The following header keys are supported:

Setting an empty value allows to disable the trusted header for the given key.

Parameters

string $key The header key
string $value The header name

Exceptions

InvalidArgumentException

at line 628
static public string getTrustedHeaderName(string $key)

Gets the trusted proxy header name.

Parameters

string $key The header key

Return Value

string The header name

Exceptions

InvalidArgumentException

at line 647
static public string normalizeQueryString(string $qs)

Normalizes a query string.

It builds a normalized query string, where keys/value pairs are alphabetized, have consistent escaping and unneeded delimiters are removed.

Parameters

string $qs Query string

Return Value

string A normalized query string for the Request

at line 691
static public enableHttpMethodParameterOverride()

Enables support for the _method request parameter to determine the intended HTTP method.

Be warned that enabling this feature might lead to CSRF issues in your code. Check that you are using CSRF tokens when required. If the HTTP method parameter override is enabled, an html-form with method "POST" can be altered and used to send a "PUT" or "DELETE" request via the _method request parameter. If these methods are not protected against CSRF, this presents a possible vulnerability.

The HTTP method can only be overridden when the real HTTP method is POST.

at line 701
static public bool getHttpMethodParameterOverride()

Checks whether support for the _method request parameter is enabled.

Return Value

bool True when the _method request parameter is enabled, false otherwise

at line 727
public mixed get(string $key, mixed $default = null, bool $deep = false)

Gets a "parameter" value.

This method is mainly useful for libraries that want to provide some flexibility.

Order of precedence: GET, PATH, POST

Avoid using this method in controllers:

It is better to explicitly get request parameters from the appropriate public property instead (query, attributes, request).

Parameters

string $key the key
mixed $default the default value
bool $deep is parameter deep in multidimensional array

Return Value

mixed

at line 751
public SessionInterface|null getSession()

Gets the Session.

Return Value

SessionInterface|null The session

at line 764
public bool hasPreviousSession()

Whether the request contains a Session which was started in one of the previous requests.

Return Value

bool

at line 781
public bool hasSession()

Whether the request contains a Session object.

This method does not give any information about the state of the session object, like whether the session is started or not. It is just a way to check if this Request is associated with a Session instance.

Return Value

bool true when the Request contains a Session object, false otherwise

at line 793
public setSession(SessionInterface $session)

Sets the Session.

Parameters

SessionInterface $session The Session

at line 811
public array getClientIps()

Returns the client IP addresses.

In the returned array the most trusted IP address is first, and the least trusted one last. The "real" client IP address is the last one, but this is also the least trusted one. Trusted proxies are stripped.

Use this method carefully; you should use getClientIp() instead.

Return Value

array The client IP addresses

See also

getClientIp()

at line 859
public string getClientIp()

Returns the client IP address.

This method can read the client IP address from the "X-Forwarded-For" header when trusted proxies were set via "setTrustedProxies()". The "X-Forwarded-For" header value is a comma+space separated list of IP addresses, the left-most being the original client, and each successive proxy that passed the request adding the IP address where it received the request from.

If your reverse proxy uses a different header name than "X-Forwarded-For", ("Client-Ip" for instance), configure it via "setTrustedHeaderName()" with the "client-ip" key.

Return Value

string The client IP address

See also

getClientIps()
http://en.wikipedia.org/wiki/X-Forwarded-For

at line 873
public string getScriptName()

Returns current script name.

Return Value

string

at line 894
public string getPathInfo()

Returns the path being requested relative to the executed script.

The path info always starts with a /.

Suppose this request is instantiated from /mysite on localhost:

Return Value

string The raw path (i.e. not urldecoded)

at line 917
public string getBasePath()

Returns the root path from which this request is executed.

Suppose that an index.php file instantiates this request object:

Return Value

string The raw path (i.e. not urldecoded)

at line 938
public string getBaseUrl()

Returns the root URL from which this request is executed.

The base URL never ends with a /.

This is similar to getBasePath(), except that it also includes the script filename (e.g. index.php) if one exists.

Return Value

string The raw URL (i.e. not urldecoded)

at line 954
public string getScheme()

Gets the request's scheme.

Return Value

string

at line 974
public string getPort()

Returns the port on which the request is made.

This method can read the client port from the "X-Forwarded-Port" header when trusted proxies were set via "setTrustedProxies()".

The "X-Forwarded-Port" header must contain the client port.

If your reverse proxy uses a different header name than "X-Forwarded-Port", configure it via "setTrustedHeaderName()" with the "client-port" key.

Return Value

string

at line 1008
public string|null getUser()

Returns the user.

Return Value

string|null

at line 1018
public string|null getPassword()

Returns the password.

Return Value

string|null

at line 1028
public string getUserInfo()

Gets the user info.

Return Value

string A user name and, optionally, scheme-specific information about how to gain authorization to access the server

at line 1049
public string getHttpHost()

Returns the HTTP host being requested.

The port name will be appended to the host if it's non-standard.

Return Value

string

at line 1068
public string getRequestUri()

Returns the requested URI (path and query string).

Return Value

string The raw URI (i.e. not URI decoded)

at line 1085
public string getSchemeAndHttpHost()

Gets the scheme and HTTP host.

If the URL was called with basic authentication, the user and the password are not added to the generated string.

Return Value

string The scheme and HTTP host

at line 1099
public string getUri()

Generates a normalized URI (URL) for the Request.

Return Value

string A normalized URI (URL) for the Request

See also

getQueryString()

at line 1117
public string getUriForPath(string $path)

Generates a normalized URI for the given path.

Parameters

string $path A path to use instead of the current one

Return Value

string The normalized URI for the path

at line 1132
public string|null getQueryString()

Generates the normalized query string for the Request.

It builds a normalized query string, where keys/value pairs are alphabetized and have consistent escaping.

Return Value

string|null A normalized query string for the Request

at line 1155
public bool isSecure()

Checks whether the request is secure or not.

This method can read the client port from the "X-Forwarded-Proto" header when trusted proxies were set via "setTrustedProxies()".

The "X-Forwarded-Proto" header must contain the protocol: "https" or "http".

If your reverse proxy uses a different header name than "X-Forwarded-Proto" ("SSL_HTTPS" for instance), configure it via "setTrustedHeaderName()" with the "client-proto" key.

Return Value

bool

at line 1183
public string getHost()

Returns the host name.

This method can read the client port from the "X-Forwarded-Host" header when trusted proxies were set via "setTrustedProxies()".

The "X-Forwarded-Host" header must contain the client host name.

If your reverse proxy uses a different header name than "X-Forwarded-Host", configure it via "setTrustedHeaderName()" with the "client-host" key.

Return Value

string

Exceptions

UnexpectedValueException when the host name is invalid

at line 1234
public setMethod(string $method)

Sets the request method.

Parameters

string $method

at line 1257
public string getMethod()

Gets the request "intended" method.

If the X-HTTP-Method-Override header is set, and if the method is a POST, then it is used to determine the "real" intended HTTP method.

The _method request parameter can also be used to determine the HTTP method, but only if enableHttpMethodParameterOverride() has been called.

The method is always an uppercased string.

Return Value

string The request method

at line 1281
public string getRealMethod()

Gets the "real" request method.

Return Value

string The request method

See also

getMethod

at line 1295
public string getMimeType(string $format)

Gets the mime type associated with the format.

Parameters

string $format The format

Return Value

string The associated mime type (null if not found)

at line 1313
public string|null getFormat(string $mimeType)

Gets the format associated with the mime type.

Parameters

string $mimeType The associated mime type

Return Value

string|null The format (null if not found)

at line 1338
public setFormat(string $format, string|array $mimeTypes)

Associates a format with mime types.

Parameters

string $format The format
string|array $mimeTypes The associated mime types (the preferred one must be the first as it will be used as the content type)

at line 1362
public string getRequestFormat(string $default = 'html')

Gets the request format.

Here is the process to determine the format:

Parameters

string $default The default format

Return Value

string The request format

at line 1378
public setRequestFormat(string $format)

Sets the request format.

Parameters

string $format The request format.

at line 1390
public string|null getContentType()

Gets the format associated with the request.

Return Value

string|null The format (null if no content type is present)

at line 1402
public setDefaultLocale(string $locale)

Sets the default locale.

Parameters

string $locale

at line 1416
public string getDefaultLocale()

Get the default locale.

Return Value

string

at line 1428
public setLocale(string $locale)

Sets the locale.

Parameters

string $locale

at line 1438
public string getLocale()

Get the locale.

Return Value

string

at line 1450
public bool isMethod(string $method)

Checks if the request method is of specified type.

Parameters

string $method Uppercase request method (GET, POST etc).

Return Value

bool

at line 1462
public bool isMethodSafe()

Checks whether the method is safe or not.

Return Value

bool

at line 1476
public string|resource getContent(bool $asResource = false)

Returns the request body content.

Parameters

bool $asResource If true, a resource will be returned

Return Value

string|resource The request body content or a resource to read the body stream.

Exceptions

LogicException

at line 1500
public array getETags()

Gets the Etags.

Return Value

array The entity tags

at line 1508
public bool isNoCache()

Return Value

bool

at line 1522
public string|null getPreferredLanguage(array $locales = null)

Returns the preferred language.

Parameters

array $locales An array of ordered available locales

Return Value

string|null The preferred locale

at line 1557
public array getLanguages()

Gets a list of languages acceptable by the client browser.

Return Value

array Languages ordered in the user browser preferences

at line 1599
public array getCharsets()

Gets a list of charsets acceptable by the client browser.

Return Value

array List of charsets in preferable order

at line 1613
public array getEncodings()

Gets a list of encodings acceptable by the client browser.

Return Value

array List of encodings in preferable order

at line 1629
public array getAcceptableContentTypes()

Gets a list of content types acceptable by the client browser

Return Value

array List of content types in preferable order

at line 1649
public bool isXmlHttpRequest()

Returns true if the request is a XMLHttpRequest.

It works if your JavaScript library sets an X-Requested-With HTTP header. It is known to work with common JavaScript frameworks:

Return Value

bool true if the request is an XMLHttpRequest, false otherwise