CodeIgniter v4.7 API

IncomingRequest extends Request
in package

Class IncomingRequest

Represents an incoming, server-side HTTP request.

Per the HTTP specification, this interface includes properties for each of the following:

  • Protocol version
  • HTTP method
  • URI
  • Headers
  • Message body

Additionally, it encapsulates all data as it has arrived to the application from the CGI and/or PHP environment, including:

  • The values represented in $_SERVER.
  • Any cookies provided (generally via $_COOKIE)
  • Query string arguments (generally via $_GET, or as parsed via parse_str())
  • Upload files, if any (as represented by $_FILES)
  • Deserialized body binds (generally from $_POST)
Tags
see
IncomingRequestTest

Table of Contents

Properties

$body  : string|null
Message body
$config  : App
Configuration settings.
$defaultLocale  : string
The default Locale this request should operate under.
$files  : FileCollection|null
File collection
$globals  : array{get?: array, post?: array, request?: array, cookie?: array, server?: array}
Stores values we've retrieved from PHP globals.
$headerMap  : array<string|int, mixed>
Holds a map of lower-case header names and their normal-case key as it is in $headers.
$headers  : array<string, Header|array<int, Header>>
List of all HTTP request headers.
$ipAddress  : string
IP address of the current user.
$locale  : string
The current locale of the application.
$method  : string
Request method.
$negotiator  : Negotiate|null
Negotiator
$oldInput  : array<string|int, mixed>
Holds the old data from a redirect.
$path  : string|null
The detected URI path (relative to the baseURL).
$protocolVersion  : string
Protocol version
$uri  : URI
The URI for this request.
$userAgent  : UserAgent
The user agent this request is from.
$validLocales  : array<string|int, mixed>
Stores the valid locale codes.
$validProtocolVersions  : array<string|int, mixed>
List of valid protocol versions

Methods

