class HTTPRequest implements ArrayAccess (View source)

Represents a HTTP-request, including a URL that is tokenised for parsing, and a request method (GET/POST/PUT/DELETE). This is used by RequestHandler objects to decide what to do.

Caution: objects of this class are immutable, e.g. echo $request['a']; works as expected, but $request['a'] = '1'; has no effect.

The intention is that a single HTTPRequest object can be passed from one object to another, each object calling match() to get the information that they need out of the URL. This is generally handled by RequestHandler::handleRequest().

Properties

protected string $url
protected array $dirParts

The non-extension parts of the passed URL as an array, originally exploded by the "/" separator.

protected string $extension

The URL extension (if present)

protected string $httpMethod

The HTTP method in all uppercase: GET/PUT/POST/DELETE/HEAD

protected string $scheme

The URL scheme in lowercase: http or https

protected string $ip

The client IP address

protected array $getVars

Contains all HTTP GET parameters passed into this request.

protected array $postVars

Contains all HTTP POST parameters passed into this request.

protected array $headers

HTTP Headers like "Content-Type: text/xml"

protected string $body

Raw HTTP body, used by PUT and POST requests.

protected array $allParams

Contains an associative array of all arguments matched in all calls to RequestHandler->handleRequest().

protected array $latestParams

Contains an associative array of all arguments matched in the current call from RequestHandler->handleRequest(), as denoted with a "$"-prefix in the $url_handlers definitions.

protected array $routeParams

Contains an associative array of all arguments explicitly set in the route table for the current request.

protected int $unshiftedButParsedParts
protected Session $session

Methods

public
__construct(string $httpMethod, string $url, array $getVars = [], array $postVars = [], string $body = null)

Construct a HTTPRequest from a URL relative to the site root.

public
setUrl(string $url)

Allow the setting of a URL

public
bool
isGET()

No description

public
bool
isPOST()

No description

public
bool
isPUT()

No description

public
bool
isDELETE()

No description

public
bool
isHEAD()

No description

public
setBody(string $body)

No description

public
null|string
getBody()

No description

public
array
getVars()

No description

public
array
postVars()

No description

public
array
requestVars()

Returns all combined HTTP GET and POST parameters passed into this request. If a parameter with the same name exists in both arrays, the POST value is returned.

public
mixed
getVar(string $name)

No description

public
mixed
postVar(string $name)

No description

public
mixed
requestVar(string $name)

No description

public
string
getExtension()

Returns a possible file extension found in parsing the URL as denoted by a "."-character near the end of the URL.

public
bool
isMedia()

Checks if the HTTPRequest->getExtension() on this request matches one of the more common media types embedded into a webpage - e.g. css, png.

public
addHeader(string $header, string $value)

Add a HTTP header to the response, replacing any header of the same name.

public
array
getHeaders()

No description

public
mixed
getHeader(string $header)

Returns a HTTP Header by name if found in the request

public
removeHeader(string $header)

Remove an existing HTTP header by its name, e.g. "Content-Type".

public
string
getURL(bool $includeGetVars = false)

Returns the URL used to generate the page

public
bool
isAjax()

Returns true if this request an ajax request, based on custom HTTP ajax added by common JavaScript libraries, or based on an explicit "ajax" request parameter.

public
bool
offsetExists(string $offset)

Enables the existence of a key-value pair in the request to be checked using array syntax, so isset($request['title']) will check for $_POST['title'] and $_GET['title']

public
mixed
offsetGet(string $offset)

Access a request variable using array syntax. eg: $request['title'] instead of $request->postVar('title')

public
offsetSet($offset, $value)

No description

public
offsetUnset($offset)

No description

public static 
send_file($fileData, $fileName, null $mimeType = null)

Construct an HTTPResponse that will deliver a file to the client.

public
array|bool
match($pattern, bool $shiftOnSuccess = false)

Matches a URL pattern The pattern can contain a number of segments, separated by / (and an extension indicated by a .)

public
array
allParams()

No description

public
string
shiftAllParams()

Shift all the parameter values down a key space, and return the shifted value.

public
array
latestParams()

No description

public
string|null
latestParam(string $name)

No description

public
array
routeParams()

No description

public
setRouteParams($params)

No description

public
array
params()

No description

public
string
param(string $name)

Finds a named URL parameter (denoted by "$"-prefix in $url_handlers) from the full URL, or a parameter specified in the route table

public
string
remaining()

