Laravel Seed Migration Estados Cidades Brasil Laravel Package

Technical Evaluation

Architecture fit. This is a thin data-provisioning package rather than a functional library: it ships a migration and a seeder that create and populate estados and cidades tables with Brazilian geographic reference data (27 states, ~5,570 municipalities). Architecturally it is a "reference data" concern that most Brazilian-facing Laravel applications eventually need — address forms, shipping zones, tax jurisdiction lookups, customer segmentation. It introduces no service layer, no runtime dependency, no facade, and no code paths that execute outside of artisan migrate/db:seed. That makes it a low-blast-radius addition if the target application's address model is willing to adopt its schema, and a poor fit if it is not.

Integration feasibility. Mechanically trivial: composer require, publish or auto-load the migration/seeders, run migrations. The primary feasibility gate is Laravel version drift. The last release is November 2020, which places it in the Laravel 7/8 era. Migrations from that period generally still execute on Laravel 9/10/11, but auto-discovery, namespace conventions, and PHP 8.1+ deprecation behavior (implicit nullable parameters, dynamic properties) need to be validated, not assumed. If the target app is Laravel 10/11 on PHP 8.2+, treat this as "verify before commit."

Technical risk. Three risks dominate:

1. Data staleness. Brazilian municipality data is mostly stable — no new municipalities have been created since 2013 and IBGE codes are durable — so a 2020 snapshot is likely acceptable for address selection. It is not acceptable if the application uses the data for regulatory, fiscal, or IBGE-code-driven integrations where occasional district/name changes matter. This is the single most important determination to make before adoption.
2. Schema and naming collisions. The tables are estados and cidades (Portuguese). Any existing address schema, or a competing package (e.g., a states/cities package), will conflict. There is no configuration for table names, key types, or column shapes. You adopt the package's opinion or you fork it.
3. Abandonment. 77 stars, last release in 2020, single maintainer. There is effectively no upstream support path. Budget for "we own this fork" from day one.

Key questions.

• Does the product need all ~5,570 municipalities, or a curated subset (e.g., only municipalities where we operate)? Full seeding has real time cost.
• Are IBGE codes required downstream (fiscal, logistics, analytics)? If yes, validate the codes against the current IBGE list rather than trusting a 2020 snapshot.
• Does an address model already exist with different naming or key types (bigIncrements vs increments, UUID, soft deletes)? If so, the package's schema will need to be copied and adapted, not installed.
• Is the target Laravel/PHP version within the validated set? If not, is forking cheaper than an alternative (IBGE API sync, hand-rolled seeder generated from a current CSV)?
• Who owns reference-data refresh? If nobody, that is a latent data-quality issue regardless of package choice.

Integration Approach

Stack fit. Best fit is a conventional Laravel monolith or modular monolith with Eloquent, MySQL/Postgres, and a Brazilian user base. It is a poor fit for APIs that only need a handful of locations, for multi-tenant architectures where reference data must be per-tenant, or for stacks that already standardize on a states/cities abstraction. It is essentially irrelevant to non-Brazilian products.

Migration path. Two viable paths, chosen by whether the schema is acceptable:

• Adopt as-is: install, publish the migration and seeder, run them, bind the resulting models. Fastest, but locks you into the package's table shape and requires the package to remain installable across future Laravel upgrades.
• Absorb the data, not the package (recommended for any long-lived system): copy the migration and seed data into the application's own database/migrations and database/seeders, then remove the Composer dependency. This eliminates the abandonment risk, allows table/column renaming to match existing conventions, and lets you replace the static seed with a refreshed IBGE-derived dataset later. The package becomes a one-time data source rather than a runtime dependency.

Compatibility. Confirm three things in a sandbox before any application change: (1) the migration runs cleanly on the target Laravel and database versions; (2) PHP 8.2+ emits no deprecations during seed; (3) the seeder completes within the deployment window (full seeding can take tens of seconds to minutes depending on insert strategy). Check whether migrations are auto-loaded or published — this determines whether a fresh migrate on a new environment silently creates these tables, which may or may not be desired.

Sequencing.

1. Sandbox spike: install on the exact target stack, run migrate + seed, time it, inspect schema and sample rows.
2. Data validation: spot-check IBGE codes and municipality counts against the current official list; decide staleness acceptability.
3. Schema decision: adopt as-is vs. absorb into app-owned migrations. Prefer absorption if the product is long-lived.
4. Integrate with the address model: define foreign keys, indexes, and any caching of the state/city lists used by forms.
5. Deploy with a backfill/validation note; ensure existing addresses still resolve.

Operational Impact

Maintenance. Low ongoing effort — it is static reference data — but with a caveat: because the package is unmaintained, "low effort" only holds if you own the fork or have absorbed the data. If you keep it as a dependency, every Laravel major upgrade becomes a small risk event you must re-test. Assign explicit ownership of the reference dataset and a periodic (annual) IBGE reconciliation.

Support. Community-only, effectively none. There is no vendor, no SLA, no issue-triage commitment. Internal runbooks must document where the data came from, how to regenerate it, and how to add or rename a municipality if a business need arises.

Scaling. Negligible runtime cost — two small, read-mostly tables. The real cost is at seed time and in deployment pipelines: re-seeding on every deploy is wasteful and can cause lock contention or duplicate-key errors if not idempotent. Seed once, seed idempotently (updateOrCreate or truncate-and-insert), and keep it out of routine deploys.

Failure modes.

• Migration collision with existing estados/cidades tables or with a competing geography package.
• Partial or failed seed leaving an incomplete city list — forms then silently omit municipalities, which surfaces as user complaints, not errors.
• Stale or incorrect IBGE codes propagating into fiscal or logistics integrations.
• Package breakage on a future Laravel upgrade, discovered at the worst time (e.g., a framework upgrade sprint).
• Duplicate rows if the seeder is re-run without idempotency guards.

Ramp-up. Near-zero for any Laravel developer — it is install, migrate, seed, query. The ramp-up cost is concentrated in the decision work (data validation, schema ownership), not the coding work. A TPM should budget roughly a day for the sandbox spike and data validation and treat the rest as routine integration. The headline recommendation: use it as a data source, absorb the migrations and seed into the application, and do not carry it as a long-term runtime dependency.