__construct()  : mixed
Constructor
addHeader()  : $this
Adds a header (not a header value) with the same name.
appendBody()  : $this
Appends data to the body of the current message.
appendHeader()  : $this
Adds an additional header value to any headers that accept multiple values (i.e. are an array or implement ArrayAccess)
detectLocale()  : void
Handles setting up the locale, perhaps auto-detecting through content negotiation.
fetchGlobal()  : array<string|int, mixed>|bool|float|int|object|string|null
Fetches one or more items from a global, like cookies, get, post, etc.
getBody()  : string|null
Returns the Message's body.
getCookie()  : array<string|int, mixed>|bool|float|int|object|string|null
Fetch an item from the COOKIE array.
getDefaultLocale()  : string
Returns the default locale as set in app/Config/App.php
getEnv()  : mixed
Fetch an item from the $_ENV array.
getFile()  : UploadedFile|null
Retrieves a single file by the name of the input field used to upload it.
getFileMultiple()  : array<string|int, mixed>|null
Verify if a file exist, by the name of the input field used to upload it, in the collection of uploaded files and if is have been uploaded with multiple option.
getFiles()  : array<string|int, mixed>
Returns an array of all files that have been uploaded with this request. Each file is represented by an UploadedFile instance.
getGet()  : array<string|int, mixed>|bool|float|int|object|string|null
Fetch an item from GET data.
getGetPost()  : array<string|int, mixed>|bool|float|int|object|string|null
Fetch an item from GET data with fallback to POST.
getHeader()  : array<string|int, mixed>|Header|null
Returns a single header object. If multiple headers with the same name exist, then will return an array of header objects.
getHeaderLine()  : string
Retrieves a comma-separated string of the values for a single header.
getHeaders()  : array<string, Header>
Returns an array containing all headers.
getIPAddress()  : string
Gets the user's IP address.
getJSON()  : array<string|int, mixed>|bool|float|int|stdClass|null
A convenience method that grabs the raw input stream and decodes the JSON into an array.
getJsonVar()  : array<string|int, mixed>|bool|float|int|stdClass|string|null
Get a specific variable from a JSON input stream
getLocale()  : string
Gets the current locale, with a fallback to the default locale if none is set.
getMethod()  : string
Retrieves the HTTP method of the request.
getOldInput()  : array<string|int, mixed>|string|null
Attempts to get old Input data that has been flashed to the session with redirect_with_input(). It first checks for the data in the old POST data, then the old GET data and finally check for dot arrays
getPath()  : string
Returns the URI path relative to baseURL, running detection as necessary.
getPost()  : array<string|int, mixed>|bool|float|int|object|string|null
Fetch an item from POST.
getPostGet()  : array<string|int, mixed>|bool|float|int|object|string|null
Fetch an item from POST data with fallback to GET.
getProtocolVersion()  : string
Returns the HTTP Protocol Version.
getRawInput()  : array<string|int, mixed>
A convenience method that grabs the raw input stream(send method in PUT, PATCH, DELETE) and decodes the String into an array.
getRawInputVar()  : array<string|int, mixed>|bool|float|int|object|string|null
Gets a specific variable from raw input stream (send method in PUT, PATCH, DELETE).
getServer()  : mixed
Fetch an item from the $_SERVER array.
getUri()  : URI
Retrieves the URI instance.
getUserAgent()  : UserAgent
Fetch the user agent string
getVar()  : array<string|int, mixed>|bool|float|int|stdClass|string|null
Fetch an item from JSON input stream with fallback to $_REQUEST object. This is the simplest way to grab data from the request object and can be used in lieu of the other get* methods in most cases.
hasHeader()  : bool
Determines whether a header exists.
header()  : Header|array<int, Header>|null
Returns a single Header object. If multiple headers with the same name exist, then will return an array of header objects.
headers()  : array<string, Header|array<int, Header>>
Returns an array containing all Headers.
is()  : bool
Checks this request type.
isAJAX()  : bool
Test to see if a request contains the HTTP_X_REQUESTED_WITH header.
isCLI()  : bool
Determines if this request was made from the command line (CLI).
isSecure()  : bool
Attempts to detect if the current connection is secure through a few different methods.
negotiate()  : string
Provides a convenient way to work with the Negotiate class for content negotiation.
populateHeaders()  : void
Populates the $headers array with any headers the server knows about.
prependHeader()  : $this
Adds an additional header value to any headers that accept multiple values (i.e. are an array or implement ArrayAccess)
removeHeader()  : $this
Removes a header from the list of headers we track.
setBody()  : $this
Sets the body of the current message.
setGlobal()  : $this
Allows manually setting the value of PHP global, like $_GET, $_POST, etc.
setHeader()  : $this
Sets a header and it's value.
setLocale()  : IncomingRequest
Sets the locale string for this request.
setMethod()  : $this
Sets the request method. Used when spoofing the request.
setProtocolVersion()  : $this
Sets the HTTP protocol version.
setValidLocales()  : $this
Set the valid locales.
withMethod()  : static
Returns an instance with the specified method.
withUri()  : static
Returns an instance with the provided URI.
getHeaderName()  : string
Takes a header name in any case, and returns the normal-case version of the header.
populateGlobals()  : void
Saves a copy of the current state of one of several PHP globals, so we can retrieve them later.
checkMultipleHeaders()  : void
getClientIP()  : string|null
Gets the client IP address from the HTTP header.
getPostMaxSize()  : int
hasMultipleHeaders()  : bool
setPath()  : $this
Sets the URI path relative to baseURL.

Properties

$body

Message body

protected string|null $body

$defaultLocale

The default Locale this request should operate under.

protected string $defaultLocale

$globals

Stores values we've retrieved from PHP globals.

Use the Superglobals service instead

protected array{get?: array, post?: array, request?: array, cookie?: array, server?: array} $globals = []

$headerMap

Holds a map of lower-case header names and their normal-case key as it is in $headers.

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

Used for case-insensitive header access.

$headers

List of all HTTP request headers.

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

