Weave Code
Geoip2 Laravel Package
gpslab/geoip2
Laravel wrapper for MaxMind's GeoIP2 databases. Look up a visitor's country, city, coordinates, and timezone from their IP address, with a service provider, facade, and config included. Works with MaxMind's downloadable database files and the web service API.
gpslab/geoip2 is a PHP library that wraps MaxMind's GeoIP2 PHP API, adding container-friendly service resolution so you can inject the reader instead of constructing it yourself. It fits Symfony and other PSR-11 containers, letting you define the database path or web-service credentials once in configuration and have a lazily initialized reader anywhere in your application.
- Lazy initialization — the GeoIP2 reader is created only when first used, keeping requests cheap.
- PSR-11 & Symfony integration — resolve readers from a container instead of hard-coding dependencies.
- Configurable backends — point it at a local
.mmdbdatabase or MaxMind's web services. - Thin wrapper — keeps MaxMind's familiar
City,Country, andASNAPIs intact.
Frequently asked questions about Geoip2
- Does gpslab/geoip2 work with Laravel?
- Not as a drop-in package. gpslab/geoip2 is a Symfony bundle built around a Bundle subclass and a DependencyInjection extension, and Laravel has no bundle loader or DI extension mechanism, so that wiring never runs. The only genuinely reusable piece is a configured GeoIp2 Database Reader, which is framework-agnostic and works fine in Laravel once you bind it yourself in a service provider. Most teams get further by requiring geoip2/geoip2 directly and adding roughly 80 lines of Laravel glue.
- How do I install MaxMind GeoIP2 in a Laravel application?
- Install the framework-agnostic library with composer require geoip2/geoip2 rather than the Symfony bundle. Add a config/geoip.php file holding your MMDB paths and feature flags, define a GeoLocator interface plus a MaxMindGeoLocator implementation, and bind it as a singleton in a service provider. Keep the bundle out of composer.json unless you are migrating an existing Symfony service that already depends on it.
- Which Laravel and PHP versions support GeoIP2 lookups?
- The underlying geoip2/geoip2 and maxmind-db/reader packages are MaxMind-maintained, framework-agnostic, and install cleanly on Laravel 10, 11, and 12 applications running PHP 8.x. The constraint to watch with gpslab/geoip2 is its symfony/* version ranges, which can veto a future Laravel or PHP upgrade. Pin geoip2/geoip2 and maxmind-db/reader explicitly in composer.json instead of letting a wrapper's ranges decide for you.
- How do I configure the MaxMind GeoLite2 or GeoIP2 database path in Laravel?
- Create config/geoip.php with environment-driven keys for the city, country, and ASN MMDB file paths, plus a flag for whether lookups are enabled. Resolve those paths into the Reader constructor inside a service provider so configuration stays in the Laravel config repository. If you are migrating from the Symfony bundle, copy its config keys over verbatim and drop the gpslab_geoip service references once call sites use your new interface.
- Do I need a MaxMind account, license key, or paid subscription?
- Yes for the data, regardless of which wrapper you use. GeoLite2 databases are free but require a MaxMind account and license key, are licensed CC BY-SA 4.0, and need that key to stay refreshed. GeoIP2 commercial databases require a paid subscription. The MIT license on any wrapper covers the code only, so confirm who owns the key and how often databases are refreshed.
- Is IP geolocation personal data under GDPR or CCPA?
- IP-to-location is generally treated as personal data, so treat the lookup as a processing activity and cover it in your DPIA and privacy notice. Define a retention policy for derived location data rather than storing it indefinitely alongside logs. Be careful about accuracy claims too: city-level results are frequently overstated, and surfacing them to users can create both compliance and product-quality problems.
- How do I test GeoIP2 lookups in Laravel without real location data?
- Depend on your own GeoLocator interface rather than on the Reader class, then bind a fake implementation in tests that returns fixed location objects. For integration coverage, point the Reader at a small test MMDB fixture from MaxMind instead of mocking the underlying library. This keeps unit tests fast and avoids asserting against data that changes with every database refresh.
- Is gpslab/geoip2 maintained, and what are the alternatives?
- The wrapper is small and MIT-licensed but has roughly 53 GitHub stars and no dependents, so there is little downstream production signal and you would effectively be its QA. Alternatives are geoip2/geoip2 wired up yourself, or community packages such as torann/geoip and stevebauman/location that already ship Laravel service providers and facades. If you need country plus ASN for fraud or anonymity signals, the official library with a thin binding is usually the safest choice.
- Should IP geolocation run on the request path or in a queue?
- Prefer async where the product allows it. A memory-mapped MMDB lookup is fast, but resolving on every request adds file handle and CPU overhead and couples request latency to data availability. Sending lookups to a queue or an analytics ETL step also makes it easier to add a fallback provider when MaxMind data is missing or degraded.
- Do I need city-level data, or is country plus ASN enough?
- Country-only databases are an order of magnitude smaller and materially cheaper to operate, and for many use cases such as regional defaults, tax or content rules, and coarse analytics they are sufficient. Add ASN when you need hosting-provider or anonymity signals for fraud checks. Only pay for city and coordinate data when a product feature genuinely depends on that precision.
Weaver
How can I help you explore Laravel packages today?