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

states

cities

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.