\Symfony\Component\HttpFoundation\TestsNewRequest

Request represents an HTTP request.

The methods dealing with URL accept / return a raw path (% encoded):

  • getBasePath
  • getBaseUrl
  • getPathInfo
  • getRequestUri
  • getUri
  • getUriForPath

Summary

Methods
Properties
Constants
__construct()
initialize()
createFromGlobals()
create()
setFactory()
duplicate()
__clone()
__toString()
overrideGlobals()
setTrustedProxies()
getTrustedProxies()
getTrustedHeaderSet()
setTrustedHosts()
getTrustedHosts()
setTrustedHeaderName()
getTrustedHeaderName()
normalizeQueryString()
enableHttpMethodParameterOverride()
getHttpMethodParameterOverride()
get()
getSession()
hasPreviousSession()
hasSession()
setSession()
getClientIps()
getClientIp()
getScriptName()
getPathInfo()
getBasePath()
getBaseUrl()
getScheme()
getPort()
getUser()
getPassword()
getUserInfo()
getHttpHost()
getRequestUri()
getSchemeAndHttpHost()
getUri()
getUriForPath()
getRelativeUriForPath()
getQueryString()
isSecure()
getHost()
setMethod()
getMethod()
getRealMethod()
getMimeType()
getMimeTypes()
getFormat()
setFormat()
getRequestFormat()
setRequestFormat()
getContentType()
setDefaultLocale()
getDefaultLocale()
setLocale()
getLocale()
isMethod()
isMethodSafe()
isMethodIdempotent()
isMethodCacheable()
getProtocolVersion()
getContent()
getETags()
isNoCache()
getPreferredLanguage()
getLanguages()
getCharsets()
getEncodings()
getAcceptableContentTypes()
isXmlHttpRequest()
isFromTrustedProxy()
getFoo()
$attributes
$request
$query
$server
$files
$cookies
$headers
HEADER_FORWARDED
HEADER_X_FORWARDED_FOR
HEADER_X_FORWARDED_HOST
HEADER_X_FORWARDED_PROTO
HEADER_X_FORWARDED_PORT
HEADER_X_FORWARDED_ALL
HEADER_X_FORWARDED_AWS_ELB
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
prepareRequestUri()
prepareBaseUrl()
prepareBasePath()
preparePathInfo()
initializeFormats()
$trustedProxies
$trustedHostPatterns
$trustedHosts
$trustedHeaders
$httpMethodParameterOverride
$content
$languages
$charsets
$encodings
$acceptableContentTypes
$pathInfo
$requestUri
$baseUrl
$basePath
$method
$format
$session
$locale
$defaultLocale
$formats
$requestFactory
N/A
setPhpDefaultLocale()
getUrlencodedPrefix()
createRequestFromFactory()
getTrustedValues()
normalizeAndFilterClientIps()
$isHostValid
$isForwardedValid
$trustedHeaderSet
$trustedHeaderNames
$forwardedParams
N/A

Constants

HEADER_FORWARDED

HEADER_FORWARDED = 1

HEADER_X_FORWARDED_FOR

HEADER_X_FORWARDED_FOR = 2

HEADER_X_FORWARDED_HOST

HEADER_X_FORWARDED_HOST = 4

HEADER_X_FORWARDED_PROTO

HEADER_X_FORWARDED_PROTO = 8

HEADER_X_FORWARDED_PORT

HEADER_X_FORWARDED_PORT = 16

HEADER_X_FORWARDED_ALL

HEADER_X_FORWARDED_ALL = 30

HEADER_X_FORWARDED_AWS_ELB

HEADER_X_FORWARDED_AWS_ELB = 26

HEADER_CLIENT_IP

HEADER_CLIENT_IP = self::HEADER_X_FORWARDED_FOR

HEADER_CLIENT_HOST

HEADER_CLIENT_HOST = self::HEADER_X_FORWARDED_HOST

HEADER_CLIENT_PROTO

HEADER_CLIENT_PROTO = self::HEADER_X_FORWARDED_PROTO

HEADER_CLIENT_PORT

HEADER_CLIENT_PORT = self::HEADER_X_FORWARDED_PORT

METHOD_HEAD

METHOD_HEAD = 'HEAD'

METHOD_GET

METHOD_GET = 'GET'

METHOD_POST

METHOD_POST = 'POST'

METHOD_PUT

METHOD_PUT = 'PUT'

METHOD_PATCH

METHOD_PATCH = 'PATCH'

METHOD_DELETE

METHOD_DELETE = 'DELETE'