[name => Header] or [name => [Header1, Header2]]

$ipAddress

IP address of the current user.

Will become private in a future release

protected string $ipAddress = ''

$locale

The current locale of the application.

protected string $locale

Default value is set in app/Config/App.php

$oldInput

Holds the old data from a redirect.

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

$path

The detected URI path (relative to the baseURL).

protected string|null $path

Note: current_url() uses this to build its URI, so this becomes the source for the "current URL" when working with the share request instance.

$protocolVersion

Protocol version

protected string $protocolVersion

$uri

The URI for this request.

protected URI $uri

Note: This WILL NOT match the actual URL in the browser since for everything this cares about (and the router, etc) is the portion AFTER the baseURL. So, if hosted in a sub-folder this will appear different than actual URI path. If you need that use getPath().

$validLocales

Stores the valid locale codes.

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

$validProtocolVersions

List of valid protocol versions

protected array<string|int, mixed> $validProtocolVersions = ['1.0', '1.1', '2.0', '3.0']

Methods

__construct()

Constructor

public __construct(App $config[, URI|null $uri = null ][, string|null $body = 'php://input' ][, UserAgent|null $userAgent = null ]) : mixed
Parameters
$config : App
$uri : URI|null = null
$body : string|null = 'php://input'
$userAgent : UserAgent|null = null

addHeader()

Adds a header (not a header value) with the same name.

public addHeader(string $name, string $value) : $this

Use this only when you set multiple headers with the same name, typically, for Set-Cookie.

Parameters
$name : string
$value : string
Return values
$this

appendBody()

Appends data to the body of the current message.

public appendBody(string $data) : $this
Parameters
$data : string
Return values
$this

appendHeader()

Adds an additional header value to any headers that accept multiple values (i.e. are an array or implement ArrayAccess)

public appendHeader(string $name, string|null $value) : $this
Parameters
$name : string
$value : string|null
Return values
$this

detectLocale()

Handles setting up the locale, perhaps auto-detecting through content negotiation.

public detectLocale(App $config) : void
Parameters
$config : App

fetchGlobal()

Fetches one or more items from a global, like cookies, get, post, etc.

public fetchGlobal("cookie"|"get"|"post"|"request"|"server" $name[, array<string|int, mixed>|int|string|null $index = null ][, int|null $filter = null ][, array<string|int, mixed>|int|null $flags = null ]) : array<string|int, mixed>|bool|float|int|object|string|null

Can optionally filter the input when you retrieve it by passing in a filter.

If $type is an array, it must conform to the input allowed by the filter_input_array method.

http://php.net/manual/en/filter.filters.sanitize.php

Parameters
$name : "cookie"|"get"|"post"|"request"|"server"

Superglobal name (lowercase)

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

Filter constant

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

Options

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

getBody()

Returns the Message's body.

public getBody() : string|null
Return values
string|null

getCookie()

Fetch an item from the COOKIE array.

public getCookie([array<string|int, mixed>|string|null $index = null ][, int|null $filter = null ][, array<string|int, mixed>|int|null $flags = null ]) : array<string|int, mixed>|bool|float|int|object|string|null
Parameters
$index : array<string|int, mixed>|string|null = null

Index for item to be fetched from $_COOKIE

$filter : int|null = null

A filter name to be applied

$flags : array<string|int, mixed>|int|null = null
Return values
array<string|int, mixed>|bool|float|int|object|string|null

getDefaultLocale()

Returns the default locale as set in app/Config/App.php

public getDefaultLocale() : string
Return values
string

getEnv()

Fetch an item from the $_ENV array.

public getEnv([array<string|int, mixed>|string|null $index = null ][, int|null $filter = null ][, array<string|int, mixed>|int|null $flags = null ]) : mixed

This method does not work from the beginning. Use env().

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

Index for item to be fetched from $_ENV

$filter : int|null = null

A filter name to be applied

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

getFile()

Retrieves a single file by the name of the input field used to upload it.

