ServerRequest extends Request implements ServerRequestInterface

Represents a typical request incoming from the server to be processed by the TYPO3 Core. The original request is built from the ServerRequestFactory inside TYPO3's Bootstrap.

Note that the PSR-7 standard works with immutable value objects, meaning that any modification to a Request object using the "with" methods will result in a new Request object.

Highly inspired by https://github.com/phly/http/

Internal

Note that this is not public API yet.

Table of Contents

Interfaces

ServerRequestInterface

Properties

$attributes  : array<string|int, mixed>
$body  : StreamInterface|null
The body as a Stream object
$cookieParams  : array<string|int, mixed>
$headers  : array<string|int, mixed>
Associative array containing all headers of this Message This is a mixed-case list of the headers (as due to the specification)
$lowercasedHeaderNames  : array<string|int, mixed>
Lowercased version of all headers, in order to check if a header is set or not this way a lot of checks are easier to be set
$method  : string
The HTTP method.
$parsedBody  : array<string|int, mixed>|object|null
$protocolVersion  : string
The HTTP Protocol version, defaults to 1.1
$queryParams  : array<string|int, mixed>
$requestTarget  : string|null
The request-target, if it has been provided or calculated.
$serverParams  : array<string|int, mixed>
$supportedMethods  : array<string|int, non-empty-string>
Supported HTTP methods
$uploadedFiles  : array<string|int, mixed>
$uri  : UriInterface|null
An instance of the Uri object

Methods

__construct()  : mixed
Constructor, the only place to set all parameters of this Message/Request
filter()  : string
Filter a header value
getAttribute()  : mixed
Retrieve a single derived request attribute.
getAttributes()  : array<string|int, mixed>
Retrieve attributes derived from the request.
getBody()  : StreamInterface
Gets the body of the message.
getCookieParams()  : array<string|int, mixed>
Retrieve cookies.
getHeader()  : array<string|int, string>
Retrieves a message header value by the given case-insensitive name.
getHeaderLine()  : string
Retrieves a comma-separated string of the values for a single header.
getHeaders()  : array<string|int, mixed>
Retrieves all message header values.
getMethod()  : string
Retrieves the HTTP method of the request, defaults to GET
getParsedBody()  : array<string|int, mixed>|object|null
Retrieve any parameters provided in the request body.
getProtocolVersion()  : string
Retrieves the HTTP protocol version as a string.
getQueryParams()  : array<string|int, mixed>
Retrieve query string arguments.
getRequestTarget()  : string
Retrieves the message's request target.
getServerParams()  : array<string|int, mixed>
Retrieve server parameters.
getUploadedFiles()  : array<string|int, mixed>
Retrieve normalized file upload data.
getUri()  : UriInterface
Retrieves the URI instance.
hasHeader()  : bool
Checks if a header exists by the given case-insensitive name.
isValidHeaderValue()  : bool
Checks if an HTTP header value is valid.
validateHeaderName()  : void
Check whether a header name is valid and throw an exception.
withAddedHeader()  : static
Return an instance with the specified header appended with the given value.
withAttribute()  : static
Return an instance with the specified derived request attribute.
withBody()  : static
Return an instance with the specified message body.
withCookieParams()  : static
Return an instance with the specified cookies.
withHeader()  : static
Return an instance with the provided value replacing the specified header.
withMethod()  : static
Return an instance with the provided HTTP method.
withoutAttribute()  : static
Return an instance that removes the specified derived request attribute.
withoutHeader()  : static
Return an instance without the specified header.
withParsedBody()  : static
Return an instance with the specified body parameters.
withProtocolVersion()  : static
Return an instance with the specified HTTP protocol version.
withQueryParams()  : static
Return an instance with the specified query string arguments.
withRequestTarget()  : static
Return an instance with the specific request-target.
withUploadedFiles()  : static
Create a new instance with the specified uploaded files.
withUri()  : static
Returns an instance with the provided URI.
arrayContainsOnlyStrings()  : bool
Helper function to test if an array contains only strings
assertHeaders()  : void
Ensure header names and values are valid.
filterHeaders()  : array<string|int, mixed>
Filter a set of headers to ensure they are in the correct internal format.
getHostFromUri()  : string
Retrieve the host from the URI instance
validateHeaderValues()  : void
Assert that the provided header values are valid.
validateMethod()  : void
Validate the HTTP method, helper function.
validateUploadedFiles()  : void
Recursively validate the structure in an uploaded files array.

Properties

$attributes

protected array<string|int, mixed> $attributes = []