Returns the unparsed part of the original URL separated by commas. This is used by RequestHandler->handleRequest() to determine if further URL processing is necessary.

public
bool
isEmptyPattern(string $pattern)

Returns true if this is a URL that will match without shifting off any of the URL.

public
string|array
shift(int $count = 1)

Shift one or more parts off the beginning of the URL.

public
bool
allParsed()

Returns true if the URL has been completely parsed.

public
string
getHost()

No description

public
string
getIP()

Returns the client IP address which originated this request.

public
$this
setIP($ip)

Sets the client IP address which originated this request.

public
array
getAcceptMimetypes(bool $includeQuality = false)

Returns all mimetypes from the HTTP "Accept" header as an array.

public
string
httpMethod()

No description

public
$this
setHttpMethod(string $method)

Explicitly set the HTTP method for this request.

public
string
getScheme()

Return the URL scheme (e.g. "http" or "https").

public
$this
setScheme(string $scheme)

Set the URL scheme (e.g. "http" or "https").

public static 
string
detect_method(string $origMethod, array $postVars) deprecated

Gets the "real" HTTP method for a request. This method is no longer used to mitigate the risk of web cache poisoning.

public
bool
hasSession()

Determines whether the request has a session

public
getSession()

No description

public
$this
setSession(Session $session)

No description

Details

__construct(string $httpMethod, string $url, array $getVars = [], array $postVars = [], string $body = null)

Construct a HTTPRequest from a URL relative to the site root.

Parameters

string $httpMethod
string $url
array $getVars
array $postVars
string $body

HTTPRequest setUrl(string $url)

Allow the setting of a URL

This is here so that RootURLController can change the URL of the request without us losing all the other info attached (like headers)

Parameters

string $url

The new URL

Return Value

HTTPRequest

The updated request

bool isGET()

No description

Return Value

bool

bool isPOST()

No description

Return Value

bool

bool isPUT()

No description

Return Value

bool

bool isDELETE()

No description

Return Value

bool

bool isHEAD()

No description

Return Value

bool

HTTPRequest setBody(string $body)

No description

Parameters

string $body

Return Value

HTTPRequest $this

null|string getBody()

No description

Return Value

null|string

array getVars()

No description

Return Value

array

array postVars()

No description

Return Value

array

array requestVars()

Returns all combined HTTP GET and POST parameters passed into this request. If a parameter with the same name exists in both arrays, the POST value is returned.

Return Value

array

mixed getVar(string $name)

No description

Parameters

string $name

Return Value

mixed

mixed postVar(string $name)

No description

Parameters

string $name

Return Value

mixed

mixed requestVar(string $name)

No description

Parameters

string $name

Return Value

mixed

string getExtension()

Returns a possible file extension found in parsing the URL as denoted by a "."-character near the end of the URL.

Doesn't necessarily have to belong to an existing file, as extensions can be also used for content-type-switching.

Return Value

string

bool isMedia()

Checks if the HTTPRequest->getExtension() on this request matches one of the more common media types embedded into a webpage - e.g. css, png.

This is useful for things like determining whether to display a fully rendered error page or not. Note that the media file types is not at all comprehensive.

Return Value

bool

addHeader(string $header, string $value)

Add a HTTP header to the response, replacing any header of the same name.

Parameters

string $header

Example: "content-type"

string $value

Example: "text/xml"

array getHeaders()

No description

Return Value

array

mixed getHeader(string $header)

Returns a HTTP Header by name if found in the request

Parameters

string $header

Name of the header (Insensitive to case as per <rfc2616 section 4.2 "Message Headers">)

Return Value

mixed

HTTPRequest removeHeader(string $header)

Remove an existing HTTP header by its name, e.g. "Content-Type".

Parameters

string $header

Return Value

HTTPRequest $this

string getURL(bool $includeGetVars = false)

Returns the URL used to generate the page

Parameters

bool $includeGetVars

whether or not to include the get parameters

Return Value

string

bool isAjax()

Returns true if this request an ajax request, based on custom HTTP ajax added by common JavaScript libraries, or based on an explicit "ajax" request parameter.

Return Value

bool

bool offsetExists(string $offset)

Enables the existence of a key-value pair in the request to be checked using array syntax, so isset($request['title']) will check for $_POST['title'] and $_GET['title']

Parameters

string $offset

Return Value

bool

mixed offsetGet(string $offset)

Access a request variable using array syntax. eg: $request['title'] instead of $request->postVar('title')

Parameters

string $offset

Return Value

mixed

offsetSet($offset, $value)