METHOD_PURGE

METHOD_PURGE = 'PURGE'

METHOD_OPTIONS

METHOD_OPTIONS = 'OPTIONS'

METHOD_TRACE

METHOD_TRACE = 'TRACE'

METHOD_CONNECT

METHOD_CONNECT = 'CONNECT'

Properties

$trustedProxies

$trustedProxies : array<mixed,string>

Type

array<mixed,string>

$trustedHostPatterns

$trustedHostPatterns : array<mixed,string>

Type

array<mixed,string>

$trustedHosts

$trustedHosts : array<mixed,string>

Type

array<mixed,string>

$trustedHeaders

$trustedHeaders : 

Names for headers that can be trusted when using trusted proxies.

The FORWARDED header is the standard as of rfc7239.

The other headers are non-standard, but widely used by popular reverse proxies (like Apache mod_proxy or Amazon EC2).

Type

$httpMethodParameterOverride

$httpMethodParameterOverride : 

Type

$content

$content : string|resource|false|null

Type

string|resource|false|null

$languages

$languages : array

Type

array

$charsets

$charsets : array

Type

array

$encodings

$encodings : array

Type

array

$acceptableContentTypes

$acceptableContentTypes : array

Type

array

$pathInfo

$pathInfo : string

Type

string

$requestUri

$requestUri : string

Type

string

$baseUrl

$baseUrl : string

Type

string

$basePath

$basePath : string

Type

string

$method

$method : string

Type

string

$format

$format : string

Type

string

$locale

$locale : string

Type

string

$defaultLocale

$defaultLocale : string

Type

string

$formats

$formats : array

Type

array

$requestFactory

$requestFactory : 

Type

$isHostValid

$isHostValid : 

Type

$isForwardedValid

$isForwardedValid : 

Type

$trustedHeaderSet

$trustedHeaderSet : 

Type

$trustedHeaderNames

$trustedHeaderNames : 

Type

$forwardedParams

$forwardedParams : 

Type

Methods

__construct()

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

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|resource|null $content

The raw body data

initialize()

