README

Selector encadenado Departamento → Municipio para Laravel y MoonShine Admin Panel, con los 1.120 municipios oficiales de Colombia según los códigos DANE/DIVIPOLA.

Requisitos

PHP 8.2+
Laravel 10, 11, 12 o 13
MoonShine 4.x (opcional — solo para los campos de panel admin)

Instalación

composer require jamesmosq/moonshine-colombia-municipios

Publicar y ejecutar migraciones:

php artisan migrate

Insertar los 33 departamentos y 1.120 municipios:

php artisan db:seed --class="Jamesmosq\ColombiaFields\Database\Seeders\ColombiaSeeder"

Uso en Laravel puro (Blade + Alpine.js)

Incluir ambos campos en tu vista. El campo de municipio escucha automáticamente los cambios del departamento:

<form method="POST" action="/mi-ruta">
    @csrf

    @include('colombia-fields::fields.departamento', [
        'column'      => 'departamento_id',
        'label'       => 'Departamento',
        'required'    => true,
        'opciones'    => \Jamesmosq\ColombiaFields\Models\Departamento::opciones(),
        'value'       => old('departamento_id'),
    ])

    @include('colombia-fields::fields.municipio', [
        'column'   => 'municipio_id',
        'label'    => 'Municipio',
        'required' => true,
        'opciones' => [],
        'value'    => old('municipio_id'),
    ])

    <button type="submit">Guardar</button>
</form>

Alpine.js debe estar disponible en la página (ya incluido si usas MoonShine o Livewire).

Uso en MoonShine Admin Panel

Campos en un Resource

use Jamesmosq\ColombiaFields\Fields\DepartamentoField;
use Jamesmosq\ColombiaFields\Fields\MunicipioField;

public function fields(): array
{
    return [
        // ... otros campos

        DepartamentoField::make('Departamento', 'departamento_id')
            ->toMoonShineField(),

        MunicipioField::make('Municipio', 'municipio_id')
            ->toMoonShineField(),
    ];
}

Filtros en un Resource

use Jamesmosq\ColombiaFields\Filters\DepartamentoFilter;
use Jamesmosq\ColombiaFields\Filters\MunicipioFilter;

public function filters(): array
{
    return [
        DepartamentoFilter::make('Departamento', 'departamento_id')
            ->toMoonShineFilter(),

        MunicipioFilter::make('Municipio', 'municipio_id')
            ->toMoonShineFilter(),
    ];
}

Uso de los modelos Eloquent directamente

use Jamesmosq\ColombiaFields\Models\Departamento;
use Jamesmosq\ColombiaFields\Models\Municipio;

// Todos los departamentos
$departamentos = Departamento::orderBy('nombre')->get();

// Municipios de Antioquia
$municipios = Municipio::byDepartamento('05')->orderBy('nombre')->get();

// Buscar por código DANE
$medellin = Municipio::find('05001');
echo $medellin->nombre;           // MEDELLIN
echo $medellin->departamento_id;  // 05

// Verificar ceros a la izquierda preservados
$choco = Departamento::find('27');
echo $choco->id; // 27 (Chocó — no truncado)

Endpoint API

El package registra automáticamente:

GET /colombia/municipios/{departamento_id}

Retorna JSON con los municipios del departamento:

[
  { "id": "05001", "nombre": "MEDELLIN" },
  { "id": "05002", "nombre": "ABEJORRAL" }
]

Publicar vistas para personalizar

php artisan vendor:publish --tag=colombia-views

Las vistas quedan en resources/views/vendor/colombia-fields/fields/.

Estructura de la base de datos

departamentos

Columna	Tipo	Descripción
id	CHAR(2) PK	Código DANE (ej: `05`)
nombre	VARCHAR(80)	Nombre oficial

municipios

Columna	Tipo	Descripción
id	CHAR(5) PK	Código DANE (ej: `05001`)
departamento_id	CHAR(2) FK	Referencia a departamentos
nombre	VARCHAR(120)	Nombre oficial

Tests

composer require --dev orchestra/testbench
vendor/bin/phpunit

Licencia

MIT — James Mosquera

Plugin 1 de 3 — Serie moonshine-colombia

jamesmosq / moonshine-colombia-municipios

Maintainers

Package info

Statistics

Security