Laravel Algereography Laravel Package

Product Decisions This Supports

• Algeria market entry / localization epic: decides whether address capture for Algerian users is in-scope for v1 and what granularity we commit to (wilaya → daira → commune). This package settles the top two levels immediately.
• Build vs. buy for reference data: replaces an internal workstream of "source, normalize, de-duplicate, and seed the 58 wilayas and their dairas." The 58-wilaya structure reflects the post-2019 reform (up from 48), so it also saves us from shipping an outdated list.
• Checkout and onboarding form design: enables province/district dropdowns backed by FK relations instead of free-text fields, which reduces invalid addresses, failed deliveries, and manual cleanup in support.
• Delivery & logistics zoning: dairas are a natural unit for coverage rules, delivery-fee tiers, and "do we serve this area" checks — useful input for pricing and ops scoping.
• Analytics and reporting segmentation: wilaya becomes a first-class dimension for demand, churn, and conversion reporting without a data-cleaning side project.
• Schema/dependency decisions: commits us to two lookup tables plus FK columns on user/order/address tables, which is the cheaper long-term shape versus a denormalized string field.
• Roadmap sequencing: a maintained package materially lowers the cost estimate for the Algeria launch, which can move it up the priority list relative to other market expansions.

When to Consider This Package

Adopt when:

• We are on Laravel/PHP and want migrations, seeders, and Eloquent models rather than an external geo API.
• Wilaya + daira granularity is genuinely sufficient for the first release (address forms, coverage checks, reporting).
• We want a small, auditable dataset (~58 wilayas, roughly 550 dairas) that is cheap to inspect, fork, and vendor into our own repo.
• Delivery timeline matters more than data provenance — the package gets us a canonical seed on day one.

Look elsewhere or plan to extend when:

• We need communes (the ~1,541 third-level units) or postal codes — this package stops at dairas, and that gap will surface the moment a courier integration asks for a commune.
• We need geospatial data: polygons, centroids, lat/long, or map boundaries for radius/distance logic.
• We need curated multilingual labels (Arabic / Tamazight / French) or romanized/standardized spellings — validate the seeded strings against our UX copy before committing.
• We are multi-country. A country-specific package multiplies into N packages; a general geo provider or Places API is the better architectural bet.
• We are not on Laravel, or we want a hosted, versioned data service with an SLA.
• Maintenance risk is unacceptable. Single maintainer, 53 stars, last release February 2023. Treat this as "vendored data with a friendly installer," not a supported dependency — fork the seeder, keep it in-repo, and own updates.

How to Pitch It (Stakeholders)

For executives: This is a free, MIT-licensed building block that removes a data-sourcing task from the critical path of our Algeria launch. It gives us the official 58-wilaya structure and district-level breakdown out of the box, which means cleaner address capture, fewer failed deliveries, and region-level reporting from day one — without us researching, cleaning, and maintaining that list ourselves. The total risk is small: the dataset is only a few hundred rows, so if the project goes quiet we fork it in an afternoon. The one caveat to budget for is that it does not include commune-level data or postal codes; if a courier or compliance requirement lands there, that is a scoped follow-on, not a blocker.

For engineering: Drop-in migrations, seeders, and Eloquent models for wilayas and dairas with the relations already wired — roughly a few days of sourcing, normalizing, and QA we do not have to spend. Two asks before we merge it: (1) diff the seeded daira list against an authoritative source and pin the version in our repo rather than depending on upstream dev-main; (2) confirm the label encoding and language of the seeded names match our form copy. We should vendor the seeder as our own migration so an abandoned upstream never blocks a deploy, and leave the address schema extensible to a commune_id FK so the third level can be added without a rewrite.