PHPackages                             alfonsobries/laravel-geo - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility &amp; Helpers](/categories/utility)
4. /
5. alfonsobries/laravel-geo

ActiveLibrary[Utility &amp; Helpers](/categories/utility)

alfonsobries/laravel-geo
========================

Geo-location data sync package for Laravel

v0.3.2(5d ago)08MITPHPPHP ^8.4CI passing

Since Mar 16Pushed 5d agoCompare

[ Source](https://github.com/alfonsobries/laravel-geo)[ Packagist](https://packagist.org/packages/alfonsobries/laravel-geo)[ RSS](/packages/alfonsobries-laravel-geo/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (6)Versions (9)Used By (0)

Laravel Geo
===========

[](#laravel-geo)

[![Tests](https://github.com/alfonsobries/laravel-geo/actions/workflows/tests.yml/badge.svg)](https://github.com/alfonsobries/laravel-geo/actions/workflows/tests.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/2a635f38413dce88ed63a807546d7d293e7036cf30d14f9fceeca35597f90e34/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616c666f6e736f62726965732f6c61726176656c2d67656f2e737667)](https://packagist.org/packages/alfonsobries/laravel-geo)[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE)

Geo-location data package for Laravel. Syncs continents, countries, divisions, cities (with translations), and a MaxMind IP geolocation database from [geo.vexilo.com](https://geo.vexilo.com). Everything runs locally after sync.

Installation
------------

[](#installation)

```
composer require alfonsobries/laravel-geo
php artisan vendor:publish --tag=geo-config
php artisan vendor:publish --tag=geo-migrations
php artisan migrate
```

Configuration
-------------

[](#configuration)

Add to your `.env`:

```
GEO_API_URL=https://geo.vexilo.com
GEO_API_KEY=your-secret-key-here

```

Full config at `config/geo.php`:

```
return [
    'api_url' => env('GEO_API_URL', 'https://geo.vexilo.com'),
    'api_key' => env('GEO_API_KEY'),

    'sync' => [
        'continents' => true,
        'countries' => true,
        'divisions' => true,
        'cities' => true,
    ],

    'locales' => null, // ['en', 'es'] or null for all
    'connection' => null, // database connection override

    'maxmind' => [
        'database_path' => storage_path('app/geoip/GeoLite2-City.mmdb'),
    ],

    'cache' => [
        'enabled' => true,
        'ttl' => 3600, // IP lookup cache in seconds
    ],
];
```

Syncing Data
------------

[](#syncing-data)

```
# Sync everything (geo tables + MaxMind database)
php artisan geo:sync

# Force full re-sync
php artisan geo:sync --force

# Use dump mode (fast initial sync via CSV files)
php artisan geo:sync --mode=dump

# Use incremental mode (daily updates via watermark)
php artisan geo:sync --mode=incremental

# Sync specific tables only
php artisan geo:sync --tables=countries,divisions

# Skip MaxMind database sync
php artisan geo:sync --no-maxmind

# Check sync status
php artisan geo:status
```

### Sync Modes

[](#sync-modes)

- **Auto** (default) — Detects the best mode. Uses dump for initial sync (no local data), incremental for daily updates.
- **Dump** — Downloads CSV dump files from the server. Fast bulk import with truncate + reimport. Best for initial setup or full re-sync.
- **Incremental** — Uses `updated_after` watermarks to only fetch changed records. Fetches deletions from the server. Best for daily scheduled updates.

The sync is:

- **Manifest-driven** — compares checksums, skips tables that haven't changed
- **Idempotent** — uses upserts keyed on `geoname_id` / `alternate_name_id`
- **Dependency-aware** — syncs in order: continents -&gt; countries -&gt; divisions -&gt; cities
- **Retry-capable** — HTTP requests retry 3x with backoff on failure

Add to your scheduler for automatic updates:

```
Schedule::command('geo:sync')->daily();
```

IP Geolocation
--------------

[](#ip-geolocation)

Resolve IP addresses to local geo models using the synced MaxMind database. Zero API calls at runtime.

```
use AlfonsoBries\Geo\Facades\Geo;

// From a specific IP
$location = Geo::locate('187.190.56.23');
$location->country();    // Country model
$location->division();   // Division model
$location->city();       // City model
$location->timezone;     // 'America/Mexico_City'
$location->latitude;     // 20.6597
$location->longitude;    // -103.3496

// From the current request
$country = Geo::country();
$code = Geo::countryCode(); // 'MX'
```

Results are cached by IP (configurable via `geo.cache.ttl`).

Models
------

[](#models)

```
use AlfonsoBries\Geo\Models\Continent;
use AlfonsoBries\Geo\Models\Country;
use AlfonsoBries\Geo\Models\Division;
use AlfonsoBries\Geo\Models\City;

// Finders
$mexico = Country::findByCode('MX');
$mexico = Country::findByIso('MEX');
$europe = Continent::findByCode('EU');
$jalisco = Division::findByName('Jalisco');
$gdl = City::findByName('Guadalajara');

// Relationships
$country->continent;       // Continent model
$country->divisions;       // Collection of Division
$country->cities;          // Collection of City
$country->translations;    // Collection of CountryTranslation
$country->getTranslation('es'); // "Mexico"
```

Traits &amp; Scopes
-------------------

[](#traits--scopes)

Add geo relationships and query scopes to your models:

```
use AlfonsoBries\Geo\Traits\BelongsToCountry;
use AlfonsoBries\Geo\Traits\BelongsToDivision;
use AlfonsoBries\Geo\Traits\BelongsToCity;
use AlfonsoBries\Geo\Traits\BelongsToContinent;

class User extends Model
{
    use BelongsToCountry, BelongsToDivision, BelongsToCity;
}
```

Each trait provides a relationship and query scopes:

```
// Relationships
$user->country;
$user->division;
$user->city;

// Scopes - by model
$mexico = Country::findByCode('MX');
User::whereCountry($mexico)->get();

// Scopes - by code/name (string)
User::whereCountry('MX')->get();
User::whereCountries(['MX', 'US', 'CA'])->get();
User::whereContinent('NA')->get();
User::whereDivision('Jalisco')->get();
User::whereCity('Guadalajara')->get();

// Combine scopes
User::whereCountry('MX')->whereDivision('Jalisco')->get();
```

Factories
---------

[](#factories)

Available for testing:

```
$continent = Continent::factory()->create();
$country = Country::factory()->create(['continent_id' => $continent->id]);
$division = Division::factory()->create(['country_id' => $country->id]);
$city = City::factory()->create([
    'country_id' => $country->id,
    'division_id' => $division->id,
]);
```

Testing
-------

[](#testing)

```
composer install
vendor/bin/pest
```

License
-------

[](#license)

MIT

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance99

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

8

Last Release

5d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d80f711672e38ea7fd45caefbc98afdf60e2986929be4c8023a1ad309f3bcbb5?d=identicon)[vexilo](/maintainers/vexilo)

---

Top Contributors

[![alfonsobries](https://avatars.githubusercontent.com/u/17262776?v=4)](https://github.com/alfonsobries "alfonsobries (8 commits)")

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/alfonsobries-laravel-geo/health.svg)

```
[![Health](https://phpackages.com/badges/alfonsobries-laravel-geo/health.svg)](https://phpackages.com/packages/alfonsobries-laravel-geo)
```

###  Alternatives

[tizis/lara-comments

Comments system for your Laravel application. Features: can be used to comment on any model, HTML filter customization (HTMLPurifier), API, comment rating, replies, events, auth rules ...

1204.7k](/packages/tizis-lara-comments)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
