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.
- PHP 8.3+
- Laravel 12+
Install the package via Composer:
composer require raiolanetworks/atlasOptionally 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:installThe 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:updatephp 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.
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();
}
}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ñaThe hierarchy support is intentionally uneven — read this before relying on it:
admin_level,topLevel()andadminLevel()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 whereparent_idis populated (340 divisions): Spain, France, Italy, Belgium, Ireland, Sri Lanka, Fiji, Bosnia & Herzegovina, Equatorial Guinea and Saint Kitts & Nevis. For any other countryparent_idisnull, soparent()returnsnullandchildren()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 bytypeorstate_code:
State::where('country_code', 'BY')->topLevel()->get()
->map(fn (State $s) => "{$s->name} ({$s->type})"); // "Minsk (oblast)", "Minsk (city)"If you are upgrading between major versions, please see UPGRADE.md for the list of breaking changes and migration steps.
Please see CHANGELOG for more information on what has changed recently.
The MIT License (MIT). Please see License File for more information.