README

Resolve a visitor's country (ISO-3166 alpha-2) from CDN and server-level request headers.

Zero dependencies, framework-agnostic, signature-gated to defeat trivial spoofing. Bundles sources for Cloudflare, AWS CloudFront, Fastly, BunnyCDN, server-level GeoIP modules (Apache mod_geoip / nginx GeoIP), and a generic X-Country-Code fallback. Register your own sources for custom GeoIP databases.

Why

Most fraud-detection / analytics / geo-routing code reaches for a paid IP-lookup API to answer "where is this visitor from?" — but if your site sits behind Cloudflare, CloudFront, Fastly, or any other major CDN, the answer's already in the request headers, for free. This library reads those headers in the right order with the right safety checks, and returns the country code.

Install

composer require arraypress/visitor-country

Usage

use ArrayPress\VisitorCountry\Country;

// Simple — returns "GB" or empty string on miss
$country = Country::resolve();

// With provenance — useful for logging / debugging
$result = Country::resolve_detailed();
$result->get_country();    // 'GB'
$result->get_source();     // 'cloudflare'
$result->get_confidence(); // 'high'
$result->has_country();    // true
$result->to_array();       // [ 'country' => 'GB', 'source' => 'cloudflare', 'confidence' => 'high' ]

// Pass a custom server array (testability)
Country::resolve( [ 'HTTP_CF_IPCOUNTRY' => 'GB', 'HTTP_CF_RAY' => 'abc' ] );

Sources

Tried in this order by default. First hit wins.

Source	Header	Confidence	Sig-gated?
Cloudflare	`HTTP_CF_IPCOUNTRY`	high	yes (`CF-Ray` / `CF-Visitor` / `CF-Connecting-IP`)
AWS CloudFront	`HTTP_CLOUDFRONT_VIEWER_COUNTRY`	high	no
Fastly	`HTTP_FASTLY_CLIENT_COUNTRY`	high	yes (`Fastly-FF` / `Fastly-Client-IP`)
BunnyCDN	`HTTP_CDN_LOOPCOUNTRY`	high	no
Server GeoIP	`GEOIP_COUNTRY_CODE` (Apache mod_geoip / nginx ngx_http_geoip_module)	medium	no
Generic	`HTTP_X_COUNTRY_CODE`	low	no

Signature gating — for headers that an attacker hitting the origin directly could trivially fake (Cloudflare, Fastly), the resolver verifies that a vendor-set companion header is also present before trusting the country. Country-spoofing alone is rarely a critical attack surface, but cheap to defend against.

Sentinel filtering — Cloudflare returns XX for unknown geo and T1 for Tor exits; both are filtered out so a downstream source can take over.

Shape validation — only ISO-3166 alpha-2 (2 letters, A-Z) values are returned.

Custom sources

Got a local MaxMind GeoLite2 database? Register a callback:

use ArrayPress\VisitorCountry\Country;
use ArrayPress\VisitorCountry\Sources\Callback;

Country::add_source(
    new Callback(
        fn( $server ) => MyGeoIP::lookup( $server['REMOTE_ADDR'] ?? '' ),
        'maxmind_local',
        'high'
    )
);

add_source() appends to the chain (lowest priority). Use prepend_source() to take precedence over the bundled CDN sources.

To replace the chain entirely:

Country::set_sources( [ new Cloudflare(), new MyCustomSource() ] );

To reset to the default chain (useful in tests):

Country::reset();

Implementing your own Source

use ArrayPress\VisitorCountry\Source;

class MyMaxMindSource implements Source {
    public function get_name(): string       { return 'maxmind'; }
    public function get_confidence(): string { return 'high'; }

    public function resolve( array $server ): ?string {
        $ip = $server['REMOTE_ADDR'] ?? '';
        if ( $ip === '' ) {
            return null;
        }

        // ... lookup logic ...
        return $country_code; // or null
    }
}

If your source reads from a single header with optional signature gating, extend Sources\HeaderSource and just declare the header name + signatures + sentinels.

Requirements

PHP 7.4+
No other dependencies

License

GPL-2.0-or-later.

arraypress / visitor-country

Maintainers

Package info

Statistics

Security