cslash/laravel-geoname

Generate location labels like FR-WEST from IP addresses in Laravel.

1.0.0 2026-03-27 12:41 UTC

Requires

• php: ^8.2
• illuminate/support: ^10.0|^11.0|^12.0
• stevebauman/location: ^7.0

Requires (Dev)

• orchestra/testbench: ^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

README

Laravel GeoName is a lightweight package that generates location labels (e.g., FR-WEST, US-CENTRAL) from IP addresses or geographic coordinates. It's built on top of stevebauman/location to provide regional resolution.

Requirements

• PHP 8.2 or higher
• Laravel 10.0 or higher

Installation

You can install the package via composer:

composer require cslash/laravel-geo-name

The package will automatically register its service provider and facade.

Optionally, you can publish the config file:

php artisan vendor:publish --tag="geoname-config"

Usage

Using the Facade

The GeoName facade provides a simple interface to resolve location labels.

From Current Request

Automatically detect the user's IP address from the current request:

use Cslash\GeoName\Facades\GeoName;

$label = GeoName::fromRequest(); 
// Returns something like "FR-NORTH" or "US-WEST"

From a Specific IP

use Cslash\GeoName\Facades\GeoName;

$label = GeoName::fromIp('8.8.8.8');

From GeoContext

If you already have coordinates or region data, you can use a GeoContext object:

use Cslash\GeoName\Data\GeoContext;
use Cslash\GeoName\Facades\GeoName;

$context = new GeoContext(
    countryCode: 'FR',
    regionName: 'Brittany',
    regionCode: 'BRE',
    latitude: 48.1173,
    longitude: -1.6778
);

$label = GeoName::fromContext($context); // "FR-WEST"

Configuration

The config/geoname.php file allows you to customize fallbacks and region mappings:

return [
    'fallback' => 'XX-UNKNOWN', // Returned when IP location cannot be determined
    'unknown_zone' => 'UNKNOWN', // Returned when coordinates are missing for generic resolution

    'countries' => [
        'FR' => [
            'thresholds' => [47.5, 44.5, -0.5, 4.5], // north, south, west, east
            'region_map' => [
                'BRE' => 'WEST',
                'NOR' => 'WEST',
                // ...
            ],
        ],
    ],
];

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.