public getFile(string $fileID) : UploadedFile|null
Parameters
$fileID : string
Return values
UploadedFile|null

getFileMultiple()

Verify if a file exist, by the name of the input field used to upload it, in the collection of uploaded files and if is have been uploaded with multiple option.

public getFileMultiple(string $fileID) : array<string|int, mixed>|null
Parameters
$fileID : string
Return values
array<string|int, mixed>|null

getFiles()

Returns an array of all files that have been uploaded with this request. Each file is represented by an UploadedFile instance.

public getFiles() : array<string|int, mixed>
Return values
array<string|int, mixed>

getGet()

Fetch an item from GET data.

public getGet([array<string|int, mixed>|string|null $index = null ][, int|null $filter = null ][, array<string|int, mixed>|int|null $flags = null ]) : array<string|int, mixed>|bool|float|int|object|string|null
Parameters
$index : array<string|int, mixed>|string|null = null

Index for item to fetch from $_GET.

$filter : int|null = null

A filter name to apply.

$flags : array<string|int, mixed>|int|null = null
Return values
array<string|int, mixed>|bool|float|int|object|string|null

getGetPost()

Fetch an item from GET data with fallback to POST.

public getGetPost([array<string|int, mixed>|string|null $index = null ][, int|null $filter = null ][, array<string|int, mixed>|int|null $flags = null ]) : array<string|int, mixed>|bool|float|int|object|string|null
Parameters
$index : array<string|int, mixed>|string|null = null

Index for item to be fetched from $_GET or $_POST

$filter : int|null = null

A filter name to apply

$flags : array<string|int, mixed>|int|null = null
Return values
array<string|int, mixed>|bool|float|int|object|string|null

getHeader()

Returns a single header object. If multiple headers with the same name exist, then will return an array of header objects.

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

Use Message::header() to make room for PSR-7

Parameters
$name : string
Tags
TODO

Incompatible return value with PSR-7

codeCoverageIgnore
Return values
array<string|int, mixed>|Header|null

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.

Parameters
$name : string
Return values
string

getHeaders()

Returns an array containing all headers.

public getHeaders() : array<string, Header>

Use Message::headers() to make room for PSR-7

Tags
TODO

Incompatible return value with PSR-7

codeCoverageIgnore
Return values
array<string, Header>

An array of the request headers

getIPAddress()

Gets the user's IP address.

public getIPAddress() : string
Return values
string

IP address if it can be detected. If the IP address is not a valid IP address, then will return '0.0.0.0'.

getJSON()

A convenience method that grabs the raw input stream and decodes the JSON into an array.

public getJSON([bool $assoc = false ][, int $depth = 512 ][, int $options = 0 ]) : array<string|int, mixed>|bool|float|int|stdClass|null

If $assoc == true, then all objects in the response will be converted to associative arrays.

Parameters
$assoc : bool = false

Whether to return objects as associative arrays

$depth : int = 512

How many levels deep to decode

$options : int = 0

Bitmask of options

Tags
see
http://php.net/manual/en/function.json-decode.php
throws
HTTPException

When the body is invalid as JSON.

Return values
array<string|int, mixed>|bool|float|int|stdClass|null

getJsonVar()

Get a specific variable from a JSON input stream

public getJsonVar([array<string|int, mixed>|string|null $index = null ][, bool $assoc = false ][, int|null $filter = null ][, array<string|int, mixed>|int|null $flags = null ]) : array<string|int, mixed>|bool|float|int|stdClass|string|null
Parameters
$index : array<string|int, mixed>|string|null = null

The variable that you want which can use dot syntax for getting specific values.

$assoc : bool = false

If true, return the result as an associative array.

$filter : int|null = null

Filter Constant

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

Option

Return values
array<string|int, mixed>|bool|float|int|stdClass|string|null

getLocale()

Gets the current locale, with a fallback to the default locale if none is set.

public getLocale() : string
Return values
string

getMethod()

