Luminova Framework

PHP Luminova: Incoming HTTP Request Management Class

Last updated: 2024-08-29 17:38:58

The Request class plays a crucial role in web applications by providing a structured and simple way to handle incoming HTTP requests and responses, providing methods for safe access and manipulation.

The Request class represents an incoming HTTP request to a server, encapsulating various components such as headers, query parameters, form data, and uploaded files. This class offers a structured approach to access and manipulate incoming HTTP requests, including built-in authentication mechanisms to validate requests based on origin, proxies, or allowed domains.

Accessing the Request Object

The request object can be accessed in multiple ways, depending on the context. You can use the global helper function, the Factory class, or the Controller class.

Access Methods

1. Using Global Helper Function

$request = request();

2. Accessing Through the Factory Class

use Luminova\Application\Factory;

$request = Factory::request();

3. Initializing the Request Instance Directly

use Luminova\Http\Request;

$request = new Request();

4. Accessing in Controller Classes

If your controller extends BaseController:

$this->request->foo();

If your controller extends BaseViewController, you can access it in two ways:

Direct Access:

$this->request()->foo();

Initializing in the onCreate Method:

You can initialize the request instance once, then access it later:

$this->request(); // Initialize

// Then access it.
$this->request->foo();

Properties

server

Http server instance.

public ?\Luminova\Http\Server $server = null;

header

Http request header instance.

public ?\Luminova\Http\Header $header = null;

agent

Browser request user-agent information.

public ?\Luminova\Http\UserAgent $agent = null;

Methods

getGet

Get a value from the GET request.