initialize(array  $query = array(), array  $request = array(), array  $attributes = array(), array  $cookies = array(), array  $files = array(), array  $server = array(), string|resource|null  $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|resource|null $content

The raw body data

createFromGlobals()

createFromGlobals() : static

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

Returns

static

create()

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

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|resource|null $content

The raw body data

Returns

static

setFactory()

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

duplicate()

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

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

Returns

static

__clone()

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

__toString()

__toString() : string

Returns the request as a string.

Returns

string —

The request

overrideGlobals()

overrideGlobals() 

Overrides the PHP global variables according to this request instance.

It overrides $_GET, $_POST, $_REQUEST, $_SERVER, $_COOKIE. $_FILES is never overridden, see rfc1867

setTrustedProxies()

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

Throws

\InvalidArgumentException

When $trustedHeaderSet is invalid

getTrustedProxies()

getTrustedProxies() : array

Gets the list of trusted proxies.

Returns

array —

An array of trusted proxies

getTrustedHeaderSet()

getTrustedHeaderSet() : integer

Gets the set of trusted headers from trusted proxies.

Returns

integer —

A bit field of Request::HEADER_* that defines which headers are trusted from your proxies

setTrustedHosts()

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

getTrustedHosts()

getTrustedHosts() : array

Gets the list of trusted host patterns.

Returns

array —

An array of trusted host patterns

setTrustedHeaderName()

setTrustedHeaderName(string  $key, string  $value) 

Sets the name for trusted headers.

The following header keys are supported:

  • Request::HEADER_CLIENT_IP: defaults to X-Forwarded-For (see getClientIp())
  • Request::HEADER_CLIENT_HOST: defaults to X-Forwarded-Host (see getHost())
  • Request::HEADER_CLIENT_PORT: defaults to X-Forwarded-Port (see getPort())
  • Request::HEADER_CLIENT_PROTO: defaults to X-Forwarded-Proto (see getScheme() and isSecure())
  • Request::HEADER_FORWARDED: defaults to Forwarded (see RFC 7239)

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

Throws

\InvalidArgumentException

getTrustedHeaderName()

getTrustedHeaderName(string  $key) : string

Gets the trusted proxy header name.

Parameters

string $key

The header key

Throws

\InvalidArgumentException

Returns

string —

The header name

normalizeQueryString()

normalizeQueryString(string  $qs) : string

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

Returns

string —

A normalized query string for the Request

enableHttpMethodParameterOverride()

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.

getHttpMethodParameterOverride()

getHttpMethodParameterOverride() : boolean

Checks whether support for the _method request parameter is enabled.

Returns

boolean —

True when the _method request parameter is enabled, false otherwise

get()

get(string  $key, mixed  $default = null) : mixed

Gets a "parameter" value from any bag.

This method is mainly useful for libraries that want to provide some flexibility. If you don't need the flexibility in controllers, it is better to explicitly get request parameters from the appropriate public property instead (attributes, query, request).

Order of precedence: PATH (routing placeholders or custom attributes), GET, BODY

Parameters

string $key

The key

mixed $default

The default value if the parameter key does not exist

Returns

mixed

hasPreviousSession()

hasPreviousSession() : boolean

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

Returns

boolean

hasSession()

hasSession() : boolean

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.

Returns

boolean —

true when the Request contains a Session object, false otherwise

getClientIps()

getClientIps() : array

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.

Returns

array —

The client IP addresses

getClientIp()

getClientIp() : string|null

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 the $trustedHeaderSet argument of the Request::setTrustedProxies() method instead.

Returns

string|null —

The client IP address

getScriptName()

getScriptName() : string

Returns current script name.

Returns

string

getBaseUrl()

getBaseUrl() : string

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.

Returns

string —

The raw URL (i.e. not urldecoded)

getScheme()

getScheme() : string

Gets the request's scheme.

Returns

string

getPort()

getPort() : integer|string

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 via the $trustedHeaderSet argument of the Request::setTrustedProxies() method instead.

Returns

integer|string —

can be a string if fetched from the server bag

getUser()

getUser() : string|null

Returns the user.

Returns

string|null

getPassword()

getPassword() : string|null

Returns the password.

Returns

string|null

getUserInfo()

getUserInfo() : string

Gets the user info.

Returns

string —

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

getHttpHost()

getHttpHost() : string

Returns the HTTP host being requested.

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

Returns

string

getRequestUri()

getRequestUri() : string

Returns the requested URI (path and query string).

Returns

string —

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

getSchemeAndHttpHost()

getSchemeAndHttpHost() : string

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.

Returns

string —

The scheme and HTTP host

getUri()

getUri() : string

Generates a normalized URI (URL) for the Request.

Returns

string —

A normalized URI (URL) for the Request

getUriForPath()

getUriForPath(string  $path) : string

Generates a normalized URI for the given path.

Parameters

string $path

A path to use instead of the current one

Returns

string —

The normalized URI for the path

getRelativeUriForPath()

getRelativeUriForPath(string  $path) : string

Returns the path as relative reference from the current Request path.

Only the URIs path component (no schema, host etc.) is relevant and must be given. Both paths must be absolute and not contain relative parts. Relative URLs from one resource to another are useful when generating self-contained downloadable document archives. Furthermore, they can be used to reduce the link size in documents.

Example target paths, given a base path of "/a/b/c/d":

  • "/a/b/c/d" -> ""
  • "/a/b/c/" -> "./"
  • "/a/b/" -> "../"
  • "/a/b/c/other" -> "other"
  • "/a/x/y" -> "../../x/y"

Parameters

string $path

The target path

Returns

string —

The relative target path

getQueryString()

getQueryString() : string|null

Generates the normalized query string for the Request.

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

Returns

string|null —

A normalized query string for the Request

isSecure()

isSecure() : boolean

Checks whether the request is secure or not.

This method can read the client protocol 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 the $trustedHeaderSet argument of the Request::setTrustedProxies() method instead.

Returns

boolean

getHost()

getHost() : string

Returns the host name.

This method can read the client host name 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 the $trustedHeaderSet argument of the Request::setTrustedProxies() method instead.

Throws

\Symfony\Component\HttpFoundation\Exception\SuspiciousOperationException

when the host name is invalid or not trusted

Returns

string

setMethod()

setMethod(string  $method) 

Sets the request method.

Parameters

string $method

getMethod()

getMethod() : string

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.

Returns

string —

The request method

getRealMethod()

getRealMethod() : string

Gets the "real" request method.

Returns

string —

The request method

getMimeType()

getMimeType(string  $format) : string|null

Gets the mime type associated with the format.

Parameters

string $format

The format

Returns

string|null —

The associated mime type (null if not found)

getMimeTypes()

getMimeTypes(string  $format) : array

Gets the mime types associated with the format.

Parameters

string $format

The format

Returns

array —

The associated mime types

getFormat()

getFormat(string  $mimeType) : string|null

Gets the format associated with the mime type.

Parameters

string $mimeType

The associated mime type

Returns

string|null —

The format (null if not found)

setFormat()

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)

