Class ServerRequest
A class that helps wrap Request information and particulars about a single request. Provides methods commonly used to introspect on the request headers and request body.
Property Summary
-
$_detectorCache protected
array
Instance cache for results of is(something) calls
-
$_detectors protected static
array<callable|array>
The built in detectors used with
is()
can be modified withaddDetector()
. -
$_environment protected
array
Array of environment data.
-
$attributes protected
array
Store the additional attributes attached to the request.
-
$base protected
string
Base URL path.
-
$cookies protected
array
Array of cookie data.
-
$data protected
object|array|null
Array of POST data. Will contain form data as well as uploaded files. In PUT/PATCH/DELETE requests this property will contain the form-urlencoded data.
-
$emulatedAttributes protected
array<string>
A list of properties that emulated by the PSR7 attribute methods.
-
$flash protected
Cake\Http\FlashMessage
Instance of a FlashMessage object relative to this request
-
$params protected
array
Array of parameters parsed from the URL.
-
$protocol protected
string|null
The HTTP protocol version used.
-
$query protected
array
Array of query string arguments
-
$requestTarget protected
string|null
The request target if overridden
-
$session protected
Cake\Http\Session
Instance of a Session object relative to this request
-
$stream protected
Psr\Http\Message\StreamInterface
Request body stream. Contains php://input unless
input
constructor option is used. -
$trustProxy public
bool
Whether to trust HTTP_X headers set by most load balancers. Only set to true if your application runs behind load balancers/proxies that you control.
-
$trustedProxies protected
array<string>
Trusted proxies list
-
$uploadedFiles protected
array
Array of Psr\Http\Message\UploadedFileInterface objects.
-
$uri protected
Psr\Http\Message\UriInterface
Uri instance
-
$webroot protected
string
webroot path segment for the request.
Method Summary
-
__call() public
Missing method handler, handles wrapping older style isAjax() type methods
-
__construct() public
Create a new request object.
-
_acceptHeaderDetector() protected
Detects if a specific accept header is present.
-
_environmentDetector() protected
Detects if a specific environment variable is present.
-
_headerDetector() protected
Detects if a specific header is present.
-
_is() protected
Worker for the public is() function
-
_paramDetector() protected
Detects if a specific request parameter is present.
-
_parseAcceptWithQualifier() protected
Parse Accept* headers with qualifier options.
-
_setConfig() protected
Process the config/settings data into properties.
-
acceptLanguage() public
Get the languages accepted by the client, or check if a specific language is accepted.
-
accepts() public
Find out which content types the client accepts or check if they accept a particular type of content.
-
addDetector() public static
Add a new detector to the list of detectors that a request can use. There are several different types of detectors that can be set.
-
allowMethod() public
Allow only certain HTTP request methods, if the request method does not match a 405 error will be shown and the required "Allow" response header will be set.
-
clearDetectorCache() public
Clears the instance detector cache, used by the is() function
-
clientIp() public
Get the IP the client is using, or says they are using.
-
contentType() public
Get the content type used in this request.
-
domain() public
Get the domain name and include $tldLength segments of the tld.
-
getAttribute() public
Read an attribute from the request, or get the default
-
getAttributes() public
Get all the attributes in the request.
-
getBody() public
Gets the body of the message.
-
getCookie() public
Read cookie data from the request's cookie data.
-
getCookieCollection() public
Get a cookie collection based on the request's cookies
-
getCookieParams() public
Get all the cookie data from the request.
-
getData() public
Provides a safe accessor for request data. Allows you to use Hash::get() compatible paths.
-
getEnv() public
Get a value from the request's environment data. Fallback to using env() if the key is not set in the $environment property.
-
getFlash() public
Returns the instance of the FlashMessage object for this request
-
getHeader() public
Get a single header from the request.
-
getHeaderLine() public
Get a single header as a string from the request.
-
getHeaders() public
Get all headers in the request.
-
getMethod() public
Get the HTTP method used for this request. There are a few ways to specify a method.
-
getParam() public
Safely access the values in $this->params.
-
getParsedBody() public
Get the parsed request body data.
-
getPath() public
Get the path of current request.
-
getProtocolVersion() public
Retrieves the HTTP protocol version as a string.
-
getQuery() public
Read a specific query value or dotted path.
-
getQueryParams() public
Get all the query parameters in accordance to the PSR-7 specifications. To read specific query values use the alternative getQuery() method.
-
getRequestTarget() public
Retrieves the request's target.
-
getServerParams() public
Get all the server environment parameters.
-
getSession() public
Returns the instance of the Session object for this request
-
getTrustedProxies() public
Get trusted proxies
-
getUploadedFile() public
Get the uploaded file from a dotted path.
-
getUploadedFiles() public
Get the array of uploaded files from the request.
-
getUri() public
Retrieves the URI instance.
-
hasHeader() public
Check if a header is set in the request.
-
host() public
Get the host that the request was handled on.
-
input() public deprecated
Read data from
php://input
. Useful when interacting with XML or JSON request body content. -
is() public
Check whether a Request is a certain type.
-
isAll() public
Check that a request matches all the given types.
-
normalizeHeaderName() protected
Normalize a header name into the SERVER version.
-
parseAccept() public
Parse the HTTP_ACCEPT header and return a sorted array with content types as the keys, and pref values as the values.
-
port() public
Get the port the request was handled on.
-
processUrlOption() protected
Set environment vars based on
url
option to facilitate UriInterface instance generation. -
referer() public
Returns the referer that referred this request.
-
scheme() public
Get the current url scheme used for the request.
-
setTrustedProxies() public
register trusted proxies
-
subdomains() public
Get the subdomains for a host.
-
validateUploadedFiles() protected
Recursively validate uploaded file data.
-
withAddedHeader() public
Get a modified request with the provided header.
-
withAttribute() public
Return an instance with the specified request attribute.
-
withBody() public
Return an instance with the specified message body.
-
withCookieCollection() public
Replace the cookies in the request with those contained in the provided CookieCollection.
-
withCookieParams() public
Replace the cookies and get a new request instance.
-
withData() public
Update the request with a new request data element.
-
withEnv() public
Update the request with a new environment data element.
-
withHeader() public
Get a modified request with the provided header.
-
withMethod() public
Update the request method and get a new instance.
-
withParam() public
Update the request with a new routing parameter
-
withParsedBody() public
Update the parsed body and get a new instance.
-
withProtocolVersion() public
Return an instance with the specified HTTP protocol version.
-
withQueryParams() public
Update the query string data and get a new instance.
-
withRequestTarget() public
Create a new instance with a specific request-target.
-
withUploadedFiles() public
Update the request replacing the files, and creating a new instance.
-
withUri() public
Return an instance with the specified uri
-
withoutAttribute() public
Return an instance without the specified request attribute.
-
withoutData() public
Update the request removing a data element.
-
withoutHeader() public
Get a modified request without a provided header.
Method Detail
__call() ¶ public
__call(string $name, array $params): bool
Missing method handler, handles wrapping older style isAjax() type methods
Parameters
-
string
$name The method called
-
array
$params Array of parameters for the method call
Returns
bool
Throws
BadMethodCallException
when an invalid method is called.
__construct() ¶ public
__construct(array<string, mixed> $config = [])
Create a new request object.
You can supply the data as either an array or as a string. If you use a string you can only supply the URL for the request. Using an array will let you provide the following keys:
post
POST data or non query string dataquery
Additional data from the query string.files
Uploaded files in a normalized structure, with each leaf an instance of UploadedFileInterface.cookies
Cookies for this request.environment
$_SERVER and $_ENV data.url
The URL without the base path for the request.uri
The PSR7 UriInterface object. If null, one will be created fromurl
orenvironment
.base
The base URL for the request.webroot
The webroot directory for the request.input
The data that would come from php://input this is useful for simulating requests with put, patch or delete data.session
An instance of a Session object
Parameters
-
array<string, mixed>
$config optional An array of request data to create a request with.
_acceptHeaderDetector() ¶ protected
_acceptHeaderDetector(array $detect): bool
Detects if a specific accept header is present.
Parameters
-
array
$detect Detector options array.
Returns
bool
_environmentDetector() ¶ protected
_environmentDetector(array $detect): bool
Detects if a specific environment variable is present.
Parameters
-
array
$detect Detector options array.
Returns
bool
_headerDetector() ¶ protected
_headerDetector(array $detect): bool
Detects if a specific header is present.
Parameters
-
array
$detect Detector options array.
Returns
bool
_is() ¶ protected
_is(string $type, array $args): bool
Worker for the public is() function
Parameters
-
string
$type The type of request you want to check.
-
array
$args Array of custom detector arguments.
Returns
bool
_paramDetector() ¶ protected
_paramDetector(array $detect): bool
Detects if a specific request parameter is present.
Parameters
-
array
$detect Detector options array.
Returns
bool
_parseAcceptWithQualifier() ¶ protected
_parseAcceptWithQualifier(string $header): array
Parse Accept* headers with qualifier options.
Only qualifiers will be extracted, any other accept extensions will be discarded as they are not frequently used.
Parameters
-
string
$header Header to parse.
Returns
array
_setConfig() ¶ protected
_setConfig(array<string, mixed> $config): void
Process the config/settings data into properties.
Parameters
-
array<string, mixed>
$config The config data to use.
Returns
void
acceptLanguage() ¶ public
acceptLanguage(string|null $language = null): array|bool
Get the languages accepted by the client, or check if a specific language is accepted.
Get the list of accepted languages:
\Cake\Http\ServerRequest::acceptLanguage();
Check if a specific language is accepted:
\Cake\Http\ServerRequest::acceptLanguage('es-es');
Parameters
-
string|null
$language optional The language to test.
Returns
array|bool
accepts() ¶ public
accepts(string|null $type = null): array<string>|bool
Find out which content types the client accepts or check if they accept a particular type of content.
Get all types:
$this->request->accepts();
Check for a single type:
$this->request->accepts('application/json');
This method will order the returned content types by the preference values indicated by the client.
Parameters
-
string|null
$type optional The content type to check for. Leave null to get all types a client accepts.
Returns
array<string>|bool
addDetector() ¶ public static
addDetector(string $name, callable|array $detector): void
Add a new detector to the list of detectors that a request can use. There are several different types of detectors that can be set.
Callback comparison
Callback detectors allow you to provide a callable to handle the check. The callback will receive the request object as its only parameter.
addDetector('custom', function ($request) { //Return a boolean });
Environment value comparison
An environment value comparison, compares a value fetched from env()
to a known value
the environment value is equality checked against the provided value.
addDetector('post', ['env' => 'REQUEST_METHOD', 'value' => 'POST']);
Request parameter comparison
Allows for custom detectors on the request parameters.
addDetector('admin', ['param' => 'prefix', 'value' => 'admin']);
Accept comparison
Allows for detector to compare against Accept header value.
addDetector('csv', ['accept' => 'text/csv']);
Header comparison
Allows for one or more headers to be compared.
addDetector('fancy', ['header' => ['X-Fancy' => 1]);
The param
, env
and comparison types allow the following
value comparison options:
Pattern value comparison
Pattern value comparison allows you to compare a value fetched from env()
to a regular expression.
addDetector('iphone', ['env' => 'HTTP_USER_AGENT', 'pattern' => '/iPhone/i']);
Option based comparison
Option based comparisons use a list of options to create a regular expression. Subsequent calls to add an already defined options detector will merge the options.
addDetector('mobile', ['env' => 'HTTP_USER_AGENT', 'options' => ['Fennec']]);
You can also make compare against multiple values
using the options
key. This is useful when you want to check
if a request value is in a list of options.
addDetector('extension', ['param' => '_ext', 'options' => ['pdf', 'csv']]
Parameters
-
string
$name The name of the detector.
-
callable|array
$detector A callable or options array for the detector definition.
Returns
void
allowMethod() ¶ public
allowMethod(array<string>|string $methods): true
Allow only certain HTTP request methods, if the request method does not match a 405 error will be shown and the required "Allow" response header will be set.
Example:
$this->request->allowMethod('post'); or $this->request->allowMethod(['post', 'delete']);
If the request would be GET, response header "Allow: POST, DELETE" will be set and a 405 error will be returned.
Parameters
-
array<string>|string
$methods Allowed HTTP request methods.
Returns
true
Throws
Cake\Http\Exception\MethodNotAllowedException
clearDetectorCache() ¶ public
clearDetectorCache(): void
Clears the instance detector cache, used by the is() function
Returns
void
clientIp() ¶ public
clientIp(): string
Get the IP the client is using, or says they are using.
Returns
string
contentType() ¶ public
contentType(): string|null
Get the content type used in this request.
Returns
string|null
domain() ¶ public
domain(int $tldLength = 1): string
Get the domain name and include $tldLength segments of the tld.
Parameters
-
int
$tldLength optional Number of segments your tld contains. For example:
example.com
contains 1 tld. Whileexample.co.uk
contains 2.
Returns
string
getAttribute() ¶ public
getAttribute(string $name, mixed $default = null): mixed
Read an attribute from the request, or get the default
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
-
string
$name The attribute name.
-
mixed
$default optional The default value if the attribute has not been set.
Returns
mixed
getAttributes() ¶ public
getAttributes(): array
Get all the attributes in the request.
This will include the params, webroot, base, and here attributes that CakePHP provides.
Returns
array
getBody() ¶ public
getBody(): Psr\Http\Message\StreamInterface
Gets the body of the message.
Returns
Psr\Http\Message\StreamInterface
getCookie() ¶ public
getCookie(string $key, array|string|null $default = null): array|string|null
Read cookie data from the request's cookie data.
Parameters
-
string
$key The key or dotted path you want to read.
-
array|string|null
$default optional The default value if the cookie is not set.
Returns
array|string|null
getCookieCollection() ¶ public
getCookieCollection(): Cake\Http\Cookie\CookieCollection
Get a cookie collection based on the request's cookies
The CookieCollection lets you interact with request cookies using
\Cake\Http\Cookie\Cookie
objects and can make converting request cookies
into response cookies easier.
This method will create a new cookie collection each time it is called.
This is an optimization that allows fewer objects to be allocated until
the more complex CookieCollection is needed. In general you should prefer
getCookie()
and getCookieParams()
over this method. Using a CookieCollection
is ideal if your cookies contain complex JSON encoded data.
Returns
Cake\Http\Cookie\CookieCollection
getCookieParams() ¶ public
getCookieParams(): array
Get all the cookie data from the request.
Retrieves cookies sent by the client to the server.
The data MUST be compatible with the structure of the $_COOKIE superglobal.
Returns
array
getData() ¶ public
getData(string|null $name = null, mixed $default = null): mixed
Provides a safe accessor for request data. Allows you to use Hash::get() compatible paths.
Reading values.
// get all data
$request->getData();
// Read a specific field.
$request->getData('Post.title');
// With a default value.
$request->getData('Post.not there', 'default value');
When reading values you will get null
for keys/values that do not exist.
Developers are encouraged to use getParsedBody() if they need the whole data array, as it is PSR-7 compliant, and this method is not. Using Hash::get() you can also get single params.
PSR-7 Alternative
$value = Hash::get($request->getParsedBody(), 'Post.id');
Parameters
-
string|null
$name optional Dot separated name of the value to read. Or null to read all data.
-
mixed
$default optional The default data.
Returns
mixed
getEnv() ¶ public
getEnv(string $key, string|null $default = null): string|null
Get a value from the request's environment data. Fallback to using env() if the key is not set in the $environment property.
Parameters
-
string
$key The key you want to read from.
-
string|null
$default optional Default value when trying to retrieve an environment variable's value that does not exist.
Returns
string|null
getFlash() ¶ public
getFlash(): Cake\Http\FlashMessage
Returns the instance of the FlashMessage object for this request
Returns
Cake\Http\FlashMessage
getHeader() ¶ public
getHeader(string $name): array<string>
Get a single header from the request.
Return the header value as an array. If the header is not present an empty array will be returned.
Parameters
-
string
$name The header you want to get (case-insensitive)
Returns
array<string>
Links
getHeaderLine() ¶ public
getHeaderLine(string $name): string
Get a single header as a string from the request.
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
-
string
$name The header you want to get (case-insensitive)
Returns
string
Links
getHeaders() ¶ public
getHeaders(): array<string[]>
Get all headers in the request.
Returns an associative array where the header names are the keys and the values are a list of header values.
While header names are not case-sensitive, getHeaders() will normalize the headers.
Returns
array<string[]>
Links
getMethod() ¶ public
getMethod(): string
Get the HTTP method used for this request. There are a few ways to specify a method.
- If your client supports it you can use native HTTP methods.
- You can set the HTTP-X-Method-Override header.
- You can submit an input with the name
_method
Any of these 3 approaches can be used to set the HTTP method used by CakePHP internally, and will effect the result of this method.
Returns
string
Links
getParam() ¶ public
getParam(string $name, mixed $default = null): mixed
Safely access the values in $this->params.
Parameters
-
string
$name The name or dotted path to parameter.
-
mixed
$default optional The default value if
$name
is not set. Defaultnull
.
Returns
mixed
getParsedBody() ¶ public
getParsedBody(): object|array|null
Get the parsed request body data.
If the request Content-Type is either application/x-www-form-urlencoded or multipart/form-data, and the request method is POST, this will be the post data. For other content types, it may be the deserialized request body.
Returns
object|array|null
getProtocolVersion() ¶ public
getProtocolVersion(): string
Retrieves the HTTP protocol version as a string.
The string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
Returns
string
getQuery() ¶ public
getQuery(string|null $name = null, mixed $default = null): array|string|null
Read a specific query value or dotted path.
Developers are encouraged to use getQueryParams() if they need the whole query array, as it is PSR-7 compliant, and this method is not. Using Hash::get() you can also get single params.
PSR-7 Alternative
$value = Hash::get($request->getQueryParams(), 'Post.id');
Parameters
-
string|null
$name optional The name or dotted path to the query param or null to read all.
-
mixed
$default optional The default value if the named parameter is not set, and $name is not null.
Returns
array|string|null
See Also
getQueryParams() ¶ public
getQueryParams(): array
Get all the query parameters in accordance to the PSR-7 specifications. To read specific query values use the alternative getQuery() method.
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.
Returns
array
Links
getRequestTarget() ¶ public
getRequestTarget(): string
Retrieves the request's target.
Retrieves the message's request-target either as it was requested,
or as set with withRequestTarget()
. By default this will return the
application relative path without base directory, and the query string
defined in the SERVER environment.
Returns
string
getServerParams() ¶ public
getServerParams(): array
Get all the server environment parameters.
Read all of the 'environment' or 'server' data that was used to create this request.
Returns
array
Links
getSession() ¶ public
getSession(): Cake\Http\Session
Returns the instance of the Session object for this request
Returns
Cake\Http\Session
getTrustedProxies() ¶ public
getTrustedProxies(): array<string>
Get trusted proxies
Returns
array<string>
getUploadedFile() ¶ public
getUploadedFile(string $path): Psr\Http\Message\UploadedFileInterface|null
Get the uploaded file from a dotted path.
Parameters
-
string
$path The dot separated path to the file you want.
Returns
Psr\Http\Message\UploadedFileInterface|null
getUploadedFiles() ¶ public
getUploadedFiles(): array
Get the array of uploaded files from the request.
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().
Returns
array
getUri() ¶ public
getUri(): Psr\Http\Message\UriInterface
Retrieves the URI instance.
This method MUST return a UriInterface instance.
Returns
Psr\Http\Message\UriInterface
hasHeader() ¶ public
hasHeader(string $name): bool
Check if a header is set in the request.
Parameters
-
string
$name The header you want to get (case-insensitive)
Returns
bool
Links
host() ¶ public
host(): string|null
Get the host that the request was handled on.
Returns
string|null
input() ¶ public
input(callable|null $callback = null, mixed ...$args): mixed
Read data from php://input
. Useful when interacting with XML or JSON
request body content.
Getting input with a decoding function:
$this->request->input('json_decode');
Getting input using a decoding function, and additional params:
$this->request->input('Xml::build', ['return' => 'DOMDocument']);
Any additional parameters are applied to the callback in the order they are given.
Parameters
-
callable|null
$callback optional A decoding callback that will convert the string data to another representation. Leave empty to access the raw input data. You can also supply additional parameters for the decoding callback using var args, see above.
-
mixed
...$args The additional arguments
Returns
mixed
is() ¶ public
is(array<string>|string $type, mixed ...$args): bool
Check whether a Request is a certain type.
Uses the built-in detection rules as well as additional rules
defined with {@link \Cake\Http\ServerRequest::addDetector()}. Any detector can be called
as is($type)
or is$Type()
.
Parameters
-
array<string>|string
$type The type of request you want to check. If an array this method will return true if the request matches any type.
-
mixed
...$args List of arguments
Returns
bool
isAll() ¶ public
isAll(array<string> $types): bool
Check that a request matches all the given types.
Allows you to test multiple types and union the results. See Request::is() for how to add additional types and the built-in types.
Parameters
-
array<string>
$types The types to check.
Returns
bool
See Also
normalizeHeaderName() ¶ protected
normalizeHeaderName(string $name): string
Normalize a header name into the SERVER version.
Parameters
-
string
$name The header name.
Returns
string
parseAccept() ¶ public
parseAccept(): array
Parse the HTTP_ACCEPT header and return a sorted array with content types as the keys, and pref values as the values.
Generally you want to use {@link \Cake\Http\ServerRequest::accepts()} to get a simple list of the accepted content types.
Returns
array
processUrlOption() ¶ protected
processUrlOption(array<string, mixed> $config): array<string, mixed>
Set environment vars based on url
option to facilitate UriInterface instance generation.
query
option is also updated based on URL's querystring.
Parameters
-
array<string, mixed>
$config Config array.
Returns
array<string, mixed>
referer() ¶ public
referer(bool $local = true): string|null
Returns the referer that referred this request.
Parameters
-
bool
$local optional Attempt to return a local address. Local addresses do not contain hostnames.
Returns
string|null
scheme() ¶ public
scheme(): string|null
Get the current url scheme used for the request.
e.g. 'http', or 'https'
Returns
string|null
setTrustedProxies() ¶ public
setTrustedProxies(array<string> $proxies): void
register trusted proxies
Parameters
-
array<string>
$proxies ips list of trusted proxies
Returns
void
subdomains() ¶ public
subdomains(int $tldLength = 1): array<string>
Get the subdomains for a host.
Parameters
-
int
$tldLength optional Number of segments your tld contains. For example:
example.com
contains 1 tld. Whileexample.co.uk
contains 2.
Returns
array<string>
validateUploadedFiles() ¶ protected
validateUploadedFiles(array $uploadedFiles, string $path): void
Recursively validate uploaded file data.
Parameters
-
array
$uploadedFiles The new files array to validate.
-
string
$path The path thus far.
Returns
void
Throws
InvalidArgumentException
If any leaf elements are not valid files.
withAddedHeader() ¶ public
withAddedHeader(string $name, string|string[] $value): static
Get a modified request with the provided header.
Existing header values will be retained. The provided value will be appended into the existing values.
Parameters
-
string
$name The header name.
-
string|string[]
$value The header value
Returns
static
Links
withAttribute() ¶ public
withAttribute(string $name, mixed $value): static
Return an instance with the specified request attribute.
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
-
string
$name The attribute name.
-
mixed
$value The value of the attribute.
Returns
static
withBody() ¶ public
withBody(StreamInterface $body): static
Return an instance with the specified message body.
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
-
StreamInterface
$body The new request body
Returns
static
withCookieCollection() ¶ public
withCookieCollection(Cake\Http\Cookie\CookieCollection $cookies): static
Replace the cookies in the request with those contained in the provided CookieCollection.
Parameters
-
Cake\Http\Cookie\CookieCollection
$cookies The cookie collection
Returns
static
withCookieParams() ¶ public
withCookieParams(array $cookies): static
Replace the cookies and get a new request instance.
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
-
array
$cookies The new cookie data to use.
Returns
static
withData() ¶ public
withData(string $name, mixed $value): static
Update the request with a new request data element.
Returns an updated request object. This method returns a new request object and does not mutate the request in-place.
Use withParsedBody()
if you need to replace the all request data.
Parameters
-
string
$name The dot separated path to insert $value at.
-
mixed
$value The value to insert into the request data.
Returns
static
withEnv() ¶ public
withEnv(string $key, string $value): static
Update the request with a new environment data element.
Returns an updated request object. This method returns a new request object and does not mutate the request in-place.
Parameters
-
string
$key The key you want to write to.
-
string
$value Value to set
Returns
static
withHeader() ¶ public
withHeader(string $name, string|string[] $value): static
Get a modified request with the provided header.
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
-
string
$name The header name.
-
string|string[]
$value The header value
Returns
static
Links
withMethod() ¶ public
withMethod(string $method): static
Update the request method and get a new instance.
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
-
string
$method The HTTP method to use.
Returns
static
Links
withParam() ¶ public
withParam(string $name, mixed $value): static
Update the request with a new routing parameter
Returns an updated request object. This method returns a new request object and does not mutate the request in-place.
Parameters
-
string
$name The dot separated path to insert $value at.
-
mixed
$value The value to insert into the the request parameters.
Returns
static
withParsedBody() ¶ public
withParsedBody(null|array|object $data): static
Update the parsed body and get a new instance.
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
-
null|array|object
$data The deserialized body data. This will typically be in an array or object.
Returns
static
withProtocolVersion() ¶ public
withProtocolVersion(string $version): static
Return an instance with the specified HTTP protocol version.
The version string MUST contain only the HTTP version number (e.g., "1.1", "1.0").
Parameters
-
string
$version HTTP protocol version
Returns
static
withQueryParams() ¶ public
withQueryParams(array $query): static
Update the query string data and get a new instance.
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
-
array
$query The query string data to use
Returns
static
Links
withRequestTarget() ¶ public
withRequestTarget(string $requestTarget): static
Create a new instance with a specific request-target.
You can use this method to overwrite the request target that is inferred from the request's Uri. This also lets you change the request target's form to an absolute-form, authority-form or asterisk-form
Parameters
-
string
$requestTarget The request target.
Returns
static
Links
withUploadedFiles() ¶ public
withUploadedFiles(array $uploadedFiles): static
Update the request replacing the files, and creating a new instance.
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
-
array
$uploadedFiles An array of uploaded file objects.
Returns
static
Throws
InvalidArgumentException
when $files contains an invalid object.
withUri() ¶ public
withUri(UriInterface $uri, bool $preserveHost = false): static
Return an instance with the specified uri
Warning Replacing the Uri will not update the base
, webroot
,
and url
attributes.
Parameters
-
UriInterface
$uri The new request uri
-
bool
$preserveHost optional Whether the host should be retained.
Returns
static
withoutAttribute() ¶ public
withoutAttribute(string $name): static
Return an instance without the specified request attribute.
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
-
string
$name The attribute name.
Returns
static
Throws
InvalidArgumentException
withoutData() ¶ public
withoutData(string $name): static
Update the request removing a data element.
Returns an updated request object. This method returns a new request object and does not mutate the request in-place.
Parameters
-
string
$name The dot separated path to remove.
Returns
static
withoutHeader() ¶ public
withoutHeader(string $name): static
Get a modified request without a provided header.
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
-
string
$name The header name to remove.
Returns
static
Links
Property Detail
$_detectors ¶ protected static
The built in detectors used with is()
can be modified with addDetector()
.
There are several ways to specify a detector, see \Cake\Http\ServerRequest::addDetector() for the various formats and ways to define detectors.
Type
array<callable|array>
$data ¶ protected
Array of POST data. Will contain form data as well as uploaded files. In PUT/PATCH/DELETE requests this property will contain the form-urlencoded data.
Type
object|array|null
$emulatedAttributes ¶ protected
A list of properties that emulated by the PSR7 attribute methods.
Type
array<string>
$flash ¶ protected
Instance of a FlashMessage object relative to this request
Type
Cake\Http\FlashMessage
$stream ¶ protected
Request body stream. Contains php://input unless input
constructor option is used.
Type
Psr\Http\Message\StreamInterface
$trustProxy ¶ public
Whether to trust HTTP_X headers set by most load balancers. Only set to true if your application runs behind load balancers/proxies that you control.
Type
bool