Product Decisions This Supports
- Brazil market entry / address capture: This package is the lowest-cost way to unblock any Brazil-facing flow that needs a state + city picker — checkout (billing/shipping), signup, lead forms, CRM records, delivery-zone setup. It replaces a multi-day data-sourcing-and-seeding chore with
composer require + php artisan migrate --seed.
- Build vs. buy decision: The "build" alternative is sourcing IBGE state/municipality data, normalizing accents and naming, designing the schema, and writing the migration/seeder. That's typically 2–4 engineering days plus ongoing maintenance. This package collapses it to hours. The real decision is adopt-and-vet vs. adopt-and-fork vs. own the dataset — not build-from-scratch.
- Roadmap gating: If "Launch in Brazil," "BR address support," or "international expansion" sits on the roadmap, this is the cheapest dependency to de-risk that milestone before committing to a full address-validation strategy (CEP lookup, geocoding, etc.).
- Enables downstream features: state-level tax rules (ICMS/ISS), delivery-zone and shipping pricing, regional analytics/reporting, city-based search and filtering, and NF-e/e-invoicing integrations — if IBGE codes are present (verify this before relying on it).
- Scope discipline: It gives you states + cities only. It does not give CEP/postal-code lookup, bairros/neighborhoods, geocoordinates, or street-level validation. Treat it as the backbone of an address model, not a complete address solution — those are separate product decisions (ViaCEP/Correios, Google Maps, etc.).
- Data-model precedent: Adopting it early fixes state/city IDs that other tables will foreign-key into. Decide now whether you own those IDs (recommended) or let the package own them — this determines how painful a future swap or fork will be.
When to Consider This Package
Adopt when:
- You're building a Laravel app that needs Brazilian states and municipalities and can accept a fixed lookup table.
- Your schema can tolerate the package's migration conventions (review column names, keys, and any soft-delete/timestamps assumptions before merging).
- You can pin the version, vendor the underlying data, and wrap access behind your own repository/service layer.
- You've validated compatibility against your Laravel and PHP version (last release Nov 2020 — likely pre-Laravel 9; test against 10/11 and PHP 8.x).
Due diligence before adoption:
- Confirm the data source and snapshot date (is it IBGE-derived? how current?).
- Verify whether IBGE state and municipality codes are included — critical if you'll ever integrate tax, fiscal (NF-e), or logistics providers.
- Scan open issues and the migration/seed files for data or schema bugs; with 77 stars and no release since 2020, expect to own any fixes.
Look elsewhere or build your own when:
- You need data refreshed on IBGE's cadence (municipal boundary changes, new districts).
- You need CEP ↔ city mapping (use ViaCEP/Correios APIs) or geocoordinates.
- You need bairros/districts or multi-country support.
- Your compliance/security posture forbids unmaintained dependencies without an internal owner.
- You want an actively maintained package with CVE responsiveness — in which case, fork the data and keep the migration in-house.
How to Pitch It (Stakeholders)
For executives: This is a free, MIT-licensed Laravel package that ships the official Brazilian states and cities as database migrations and seeders. It lets us ship Brazil address capture in days rather than weeks, with no data-licensing cost and negligible integration footprint. It's a contained, reversible dependency — not a platform commitment.
For engineering: It saves roughly 2–4 days of data sourcing, schema design, seeding, and normalization, and keeps state/city data consistent across environments. The trade-off is maintenance risk: no release since November 2020, so assume we may need to fork. Mitigate by (1) pinning the version, (2) reviewing the migration and confirming IBGE codes are present, (3) wrapping access behind our own address service so we can swap or vendor the data without app-wide changes, and (4) running a half-day compatibility spike against our Laravel/PHP versions before committing.
Recommendation: Approve a time-boxed spike (≤1 day) to validate compatibility and data quality; if it passes, adopt behind an abstraction layer and log a follow-up to re-baseline the dataset against IBGE. If it fails, fork the data into our own migration — the effort is small and the dependency risk disappears.