$body

The body as a Stream object

protected StreamInterface|null $body = null

$cookieParams

protected array<string|int, mixed> $cookieParams = []

$headers

Associative array containing all headers of this Message This is a mixed-case list of the headers (as due to the specification)

protected array<string|int, mixed> $headers = []

$lowercasedHeaderNames

Lowercased version of all headers, in order to check if a header is set or not this way a lot of checks are easier to be set

protected array<string|int, mixed> $lowercasedHeaderNames = []

$method

The HTTP method.

protected string $method = 'GET'

$parsedBody

protected array<string|int, mixed>|object|null $parsedBody

$protocolVersion

The HTTP Protocol version, defaults to 1.1

protected string $protocolVersion = '1.1'

$queryParams

protected array<string|int, mixed> $queryParams = []

$requestTarget

The request-target, if it has been provided or calculated.

protected string|null $requestTarget = null

$serverParams

protected array<string|int, mixed> $serverParams = []

$supportedMethods

Supported HTTP methods

protected array<string|int, non-empty-string> $supportedMethods = [ 'CONNECT', 'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PATCH', 'POST', 'PUT', 'TRACE', // WebDAV methods 'COPY', 'LOCK', 'MKCOL', 'MOVE', 'PROPFIND', 'PROPPATCH', 'REPORT', 'UNLOCK', // Custom methods 'PURGE', 'BAN', ]

$uploadedFiles

protected array<string|int, mixed> $uploadedFiles = []

$uri

An instance of the Uri object

protected UriInterface|null $uri
Tags
todo

It is a PSR-7 spec violation for this to be null. This should be corrected.

Methods

__construct()

Constructor, the only place to set all parameters of this Message/Request

public __construct([string|UriInterface|null $uri = null ][, string|null $method = null ][, string|resource|StreamInterface|null $body = 'php://input' ][, array<string|int, mixed> $headers = [] ][, array<string|int, mixed> $serverParams = [] ][, array<string|int, mixed>|null $uploadedFiles = null ]) : mixed
Parameters
$uri : string|UriInterface|null = null

URI for the request, if any.

$method : string|null = null

HTTP method for the request, if any.

$body : string|resource|StreamInterface|null = 'php://input'

Message body, if any.

$headers : array<string|int, mixed> = []

Headers for the message, if any.

$serverParams : array<string|int, mixed> = []

Server parameters, typically from $_SERVER

$uploadedFiles : array<string|int, mixed>|null = null

Upload file information, a tree of UploadedFiles

Tags
throws
InvalidArgumentException

for any invalid value.

filter()

Filter a header value

public filter(string $value) : string

Ensures CRLF header injection vectors are filtered.

Per RFC 7230, only VISIBLE ASCII characters, spaces, and horizontal tabs are allowed in values; header continuations MUST consist of a single CRLF sequence followed by a space or horizontal tab.

This method filters any values not allowed from the string, and is lossy.

Parameters
$value : string
Tags
see
http://en.wikipedia.org/wiki/HTTP_response_splitting
todo:

Unused? And why is this public? Maybe align with zend-diactoros again

Return values
string

getAttribute()

Retrieve a single derived request attribute.

public getAttribute(string $name[, mixed $default = null ]) : mixed

Retrieves a single derived request attribute as described in getAttributes(). If the attribute has not been previously set, returns the default value as provided.

This method obviates the need for a hasAttribute() method, as it allows specifying a default value to return if the attribute is not found.

Parameters
$name : string

The attribute name.

$default : mixed = null

Default value to return if the attribute does not exist.

Tags
see
getAttributes()

getAttributes()

Retrieve attributes derived from the request.

public getAttributes() : array<string|int, mixed>

The request "attributes" may be used to allow injection of any parameters derived from the request: e.g., the results of path match operations; the results of decrypting cookies; the results of deserializing non-form-encoded message bodies; etc. Attributes will be application and request specific, and CAN be mutable.

Return values
array<string|int, mixed> —

Attributes derived from the request.

getBody()

Gets the body of the message.

public getBody() : StreamInterface
Return values
StreamInterface —

Returns the body as a stream.

getCookieParams()

Retrieve cookies.

public getCookieParams() : array<string|int, mixed>

Retrieves cookies sent by the client to the server.

The data MUST be compatible with the structure of the $_COOKIE super global.

Return values
array<string|int, mixed>

getHeader()

Retrieves a message header value by the given case-insensitive name.

public getHeader(string $name) : array<string|int, string>

This method returns an array of all the header values of the given case-insensitive header name.

If the header does not appear in the message, this method MUST return an empty array.

Parameters
$name : string

Case-insensitive header field name.

Return values
array<string|int, string> —

An array of string values as provided for the given header. If the header does not appear in the message, this method MUST return an empty array.

getHeaderLine()

Retrieves a comma-separated string of the values for a single header.

public getHeaderLine(string $name) : string

This method returns all of the header values of the given case-insensitive header name as a string concatenated together using a comma.

NOTE: Not all header values may be appropriately represented using comma concatenation. For such headers, use getHeader() instead and supply your own delimiter when concatenating.

If the header does not appear in the message, this method MUST return an empty string.

Parameters
$name : string

Case-insensitive header field name.

Return values
string —

A string of values as provided for the given header concatenated together using a comma. If the header does not appear in the message, this method MUST return an empty string.

getHeaders()

Retrieves all message header values.

public getHeaders() : array<string|int, mixed>

The keys represent the header name as it will be sent over the wire, and each value is an array of strings associated with the header.

    // Represent the headers as a string
    foreach ($message->getHeaders() as $name => $values) {
        echo $name . ": " . implode(", ", $values);
    }

    // Emit headers iteratively:
    foreach ($message->getHeaders() as $name => $values) {
        foreach ($values as $value) {
            header(sprintf('%s: %s', $name, $value), false);
        }
    }

While header names are not case-sensitive, getHeaders() will preserve the exact case in which headers were originally specified.

Return values
array<string|int, mixed> —

Returns an associative array of the message's headers. Each key MUST be a header name, and each value MUST be an array of strings for that header.

getMethod()

Retrieves the HTTP method of the request, defaults to GET

public getMethod() : string
Return values
string

getParsedBody()

Retrieve any parameters provided in the request body.

public getParsedBody() : array<string|int, mixed>|object|null

If the request Content-Type is either application/x-www-form-urlencoded or multipart/form-data, and the request method is POST, this method MUST return the contents of $_POST.

Otherwise, this method may return any results of deserializing the request body content; as parsing returns structured content, the potential types MUST be arrays or objects only. A null value indicates the absence of body content.

Return values
array<string|int, mixed>|object|null —

The deserialized body parameters, if any. These will typically be an array or object.

getProtocolVersion()

Retrieves the HTTP protocol version as a string.

public getProtocolVersion() : string

The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").

Return values
string —

HTTP protocol version.

getQueryParams()

Retrieve query string arguments.

public getQueryParams() : array<string|int, mixed>

Retrieves the deserialized query string arguments, if any.

Note: the query params might not be in sync with the URI or server params. If you need to ensure you are only getting the original values, you may need to parse the query string from getUri()->getQuery() or from the QUERY_STRING server param.

Return values
array<string|int, mixed>

getRequestTarget()

Retrieves the message's request target.

public getRequestTarget() : string

Retrieves the message's request-target either as it will appear (for clients), as it appeared at request (for servers), or as it was specified for the instance (see withRequestTarget()).

In most cases, this will be the origin-form of the composed URI, unless a value was provided to the concrete implementation (see withRequestTarget() below).

If no URI is available, and no request-target has been specifically provided, this method MUST return the string "/".

Return values
string

getServerParams()

Retrieve server parameters.

public getServerParams() : array<string|int, mixed>

Retrieves data related to the incoming request environment, typically derived from PHP's $_SERVER superglobal. The data IS NOT REQUIRED to originate from $_SERVER.

Return values
array<string|int, mixed>

getUploadedFiles()

Retrieve normalized file upload data.

public getUploadedFiles() : array<string|int, mixed>

This method returns upload metadata in a normalized tree, with each leaf an instance of Psr\Http\Message\UploadedFileInterface.

These values MAY be prepared from $_FILES or the message body during instantiation, or MAY be injected via withUploadedFiles().

Return values
array<string|int, mixed> —

An array tree of UploadedFileInterface instances; an empty array MUST be returned if no data is present.

hasHeader()

Checks if a header exists by the given case-insensitive name.

public hasHeader(string $name) : bool
Parameters
$name : string

Case-insensitive header field name.

Return values
bool —

Returns true if any header names match the given header name using a case-insensitive string comparison. Returns false if no matching header name is found in the message.

isValidHeaderValue()

Checks if an HTTP header value is valid.

public isValidHeaderValue(string $value) : bool

Per RFC 7230, only VISIBLE ASCII characters, spaces, and horizontal tabs are allowed in values; header continuations MUST consist of a single CRLF sequence followed by a space or horizontal tab.

Parameters
$value : string
Tags
see
http://en.wikipedia.org/wiki/HTTP_response_splitting
todo:

Review. Should be protected / private, maybe align with zend-diactoros again

Return values
bool

validateHeaderName()

Check whether a header name is valid and throw an exception.

public validateHeaderName(string $name) : void
Parameters
$name : string
Tags
see
https://tools.ietf.org/html/rfc7230#section-3.2
throws
InvalidArgumentException
todo:

Review. Should be protected / private, maybe align with zend-diactoros again

withAddedHeader()

Return an instance with the specified header appended with the given value.

public withAddedHeader(string $name, string|array<string|int, string> $value) : static

Existing values for the specified header will be maintained. The new value(s) will be appended to the existing list. If the header did not exist previously, it will be added.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new header and/or value.

Parameters
$name : string

Case-insensitive header field name to add.

$value : string|array<string|int, string>

Header value(s).

Tags
throws
InvalidArgumentException

for invalid header names or values.

Return values
static

withAttribute()

Return an instance with the specified derived request attribute.

public withAttribute(string $name, mixed $value) : static

This method allows setting a single derived request attribute as described in getAttributes().

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the updated attribute.

Parameters
$name : string

The attribute name.

$value : mixed

The value of the attribute.

Tags
see
getAttributes()
Return values
static

withBody()

Return an instance with the specified message body.

public withBody(StreamInterface $body) : static

The body MUST be a StreamInterface object.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return a new instance that has the new body stream.

Parameters
$body : StreamInterface
Tags
throws
InvalidArgumentException

When the body is not valid.

Return values
static

withCookieParams()

Return an instance with the specified cookies.

public withCookieParams(array<string|int, mixed> $cookies) : static

The data IS NOT REQUIRED to come from the $_COOKIE superglobal, but MUST be compatible with the structure of $_COOKIE. Typically, this data will be injected at instantiation.

This method MUST NOT update the related Cookie header of the request instance, nor related values in the server params.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the updated cookie values.

Parameters
$cookies : array<string|int, mixed>

Array of key/value pairs representing cookies.

Return values
static

withHeader()

Return an instance with the provided value replacing the specified header.

public withHeader(string $name, string|array<string|int, string> $value) : static

While header names are case-insensitive, the casing of the header will be preserved by this function, and returned from getHeaders().

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new and/or updated header and value.

Parameters
$name : string

Case-insensitive header field name.

$value : string|array<string|int, string>

Header value(s).

Tags
throws
InvalidArgumentException

for invalid header names or values.

Return values
static

withMethod()

Return an instance with the provided HTTP method.

public withMethod(string $method) : static

While HTTP method names are typically all uppercase characters, HTTP method names are case-sensitive and thus implementations SHOULD NOT modify the given string.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the changed request method.

Parameters
$method : string

Case-sensitive method.

Tags
throws
InvalidArgumentException

for invalid HTTP methods.

Return values
static

withoutAttribute()

Return an instance that removes the specified derived request attribute.

public withoutAttribute(string $name) : static

This method allows removing a single derived request attribute as described in getAttributes().

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that removes the attribute.

Parameters
$name : string

The attribute name.

Tags
see
getAttributes()
Return values
static

withoutHeader()

Return an instance without the specified header.

public withoutHeader(string $name) : static

Header resolution MUST be done without case-sensitivity.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that removes the named header.

Parameters
$name : string

Case-insensitive header field name to remove.

Return values
static

withParsedBody()

Return an instance with the specified body parameters.

public withParsedBody(array<string|int, mixed>|object|null $data) : static

These MAY be injected during instantiation.

If the request Content-Type is either application/x-www-form-urlencoded or multipart/form-data, and the request method is POST, use this method ONLY to inject the contents of $_POST.

The data IS NOT REQUIRED to come from $_POST, but MUST be the results of deserializing the request body content. Deserialization/parsing returns structured data, and, as such, this method ONLY accepts arrays or objects, or a null value if nothing was available to parse.

As an example, if content negotiation determines that the request data is a JSON payload, this method could be used to create a request instance with the deserialized parameters.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the updated body parameters.

Parameters
$data : array<string|int, mixed>|object|null

The deserialized body data. This will typically be in an array or object.

Tags
throws
InvalidArgumentException

if an unsupported argument type is provided.

Return values
static

withProtocolVersion()

Return an instance with the specified HTTP protocol version.

public withProtocolVersion(string $version) : static

The version string MUST contain only the HTTP version number (e.g., "1.1", "1.0").

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new protocol version.

Parameters
$version : string

HTTP protocol version

Return values
static

withQueryParams()

Return an instance with the specified query string arguments.

public withQueryParams(array<string|int, mixed> $query) : static

These values SHOULD remain immutable over the course of the incoming request. They MAY be injected during instantiation, such as from PHP's $_GET superglobal, or MAY be derived from some other value such as the URI. In cases where the arguments are parsed from the URI, the data MUST be compatible with what PHP's parse_str() would return for purposes of how duplicate query parameters are handled, and how nested sets are handled.

Setting query string arguments MUST NOT change the URI stored by the request, nor the values in the server params.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the updated query string arguments.

Parameters
$query : array<string|int, mixed>

Array of query string arguments, typically from $_GET.

Return values
static

withRequestTarget()

Return an instance with the specific request-target.

public withRequestTarget(mixed $requestTarget) : static

If the request needs a non-origin-form request-target — e.g., for specifying an absolute-form, authority-form, or asterisk-form — this method may be used to create an instance with the specified request-target, verbatim.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the changed request target.

Parameters
$requestTarget : mixed
Tags
link

(for the various request-target forms allowed in request messages)
Return values
static

withUploadedFiles()

Create a new instance with the specified uploaded files.

public withUploadedFiles(array<string|int, mixed> $uploadedFiles) : static

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the updated body parameters.

Parameters
$uploadedFiles : array<string|int, mixed>

An array tree of UploadedFileInterface instances.

Tags
throws
InvalidArgumentException

if an invalid structure is provided.

Return values
static

withUri()

Returns an instance with the provided URI.

public withUri(UriInterface $uri[, bool $preserveHost = false ]) : static

This method MUST update the Host header of the returned request by default if the URI contains a host component. If the URI does not contain a host component, any pre-existing Host header MUST be carried over to the returned request.

You can opt-in to preserving the original state of the Host header by setting $preserveHost to true. When $preserveHost is set to true, this method interacts with the Host header in the following ways:

  • If the the Host header is missing or empty, and the new URI contains a host component, this method MUST update the Host header in the returned request.
  • If the Host header is missing or empty, and the new URI does not contain a host component, this method MUST NOT update the Host header in the returned request.
  • If a Host header is present and non-empty, this method MUST NOT update the Host header in the returned request.

This method MUST be implemented in such a way as to retain the immutability of the message, and MUST return an instance that has the new UriInterface instance.

Parameters
$uri : UriInterface

New request URI to use.

$preserveHost : bool = false

Preserve the original state of the Host header.

Tags
link
https://tools.ietf.org/html/rfc3986#section-4.3
Return values
static

arrayContainsOnlyStrings()

Helper function to test if an array contains only strings

protected arrayContainsOnlyStrings(array<string|int, mixed> $data) : bool
Parameters
$data : array<string|int, mixed>
Return values
bool

assertHeaders()

Ensure header names and values are valid.

protected assertHeaders(array<string|int, mixed> $headers) : void
Parameters
$headers : array<string|int, mixed>
Tags
throws
InvalidArgumentException

filterHeaders()

Filter a set of headers to ensure they are in the correct internal format.

protected filterHeaders(array<string|int, mixed> $originalHeaders) : array<string|int, mixed>

Used by message constructors to allow setting all initial headers at once.

Parameters
$originalHeaders : array<string|int, mixed>

Headers to filter.

Return values
array<string|int, mixed> —

Filtered headers and names.

getHostFromUri()

Retrieve the host from the URI instance

protected getHostFromUri() : string
Return values
string

validateHeaderValues()

Assert that the provided header values are valid.

protected validateHeaderValues(array<string|int, string> $values) : void
Parameters
$values : array<string|int, string>
Tags
see
https://tools.ietf.org/html/rfc7230#section-3.2
throws
InvalidArgumentException

validateMethod()

Validate the HTTP method, helper function.

protected validateMethod(string|null $method) : void
Parameters
$method : string|null
Tags
throws
InvalidArgumentException

on invalid HTTP method.

validateUploadedFiles()

Recursively validate the structure in an uploaded files array.

protected validateUploadedFiles(array<string|int, mixed> $uploadedFiles) : void
Parameters
$uploadedFiles : array<string|int, mixed>
Tags
throws
InvalidArgumentException

if any leaf is not an UploadedFileInterface instance.


        

        
    




    

    

                            

            

                            
    

        On this page

        
    


            

                    

        

    

        

            
Search results