Laravel Algerian Provinces Laravel Package

Product Decisions This Supports

• Market entry & localization for Algeria: Ships the canonical 58-wilaya list so checkout, KYC, dealer/territory assignment, and delivery-zone flows can go live without your team owning an administrative geography dataset.
• Build vs. buy on reference data: Replaces a small but nagging internal chore (maintaining province codes/names, and the 2019 48→58 split) with a composer dependency. Low cost, low lock-in, but it is reference data your business logic will quietly depend on.
• Roadmap pattern for MENA expansion: Establishes a reusable convention ("one geography package per country, model-backed") that you can repeat for Morocco/Tunisia/Egypt, or consciously reject in favor of a single internal geography service.
• MVP vs. scale tradeoff — changed by v2.0.0: The move to calebporzio/sushi means the package is now a static, read-only Eloquent model with no migration and no table. This is a genuine product-level change, not a cosmetic one:
  • Pro: near-zero install friction; ideal for prototypes, single-tenant apps, and fast market tests. No seed step, no migration ordering issues, nothing to provision.
  • Con: you can no longer JOIN provinces in SQL for reporting, enforce a real foreign key from orders.wilaya_id/users.wilaya_id, or let ops edit/translate province names per tenant or per locale without forking. Any analytics or BI work that expects a provinces table now needs an in-PHP join or a replicated lookup table you maintain yourself.
• Reporting & finance: If revenue-by-region, shipping-cost-by-wilaya, or territory dashboards are on the roadmap, decide now whether static-in-code geography is acceptable or whether you need a first-class table. This is the main decision v2.0.0 forces.
• Admin/product configurability: Rules out "let admins manage provinces, delivery zones per wilaya, or Arabic/French name overrides" as a built-in capability; budget that as custom work on top.

When to Consider This Package

Adopt when:

• You're a Laravel app launching or operating in Algeria and need a correct, low-effort wilaya dropdown/list.
• Geography is reference data only — display, filtering, form input — and not a join target for reporting or a foreign-key anchor.
• You want zero migration/seed overhead (v2.0.0's Sushi-based model is genuinely the fastest path to a working province selector).
• You're comfortable with a thin, single-maintainer package plus a transitive dependency on calebporzio/sushi (widely used, but a read-only static-model shim with known limits on querying/serialization).

Look elsewhere or build your own table when:

• You need communes/dairas, postal codes, Arabic/French/Latin name variants, or geo shapes — this package is province-level only.
• You need belongs_to-style FK integrity from users/orders, or SQL-level aggregation by wilaya (v2.0.0's static model makes this awkward; v1.x's table-based approach did not).
• Ops or per-tenant customization of names, ordering, or activation is a requirement.
• You need SLAs, data-freshness guarantees, or a documented upgrade path — v2.0.0 is a breaking change ("depending on sushi") with no migration guide, so plan for it as a one-way door.

How to Pitch It (Stakeholders)

To executives: This is a small, free building block that removes a recurring data-maintenance chore for our Algeria launch — the official 58-province list, ready to drop into address and delivery flows. Cost is effectively zero and time-to-first-screen is hours, not days. The tradeoff to sign off on: as of v2.0.0 the data lives in application code rather than our database, which is perfect for a fast launch but means regional reporting and per-market customization would need custom work. Approve it as a launch accelerator, not as the permanent foundation of our geography/reporting model.

To engineering: composer require elaborate-code/laravel-algerian-provinces and you get a province model with no migration and no seeder — v2.0.0 delegates to calebporzio/sushi, so the data is a static, read-only Eloquent source. Treat it as a breaking upgrade from 1.x: if anything currently references a provinces table or FK, that assumption is gone. Pin the version, wrap it behind our own ProvinceRepository/enum so we can swap to a real table later without touching call sites, and don't build SQL joins or admin CRUD against it.