Retrieves the HTTP method of the request.

public getMethod() : string
Return values
string

Returns the request method (always uppercase)

getOldInput()

Attempts to get old Input data that has been flashed to the session with redirect_with_input(). It first checks for the data in the old POST data, then the old GET data and finally check for dot arrays

public getOldInput(string $key) : array<string|int, mixed>|string|null
Parameters
$key : string
Return values
array<string|int, mixed>|string|null

getPath()

Returns the URI path relative to baseURL, running detection as necessary.

public getPath() : string
Return values
string

getPost()

Fetch an item from POST.

public getPost([array<string|int, mixed>|string|null $index = null ][, int|null $filter = null ][, array<string|int, mixed>|int|null $flags = null ]) : array<string|int, mixed>|bool|float|int|object|string|null
Parameters
$index : array<string|int, mixed>|string|null = null

Index for item to fetch from $_POST.

$filter : int|null = null

A filter name to apply

$flags : array<string|int, mixed>|int|null = null
Return values
array<string|int, mixed>|bool|float|int|object|string|null

getPostGet()

Fetch an item from POST data with fallback to GET.

public getPostGet([array<string|int, mixed>|string|null $index = null ][, int|null $filter = null ][, array<string|int, mixed>|int|null $flags = null ]) : array<string|int, mixed>|bool|float|int|object|string|null
Parameters
$index : array<string|int, mixed>|string|null = null

Index for item to fetch from $_POST or $_GET

$filter : int|null = null

A filter name to apply

$flags : array<string|int, mixed>|int|null = null
Return values
array<string|int, mixed>|bool|float|int|object|string|null

getProtocolVersion()

Returns the HTTP Protocol Version.

public getProtocolVersion() : string
Return values
string

HTTP protocol version.

getRawInput()

A convenience method that grabs the raw input stream(send method in PUT, PATCH, DELETE) and decodes the String into an array.

public getRawInput() : array<string|int, mixed>
Return values
array<string|int, mixed>

getRawInputVar()

Gets a specific variable from raw input stream (send method in PUT, PATCH, DELETE).

public getRawInputVar([array<string|int, mixed>|string|null $index = null ][, int|null $filter = null ][, array<string|int, mixed>|int|null $flags = null ]) : array<string|int, mixed>|bool|float|int|object|string|null
Parameters
$index : array<string|int, mixed>|string|null = null

The variable that you want which can use dot syntax for getting specific values.

$filter : int|null = null

Filter Constant

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

Option

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

getServer()

Fetch an item from the $_SERVER array.

public getServer([array<string|int, mixed>|string|null $index = null ][, int|null $filter = null ][, array<string|int, mixed>|int|null $flags = null ]) : mixed
Parameters
$index : array<string|int, mixed>|string|null = null

Index for item to be fetched from $_SERVER

$filter : int|null = null

A filter name to be applied

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

getUri()

Retrieves the URI instance.

public getUri() : URI
Return values
URI

getVar()

Fetch an item from JSON input stream with fallback to $_REQUEST object. This is the simplest way to grab data from the request object and can be used in lieu of the other get* methods in most cases.

public getVar([array<string|int, mixed>|string|null $index = null ][, int|null $filter = null ][, array<string|int, mixed>|int|null $flags = null ]) : array<string|int, mixed>|bool|float|int|stdClass|string|null
Parameters
$index : array<string|int, mixed>|string|null = null
$filter : int|null = null

Filter constant

$flags : array<string|int, mixed>|int|null = null
Return values
array<string|int, mixed>|bool|float|int|stdClass|string|null

hasHeader()

Determines whether a header exists.

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.

header()

Returns a single Header object. If multiple headers with the same name exist, then will return an array of header objects.

public header(string $name) : Header|array<int, Header>|null
Parameters
$name : string
Return values
Header|array<int, Header>|null

headers()

Returns an array containing all Headers.

public headers() : array<string, Header|array<int, Header>>
Return values
array<string, Header|array<int, Header>>

