laranail/ip-intel is not published to Packagist, so there is no registry-version badge to show: see Install.
IP intelligence for Laravel — country, ASN and threat signals behind one resolver chain that answers offline first, with an opt-in REST API.
Requires PHP ^8.4.1 || ^8.5 and Laravel ^13.0. Built on
laranail/atlas, which owns the
address parsing and the offline country table.
composer require laranail/ip-intelBehind Cloudflare, Vercel, Fastly or CloudFront, a country lookup makes no network call at all — the edge already worked it out and put it in a request header.
Nothing is required: the default chain is ['edge', 'local'], both free and keyless. To widen it:
-
Offline tier. Build
laranail/atlas' registry table, then turn its IP lookup on:php vendor/laranail/atlas/tools/build-ip-table.php
ATLAS_IP_LOOKUP=true
-
Metered tier (city, ASN, threats). Publish the config, add
'ipapi'tochain, and set the key:php artisan vendor:publish --tag="laranail::ip-intel-config"IP_INTEL_IPAPI_KEY=…
use Simtabi\Laranail\IpIntel\Facades\IpIntel;
IpIntel::forRequest(); // about the caller
IpIntel::country('8.8.8.8'); // country only — the cheap path
IpIntel::full('8.8.8.8'); // everything a configured source can supplyEvery call returns an IpIntelResult, never null:
$result = IpIntel::country('8.8.8.8');
$result->countryCode; // ?string
$result->madeNetworkCall; // false, when an edge header answerededge header → no lookup at all, free, already computed
local table → offline, registry data, country only
remote → metered, and the only source for city/ASN/threats
Sources are asked in order until the question is answered, and that order is the cost policy. A single configurable "driver" cannot express it, because the right source depends on the question: the header answers country and nothing else, so a chain that treated it as the driver would make ASN unavailable.
Capability is a type — the chain asks $driver instanceof ResolvesAsn, so a source that cannot
answer is skipped without being called. That is what makes this true rather than approximate:
IpIntel::country('8.8.8.8')->madeNetworkCall; // falseOutcome |
Means |
|---|---|
Found |
A source answered |
Reserved |
RFC 1918, loopback — normal in development |
NotFound |
A genuine registry gap |
Unavailable |
A source is broken — dead key, 5xx |
Disabled |
Switched off in config |
The implementation this replaces returned bare null for every one, so "we do not know where this
address is" and "the API key expired three weeks ago" were the same value — and the second never got
noticed. $result->needsAttention() separates them.
It also defaulted to the United States when a lookup failed, which is a confidently wrong answer on every request from localhost and surfaces as a tax rate rather than as an error.
Hosted at opensource.simtabi.com/documentation/laranail/ip-intel.
- Installation — the VCS closure, and the two tiers that need setting up
- Getting started — the chain, the five outcomes, reading a result
- Configuration — every key and its environment variable
- Architecture — why a chain, why capability is a type, where the key goes
- Release — cutting a version, and the path repository to remove first
- The resolver chain — how sources are chosen and skipped
- Outcomes — the five cases, and why a failure is never cached
- Drivers — what each source can and cannot answer
- The REST API — opt-in, read-only, two endpoints
Registry data gives country and the fact of an allocation. It does not give city, ISP name, or VPN/proxy status, and those cannot be derived from it — that is a property of the data, not a limitation here. Those need a commercial feed, so the package ships the seam for one rather than pretending the free tier covers it.
laranail/atlas— the country catalogue and the offline IP table this builds on
Issues and PRs are welcome — see CONTRIBUTING.md. Report vulnerabilities per SECURITY.md (opensource@simtabi.com); participation follows the Code of Conduct.
MIT © Simtabi LLC. See LICENSE.