Provinces Laravel Package

Technical Evaluation

Architecture fit The package is a thin reference-data provider: a Laravel service provider that registers models, migrations, seeders, and (likely) config for Afghanistan's 34 provinces and ~400 districts. There is no runtime logic, no external service dependency, and no meaningful coupling surface. That makes it an unusually clean architectural fit — it slots in as a read-mostly lookup table alongside existing address, user-profile, or logistics models. The real question is not "does it fit" but "do we want a third-party package owning a table our domain models will foreign-key into," which is a data-ownership decision, not an architecture one.

Integration feasibility Low effort. Standard composer require, publish config/migrations, php artisan migrate --seed, then relate via belongsTo. Expect an afternoon for a spike and one to two days to productionize, dominated not by code but by deciding whether to store province/district IDs, ISO codes, or names as the canonical key in our own tables. The 0-dependent count means we will be the first real consumer exercising the migration path in anger — budget time for reading the source rather than the README.

Technical risk

• Code risk: minimal; small, auditable, no I/O or network calls.
• Supply-chain risk: high relative to value. Nine stars, zero dependents, and what appears to be a single-maintainer organization. Abandonment is the default assumption, not the tail case.
• Metadata anomaly: a last-release date of 2026-10-21 postdates this review and should be treated as a registry or tagging error until verified against the actual Git history and Packagist.
• Data accuracy: administrative geography in Afghanistan is politically and practically contested — district counts, provincial naming conventions, and Dari/Pashto transliterations vary by source. If the package ships no provenance for its dataset, we inherit an unverifiable ground truth.
• Licensing: unconfirmed; must be checked before any redistribution of the dataset inside our own product.

Key questions

1. What is the license, and does it permit redistribution of the dataset in our shipped artifacts?
2. What is the upstream source of the province/district data, and how is it refreshed when administrative boundaries change?
3. Are primary keys stable across releases, or can a district ID be reassigned?
4. Which Laravel and PHP versions are supported, and is there a test matrix?
5. Do the migrations create tables or modify existing ones, and are seeders idempotent or truncating?
6. Are native-language names, ISO 3166-2 codes, and coordinates included, or English labels only?
7. Is the 2026-10-21 release date a tagging/registry artifact?

Integration Approach

Stack fit Assumes a conventional Laravel application with Eloquent and migrations. If we are on a non-Laravel PHP stack, on a read-only replica, or on an event-sourced schema where reference data must be versioned rather than mutated, the fit degrades quickly and we should consume the raw dataset rather than the package.

Migration path Recommend a two-step adoption: first, install the package unmodified in a scratch branch and reverse-engineer its schema and seed payload. Second, fork or vendor the migrations and seed data into our own database/ tree and drop the dependency. Given the trivial code volume and the abandonment risk, vendoring is the correct end state for anything beyond a prototype — we keep the dataset, lose the maintenance exposure, and gain the ability to add fields we need (coordinates, native names, effective-from dates) without upstreaming.

Compatibility Verify PHP and Laravel constraint ranges against our current version before spiking. Non-Latin scripts in province and district names mean we must confirm utf8mb4 collation end-to-end — database, connection, and any search index — or Dari/Pashto labels will corrupt silently. Check whether IDs are auto-increment integers or fixed codes; the latter is far better for cross-environment consistency and for seeding idempotency.

Sequencing

1. License and provenance check (blocking gate).
2. Spike: install, migrate, seed in a disposable database; dump and inspect the schema.
3. Domain decision: which column do our models foreign-key to, and do we store a snapshot of the name alongside the ID?
4. Vendor the migrations and dataset into our repo; remove the composer dependency.
5. Seed staging and production via our standard seeding pipeline, not the package's.
6. Add a CI assertion on row counts (34 provinces, expected district count) so silent dataset regressions fail the build.
7. Only revisit upstream tracking if the maintainer demonstrates a real refresh cadence.

Operational Impact

Maintenance Near-zero steady state once vendored — it is a static table that changes only when Afghanistan's administrative geography changes, which is infrequent but not never. The maintenance burden shifts from "upgrade the package" to "occasionally re-validate the dataset," which we control. Keeping the package as a live dependency is the higher-maintenance option, because we would be tracking releases from an unproven maintainer with no leverage to get fixes merged.

Support No commercial support, no SLA, no security response process. Acceptable only because the blast radius is a static lookup table. If our product depends on address validation for real users in Afghanistan, the support gap belongs to us, not to the vendor.

Scaling Negligible — hundreds of rows, cacheable in full at boot or in Redis, no query pressure. The only scaling consideration is read amplification if every request joins to district names; denormalizing the display name onto our own records removes that entirely.

Failure modes

• Silent data drift: upstream renames a district; our stored IDs still resolve but labels diverge from what users expect.
• Seeder non-idempotency: re-running seeds either truncates and breaks foreign keys or duplicates rows.
• Encoding corruption: latin1 collation mangles native-language names at insert without erroring.
• Package abandonment: no updates, but also no breakage — the failure is quiet and non-urgent.
• Unstable IDs: if upstream renumbers, historical records point at the wrong district. This is the one genuinely damaging scenario and is fully mitigated by vendoring plus snapshotting the name at write time.

Ramp-up Trivial for any Laravel developer — an hour to read the source and understand the schema. The real ramp-up cost is domain knowledge: someone on the team needs to own the question of what the authoritative Afghan administrative dataset is, and that is a research task, not an engineering one. Assign that owner before integration, not after.