China Distpicker Laravel Package

Product Decisions This Supports

• China market entry / localization roadmap. If China is on the roadmap (or already live), every operational workflow — order fulfillment, customer profiles, merchant onboarding, logistics routing, after-sales — needs a validated province/city/district (省/市/区) field. This package is the smallest possible unblocker for that requirement inside an existing laravel-admin back office.
• Build vs. buy vs. borrow: borrow. A three-level cascading administrative-division selector looks trivial and is not — it requires bundled division data, cascade logic, and integration with the admin form layer. Buying/borrowing at MIT license cost is clearly correct versus a multi-day internal build of the same widget.
• Internal tooling velocity. This is an admin-panel-only dependency. It should be evaluated as productivity tooling for ops/support staff, not as a product differentiator. It accelerates feature delivery (ship the address form this sprint) rather than creating customer-visible value.
• Compliance and data-quality decisions. The package's bundled division data was released around 2021. Adopting it forces an explicit decision about who owns administrative-division data freshness — a recurring operational obligation, since China's divisions change (city mergers, district renames, new development zones) on a regular cadence.
• Vendor/architecture optionality. Because the widget is bound to laravel-admin's form API, adopting it is a mild bet on that admin framework. The decision record should note this coupling, especially if there is any appetite to migrate to Filament, Nova, or a custom front end.
• Not a customer-facing use case. This does not solve address capture for end users on a storefront or app; it solves operator data entry. Confusing the two would lead to the wrong build.

When to Consider This Package

Consider it when all of the following hold:

• You are already running laravel-admin (encore/laravel-admin) and the address field will live inside its form builder.
• The requirement is internal/admin-side capture of Chinese administrative divisions — not public-facing checkout or autocomplete.
• You accept a low-ceremony, small-surface dependency: MIT-licensed, ~132 stars, no dependents, last release October 2021. The code footprint is small enough to vendor and patch in-house if needed.
• Province/city/district granularity is sufficient; you do not require street-level, postal-code validation, geocoding, or map-pin selection.
• Your team is comfortable owning the data-freshness question separately, either by scheduling periodic data updates or by treating it as an accepted, documented limitation.

Look elsewhere — or build — if:

• You are not on laravel-admin, or you are on a version of it that this unmaintained extension no longer targets. Verify compatibility before committing.
• You need a maintained dependency with active security response; unmaintained front-end assets in an admin panel are a low-but-nonzero risk, and some organizations' policy forbids them outright.
• You need current division data, or region data beyond China (multi-country address forms).
• You need customer-facing UX, mobile-native input, or address validation against a live service.
• Your roadmap already points away from laravel-admin; adding a coupled extension increases migration cost for marginal short-term gain.

How to Pitch It (Stakeholders)

For executives: This is a small, free, MIT-licensed component that lets our existing admin back office capture Chinese province/city/district addresses correctly. It removes a concrete blocker for China-facing operations at effectively zero license cost and roughly a day of integration effort, versus several days to build and maintain the same widget. It is not strategic infrastructure and carries no vendor lock-in beyond the admin framework we already use — the main caveat is that it has not been updated since 2021, so we should assign a named owner for refreshing the region data and be prepared to vendor the code if needed.

For engineering: Treat it as a thin, replaceable form-field adapter, not a platform dependency. Wrap it behind our own form-field class so the widget can be swapped without touching feature code, confirm compatibility with our pinned laravel-admin version in a spike before committing, and add a small scheduled task or documented runbook for updating administrative-division data. Scope it to admin forms only; it is not the answer for storefront address entry.