PHP Luminova: Proxy and IP Address Management
Manage and retrieve the client’s IP address, detect proxies or Tor exit nodes, and fetch detailed info via IPHub or IPApi.
The IP address class is a utility for managing and validating IP addresses. It can retrieve a client's IP from server request data, even when the app is behind proxies or load balancers.
It also supports detailed IP lookups through third-party APIs (ipapi.co
or iphub.info
) and caches results locally to avoid unnecessary network calls and improve performance.
Usages
Get Client IP Address
Retrieve the client’s IP address using the static IP::get()
method:
echo IP::get();
Get Client IP Address Information
Fetch detailed information about a specific IP address (or the current client IP if none is given):
var_dump(IP::info('192.168.20.2', ['username' => 'peter']));
Using Global Helper Functions
Use the ip_address()
helper to quickly retrieve the client IP:
echo Luminova\Funcs\ip_address();
Get Client IP Address Information:
Pass true
as the first argument to fetch detailed IP information, optionally with extra metadata:
$info = Luminova\Funcs\ip_address(true, ['username' => 'peter']);
var_dump($info);
Get an IP Class Instance
Obtain an instance of the IP class using the global func()
helpers:
$instance = Luminova\Funcs\func('ip');
// Or:
$instance = Luminova\Funcs\func()->ip();
This instance provides access to all IP-related methods for advanced usage.
Class Definition
- Class namespace:
\Luminova\Functions\IP
Methods
get
Resolve the real client IP address.
This method checks common proxy and CDN headers (including Cloudflare) to determine the real client IP. It validates that the IP is public (not private or reserved) and returns the first valid match.
- Checks Cloudflare's header first, then other common proxy/CDN headers.
- Skips private and reserved IP ranges to ensure only public addresses are returned.
- Caches the result for subsequent calls during the same request.
- Defaults to
0.0.0.0
in production if no valid IP is found (or127.0.0.1
in development for easier debugging). - Returns
0.0.0.0
automatically for CLI environments, since there’s no client.
public static get(): string
Return Value:
string
- Return the detected client IP address, or a fallback if unavailable.
info
Retrieve detailed IP address information from a third-party API.
- Uses the current client IP if
$ip
is null. - Caches responses locally to avoid repeated lookups.
- Merges any additional
$metadata
into the stored result.
Fetches and stores information about client IP address using third-party APIs
, either ipapi or iphub, with an API key is required for both providers. To configured API provide and key see App\Config\IPConfig documentation.
public static info(?string $ip = null, array $metadata = []): ?object
Parameters:
Parameter | Type | Description |
---|---|---|
$ip | string|null | The IP address to query (default: detected client IP). |
$metadata | array | Optional metadata to associate with the lookup.. |
Return Value:
object|null
- Return the resolved IP information as an object on success, or null
on failure.
This method caches IP lookup results in the filesystem to reduce redundant network calls.Cache files are stored in
/writeable/caches/ip/
asip_info_<IP_ADDRESS>.json
and do not expire automatically.To refresh data, delete the cache files manually or clear the directory during deployment, cron jobs, or maintenance scripts.
equals
Compare two IP addresses to determine if they are equal.
This method checks the equality of two IP addresses (IPv4 or IPv6) by converting them to their numeric binary representations. If either IP address is invalid, the method returns false
. Otherwise, it compares the numeric forms to check for equality.
public static equals(string $ip1, ?string $ip2 = null): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$ip1 | string | The first IP address to compare. |
$ip2 | string|null | The second IP address to compare (default: null). |
Return Value:
bool
- Returns true
if both IP addresses are valid and equal; false
otherwise.
Note:If the second IP address (
$ip2
) is not provided, it defaults to the current client IP obtained via theIP::get()
method.
isValid
Validate an IP address.
This method validates an IP address for a specific IP version (e.g., 4
, 6
, or 0
for any). If $ip
is null
, the current client IP (via IP::get()
) is used.
public static isValid(?string $ip = null, int $version = 0): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$ip | string|null | The IP address to validate (default: current client IP). |
$version | int | The IP version to check: 4 for IPv4, 6 for IPv6, or 0 for either (default: 0 ). |
Return Value:
bool
- Return true if the IP is valid for the specified version, false otherwise.
isTor
Check if an IP address is a Tor exit node. If $ip
is null
, it uses the current IP address.
This method performs the following actions:
- Network Request: Retrieves the Tor bulk exit list from
https://check.torproject.org/torbulkexitlist
. - Check IP: Verifies if the given IP address is in the Tor exit list.
- Caching: Stores the bulk list for future use to avoid repeated network requests. The cached list expires after the specified period, the default is 30 days.
public static isTor(?string $ip = null, int $expiration = 2592000): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$ip | string|null | The IP address to check. |
$expiration | int | The expiration time to request for new exit nodes from tor api (default: 2592000 ). |
Return Value:
bool
- Return true if the IP address is a Tor exit node, otherwise false.
Throws:
- Luminova\Exceptions\FileException - Throws if error occurs or unable to read or write to directory.
Note:You can also use the global helper function
is_tor
to check if an IP address is a Tor exit node.
isTrustedProxy
Check if the request origin IP is a trusted proxy IP or subnet.This method used the configuration in app/Config/IPConfig.php
variable trustedProxies
to determine if the ip can be trusted or not. If no proxies are set for trustedProxies
, this will always return false
public static isTrustedProxy(?string $ip = null): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$ip | string|null | The IP address to check. If null defaults to the current IP address. |
Return Value:
bool
- Return true if the request origin IP matches the trusted proxy IPs
, false otherwise.
getLocalAddress
Get the local IP address of the machine.
This method first attempts to retrieve the machine's IP address via its hostname.If that fails or returns an invalid IP address, it falls back to using platform-specific shell commands (ipconfig
on Windows or ifconfig
on Linux/macOS) to retrieve the IP.
public static getLocalAddress(): string|false
Return Value:
string|false
- Returns the local IP address as a string, or false if unable to retrieve it.
getLocalNetworkAddress
Get the local network IP address (not the loopback address).
This method attempts to retrieve the machine's IP address on the network, avoiding the loopback IP (127.0.0.1). It first checks platform-specific network interfaces using shell commands (ipconfig
on Windows, ifconfig
on Linux/macOS).
public static getLocalNetworkAddress(): string|false
Return Value:
string|false
- Returns the local network IP address as a string, or false if unable to retrieve it.
toNumeric
Convert an IP address to its numeric long integer representation (IPv4
or IPv6
).
public static toNumeric(?string $ip = null): string|false
Parameters:
Parameter | Type | Description |
---|---|---|
$ip | string|null | The IP address to convert (default: null). If null use the current client Ip. |
Return Value:
string|false
- Return long integer representation of the IP address, otherwise false.
toAddress
Convert a numeric or hexadecimal IP address representation to its original (IPv4
or IPv6
).
public static toAddress(string|int|null $numeric = null): string|false
Parameters:
Parameter | Type | Description |
---|---|---|
$numeric | string|int|null | The ipv4 numeric or ipv6 hexadecimal representation to convert. |
Return Value:
string|false
- Return original IP address from numeric representation, otherwise false on error.
toBinary
Convert IP address to binary representation (IPv4
or IPv6
).
public static toBinary(?string $ip = null): string|false
Parameters:
Parameter | Type | Description |
---|---|---|
$ip | string|null | The IP address to convert. |
Return Value:
string|false
- Return binary representation of an IP address, otherwise false on error.
toIpv4
Convert an IPv6
address to its IPv4-mapped representation.
public static toIpv4(?string $ipv6 = null): string|false
Parameters:
Parameter | Type | Description |
---|---|---|
$ipv6 | string | The IPv6 address to convert (e.g, ::ffff:192.16.0.1 ). |
Return Value:
string|false
- Return the IPv4-mapped address, or false if the input is not a valid IPv6 address.
toIpv6
Convert an IPv4
address to its IPv6-mapped representation.
public static toIpv6(?string $ipv4 = null, bool $binary = false): string|false
Parameters:
Parameter | Type | Description |
---|---|---|
$ipv4 | string | The IPv4 address to convert. |
$binary | bool | Whether to return the binary representation (default: false). |
Return Value:
string|false
- Return the IPv6-mapped address, or false if the input is not a valid IPv4 address.
fromBinary
Convert a binary representation of an IP address to its original IP address.
public static fromBinary(string $binary, bool $ipv6 = false): string|false
Parameters:
Parameter | Type | Description |
---|---|---|
$binary | string | The binary representation of the IP address. |
$ipv6 | bool | Optional flag to specify if the IP address is IPv6 (default: false). If true, assumes the address is IPv6. |
Return Value:
string|false
- Returns the original IP address as a string, or false if the conversion fails.
NoteIf the binary is a representation of an IPV6, it will return the
IPV4
representation of the binary if you didn't specify true in the second parameter indicating it's an IPV6.