sameoldnick / laravel-geolocator

v2.0.0 2026-09-29 05:12 UTC

Requires

• php: ^8.4
• illuminate/contracts: ^11.0||^12.0||^13.0
• maxmind-db/reader: ^1.14.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.30
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^11.0.0||^10.0.0||^9.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0

MIT

• Nick Hamnett

• geolocation
• laravel
• location
• geolocator
• SameOldNick
• laravel-geolocator

Published on Packagist.org on 2026-09-29 05:12 UTC

README

An offline IP geolocation package for Laravel, backed by MaxMind databases. Look up the country, city and ASN behind an IP address, resolve the location of the current request, and keep the databases up to date with a scheduled Artisan command.

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. ext-bcmath or ext-gmp (for the pure PHP decoder) and ext-maxminddb (a faster C decoder) are recommended but optional. See Installation for the full setup, including deployment notes.

Installation

composer require sameoldnick/laravel-geolocator
php artisan vendor:publish --tag=geolocator-config
php artisan geolocator:update-iplocationdb

The service provider is auto-discovered. The package does not ship the databases, so run the update command once per environment; lookups throw an InvalidArgumentException when a configured database file is missing. Every path and environment variable is in Configuration.

Quick start

Once the databases are in place, the shortest working path is a route that resolves the caller:

use Illuminate\Http\Request;

Route::get('/where-am-i', function (Request $request) {
    $location = $request->geolocate();

    return [
        'ip' => $location->ipAddress,
        'country' => $location->country?->countryCode,
        'city' => $location->city?->city,
        'asn' => $location->asn?->organization,
    ];
});

That is the whole integration. The service provider, the geolocate macro and the Geolocator facade alias are registered for you, there is no API key to configure, and a lookup is a file read rather than an HTTP call.

To look up an address other than the caller's, call the facade directly:

use SameOldNick\Geolocator\Facades\Geolocator;

$location = Geolocator::lookup('8.8.8.8');

Both return the same LocationResult — see Usage for what you can read from it.

Documentation

This file is the entry point; the wiki holds the detail.

Changelog

See CHANGELOG.md for what has changed recently, and UPGRADING.md for the steps each major version needs. This project follows Semantic Versioning.

Contributing

Pull requests are welcome. Please keep the suite green and the code style applied before opening one:

composer test      # the test suite
composer format    # the code style

See CONTRIBUTING.md for the development environment, the full set of checks, the test layout and the documentation rules.

Security

Please review the security policy before reporting a vulnerability, and do not open a public issue for security problems.

License

This package is open-sourced software licensed under the MIT license.