public getGet(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP GET request.


getPost

Get a value from the POST request.

public getPost(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP POST request.


getPut

Get a value from the PUT request.

public getPut(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP PUT request.


getOptions

Get a value from the OPTIONS request.

public getOptions(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP OPTIONS request.


getPatch

Get a value from the PATCH request.

public getPatch(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP PATCH request.


getHead

Get a value from the HEAD request.

public getHead(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP HEAD request.


getConnect

Get a value from the CONNECT request.

public getConnect(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP CONNECT request.


getTrace

Get a value from the TRACE request.

public getTrace(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP TRACE request.


getPropfind

Get a value from the PROPFIND request.

public getPropfind(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP PROPFIND request.


getMkcol

Get a value from the MKCOL request.

public getMkcol(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP MKCOL request.


getCopy

Get a value from the COPY request.

public getCopy(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP COPY request.


getMove

Get a value from the MOVE request.

public getMove(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP MOVE request.


getLock

Get a value from the LOCK request.

public getLock(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP LOCK request.


getUnlock

Get a value from the UNLOCK request.

public getUnlock(string $key, mixed $default = null): mixed

Parameters:

ParameterTypeDescription
$keystringThe key of the value to retrieve.
$defaultmixed(optional) The default value to return if the key is not found.

Return Value:

mixed - Response from HTTP UNLOCK request.


getArray

Get a value from the request body as an array.

public getArray(string $method, string $key, array $default = []): array

Parameters:

ParameterTypeDescription
$methodstringThe HTTP request method (e.g, GET, POST, etc..).
$keystringThe request body name to return.
$defaultarrayOptional default value to return (default: []).

Return Value:

array - Return array of HTTP request method key values.

Throws:


getBody

Get the entire request body as an Array or JSON object.

public getBody(bool $object = false): array|object

Parameters:

ParameterTypeDescription
$objectboolWhether to return an array or a json object (default: false).

Return Value:

array|object - Return the request body as an array or json object.


getFile

Get an uploaded file object by its input name.

public getFile(string $name): ?\Luminova\Http\File

Parameters:

ParameterTypeDescription
$namestringThe input file name.

Return Value:

\Luminova\Http\File|null - Return uploaded file instance or null if file input name not found.

See Also:

To learn more about File Upload Object, refer to the documentation.


getFiles

Get irritable array of uploaded files information.

public getFiles(): \Luminova\Http\File[]|false

Return Value:

\Luminova\Http\File[]|false - Return an array containing uploaded files information or false if no files found.


getMethod

Get the current request method.

public getMethod(): string

Return Value:

string - Return the HTTP request method.


isGet

Check if the request method is GET.

public isGet(): bool

Return Value:

bool - Returns true if the request method is GET, false otherwise.


isPost

Check if the request method is POST.

public isPost(): bool

Return Value:

bool - Returns true if the request method is POST, false otherwise.


isMethod

Check if the request method is the provided method.

public isMethod(string $method): bool

Parameters:

ParameterTypeDescription
$methodstringThe method to check against (e.g, POST, GET).

Return Value:

bool - Returns true if the request method matches the provided method, false otherwise.


getContentType

Get the request content type.

public getContentType(): string

Return Value:

string - Return the request content type or blank string if not available.


getAuth

Get HTTP request header authorization from (e.g, HTTP_AUTHORIZATION, Authorization or REDIRECT_HTTP_AUTHORIZATION).

public getAuth(): ?string

Return Value:

string|null - Return the authorization header value or null if no authorization header was sent.


Return Value:

bool - Return true if the request was made from the command line.


isSecure

Check if the current request connection is secure.

public isSecure(): bool

Return Value:

bool - Return true if the connection is secure false otherwise.


isAJAX

Check if request is ajax request, see if a request contains the HTTP_X_REQUESTED_WITH header.

public isAJAX(): bool

Return Value:

bool - Return true if request is ajax request, false otherwise


isApi

Check if the request URL indicates an API request endpoint.This method checks if the URL path prefix matched any of /api or public/api or your custom defined API URL prefix.

public isApi(): bool

Return Value:

bool - Returns true if the URL indicates an API endpoint, false otherwise.


getQuery

Get the request URL query string.

public getQuery(): string

Return Value:

string - Return the request URL query parameters as string.


getQueries

Get current URL query parameters as an associative array using the parameter name as key.

public getQueries(): array<string,mixed>

Return Value:

array<string,mixed> - Return the request URL query parameters as an array.


getUri

Get current request URL including the scheme, host and query parameters.

public getUri(): string

Return Value:

string - Return the request full URL.


getPaths

Get current request URL path information.

public getPaths(): string

Return Value:

string - Return the request URL paths.


getRequestUri

Returns un-decoded request URI, path and query string.

public getRequestUri(): string

Return Value:

string - Return the raw request URI (i.e. URI not decoded).


getHost

Get current request hostname without port, if allowed host is set it will check if host is in allowed list or patterns.

public getHost(bool $extension = false): string

Parameters:

ParameterTypeDescription
$extensionboolWeather to throw an exception if invalid host or not allowed host (default: false).

Return Value:

string - Throw if host is invalid or not allowed.

Throws:


getHostname

Get current request hostname with port if port is available.If allowed host is set it will check if host is in allowed list or patterns.

public getHostname(bool $extension = false, bool $port = true): string

Parameters:

ParameterTypeDescription
$extensionboolWeather to throw an exception if invalid host or not allowed host (default: false).
$portboolWeather to return hostname with port (default: true).

Return Value:

string - Return request hostname and port.

Throws:


getOrigin

Get the request origin domain, if the list of trusted origin domains are specified, it will check if the origin is a trusted origin domain.

public getOrigin(): ?string

Return Value:

string|null - Return the request origin domain if found and trusted, otherwise null.


getPort

Get the request origin port from X_FORWARDED_PORT or SERVER_PORT if available.

public getPort(): int|string|null

Return Value:

int|string|null - Return either a string if fetched from the server available, or integer, otherwise null.

Check if X-Forwarded-Port header exists and use if available.If not available check for server-port header if also not available return NULL as default.


getScheme

Gets the request scheme name.

public getScheme(): string

Return Value:

string - Return request scheme, if secured return https otherwise http.


getProtocol

Gets the request server protocol name and version (e.g: HTTP/1.1).

public getProtocol(string $default = 'HTTP/1.1'): string

Parameters:

ParameterTypeDescription
$defaultstringThe default server protocol to return if no available (default: HTTP/1.1).

Return Value:

string - Return Request protocol name and version, if available, otherwise default is return HTTP/1.1.


getBrowser

Get the request browser name and platform from user-agent information.

public getBrowser(): string

Return Value:

string - Return browser name and platform.


getUserAgent

Get request browser user-agent information.

public getUserAgent(?string $useragent = null): UserAgent

Parameters:

ParameterTypeDescription
$useragentstring|nullThe User Agent string, if not provided, it defaults to (HTTP_USER_AGENT).

Return Value:

UserAgent - Return instance user-agent class containing browser information.


isSameOrigin

Check if the request origin matches the current application host.

public isSameOrigin(bool $subdomains = false): bool

Parameters:

ParameterTypeDescription
$subdomainsboolWhether to consider sub-domains or not (default: false).

Return Value:

bool - Returns true if the request origin matches the current host, false otherwise.


isTrusted

Validates if the given (hostname, origin, proxy ip or subnet) matches any of the trusted patterns.

public static isTrusted(string $input, string $context = 'hostname'): bool

Parameters:

ParameterTypeDescription
$inputstringThe domain, origin or IP address to check.
$contextstringThe context to check input for (e.g, hostname).

Return Value:

bool - Return true if the input is trusted, false otherwise.

Throws:

Supported Context:

  • hostname - Validates a host name.
  • origin - Validates an origin hostname.
  • proxy Validates an IP address or proxy.

Note: This will consider the defined configuration in App\Config\Security during validation.


isTrustedProxy

Check whether this request origin IP address is from a trusted proxy.

public isTrustedProxy(): bool

Return Value:

bool - Return true if the request origin IP address is trusted false otherwise.


isTrustedOrigin

Check whether this request origin is from a trusted origins.

public isTrustedOrigin(): bool

Return Value:

bool - Return true if the request origin is trusted false otherwise.