interaction-design-foundation/laravel-geoip

GeoIP for Laravel

Determine the geographical location and currency of website visitors based on their IP addresses.

Actively maintained fork of torann/geoip with modern PHP/Laravel support, better types, and additional features. Migration guide.

Installation

composer require interaction-design-foundation/laravel-geoip

Upgrading from 4.x? See UPGRADING.md.

Publish the config file:

php artisan vendor:publish --provider="InteractionDesignFoundation\GeoIP\GeoIPServiceProvider" --tag=config

Set the GEOIP_SERVICE env variable to one of the supported services.

Quick Start

Use the geoip() helper or the GeoIP facade:

// Get location for an IP
$location = geoip('203.0.113.1');

// Get location for the current visitor
$location = geoip()->getLocation();

// Access location data
$location->city;       // "New Haven"
$location->country;    // "United States"
$location->iso_code;   // "US"
$location->timezone;   // "America/New_York"
$location->currency;   // "USD"

The Location object contains: ip, iso_code, country, city, state, state_name, postal_code, lat, lon, timezone, continent, currency, default, and cached.

It implements ArrayAccess, so both $location->city and $location['city'] work.

Services

Set the service via the GEOIP_SERVICE env variable or in config/geoip.php:

For detailed service configuration, see services documentation.

Configuration

Key options in config/geoip.php:

Caching

GeoIP caches lookups using Laravel's cache system to reduce API calls. Set the cache option to:

• all -- cache all lookups
• some -- cache only the current user's lookup
• none -- disable caching

You can also configure cache_tags, cache_expires (TTL in seconds), and cache_prefix.

Addresses the service reports as not found (MaxMind AddressNotFoundException) are cached too, as the default location with default and cached set to true, for cache_not_found_expires seconds (defaults to cache_expires). Other failures, such as timeouts, are never cached. Set cache to none to disable this.

Timeouts

HTTP-based services and the MaxMind Web API fail fast so a slow provider cannot hold up your request: connect_timeout (default 2 s) and timeout (default 5 s) in config/geoip.php. Either can be overridden per service. Responses larger than 1 MiB are rejected when the server announces their size. A non-2xx HTTP status makes the lookup fail (the default location is returned).

Currency Detection

When include_currency is enabled (default), the package resolves the visitor's currency from their country ISO code using the league/iso3166 package.

Default Location

Configure a fallback location returned when a lookup fails or the IP is local/non-global (private, loopback, reserved). An explicitly passed IP that is not a valid IP address throws InvalidArgumentException.

Artisan Commands

# Download/update the local GeoIP database (required for maxmind_database)
php artisan geoip:update

# Clear cached locations
php artisan geoip:clear

Changelog

See Releases for what has changed recently.

Contributing

See CONTRIBUTING for details.