Documentation

IncomingRequest extends Request
in package

Application

Class IncomingRequest

Represents an incoming, getServer-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)

$config : App: Configuration settings.
$uri : URI: The URI for this request.
$body : mixed: Message body
$defaultLocale : string: The default Locale this request should operate under.
$enableCSRF : bool: Enable CSRF flag
$files : FileCollection|null: File collection
$globals : array<string|int, mixed>: 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>: 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 path (relative to SCRIPT_NAME).
$protocolVersion : string: Protocol version
$proxyIPs : string|array<string|int, mixed>: Proxy IPs
$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
__construct() : mixed: Constructor
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() : mixed: Handles setting up the locale, perhaps auto-detecting through content negotiation.
detectPath() : string: Detects the relative path based on the URIProtocol Config setting.
fetchGlobal() : mixed: Fetches one or more items from a global, like cookies, get, post, etc.
getBody() : mixed: Returns the Message's body.
getCookie() : mixed: Fetch an item from the COOKIE array.
getDefaultLocale() : string: Returns the default locale as set in 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() : mixed: Fetch an item from GET data.
getGetPost() : mixed: 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() : mixed: A convenience method that grabs the raw input stream and decodes the JSON into an array.
getJsonVar() : mixed: 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: Get the request method.
getOldInput() : mixed: 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 path relative to SCRIPT_NAME, running detection as necessary.
getPost() : mixed: Fetch an item from POST.
getPostGet() : mixed: Fetch an item from POST data with fallback to GET.
getProtocolVersion() : string: Returns the HTTP Protocol Version.
getRawInput() : mixed: A convenience method that grabs the raw input stream(send method in PUT, PATCH, DELETE) and decodes the String into an array.
getServer() : mixed: Fetch an item from the $_SERVER array.
getUri() : URI: Retrieves the URI instance.
getUserAgent() : UserAgent: Fetch the user agent string
getVar() : mixed: 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() : 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.
headers() : array<string, Header>: Returns an array containing all Headers.
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.
isValidIP() : bool: Validate an IP address
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 getServer 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() : Request: Sets the request method. Used when spoofing the request.
setPath() : $this: Sets the relative path and updates the URI object.
setProtocolVersion() : $this: Sets the HTTP protocol version.
withMethod() : static: Returns an instance with the specified method.
detectURI() : mixed: Sets up our URI object based on the information we have. This is either provided by the user in the baseURL Config setting, or determined from the environment as needed.
getHeaderName() : string: Takes a header name in any case, and returns the normal-case version of the header.
parseQueryString() : string: Parse QUERY_STRING
parseRequestURI() : string: Will parse the REQUEST_URI and automatically detect the URI from it, fixing the query string if necessary.
populateGlobals() : mixed: Saves a copy of the current state of one of several PHP globals so we can retrieve them later.
removeRelativeDirectory() : string: Remove relative directory (../) and multi slashes (///)

$config

Configuration settings.


    public
        App
    $config

$uri

The URI for this request.


    public
        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 script name. So, if hosted in a sub-folder this will appear different than actual URL. If you need that use getPath().

$body

Message body


    protected
        mixed
    $body

$defaultLocale

The default Locale this request should operate under.


    protected
        string
    $defaultLocale

$enableCSRF

Enable CSRF flag


    protected
        bool
    $enableCSRF
     = false

Enables a CSRF cookie token to be set. Set automatically based on Config setting.

$files

File collection


    protected
        FileCollection|null
    $files

$globals

Stores values we've retrieved from PHP globals.


    protected
        array<string|int, mixed>
    $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>
    $headers
     = []

$ipAddress

IP address of the current user.


    protected
        string
    $ipAddress
     = ''

$locale

The current locale of the application.


    protected
        string
    $locale

Default value is set in Config\App.php

$method

Request method.


    protected
        string
    $method

$negotiator

Negotiator


    protected
        Negotiate|null
    $negotiator

$oldInput

Holds the old data from a redirect.


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

$path

The detected path (relative to SCRIPT_NAME).


    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

$proxyIPs

Proxy IPs


    protected
        string|array<string|int, mixed>
    $proxyIPs

$userAgent

The user agent this request is from.


    protected
        UserAgent
    $userAgent

$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']

__construct()

Constructor


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

Parameters

$config : App
$uri : URI = null
$body : string|null = 'php://input'
$userAgent : UserAgent = null

Return values

mixed —

appendBody()

Appends data to the body of the current message.


    public
                appendBody(mixed $data) : $this

Parameters

$data : mixed

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) : mixed

