PHP Luminova: Proxy and IP Address Management

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 (or 127.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:

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/ as ip_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:

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 the IP::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:

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:

1. Network Request: Retrieves the Tor bulk exit list from https://check.torproject.org/torbulkexitlist.
2. Check IP: Verifies if the given IP address is in the Tor exit list.
3. 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:

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:

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:

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:

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:

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:

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:

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:

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.