← All plugins
Provides a chained selector for selecting departments and municipalities of Colombia
This package provides a chained selector for selecting departments and municipalities in Laravel applications, particularly for the MoonShine Admin Panel. It includes all 1,120 official municipalities of Colombia, along with installation instructions, usage examples, and API endpoints for retrieving municipalities by department. The package simplifies the management of Colombian geographical data within web applications.
moonshine-colombia-municipios
Chained selector Department → Municipality for Laravel and MoonShine Admin Panel, with the 1,120 official municipalities of Colombia according to DANE/DIVIPOLA codes.
Requirements
- PHP 8.2+
- Laravel 10, 11, 12 or 13
- MoonShine 4.x (optional — only for admin panel fields)
Installation
composer require jamesmosq/moonshine-colombia-municipios
composer require jamesmosq/moonshine-colombia-municipios
composer require jamesmosq/moonshine-colombia-municipios
composer require jamesmosq/moonshine-colombia-municipios
composer require jamesmosq/moonshine-colombia-municipios
Publish and run migrations:
php artisan migrate
php artisan migrate
php artisan migrate
php artisan migrate
php artisan migrate
Insert the 33 departments and 1,120 municipalities:
php artisan db:seed --class="Jamesmosq\ColombiaFields\Database\Seeders\ColombiaSeeder"
php artisan db:seed --class="Jamesmosq\ColombiaFields\Database\Seeders\ColombiaSeeder"
php artisan db:seed --class="Jamesmosq\ColombiaFields\Database\Seeders\ColombiaSeeder"
php artisan db:seed --class="Jamesmosq\ColombiaFields\Database\Seeders\ColombiaSeeder"
php artisan db:seed --class="Jamesmosq\ColombiaFields\Database\Seeders\ColombiaSeeder"
Usage in pure Laravel (Blade + Alpine.js)
Include both fields in your view. The municipality field automatically listens for changes in the department:
<form method="POST" action="/my-route">
@csrf
@include('colombia-fields::fields.departamento', [
'column' => 'departamento_id',
'label' => 'Department',
'required' => true,
'options' => \Jamesmosq\ColombiaFields\Models\Departamento::options(),
'value' => old('departamento_id'),
])
@include('colombia-fields::fields.municipio', [
'column' => 'municipio_id',
'label' => 'Municipality',
'required' => true,
'options' => [],
'value' => old('municipio_id'),
])
<button type="submit">Save</button>
</form>
<form method="POST" action="/my-route">
@csrf
@include('colombia-fields::fields.departamento', [
'column' => 'departamento_id',
'label' => 'Department',
'required' => true,
'options' => \Jamesmosq\ColombiaFields\Models\Departamento::options(),
'value' => old('departamento_id'),
])
@include('colombia-fields::fields.municipio', [
'column' => 'municipio_id',
'label' => 'Municipality',
'required' => true,
'options' => [],
'value' => old('municipio_id'),
])
<button type="submit">Save</button>
</form>
<form method="POST" action="/my-route">
@csrf
@include('colombia-fields::fields.departamento', [
'column' => 'departamento_id',
'label' => 'Department',
'required' => true,
'options' => \Jamesmosq\ColombiaFields\Models\Departamento::options(),
'value' => old('departamento_id'),
])
@include('colombia-fields::fields.municipio', [
'column' => 'municipio_id',
'label' => 'Municipality',
'required' => true,
'options' => [],
'value' => old('municipio_id'),
])
<button type="submit">Save</button>
</form>
<form method="POST" action="/my-route">
@csrf
@include('colombia-fields::fields.departamento', [
'column' => 'departamento_id',
'label' => 'Department',
'required' => true,
'options' => \Jamesmosq\ColombiaFields\Models\Departamento::options(),
'value' => old('departamento_id'),
])
@include('colombia-fields::fields.municipio', [
'column' => 'municipio_id',
'label' => 'Municipality',
'required' => true,
'options' => [],
'value' => old('municipio_id'),
])
<button type="submit">Save</button>
</form>
<form method="POST" action="/my-route">
@csrf
@include('colombia-fields::fields.departamento', [
'column' => 'departamento_id',
'label' => 'Department',
'required' => true,
'options' => \Jamesmosq\ColombiaFields\Models\Departamento::options(),
'value' => old('departamento_id'),
])
@include('colombia-fields::fields.municipio', [
'column' => 'municipio_id',
'label' => 'Municipality',
'required' => true,
'options' => [],
'value' => old('municipio_id'),
])
<button type="submit">Save</button>
</form>
Alpine.js must be available on the page (already included if you use MoonShine or Livewire).
Usage in MoonShine Admin Panel
Fields in a Resource
use Jamesmosq\ColombiaFields\Fields\DepartamentoField;
use Jamesmosq\ColombiaFields\Fields\MunicipioField;
public function fields(): array
{
return [
DepartamentoField::make('Department', 'departamento_id')
->toMoonShineField(),
MunicipioField::make('Municipality', 'municipio_id')
->toMoonShineField(),
];
}
use Jamesmosq\ColombiaFields\Fields\DepartamentoField;
use Jamesmosq\ColombiaFields\Fields\MunicipioField;
public function fields(): array
{
return [
// ... other fields
DepartamentoField::make('Department', 'departamento_id')
->toMoonShineField(),
MunicipioField::make('Municipality', 'municipio_id')
->toMoonShineField(),
];
}
use Jamesmosq\ColombiaFields\Fields\DepartamentoField;
use Jamesmosq\ColombiaFields\Fields\MunicipioField;
public function fields(): array
{
return [
// ... other fields
DepartamentoField::make('Department', 'departamento_id')
->toMoonShineField(),
MunicipioField::make('Municipality', 'municipio_id')
->toMoonShineField(),
];
}
use Jamesmosq\ColombiaFields\Fields\DepartamentoField;
use Jamesmosq\ColombiaFields\Fields\MunicipioField;
public function fields(): array
{
return [
// ... other fields
DepartamentoField::make('Department', 'departamento_id')
->toMoonShineField(),
MunicipioField::make('Municipality', 'municipio_id')
->toMoonShineField(),
];
}
use Jamesmosq\ColombiaFields\Fields\DepartamentoField;
use Jamesmosq\ColombiaFields\Fields\MunicipioField;
public function fields(): array
{
return [
// ... other fields
DepartamentoField::make('Department', 'departamento_id')
->toMoonShineField(),
MunicipioField::make('Municipality', 'municipio_id')
->toMoonShineField(),
];
}
Filters in a Resource
use Jamesmosq\ColombiaFields\Filters\DepartamentoFilter;
use Jamesmosq\ColombiaFields\Filters\MunicipioFilter;
public function filters(): array
{
return [
DepartamentoFilter::make('Department', 'departamento_id')
->toMoonShineFilter(),
MunicipioFilter::make('Municipality', 'municipio_id')
->toMoonShineFilter(),
];
}
use Jamesmosq\ColombiaFields\Filters\DepartamentoFilter;
use Jamesmosq\ColombiaFields\Filters\MunicipioFilter;
public function filters(): array
{
return [
DepartamentoFilter::make('Department', 'departamento_id')
->toMoonShineFilter(),
MunicipioFilter::make('Municipality', 'municipio_id')
->toMoonShineFilter(),
];
}
use Jamesmosq\ColombiaFields\Filters\DepartamentoFilter;
use Jamesmosq\ColombiaFields\Filters\MunicipioFilter;
public function filters(): array
{
return [
DepartamentoFilter::make('Department', 'departamento_id')
->toMoonShineFilter(),
MunicipioFilter::make('Municipality', 'municipio_id')
->toMoonShineFilter(),
];
}
use Jamesmosq\ColombiaFields\Filters\DepartamentoFilter;
use Jamesmosq\ColombiaFields\Filters\MunicipioFilter;
public function filters(): array
{
return [
DepartamentoFilter::make('Department', 'departamento_id')
->toMoonShineFilter(),
MunicipioFilter::make('Municipality', 'municipio_id')
->toMoonShineFilter(),
];
}
use Jamesmosq\ColombiaFields\Filters\DepartamentoFilter;
use Jamesmosq\ColombiaFields\Filters\MunicipioFilter;
public function filters(): array
{
return [
DepartamentoFilter::make('Department', 'departamento_id')
->toMoonShineFilter(),
MunicipioFilter::make('Municipality', 'municipio_id')
->toMoonShineFilter(),
];
}
Usage of Eloquent models directly
use Jamesmosq\ColombiaFields\Models\Departamento;
use Jamesmosq\ColombiaFields\Models\Municipio;
$departamentos = Departamento::orderBy('nombre')->get();
$municipios = Municipio::byDepartamento('05')->orderBy('nombre')->get();
$medellin = Municipio::find('05001');
echo $medellin->nombre; echo $medellin->departamento_id;
$choco = Departamento::find('27');
echo $choco->id;
use Jamesmosq\ColombiaFields\Models\Departamento;
use Jamesmosq\ColombiaFields\Models\Municipio;
// All departments
$departamentos = Departamento::orderBy('nombre')->get();
// Municipalities of Antioquia
$municipios = Municipio::byDepartamento('05')->orderBy('nombre')->get();
// Search by DANE code
$medellin = Municipio::find('05001');
echo $medellin->nombre; // MEDELLIN
echo $medellin->departamento_id; // 05
// Check preserved leading zeros
$choco = Departamento::find('27');
echo $choco->id; // 27 (Chocó — not truncated)
use Jamesmosq\ColombiaFields\Models\Departamento;
use Jamesmosq\ColombiaFields\Models\Municipio;
// All departments
$departamentos = Departamento::orderBy('nombre')->get();
// Municipalities of Antioquia
$municipios = Municipio::byDepartamento('05')->orderBy('nombre')->get();
// Search by DANE code
$medellin = Municipio::find('05001');
echo $medellin->nombre; // MEDELLIN
echo $medellin->departamento_id; // 05
// Check preserved leading zeros
$choco = Departamento::find('27');
echo $choco->id; // 27 (Chocó — not truncated)
use Jamesmosq\ColombiaFields\Models\Departamento;
use Jamesmosq\ColombiaFields\Models\Municipio;
// All departments
$departamentos = Departamento::orderBy('nombre')->get();
// Municipalities of Antioquia
$municipios = Municipio::byDepartamento('05')->orderBy('nombre')->get();
// Search by DANE code
$medellin = Municipio::find('05001');
echo $medellin->nombre; // MEDELLIN
echo $medellin->departamento_id; // 05
// Check preserved leading zeros
$choco = Departamento::find('27');
echo $choco->id; // 27 (Chocó — not truncated)
use Jamesmosq\ColombiaFields\Models\Departamento;
use Jamesmosq\ColombiaFields\Models\Municipio;
// All departments
$departamentos = Departamento::orderBy('nombre')->get();
// Municipalities of Antioquia
$municipios = Municipio::byDepartamento('05')->orderBy('nombre')->get();
// Search by DANE code
$medellin = Municipio::find('05001');
echo $medellin->nombre; // MEDELLIN
echo $medellin->departamento_id; // 05
// Check preserved leading zeros
$choco = Departamento::find('27');
echo $choco->id; // 27 (Chocó — not truncated)
API Endpoint
The package automatically registers:
GET /colombia/municipios/{departamento_id}
GET /colombia/municipios/{departamento_id}
GET /colombia/municipios/{departamento_id}
GET /colombia/municipios/{departamento_id}
GET /colombia/municipios/{departamento_id}
Returns JSON with the municipalities of the department:
[
{ "id": "05001", "nombre": "MEDELLIN" },
{ "id": "05002", "nombre": "ABEJORRAL" }
]
[
{ "id": "05001", "nombre": "MEDELLIN" },
{ "id": "05002", "nombre": "ABEJORRAL" }
]
[
{ "id": "05001", "nombre": "MEDELLIN" },
{ "id": "05002", "nombre": "ABEJORRAL" }
]
[
{ "id": "05001", "nombre": "MEDELLIN" },
{ "id": "05002", "nombre": "ABEJORRAL" }
]
[
{ "id": "05001", "nombre": "MEDELLIN" },
{ "id": "05002", "nombre": "ABEJORRAL" }
]
Publish views for customization
php artisan vendor:publish --tag=colombia-views
php artisan vendor:publish --tag=colombia-views
php artisan vendor:publish --tag=colombia-views
php artisan vendor:publish --tag=colombia-views
php artisan vendor:publish --tag=colombia-views
Views will be located at resources/views/vendor/colombia-fields/fields/.
Database structure
departamentos
| Column |
Type |
Description |
| id |
CHAR(2) PK |
DANE code (e.g., 05) |
| nombre |
VARCHAR(80) |
Official name |
municipios
| Column |
Type |
Description |
| id |
CHAR(5) PK |
DANE code (e.g., 05001) |
| departamento_id |
CHAR(2) FK |
Reference to departments |
| nombre |
VARCHAR(120) |
Official name |
Tests
composer require --dev orchestra/testbench
vendor/bin/phpunit
composer require --dev orchestra/testbench
vendor/bin/phpunit
composer require --dev orchestra/testbench
vendor/bin/phpunit
composer require --dev orchestra/testbench
vendor/bin/phpunit
composer require --dev orchestra/testbench
vendor/bin/phpunit
License
MIT — James Mosquera
Plugin 1 of 3 — moonshine-colombia series