Parameters

$config : App

Return values

mixed —

detectPath()

Detects the relative path based on the URIProtocol Config setting.


    public
                detectPath([string $protocol = '' ]) : string

Parameters

$protocol : string = ''

Return values

string —

fetchGlobal()

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


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

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

$method : string: Input filter constant
$index : string|array<string|int, mixed>|null = null
$filter : int|null = null: Filter constant
$flags : array<string|int, mixed>|int|null = null: Options

Return values

mixed —

getBody()

Returns the Message's body.


    public
                getBody() : mixed

Return values

mixed —

getCookie()

Fetch an item from the COOKIE array.


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

Parameters

$index : string|array<string|int, mixed>|null = null: Index for item to be fetched from $_COOKIE
$filter : int|null = null: A filter name to be applied
$flags : mixed = null

Return values

mixed —

getDefaultLocale()

Returns the default locale as set in Config\App.php


    public
                getDefaultLocale() : string

Return values

string —

getEnv()

Fetch an item from the $_ENV array.


    public
                getEnv([null $index = null ][, null $filter = null ][, null $flags = null ]) : mixed

Parameters

$index : null = null: Index for item to be fetched from $_ENV
$filter : null = null: A filter name to be applied
$flags : null = null

Return values

mixed —

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([string|array<string|int, mixed>|null $index = null ][, int|null $filter = null ][, mixed|null $flags = null ]) : mixed

Parameters

$index : string|array<string|int, mixed>|null = null: Index for item to fetch from $_GET.
$filter : int|null = null: A filter name to apply.
$flags : mixed|null = null

Return values

mixed —

getGetPost()

Fetch an item from GET data with fallback to POST.


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

Parameters

$index : string|array<string|int, mixed>|null = null: Index for item to be fetched from $_GET or $_POST
$filter : int|null = null: A filter name to apply
$flags : mixed = null

Return values

mixed —

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

Parameters

$name : string

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>

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

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) : mixed

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: Bitmask of options

Return values

mixed —

getJsonVar()

Get a specific variable from a JSON input stream


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

Parameters

$index : string: 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

mixed —

getLocale()

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


    public
                getLocale() : string

Return values

string —

getMethod()

Get the request method.


    public
                getMethod([bool $upper = false ]) : string

Parameters

$upper : bool = false: Whether to return in upper or lower case.

Return values

string —

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) : mixed

Parameters

$key : string

Return values

mixed —

getPath()

Returns the path relative to SCRIPT_NAME, running detection as necessary.


    public
                getPath() : string

Return values

string —

getPost()

Fetch an item from POST.


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

Parameters

$index : string|array<string|int, mixed>|null = null: Index for item to fetch from $_POST.
$filter : int|null = null: A filter name to apply
$flags : mixed = null

Return values

mixed —

getPostGet()

Fetch an item from POST data with fallback to GET.


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

Parameters

$index : string|array<string|int, mixed>|null = null: Index for item to fetch from $_POST or $_GET
$filter : int|null = null: A filter name to apply
$flags : mixed = null

Return values

mixed —

getProtocolVersion()

Returns the HTTP Protocol Version.


    public
                getProtocolVersion() : string

Return values

string —

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() : mixed

Return values

mixed —

getServer()

Fetch an item from the $_SERVER array.


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

Parameters

$index : string|array<string|int, mixed>|null = null: Index for item to be fetched from $_SERVER
$filter : int|null = null: A filter name to be applied
$flags : null = null

Return values

mixed —

getUri()

Retrieves the URI instance.


    public
                getUri() : URI

Return values

URI —

getUserAgent()

Fetch the user agent string


    public
                getUserAgent() : UserAgent

Return values

UserAgent —

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([string|array<string|int, mixed>|null $index = null ][, int|null $filter = null ][, mixed $flags = null ]) : mixed