An array of the Header objects

is()

Checks this request type.

public is(string $type) : bool
Parameters
$type : string
Return values
bool

isAJAX()

Test to see if a request contains the HTTP_X_REQUESTED_WITH header.

public isAJAX() : bool
Return values
bool

isCLI()

Determines if this request was made from the command line (CLI).

public isCLI() : bool
Return values
bool

isSecure()

Attempts to detect if the current connection is secure through a few different methods.

public isSecure() : bool
Return values
bool

negotiate()

Provides a convenient way to work with the Negotiate class for content negotiation.

public negotiate(string $type, array<string|int, mixed> $supported[, bool $strictMatch = false ]) : string
Parameters
$type : string
$supported : array<string|int, mixed>
$strictMatch : bool = false
Return values
string

populateHeaders()

Populates the $headers array with any headers the server knows about.

public populateHeaders() : void

prependHeader()

Adds an additional header value to any headers that accept multiple values (i.e. are an array or implement ArrayAccess)

public prependHeader(string $name, string $value) : $this
Parameters
$name : string
$value : string
Return values
$this

removeHeader()

Removes a header from the list of headers we track.

public removeHeader(string $name) : $this
Parameters
$name : string
Return values
$this

setBody()

Sets the body of the current message.

public setBody(string $data) : $this
Parameters
$data : string
Return values
$this

setGlobal()

Allows manually setting the value of PHP global, like $_GET, $_POST, etc.

public setGlobal("cookie"|"get"|"post"|"request"|"server" $name, mixed $value) : $this
Parameters
$name : "cookie"|"get"|"post"|"request"|"server"

Superglobal name (lowercase)

$value : mixed
Return values
$this

setHeader()

Sets a header and it's value.

public setHeader(string $name, array<string|int, mixed>|string|null $value) : $this
Parameters
$name : string
$value : array<string|int, mixed>|string|null
Return values
$this

setMethod()

Sets the request method. Used when spoofing the request.

public setMethod(string $method) : $this

Use withMethod() instead for immutability

Parameters
$method : string
Tags
codeCoverageIgnore
Return values
$this

setProtocolVersion()

Sets the HTTP protocol version.

public setProtocolVersion(string $version) : $this
Parameters
$version : string
Tags
throws
HTTPException

For invalid protocols

Return values
$this

setValidLocales()

Set the valid locales.

public setValidLocales(array<string|int, mixed> $locales) : $this
Parameters
$locales : array<string|int, mixed>
Return values
$this

withMethod()

Returns an instance with the specified method.

public withMethod(string $method) : static
Parameters
$method : string
Return values
static

withUri()

Returns an instance with the provided URI.

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

New request URI to use.

$preserveHost : bool = false

Preserve the original state of the Host header.

Return values
static

getHeaderName()

Takes a header name in any case, and returns the normal-case version of the header.

protected getHeaderName(string $name) : string
Parameters
$name : string
Return values
string

populateGlobals()

Saves a copy of the current state of one of several PHP globals, so we can retrieve them later.

protected populateGlobals("cookie"|"get"|"post"|"request"|"server" $name) : void

No longer needs to be called explicitly. Used internally to maintain BC with $globals.

Parameters
$name : "cookie"|"get"|"post"|"request"|"server"

Superglobal name (lowercase)

checkMultipleHeaders()

private checkMultipleHeaders(string $name) : void
Parameters
$name : string

getClientIP()

Gets the client IP address from the HTTP header.

private getClientIP(string $header) : string|null
Parameters
$header : string
Return values
string|null

hasMultipleHeaders()

private hasMultipleHeaders(string $name) : bool
Parameters
$name : string
Return values
bool

setPath()

Sets the URI path relative to baseURL.

private setPath(string $path) : $this

Note: Since current_url() accesses the shared request instance, this can be used to change the "current URL" for testing.

Parameters
$path : string

URI path relative to baseURL

Return values
$this

        
On this page

Search results