Laravel Algerian States Laravel Package

Product Decisions This Supports

• Build vs. buy for geo reference data. Algeria's wilaya (province) list is small, canonical, and periodically amended (48 → 58 wilayas in 2019, plus code reassignments). This package answers the recurring "do we maintain our own seeder or lean on a community list?" question — the answer is usually "lean on one, but wrap it."
• Address/checkout design for the Algerian market. Decides whether wilaya appears in onboarding, address forms, delivery estimates, or KYC flows, and in what shape.
• Data modeling for addresses and shipping. v2.0.0's Sushi dependency means provinces are exposed as a real Eloquent model, so you can now make belongsTo/hasMany relationships and where/pluck/find queries against reference data with no migration. That materially changes the "store province as a string, an int code, or a foreign key?" decision in favor of a keyed reference — a decision that is expensive to reverse once addresses and orders depend on it.
• Roadmap inputs. Whether to invest in commune/daira coverage (1,541 communes — a much bigger dataset than 58 wilayas), postal codes, or multi-country expansion.
• Concrete use cases to scope: e-commerce/delivery address capture, shipping-zone pricing tables, ride-hailing and logistics routing regions, tax/regulatory reporting grouped by wilaya, admin filters, and analytics segmentation by region.
• Packaging decisions. Sushi-backed read-only data can ship inside a package or a multi-tenant context without schema changes, which matters if you distribute modules or run per-tenant databases.

When to Consider This Package

Adopt when:

• Algeria is a real, funded market and you need wilaya data with codes matching official numbering.
• You want Eloquent ergonomics over static reference data without a table, migration, or seeder.
• The data is strictly read-only and small (tens to low thousands of rows — well within Sushi's comfortable range).

Look elsewhere when:

• You need to write to the province list (admin editing, custom ordering, soft deletes). Sushi models are file-backed; use a real table plus a seeder.
• You need global coverage (countries, states, cities) or commune/postal-code granularity at scale. Verify actual commune coverage before committing — 58 wilayas is a much smaller promise than a full address dataset.
• You already have a geo table or multi-country ambitions. Consistency across markets beats one country-specific package.
• You need geospatial features (polygons, boundaries, distance queries). This is reference data, not a geo service.

Specific to v2.0.0: this is a major version bump that introduces a hard dependency on calebporzio/sushi. If you are on 1.0.0, treat it as a migration, not a patch — verify model class names and public API, and confirm nothing in your code relies on behavior Sushi-backed models don't support (no create, no migrations, no insert). If you haven't adopted it yet, start at 2.0.0 directly. Either way, wrap it behind your own repository/adapter so the underlying source can be swapped later without touching call sites.

How to Pitch It (Stakeholders)

This is a small, single-purpose open-source Laravel package that supplies the official Algerian wilaya (province) list as Eloquent-readable reference data. The v2.0.0 release rebuilds it on calebporzio/sushi, so the data is served from a bundled file through a normal Eloquent model — no database table, no migration, but full query and relationship support. For us, that means we can add a correct, officially numbered province picker to Algerian address flows in hours rather than a sprint, and we can key addresses and shipping rules to a stable wilaya code instead of a free-text string. Risks are modest but real: it is maintained by a single author, the data is read-only (any admin editing requires our own table), and the 2.0 release is a breaking change with a new transitive dependency, so any upgrade needs a quick API check. Recommendation: adopt only if Algeria is a committed market, wrap it behind our own adapter so we can swap to an internal table or a broader dataset later, and revisit if we expand to communes, postal codes, or additional countries.