README

A Laravel package that provides migrations, seeders, and Eloquent models for countries, states, and cities — with full data for all Brazilian states and municipalities.

Data sourced from the IBGE Localities API.

Features

All world countries with M49 codes and region classification
All 27 Brazilian states with regional data
All Brazilian municipalities (5,000+)
Ready-to-use Eloquent models with relationships
Fully configurable table names, column names, and models
Auto-discovery support for Laravel 9+

Requirements

PHP 8.1+
Laravel 9.0+

Installation

Install the package via Composer:

composer require paulofelipem/brazilian-regions

The service provider is registered automatically. If needed, you can register it manually in config/app.php:

'providers' => [
    // ...
    PauloFelipeM\BrazilianRegions\BrazilianRegionsServiceProvider::class,
],

Publish the configuration and migration files:

php artisan vendor:publish --provider="PauloFelipeM\BrazilianRegions\BrazilianRegionsServiceProvider"

Note: This publishes a config/brazilianregions.php file. If you already have a file with that name, rename or remove it before publishing.

Usage

Run the migrations and seeders to create and populate the tables:

php artisan migrate
php artisan db:seed --class="PauloFelipeM\\BrazilianRegions\\Database\\Seeds\\DatabaseSeeder"

Then use the provided Eloquent models in your application:

use PauloFelipeM\BrazilianRegions\Models\Country;
use PauloFelipeM\BrazilianRegions\Models\State;
use PauloFelipeM\BrazilianRegions\Models\City;

// Get all Brazilian states
$brazil = Country::where('acronym', 'BRA')->first();
$states = $brazil->states;

// Get all cities in a state
$state = State::where('acronym', 'SP')->first();
$cities = $state->cities;

// Navigate from city to country
$city = City::where('name', 'São Paulo')->first();
$state = $city->state;
$country = $city->state->country;

Database Schema

`countries`

Column	Description
`id`	Auto-increment primary key
`m_49`	UN M49 numeric code
`acronym`	ISO Alpha-3 country code
`name`	Country name
`region`	Geographic region

`states`

Column	Description
`id`	Auto-increment primary key
`acronym`	State abbreviation (e.g. SP, RJ)
`name`	State name
`region`	Region name (e.g. Sudeste)
`region_acronym`	Region abbreviation
`country_id`	Foreign key to `countries`

`cities`

Column	Description
`id`	Auto-increment primary key
`name`	City name
`state_id`	Foreign key to `states`

All foreign keys use CASCADE on delete.

Configuration

The published config/brazilianregions.php file allows you to customize:

return [
    // Override the default Eloquent models
    'models' => [
        'country' => PauloFelipeM\BrazilianRegions\Models\Country::class,
        'state'   => PauloFelipeM\BrazilianRegions\Models\State::class,
        'city'    => PauloFelipeM\BrazilianRegions\Models\City::class,
    ],

    // Customize table names
    'tables' => [
        'countries' => 'countries',
        'states'    => 'states',
        'cities'    => 'cities',
    ],

    // Customize foreign key column names
    'columns' => [
        'country_id' => 'country_id',
        'state_id'   => 'state_id',
        'city_id'    => 'city_id',
    ],
];

This is useful when you need to integrate with an existing database schema or extend the default models.

Changelog

See CHANGELOG for release history.

Bugs

If you find any issues, please open an issue on GitHub.

Credits

Paulo Felipe Martins

License

The MIT License (MIT). See LICENSE for more information.

paulofelipem / brazilian-regions

Maintainers

Details