Laravel IP Info

Laravel package for IP detection, normalization, request IP resolution, geo lookup, caching, and infrastructure-aware IP intelligence.

Author: Bohdan Suprun

Quick Start

composer require suprun-bohdan/laravel-ip-info
php artisan ip-info:install

use SuprunBohdan\IpInfo\Laravel\Facades\IpInfo;

$country = IpInfo::for('8.8.8.8')->countryCode(); // "US"
$client = IpInfo::forRequest(request())->countryCode();

Testing:

use SuprunBohdan\IpInfo\Laravel\Facades\IpInfo;
use SuprunBohdan\IpInfo\Testing\InteractsWithIpInfo;

class ExampleTest extends TestCase
{
    use InteractsWithIpInfo;

    public function test_country(): void
    {
        $this->fakeIpInfo(['203.0.113.1' => 'UA']);

        $this->assertSame('UA', IpInfo::for('203.0.113.1')->countryCode());
    }
}

Middleware (Cloudflare preset):

php artisan vendor:publish --tag=ip-info-middleware
# Configure trusted proxy CIDRs, e.g. IP_INFO_TRUSTED_PROXY_CIDRS=173.245.48.0/20,...
# .env: IP_INFO_PRESET=cloudflare

Security model (client IP)

• Never trust X-Forwarded-For blindly. Headers are read only when the remote address matches trusted_proxies.proxy_cidrs, unless require_trusted_proxy_for_headers=false.
• Mirror Laravel TrustProxies when using respect_laravel=true (default). Set trusted_proxies.sync_with_laravel as a reminder to keep both in sync.
• Cloudflare presets require IP_INFO_TRUSTED_PROXY_CIDRS (Cloudflare egress ranges) or network-level restriction. Presets do not embed rotating Cloudflare CIDRs.
• HTTP providers use HTTPS by default. Insecure http:// URLs require IP_INFO_HTTP_ALLOW_INSECURE=true.

Testing / fake behavior

IpInfo::fake() and fakeSequence():

• Replace the provider chain for the current manager instance.
• Bypass positive and negative cache — tests stay deterministic even when cache is populated.
• Do not write lookup results to production cache while fake mode is active.

IpInfo::fake(['8.8.8.8' => 'UA']); // overrides cached US for 8.8.8.8
IpInfo::assertLookedUp('8.8.8.8');

Batch lookup

IpInfo::forMany() resolves cache hits first, then uses BatchIpProvider::lookupMany() on the chain when available (offline DB uses a single bounded SQL query). Remaining misses fall back to per-IP chain lookup.

Architecture

Privacy/logging policy lives in IpPrivacyPolicy — DTOs do not read Laravel config.

What this package does

• Normalizes and validates IPv4/IPv6 input.
• Classifies public, private, localhost, link-local, and reserved addresses.
• Resolves client IP from HTTP requests using Laravel trusted proxy behavior by default.
• Looks up country codes through a provider chain:
  • LocalProvider — private/local/reserved IPs (no external call)
  • DatabaseRangeProvider — optional offline IPv4 ranges
  • MaxMindProvider — optional offline GeoLite2 MMDB
  • HttpIpProvider — optional HTTP drivers (ip-api, ipinfo)
  • CleanTalkProvider — optional HTTP fallback
• Caches public IP lookups via Laravel cache stores (with negative cache).
• Optional HTTP endpoint, middleware, and Artisan commands.

Requirements

• PHP ^8.2
• Laravel ^10, ^11, or ^12
• Laravel cache (array, file, redis, etc.)
• Database optional (offline IPv4 lookup)
• maxmind-db/reader optional (MaxMind MMDB lookup)

Installation

composer require suprun-bohdan/laravel-ip-info
php artisan ip-info:install
php artisan ip-info:install --preset=cloudflare
php artisan ip-info:install --with-database

Publish configuration only:

php artisan vendor:publish --tag=ip-info-config

Optional offline database:

# .env: IP_INFO_DATABASE_ENABLED=true
php artisan ip-info:install-database

Optional MaxMind GeoLite2:

# .env: IP_INFO_MAXMIND_ENABLED=true, IP_INFO_MAXMIND_LICENSE_KEY=...
composer require maxmind-db/reader
php artisan ip-info:update-maxmind

Diagnostics:

php artisan ip-info:diagnose
php artisan ip-info:diagnose 8.8.8.8 --json

Application sync

Audit how the package is integrated into your Laravel app:

php artisan ip-info:sync
php artisan ip-info:sync --json
php artisan ip-info:sync --fix
php artisan ip-info:sync --publish-config --publish-middleware

--fix only performs safe actions: publish missing config/middleware stubs and run migrations. It does not edit bootstrap/app.php, Kernel.php, or .env. Preset recommendations are report-only.

When routes are enabled, configure protection:

IP_INFO_ROUTES_ENABLED=true
IP_INFO_ROUTE_MIDDLEWARE=throttle:60,1

Configuration

File: config/ip-info.php

See docs/migration-guide.md and docs/roadmap-v3.md.

Commands

Development

Local Docker sandbox (gitignored):

cd sandbox && make init && make test
make test-package   # PHPUnit + PHPStan in package root

License

MIT. See LICENSE.