Installation

Requirements

• PHP 8.4 or newer
• Laravel 11, 12 or 13 (illuminate/contracts ^11.0 || ^12.0 || ^13.0)
• Composer

The MaxMind database reader is pure PHP, but MaxMind recommends one of the following extensions:

• ext-bcmath or ext-gmp, required for decoding larger integers with the pure PHP decoder
• ext-maxminddb, a C-based decoder that provides significantly faster lookups

Install

composer require sameoldnick/laravel-geolocator

The service provider is auto-discovered. Publish the configuration file:

php artisan vendor:publish --tag=geolocator-config

Download the MaxMind databases:

php artisan geolocator:update-iplocationdb

The package does not ship the databases. The command downloads the country, city and ASN editions (both IPv4 and IPv6) into storage/app/geolocation. Lookups throw an InvalidArgumentException when the configured database file is missing, so run the command once after installing, or point the package at databases you already have.

See Configuration for every path and environment variable, and Database updates for what the command does on later runs.

Deployment notes

• Network: the update command downloads over HTTPS from a public CDN, so whatever machine runs it needs outbound access (or a proxy) at install and update time. Lookups themselves are offline.
• Filesystem: the databases are written to storage/app/geolocation, which needs to be writable and large enough for the editions you enable (the city edition is the largest). On a read-only or ephemeral filesystem, either bake the databases into your image or point the IPLOCATIONDB_*_PATH variables at a writable mount.
• Long-running workers: each edition's reader is cached by the scoped reader provider that built it, so queue:work discards it before every job and Octane discards it between requests — both read a replaced database without a restart. Only a process that keeps one open across an update (a long-running console command, or the job that is mid-flight) serves the old file until it finishes.