No description

Parameters

$offset
$value

offsetUnset($offset)

No description

Parameters

$offset

static HTTPResponse send_file($fileData, $fileName, null $mimeType = null)

Construct an HTTPResponse that will deliver a file to the client.

Caution: Since it requires $fileData to be passed as binary data (no stream support), it's only advisable to send small files through this method. This function needs to be called inside the controller’s response, e.g.: $this->setResponse(HTTPRequest::send_file('the content', 'filename.txt'));

Parameters

$fileData
$fileName
null $mimeType

Return Value

HTTPResponse

array|bool match($pattern, bool $shiftOnSuccess = false)

Matches a URL pattern The pattern can contain a number of segments, separated by / (and an extension indicated by a .)

The parts can be either literals, or, if they start with a $ they are interpreted as variables.

  • Literals must be provided in order to match
  • $Variables are optional
  • However, if you put ! at the end of a variable, then it becomes mandatory.

For example:

  • admin/crm/list will match admin/crm/$Action/$ID/$OtherID, but it won't match admin/crm/$Action!/$ClassName!

The pattern can optionally start with an HTTP method and a space. For example, "POST $Controller/$Action". This is used to define a rule that only matches on a specific HTTP method.

Parameters

$pattern
bool $shiftOnSuccess

Return Value

array|bool

array allParams()

No description

Return Value

array

string shiftAllParams()

Shift all the parameter values down a key space, and return the shifted value.

Return Value

string

array latestParams()

No description

Return Value

array

string|null latestParam(string $name)

No description

Parameters

string $name

Return Value

string|null

array routeParams()

No description

Return Value

array

HTTPRequest setRouteParams($params)

No description

Parameters

$params

Return Value

HTTPRequest $this

array params()

No description

Return Value

array

string param(string $name)

Finds a named URL parameter (denoted by "$"-prefix in $url_handlers) from the full URL, or a parameter specified in the route table

Parameters

string $name

Return Value

string

Value of the URL parameter (if found)

string remaining()

Returns the unparsed part of the original URL separated by commas. This is used by RequestHandler->handleRequest() to determine if further URL processing is necessary.

Return Value

string

Partial URL

bool isEmptyPattern(string $pattern)

Returns true if this is a URL that will match without shifting off any of the URL.

This is used by the request handler to prevent infinite parsing loops.

Parameters

string $pattern

Return Value

bool

string|array shift(int $count = 1)

Shift one or more parts off the beginning of the URL.

If you specify shifting more than 1 item off, then the items will be returned as an array

Parameters

int $count

Shift Count

Return Value

string|array

bool allParsed()

Returns true if the URL has been completely parsed.

This will respect parsed but unshifted directory parts.

Return Value

bool

string getHost()

No description

Return Value

string

Return the host from the request

string getIP()

Returns the client IP address which originated this request.

Return Value

string

$this setIP($ip)

Sets the client IP address which originated this request.

Use setIPFromHeaderValue if assigning from header value.

Parameters

$ip string

Return Value

$this

array getAcceptMimetypes(bool $includeQuality = false)

Returns all mimetypes from the HTTP "Accept" header as an array.

Parameters

bool $includeQuality

Don't strip away optional "quality indicators", e.g. "application/xml;q=0.9" (Default: false)

Return Value

array

string httpMethod()

No description

Return Value

string

HTTP method (all uppercase)

$this setHttpMethod(string $method)

Explicitly set the HTTP method for this request.

Parameters

string $method

Return Value

$this

string getScheme()

Return the URL scheme (e.g. "http" or "https").

Equivalent to PSR-7 getUri()->getScheme()

Return Value

string

$this setScheme(string $scheme)

Set the URL scheme (e.g. "http" or "https").

Equivalent to PSR-7 getUri()->getScheme(),

Parameters

string $scheme

Return Value

$this

static string detect_method(string $origMethod, array $postVars) deprecated

deprecated 4.4.7 Will be removed without equivalent functionality

Gets the "real" HTTP method for a request. This method is no longer used to mitigate the risk of web cache poisoning.

Parameters

string $origMethod

Original HTTP method from the browser request

array $postVars

Return Value

string

HTTP method (all uppercase)

See also

https://www.silverstripe.org/download/security-releases/CVE-2019-19326

bool hasSession()

Determines whether the request has a session

Return Value

bool

Session getSession()

No description

Return Value

Session

$this setSession(Session $session)

No description

Parameters

Session $session

Return Value

$this