PHPackages raiolanetworks/atlas - 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. raiolanetworks/atlas ActiveLibrary[Utility & Helpers](/categories/utility) raiolanetworks/atlas ==================== Get the data from the most recondite place with 'Atlas' 3.0.2(1mo ago)3651↓66.3%MITPHPPHP ^8.3CI passing Since Mar 19Pushed 1mo ago2 watchersCompare [ Source](https://github.com/RaiolaNetworks/Atlas)[ Packagist](https://packagist.org/packages/raiolanetworks/atlas)[ Docs](https://github.com/RaiolaNetworks/Atlas)[ RSS](/packages/raiolanetworks-atlas/feed)WikiDiscussions main Synced 2w ago READMEChangelog (10)Dependencies (20)Versions (43)Used By (0) Get the data from the most recondite place with 'Atlas' ======================================================= [](#get-the-data-from-the-most-recondite-place-with-atlas) [![Latest Version on Packagist](https://camo.githubusercontent.com/a6c7771323a48ad678356399eccd623f6025ad4ff7c82b57aebb28133e566643/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7261696f6c616e6574776f726b732f61746c61732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/raiolanetworks/atlas)[![GitHub Tests Action Status](https://camo.githubusercontent.com/375271c8712f4aabc0f8352866ccf4fd0661b859f5f13eeef533d58af94f16f1/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7261696f6c616e6574776f726b732f61746c61732f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/raiolanetworks/atlas/actions?query=workflow%3ATests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/89f28370513ae05614bace9a336b3f99a01704bd959898f616748c515c153c71/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7261696f6c616e6574776f726b732f61746c61732f70696e742e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/raiolanetworks/atlas/actions?query=workflow%3APint+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/a70bc5eb97525739ed5c17dcddf3627c6ccd516333dfd571ac412eef5d5c3214/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7261696f6c616e6574776f726b732f61746c61732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/raiolanetworks/atlas) With 'Atlas' you will be able to create new tables in the database and fill them with information about countries, states, cities, timezones and more. Requirements ------------ [](#requirements) - PHP 8.3+ - Laravel 12+ Get to know us -------------- [](#get-to-know-us) [![](https://camo.githubusercontent.com/a2a13aedf73f874d9f95dd4a2e9c0505a43a8e0934ef8dd225b8935fe0ad1192/68747470733a2f2f63646e2d6173736574732e7261696f6c616e6574776f726b732e636f6d2f646973742f696d616765732f6c6f676f732f6c6f676f2d626c75652e737667)](https://raiolanetworks.com) Installation ------------ [](#installation) Install the package via Composer: ``` composer require raiolanetworks/atlas ``` Optionally publish the config file to customise table names or toggle entities: ``` php artisan vendor:publish --tag="atlas-config" ``` Run the migrations and seed the database: ``` php artisan atlas:install ``` The command will migrate the tables for every entity enabled in `config('atlas.entities')` (all enabled by default) and let you choose which seeders to run. The process may take a few minutes due to the large number of cities. To re-seed the data after a package upgrade: ``` php artisan atlas:update ``` ### Other publishable resources [](#other-publishable-resources) ``` php artisan vendor:publish --tag="atlas-translations" php artisan vendor:publish --tag="atlas-jsons" # JSON data files (for overriding) ``` > **Note:** Migrations are auto-loaded by the package. Do **not** publish them with `--tag="atlas-migrations"` unless you have a specific reason — published copies will cause "table already exists" errors. Usage ----- [](#usage) Internally, the package works with Laravel models, which allows you to work with this model as if they were models of your own project. For example, if you want to get all the countries in Africa: ``` use Raiolanetworks\Atlas\Models\Country; class MyClass { public function getAllAfricaCountries(): Collection { return Country::where('region_name', 'Africa') ->orderBy('name') ->get(); } } ``` ### State hierarchy [](#state-hierarchy) States support multi-level administrative divisions. Use `admin_level` to distinguish between primary regions (level 1) and subdivisions (level 2+): ``` use Raiolanetworks\Atlas\Models\State; // Get only top-level divisions (e.g., Autonomous Communities in Spain) State::where('country_code', 'ES')->topLevel()->get(); // Get subdivisions of a specific state $catalonia = State::where('state_code', 'CT')->first(); $catalonia->children; // Provinces: Barcelona, Girona, Lleida, Tarragona // Navigate up the hierarchy $barcelona = State::where('name', 'Barcelona')->first(); $barcelona->parent; // Cataluña ``` #### Scope and limitations [](#scope-and-limitations) The hierarchy support is intentionally uneven — read this before relying on it: - **`admin_level`, `topLevel()` and `adminLevel()` work for every country.** They classify each division as primary (level 1) or subdivision (level 2), which is enough to keep dropdowns to first-level divisions. - **`parent()` / `children()` only return data for the countries where `parent_id` is populated** (340 divisions): Spain, France, Italy, Belgium, Ireland, Sri Lanka, Fiji, Bosnia & Herzegovina, Equatorial Guinea and Saint Kitts & Nevis. For any other country `parent_id` is `null`, so `parent()` returns `null` and `children()` returns an empty collection. - **`topLevel()` does not guarantee unique names within a country.** A few countries have two *co-equal* first-level divisions that share a name — e.g. Minsk oblast + Minsk city (BY), Almaty region + Almaty city (KZ), Moscow oblast + Moscow city (RU), Zagreb county + Zagreb city (HR), cities vs counties in Taiwan, state cities vs municipalities in Latvia. These are genuinely different places (not parent/child), so both correctly stay at level 1. Disambiguate them by `type` or `state_code`: ``` State::where('country_code', 'BY')->topLevel()->get() ->map(fn (State $s) => "{$s->name} ({$s->type})"); // "Minsk (oblast)", "Minsk (city)" ``` Upgrading --------- [](#upgrading) If you are upgrading between major versions, please see [UPGRADE.md](./UPGRADE.md) for the list of breaking changes and migration steps. Changelog --------- [](#changelog) Please see [CHANGELOG](./CHANGELOG.md) for more information on what has changed recently. Credits ------- [](#credits) - [Martín Gómez](https://github.com/soymgomez) - [Víctor Escribano](https://github.com/victore13) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 52 — FairBetter than 96% of packages Maintenance94 Actively maintained with recent releases Popularity19 Limited adoption so far Community11 Small or concentrated contributor base Maturity69 Established project with proven stability Bus Factor1 Top contributor holds 60.1% 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 ~77 days Recently: every ~110 days Total 12 Last Release 32d ago Major Versions 1.0.7 → 2.0.02026-02-06 2.0.0 → 3.0.02026-07-15 PHP version history (3 changes)1.0.0PHP ^8.1 1.0.1PHP ^8.2 2.0.0PHP ^8.3 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/162998172?v=4)[Raiola Networks](/maintainers/RaiolaNetworks)[@RaiolaNetworks](https://github.com/RaiolaNetworks) --- Top Contributors [![victore13](https://avatars.githubusercontent.com/u/73330191?v=4)](https://github.com/victore13 "victore13 (92 commits)")[![soymgomez](https://avatars.githubusercontent.com/u/6207345?v=4)](https://github.com/soymgomez "soymgomez (59 commits)")[![EnriqueSanVic](https://avatars.githubusercontent.com/u/82119845?v=4)](https://github.com/EnriqueSanVic "EnriqueSanVic (2 commits)") --- Tags citiescountriescountry-listlaravellaravel-frameworklaravel-packagephpphp8stateslaravelcountriescountrycityatlascitiesraiolanetworks ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/raiolanetworks-atlas/health.svg) ``` [![Health](https://phpackages.com/badges/raiolanetworks-atlas/health.svg)](https://phpackages.com/packages/raiolanetworks-atlas) ``` ### Alternatives [laravel/octane Supercharge your Laravel application's performance. 4.0k28.5M262](/packages/laravel-octane)[statamic/cms The Statamic CMS Core Package 4.9k3.8M1.2k](/packages/statamic-cms)[typicms/base A modular multilingual CMS built with Laravel, enabling developers to manage structured content like pages, news, events, and more. 1.6k20.4k](/packages/typicms-base)[code16/sharp Laravel Content Management Framework 79466.1k10](/packages/code16-sharp)[dipeshsukhia/laravel-country-state-city-data Country State City Data Provider 8231.8k1](/packages/dipeshsukhia-laravel-country-state-city-data)[usamamuneerchaudhary/country-city-state Country City State Data Provider for Laravel 12+ 242.7k](/packages/usamamuneerchaudhary-country-city-state) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)