kuria / request-info
Get information about the current HTTP request
Requires
- php: >=7.1
- ext-filter: *
- kuria/url: ^5.0
Requires (Dev)
- kuria/dev-meta: ^0.6
- php-mock/php-mock-phpunit: ^2.1.1
This package is auto-updated.
Last update: 2024-10-07 13:00:23 UTC
README
Get information about the current HTTP request.
Contents
Features
- getting request information:
- headers
- HTTPS detection
- client IP address
- scheme
- method
- host
- port
- URL
- base directory
- base path
- path info
- script name
- trusted proxy header support (x-forwarded / forwarded)
- host validation (inc. defining specific trusted hosts or host patterns)
- optional HTTP method override support
Requirements
- PHP 7.1+
Usage
All configuration and value retrieval is done via the static Kuria\RequestInfo\RequestInfo
class.
Configuration
Trusted proxies
By default all proxy headers are ignored. To trust select proxy headers, call RequestInfo::setTrustedProxies()
with an appropriately configured TrustedProxies
instance.
<?php use Kuria\RequestInfo\RequestInfo; use Kuria\RequestInfo\TrustedProxies; $trustedProxies = new TrustedProxies( ['192.168.1.10', '192.168.1.20'], // one or more IP adresses or subnets in CIDR notation TrustedProxies::HEADER_FORWARDED // which headers to trust (bit mask) ); RequestInfo::setTrustedProxies($trustedProxies);
Choosing which headers to trust
Trusted headers are a bitmask of the following constants:
Note
Trusting both the Forwarded
and X-Forwarded-*
headers is supported,
but they must report the same values. Different values will cause
Kuria\RequestInfo\Exception\HeaderConflictException
.
Applications always behind a trusted proxy
If you are sure that an application will always be behind a trusted proxy, you can
use $_SERVER['REMOTE_ADDR']
in place of a hardcoded IP address:
<?php use Kuria\RequestInfo\RequestInfo; use Kuria\RequestInfo\Helper\Server; use Kuria\RequestInfo\TrustedProxies; $trustedProxies = new TrustedProxies( [Server::require('REMOTE_ADDR')], TrustedProxies::HEADER_FORWARDED ); RequestInfo::setTrustedProxies($trustedProxies);
Trusted hosts
The request host is always validated according to the standards.
To restrict accepted hosts further, use the following methods:
<?php use Kuria\RequestInfo\RequestInfo; // specific hosts (exact match) RequestInfo::setTrustedHosts([ 'www.example.com', 'cdn.example.com', ]); // host patterns RequestInfo::setTrustedHostPatterns([ '{\w+\.example\.com$}AD', '{example-node-\d+$}AD', ]);
HTTP method override
By default, the X-HTTP-Method-Override
header is ignored.
If you need to override the HTTP method via this header (e.g. because of restrictive firewall rules), you can enable its support:
<?php use Kuria\RequestInfo\RequestInfo; RequestInfo::setAllowHttpMethodOverride(true);
Resetting configuration
To restore default RequestInfo
configuration:
<?php use Kuria\RequestInfo\RequestInfo; RequestInfo::reset();
Getting request information
Headers
Get all request headers as an array. Header names are lowercased and used as keys.
<?php print_r(RequestInfo::getHeaders());
Example output:
Array ( [host] => localhost:8080 [connection] => keep-alive [cache-control] => max-age=0 [upgrade-insecure-requests] => 1 [user-agent] => Mozilla/5.0 (Example) [accept] => text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8 [accept-encoding] => gzip, deflate, br [accept-language] => en-US,en;q=0.9,cs;q=0.8 )
Trusted proxy detection
Check whether the request originated from a trusted proxy.
<?php use Kuria\RequestInfo\RequestInfo; if (RequestInfo::isFromTrustedProxy()) { // request is from a trusted proxy }
HTTPS detection
See whether the request uses HTTPS.
<?php use Kuria\RequestInfo\RequestInfo; if (RequestInfo::isSecure()) { // request uses HTTPS }
Client IP address
Get the client IP address.
<?php use Kuria\RequestInfo\RequestInfo; var_dump(RequestInfo::getClientIp());
Example output:
string(9) "127.0.0.1"
Note
RequestInfo::getClientIp()
will return NULL
if the client IP address is not known (e.g. in CLI).
To get all known client IP addresses (ordered from most trusted to least trusted), use getClientIps()
:
<?php use Kuria\RequestInfo\RequestInfo; print_r(RequestInfo::getClientIps());
Example output:
Array ( [0] => 20.30.40.50 [1] => 10.20.30.40 )
Note
RequestInfo::getClientIps()
will return an empty array if the client IP addresses are not known (e.g. in CLI).
Method
Get the request method. The method name will always be in uppercase.
Also see HTTP method override.
<?php use Kuria\RequestInfo\RequestInfo; var_dump(RequestInfo::getMethod());
Example output:
string(3) "GET"
Scheme
Get the request scheme.
<?php use Kuria\RequestInfo\RequestInfo; var_dump(RequestInfo::getScheme());
Example output:
string(4) "https"
Host
Get the host name.
Also see Trusted hosts.
<?php use Kuria\RequestInfo\RequestInfo; var_dump(RequestInfo::getHost());
Example output:
string(9) "localhost"
Note
The returned host name does not include the port number. Use RequestInfo::getPort()
to get
the port number or RequestInfo::getUrl()->getFullHost()
to get the host name with the port
number (if it is non-standard).
Port
Get the port number.
<?php use Kuria\RequestInfo\RequestInfo; var_dump(RequestInfo::getPort());
Example output:
int(80)
URL
Get the request URL. Returns an unique instance of Kuria\Url\Url
.
See the kuria/url component for more information.
<?php use Kuria\RequestInfo\RequestInfo; $url = RequestInfo::getUrl(); echo "URL:\t", $url->build(), PHP_EOL, "Scheme:\t", $url->getScheme(), PHP_EOL, "Host:\t", $url->getHost(), PHP_EOL, "Port:\t", $url->getPort(), PHP_EOL, "Path:\t", $url->getPath(), PHP_EOL, "Query:\t", json_encode($url->getQuery()), PHP_EOL;
Example output:
URL: http://localhost:8080/test/index.php/foo?bar=baz Scheme: http Host: localhost Port: 8080 Path: /test/index.php/foo Query: {"bar":"baz"}
Base directory
Get base directory (without script name, if any). The returned path never ends with a "/".
<?php use Kuria\RequestInfo\RequestInfo; var_dump(RequestInfo::getBaseDir());
Examples:
Base path
Get base path (including the script name, if any). The returned path never ends with a "/".
<?php use Kuria\RequestInfo\RequestInfo; var_dump(RequestInfo::getBasePath());
Examples:
Path info
Get path info.
<?php use Kuria\RequestInfo\RequestInfo; var_dump(RequestInfo::getPathInfo());
Examples:
Script name
Get the current script name.
<?php use Kuria\RequestInfo\RequestInfo; var_dump(RequestInfo::getScriptName());
Example output:
string(18) "./public/index.php"
Internal cache
Most methods of the RequestInfo
class cache their results internally. If you manipulate $_SERVER
after already reading some request information, you will need to call RequestInfo::clearCache()
to clear the cache.