Laravel Hanhchinhvn Laravel Package

Product Decisions This Supports

• Vietnam market entry (build vs. buy vs. scrape): This package is the "buy" option for one of the most tedious pieces of a Vietnam launch — the province → district → ward hierarchy (tỉnh/thành phố → quận/huyện → phường/xã) with official administrative codes. It replaces a week or two of data collection and manual seeding with a Composer install.
• Address capture and checkout design: Directly informs whether you ship cascading dropdowns, free-text + lookup, or code-based address storage. Because the package exposes codes alongside names, it pushes the product toward storing codes as the source of truth and names as display labels — the decision that determines how painful future boundary changes will be.
• Data ownership and refresh strategy: The presence of a third-party dataset forces an explicit roadmap decision: do we depend on a package, fork and vendor the dataset into our own repo, or treat administrative data as a first-class internal reference service? This is a durable architectural choice, not a one-off.
• Feature enablement gated on geography: Shipping-fee zones and delivery-route grouping, sales/ops reporting by region, territory assignment for sales reps, KYC and customer-address validation, and Vietnam e-invoice requirements that expect buyer/seller administrative identifiers.
• Scope discipline: Anything requiring boundary polygons, geocoding, or lat/long is out of scope for this package — it is names, codes, and parent-child relationships. That boundary should be stated early so nobody scopes a map feature onto it.

When to Consider This Package

Adopt when:

• You're on Laravel/Eloquent and want migrations, models, and seeders rather than raw JSON wrangling.
• You need reference data for an MVP or internal tool where "good enough, roughly current" beats "authoritative and maintained."
• You intend to fork and vendor the dataset — treating the package as a starting dataset, not a living dependency.
• Your addresses are low-stakes (marketing segmentation, internal reporting) rather than regulatory or financial.

Look elsewhere when:

• Data vintage is a blocker. Last release was March 2022. Vietnam's administrative structure has changed materially since — validate against the current province count and district-level status before committing. For a shipping, tax, or legal-entity use case, stale hierarchy is a correctness bug, not a cosmetic one.
• You need geospatial boundaries, geocoding, or postal-code enrichment.
• You're not on Laravel, or you want the data as a standalone SQL/JSON artifact (use the upstream hanhchinhvn dataset directly).
• You need vendor support, SLAs, or a security-response commitment — 39 stars, a single maintainer, and no release in years means bus-factor and abandonment risk are real.
• You need a guaranteed update cadence tied to government decrees. Nothing here provides that; you'd be building the refresh pipeline yourself anyway, so own the data outright.

How to Pitch It (Stakeholders)

To executives: This is a small, free (MIT), open-source dataset that removes a known time sink from a Vietnam launch — the administrative address hierarchy — and lets us ship localized address capture in days rather than weeks. The honest caveat: it's a snapshot, not a maintained service, last updated in 2022, and Vietnam's administrative boundaries have shifted since. I'd recommend adopting it as a seed dataset, budgeting a small amount of engineering to fork and own the refresh, and not treating it as a dependency we rely on someone else to keep current. That converts an abandonment risk into a one-time cost.

To engineering: Thin Eloquent models, migrations, and seeders for the three-level hierarchy with codes — low integration cost, easy to fork into our repo. Plan for it as vendored reference data: copy the schema and dataset in, add our own refresh job and a version/effective-date column so historical addresses remain resolvable when boundaries change. Do not build geospatial features on it; it's textual hierarchy only.