getRequestFormat()

getRequestFormat(string  $default = 'html') : string

Gets the request format.

Here is the process to determine the format:

  • format defined by the user (with setRequestFormat())
  • _format request attribute
  • $default

Parameters

string $default

The default format

Returns

string —

The request format

setRequestFormat()

setRequestFormat(string  $format) 

Sets the request format.

Parameters

string $format

The request format

getContentType()

getContentType() : string|null

Gets the format associated with the request.

Returns

string|null —

The format (null if no content type is present)

setDefaultLocale()

setDefaultLocale(string  $locale) 

Sets the default locale.

Parameters

string $locale

getDefaultLocale()

getDefaultLocale() : string

Get the default locale.

Returns

string

setLocale()

setLocale(string  $locale) 

Sets the locale.

Parameters

string $locale

getLocale()

getLocale() : string

Get the locale.

Returns

string

isMethod()

isMethod(string  $method) : boolean

Checks if the request method is of specified type.

Parameters

string $method

Uppercase request method (GET, POST etc)

Returns

boolean

isMethodSafe()

isMethodSafe() : boolean

Checks whether or not the method is safe.

Returns

boolean

isMethodIdempotent()

isMethodIdempotent() : boolean

Checks whether or not the method is idempotent.

Returns

boolean

isMethodCacheable()

isMethodCacheable() : boolean

Checks whether the method is cacheable or not.

Returns

boolean

getProtocolVersion()

getProtocolVersion() : string

Returns the protocol version.

If the application is behind a proxy, the protocol version used in the requests between the client and the proxy and between the proxy and the server might be different. This returns the former (from the "Via" header) if the proxy is trusted (see "setTrustedProxies()"), otherwise it returns the latter (from the "SERVER_PROTOCOL" server parameter).

Returns

string

getContent()

getContent(boolean  $asResource = false) : string|resource

Returns the request body content.

Parameters

boolean $asResource

If true, a resource will be returned

Throws

\LogicException

Returns

string|resource —

The request body content or a resource to read the body stream

getETags()

getETags() : array

Gets the Etags.

Returns

array —

The entity tags

isNoCache()

isNoCache() : boolean

Returns

boolean

getPreferredLanguage()

getPreferredLanguage(array  $locales = null) : string|null

Returns the preferred language.

Parameters

array $locales

An array of ordered available locales

Returns

string|null —

The preferred locale

getLanguages()

getLanguages() : array

Gets a list of languages acceptable by the client browser.

Returns

array —

Languages ordered in the user browser preferences

getCharsets()

getCharsets() : array

Gets a list of charsets acceptable by the client browser.

Returns

array —

List of charsets in preferable order

getEncodings()

getEncodings() : array

Gets a list of encodings acceptable by the client browser.

Returns

array —

List of encodings in preferable order

getAcceptableContentTypes()

getAcceptableContentTypes() : array

Gets a list of content types acceptable by the client browser.

Returns

array —

List of content types in preferable order

isXmlHttpRequest()

isXmlHttpRequest() : boolean

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:

Returns

boolean —

true if the request is an XMLHttpRequest, false otherwise

isFromTrustedProxy()

isFromTrustedProxy() : boolean

Indicates whether this request originated from a trusted proxy.

This can be useful to determine whether or not to trust the contents of a proxy-specific header.

Returns

boolean —

true if the request came from a trusted proxy, false otherwise

getFoo()

getFoo() 

prepareRequestUri()

prepareRequestUri() 

prepareBaseUrl()

prepareBaseUrl() : string

Prepares the base URL.

Returns

string

prepareBasePath()

prepareBasePath() : string

Prepares the base path.

Returns

string —

base path

preparePathInfo()

preparePathInfo() : string

Prepares the path info.

Returns

string —

path info

initializeFormats()

initializeFormats() 

Initializes HTTP request formats.

setPhpDefaultLocale()

setPhpDefaultLocale(string  $locale) 

Sets the default PHP locale.

Parameters

string $locale

getUrlencodedPrefix()

getUrlencodedPrefix(  $string,   $prefix) 

Parameters

$string
$prefix

createRequestFromFactory()

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

Parameters

array $query
array $request
array $attributes
array $cookies
array $files
array $server
$content

getTrustedValues()

getTrustedValues(  $type,   $ip = null) 

Parameters

$type
$ip

normalizeAndFilterClientIps()

normalizeAndFilterClientIps(array  $clientIps,   $ip) 

Parameters

array $clientIps
$ip