Laravel Hanhchinhvn Laravel Package

Technical Evaluation

What the package is. laravel-hanhchinhvn is a thin Laravel wrapper around the Vietnamese administrative hierarchy dataset (province → district → ward/commune). Expected deliverables: Eloquent models for the three tiers, publishable migrations, a seeder or import command, and relationship helpers. This is a data bundle with an ORM veneer, not an application service — the value is the dataset and the code mappings, not the PHP code.

Architecture fit. Good structural fit for Laravel domain modelling: three-tier self-referential hierarchy maps cleanly to hasMany/belongsTo, and address selection (checkout, KYC, shipping, tax registration) is a common, well-understood requirement. The package's natural integration points — a provinces / districts / wards table trio plus FK columns on your address entities — are conventional and low-friction. The fit is architecturally sound and temporally poor (see risk).

Integration feasibility. Straightforward mechanically: composer require, publish migrations/config, seed. The friction is not installation, it is everything after: verifying dataset vintage, mapping the package's internal IDs to the identifiers your other systems use (GSO codes, logistics provider codes, e-invoice tax codes), and deciding whether your domain models FK into vendor-owned tables. That last decision is the one that determines exit cost.

Technical risk. Ranked:

Net position: treat this as a reference dataset and schema pattern, not a runtime dependency. Score 0.495 with these signals reads correctly as "useful starting point, do not bet the address model on it."

Key questions to resolve before committing:

1. What is the dataset's legal vintage, and does it model districts as a required tier?
2. Are identifiers official GSO codes (interoperable with government/logistics/e-invoice APIs) or package-local?
3. Which Laravel/PHP versions are actually supported by composer.json?
4. Is there an update mechanism (command, config source URL) or is data hard-coded in migrations/seeders?
5. Does it ship validation rules, form components, or search helpers — or only models + data?
6. What is the data provenance and is redistribution under MIT clean? (Dataset licensing is often separate from code licensing.)
7. Does it cover the full depth (islands, sub-communes, historical units still in use in legacy records)?

Integration Approach

Stack fit. Native Laravel/Eloquent — no impedance mismatch, no external service, no runtime dependency on a third party. That is genuinely attractive for an address reference table: it is read-mostly, small, and cacheable. The package fits inside the monolith cleanly; it should not be allowed to shape the domain model of your address entities.

Recommended migration path — fork, don't depend.

1. Fork the repo (or vendor the dataset) into an internal package, e.g. acme/vn-administrative-data.
2. Pin the original MIT licence and attribution; confirm dataset provenance separately.
3. Replace the seed source with a current, versioned snapshot (GSO / official published decisions, or an actively maintained dataset repo) captured as a dated artefact.
4. Re-model to the current legal structure — two-tier if that is the standing regime — while retaining a legacacy district tier if historical records require it. Model as province and ward, with district as a nullable/deprecated dimension, not a required join.
5. Key rows on official codes, with an internal surrogate PK only if you must. Never expose a package-local ID to other systems.
6. Wrap access behind your own repository/service (AdministrativeUnitRepository) so the data source is swappable and the package is not referenced directly from controllers.

Compatibility. Validate composer.json constraints against your Laravel/PHP target first — this is a 10-minute check that can end the evaluation. Require MySQL/Postgres utf8mb4 (or equivalent) and confirm collation behaviour for Vietnamese text. Test accent-insensitive search explicitly.

Sequencing.

1. Spike (1–2 days): install in a scratch app, inspect migrations and data shape, confirm Laravel/PHP compatibility, capture row counts and ID scheme.
2. Data currency check (parallel, gating): confirm current legal administrative structure and source a fresh snapshot. Do not proceed past this gate without an answer.
3. Decide dependency posture: direct dependency vs internal fork. Default to fork given maintenance signals.
4. Schema design: finalise two-tier-with-legacy model, code strategy, and FK policy for address entities.
5. Ingestion pipeline: versioned, idempotent import command with a dataset version stamp recorded in the DB.
6. Application integration: address forms, validation, search normalisation, caching layer.
7. Backfill/mapping: reconcile existing stored addresses to new codes; log unmatched rows for manual review.

Operational Impact

Maintenance. Effectively 100% internal. With no upstream releases since March 2022, assume you own the code and the data. Budget for an annual (or event-driven) data refresh — Vietnamese administrative units change by decree, and changes are not rare. The refresh should be a repeatable, tested pipeline, not a manual SQL exercise; if it is manual, it will not happen on schedule.

Support. Community-only, no SLA, no vendor. Documentation is likely Vietnamese-language, which is fine for a Vietnamese-market team but is a bus-factor consideration for a distributed or outsourced team. Internal knowledge should be documented in English alongside.

Scaling. A non-issue. The dataset is on the order of tens of thousands of rows at most (pre-2025: ~63 / ~700 / ~11k; current two-tier: ~34 / ~3.3k). Load once into a cache (Redis or a bootstrapped array/config) and serve address dropdowns from memory. Read-mostly, near-zero write volume, negligible DB pressure. This is one of the least operationally demanding integration surfaces you will own.

Failure modes to design against.

• Silent staleness — the system keeps returning abolished districts and deleted communes, and orders/KYC records are created with invalid addresses. Mitigation: dataset version stamp surfaced in admin, refresh runbook, monitoring on validation-rejection rate.
• ID drift on refresh — new snapshot renumbers rows, orphaning stored FKs. Mitigation: official codes as the stable key, plus an explicit mapping table for retired codes.
• Ambiguous matching — many communes share names across provinces; name-only lookup produces wrong addresses. Mitigation: always require the full hierarchy path, never resolve on leaf name alone.
• Diacritic mismatch — user input without accents fails exact match. Mitigation: accent-folded search column/index.
• Tier-model break — a schema that hard-requires a district cannot represent post-2025 units. Mitigation: nullable district, tested against a two-tier fixture.
• Legacy record breakage — historical orders referencing abolished units fail joins or display blank. Mitigation: soft-retire, never hard-delete reference rows.

Ramp-up. Low for any Laravel developer — installation and familiar Eloquent consumption is hours, not days. The real ramp-up cost is domain: understanding Vietnamese administrative reform cadence and the address-data expectations of logistics, e-invoicing, and tax systems. Assign one owner who tracks administrative changes; that person, not the code, is the actual asset.

TPM recommendation. Proceed with a bounded spike, but plan to fork and re-source the data. Adopt the package's schema pattern and dataset structure; reject it as a long-lived runtime dependency on maintenance-risk and data-currency grounds. Gate all downstream work on confirming the current administrative tier model — that answer determines whether this is a data refresh or a redesign.