Parameters

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

Return values

mixed —

hasHeader()

Determines whether a header exists.


    public
                hasHeader(string $name) : bool

Parameters

$name : string

Return values

bool —

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) : array<string|int, mixed>|Header|null

Parameters

$name : string

Return values

array<string|int, mixed>|Header|null —

headers()

Returns an array containing all Headers.


    public
                headers() : array<string, Header>

Return values

array<string, Header> —

An array of the Header objects

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 —

isValidIP()

Validate an IP address


    public
                isValidIP([string $ip = null ][, string $which = null ]) : bool

Parameters

$ip : string = null: IP Address
$which : string = null: IP protocol: 'ipv4' or 'ipv6'

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 getServer knows about.


    public
                populateHeaders() : void

Return values

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(mixed $data) : $this

Parameters

$data : mixed

Return values

$this —

setGlobal()

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


    public
                setGlobal(string $method, mixed $value) : $this

Parameters

$method : string
$value : mixed

Return values

$this —

setHeader()

Sets a header and it's value.


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

Parameters

$name : string
$value : array<string|int, mixed>|null|string

Return values

$this —

setLocale()

Sets the locale string for this request.


    public
                setLocale(string $locale) : IncomingRequest

Parameters

$locale : string

Return values

IncomingRequest —

setMethod()

Sets the request method. Used when spoofing the request.


    public
                setMethod(string $method) : Request

Parameters

$method : string

Return values

Request —

setPath()

Sets the relative path and updates the URI object.


    public
                setPath(string $path[, App $config = null ]) : $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 SCRIPT_NAME
$config : App = null: Optional alternate config to use

Return values

$this —

setProtocolVersion()

Sets the HTTP protocol version.


    public
                setProtocolVersion(string $version) : $this

Parameters

$version : string

Return values

$this —

withMethod()

Returns an instance with the specified method.


    public
                withMethod(string $method) : static

Parameters

$method : string

Return values

static —

detectURI()

Sets up our URI object based on the information we have. This is either provided by the user in the baseURL Config setting, or determined from the environment as needed.


    protected
                detectURI(string $protocol, string $baseURL) : mixed

Parameters

$protocol : string
$baseURL : string

Return values

mixed —

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 —

parseQueryString()

Parse QUERY_STRING


    protected
                parseQueryString() : string

Will parse QUERY_STRING and automatically detect the URI from it.

Return values

string —

parseRequestURI()

Will parse the REQUEST_URI and automatically detect the URI from it, fixing the query string if necessary.


    protected
                parseRequestURI() : string

Return values

string —

The URI it found.

populateGlobals()

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


    protected
                populateGlobals(string $method) : mixed

Parameters

$method : string

Return values

mixed —

removeRelativeDirectory()

Remove relative directory (../) and multi slashes (///)


    protected
                removeRelativeDirectory(string $uri) : string

Do some final cleaning of the URI and return it, currently only used in static::_parse_request_uri()

Parameters

$uri : string

Return values

string —

IncomingRequest extends Request in package Application

Table of Contents

Properties

$config

$uri

$body

$defaultLocale

$enableCSRF

$files

$globals

$headerMap

$headers

$ipAddress

Tags

$locale

$method

$negotiator

$oldInput

$path

$protocolVersion

$proxyIPs

Tags

$userAgent

$validLocales

$validProtocolVersions

Methods

__construct()

Parameters

Return values

appendBody()

Parameters

Return values

appendHeader()

Parameters

Return values

detectLocale()

Parameters

Return values

detectPath()

Parameters

Return values

fetchGlobal()

Parameters

Return values

getBody()

Return values

getCookie()

Parameters

Return values

getDefaultLocale()

Return values

getEnv()

Parameters

Return values

getFile()

Parameters

Return values

getFileMultiple()

Parameters

Return values

getFiles()

Return values

getGet()

Parameters

Return values

getGetPost()

Parameters

Return values

getHeader()

Parameters

Tags

Return values

getHeaderLine()

Parameters

Return values

getHeaders()

Tags

Return values

getIPAddress()

Return values

IncomingRequest extends Request
in package

Application