GeoIP2 PHP

GeoIP2 PHP is MaxMind’s official client library for looking up IP address intelligence — city, country, ISP, connection type, anonymizer status, and enterprise-grade confidence scores — through either a local .mmdb database file or MaxMind’s hosted GeoIP2 web service. It provides two parallel APIs sharing the same model classes: a Database\Reader for offline lookups against downloaded GeoIP2/GeoLite database files, and a WebService\Client for querying MaxMind’s REST API directly with an account ID and license key.

Each lookup returns typed model and record objects (Country, City, Subdivision, Location, Traits, etc.) rather than raw arrays, giving PHP applications structured access to geolocation data with IDE autocompletion and static-analysis support. The library covers MaxMind’s full database lineup — City, Country, Anonymous IP, Anonymous Plus, Connection Type, Domain, Enterprise, and ISP — and is built on top of MaxMind’s shared maxmind-db/reader and maxmind/web-service-common packages.

What You Get

• A Database\Reader class for fast, offline lookups against local .mmdb files (City, Country, ISP, Anonymous IP, Connection Type, Domain, Enterprise databases)
• A WebService\Client class for querying MaxMind’s hosted GeoIP2/GeoLite REST API with account ID and license key authentication
• Typed model and record classes (Country, City, Subdivision, Location, Postal, Traits) instead of raw associative arrays
• Structured exceptions (AddressNotFoundException, InvalidDatabaseException) for distinguishing lookup misses from data-integrity errors
• An optional C extension integration path (via maxmind-db/reader) for dramatically faster local database lookups

Common Use Cases

• Resolving a visitor’s country or city from their IP address for content localization or analytics
• Blocking or challenging traffic from anonymizer/VPN/proxy networks using the Anonymous IP or Anonymous Plus databases
• Enriching fraud-detection pipelines with ISP, connection-type, and confidence-scored location data from the Enterprise database
• Building offline-first geolocation lookups in latency-sensitive services using local .mmdb files instead of a network call per request

Under The Hood

Architecture: The library is cleanly split by concern under src/: Database/ wraps the maxmind-db/reader package for local .mmdb file lookups, WebService/ implements the HTTP client for MaxMind’s hosted API (built on the shared maxmind/web-service-common package), Model/ defines per-endpoint response wrappers (City, Country, Insights, Enterprise, etc.), and Record/ defines the smaller typed value objects (Continent, Subdivision, Location, Traits) that models are composed from. Both the database and web-service paths return the same model/record class hierarchy, so application code written against one can largely switch to the other with minimal changes.

Tech Stack: Requires PHP >= 8.1 and the ext-json extension, with maxmind-db/reader (^1.13.0) and maxmind/web-service-common (~0.11) as first-party MaxMind dependencies rather than generic HTTP libraries. Development tooling includes PHPStan for static analysis, PHP-CS-Fixer and PHP_CodeSniffer for style enforcement, and PHPUnit ^10.0 for testing; the project also ships a .phar archive build (box.json) as an alternative to Composer installation.

Code Quality: MaxMind maintains strict static-analysis gating (phpstan.neon) and dual linting (cs-fixer + codesniffer) for a library that many downstream security and fraud-detection systems depend on for correctness. Test coverage is comparatively lean (6 test files) relative to the model/record class count, but the surface area is largely data-mapping code generated consistently across database types, reducing the risk profile of undertested branches.

API Design: The consistent split between Model (top-level lookup result) and Record (nested value objects like $record->country->isoCode) gives a predictable, IDE-friendly navigation pattern across all eight supported database/service types. The README explicitly warns against using names properties (localized display names) as array or database keys since they can change between releases, steering developers toward stable identifiers (geonameId, isoCode) instead — a small but meaningful API-safety guardrail baked into the documentation.