arraypress / wp-ip-utils
A lean WordPress utility for IP address validation, CIDR operations, and GDPR-compliant anonymization
Requires
- php: >=8.3
Requires (Dev)
- phpcompatibility/phpcompatibility-wp: ^2.1
- phpunit/phpunit: ^12.0
- squizlabs/php_codesniffer: ^3.13.5
- wp-coding-standards/wpcs: ^3.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
This library has moved. It is now part of
sugarcommerce/network(namespaceSugarCommerce\Network, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.
WordPress IP Utilities
Get the visitor's real IP, and check it against the rules you care about.
What it does
$_SERVER['REMOTE_ADDR'] is the proxy's address when there is a proxy, and
HTTP_X_FORWARDED_FOR is attacker-controlled unless you know which proxy you
trust. Getting this wrong means either everyone shares one IP, or anyone can
claim any IP they like.
You say what the site is behind -- nothing, Cloudflare, a proxy of your own -- and a forwarding header is read only when the connection came from that, from the right-hand end, stepping over your own proxies. Then it answers the follow-ups: what is this address in its one standard spelling, is it in that range however the range was written, and what does it look like with the last octet dropped for GDPR.
Features
- Read the visitor's IP, believing a forwarding header only from a proxy you named
- Say what you are behind in one line: nothing, Cloudflare, a local proxy, or your own list
- Give an address one spelling, so the same IPv6 address typed two ways is one rule
- Read a range written as
203.0.113.0/24,203.0.113.*or203.0.113.1-203.0.113.50, and store it one way - Test whether a range, or any of a list, holds an address, in IPv4 and IPv6
- Tell how wide a range is before you let somebody save it
- Anonymise for GDPR by masking the last octet, or the last group of IPv6
- Validate and clean a user-entered list of IPs and patterns
Installation
composer require arraypress/wp-ip-utils
Quick start
use ArrayPress\IPUtils\ClientIp; use ArrayPress\IPUtils\IP; use ArrayPress\IPUtils\Range; use ArrayPress\IPUtils\TrustedProxies; // Behind Cloudflare. Its header is believed only from its own addresses. $ip = ClientIp::resolve( null, TrustedProxies::cloudflare() ); // One spelling to store and compare: "2001:db8::1", "203.0.113.9". $ip = IP::canonical( (string) $ip ); // A block list, as somebody typed it: an address or a range per line. foreach ( $typed as $line ) { $rule = Range::normalize( $line ); // "203.0.113.77/24" -> "203.0.113.0/24" if ( null !== $rule && Range::prefix( $rule ) >= 8 ) { $rules[] = $rule; } } if ( null !== $ip && Range::contains_any( $rules, $ip ) ) { wp_die( 'Access denied' ); } // Store it without storing all of it. $for_logs = IP::anonymize( $ip ); // 203.0.113.0
With no second argument ClientIp::resolve() trusts nothing and returns the
connection's own address, which is right for a site reached directly.
TrustedProxies::local() is nginx or Caddy on the same machine;
TrustedProxies::none()->and_also( [ '198.51.100.7' ] ) is a load balancer of
your own. IP::get() is the older call, kept as it was: it assumes Cloudflare
and a local proxy at once.
Requirements
- PHP 8.3 or later
- WordPress 7.1 or later
License
GPL-2.0-or-later