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 & Helpers](/categories/utility) 4. / 5. alfonsobries/laravel-geo ActiveLibrary[Utility & Helpers](/categories/utility) alfonsobries/laravel-geo ======================== Geo-location data sync package for Laravel v0.3.2(1mo ago)08MITPHPPHP ^8.4CI passing Since Mar 16Pushed 1mo 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 1mo ago 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 -> countries -> divisions -> 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 & 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 39 — LowBetter than 86% of packages Maintenance89 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 57d 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 [yajra/laravel-datatables-oracle jQuery DataTables API for Laravel 4.9k33.8M339](/packages/yajra-laravel-datatables-oracle)[spatie/laravel-enum Laravel Enum support 3655.4M31](/packages/spatie-laravel-enum)[psalm/plugin-laravel Psalm plugin for Laravel 3274.9M308](/packages/psalm-plugin-laravel)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 255.2k](/packages/aedart-athenaeum)[datomatic/nova-enum-field A Laravel Nova PHP 8.1 enum field with filters 20134.2k](/packages/datomatic-nova-enum-field)[bjuppa/laravel-blog Add blog functionality to your Laravel project 483.3k2](/packages/bjuppa-laravel-blog) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)