Laravel Algeria Laravel Package

Product Decisions This Supports

• Build vs. buy for Algerian geographic data: v1.2.0 ships verified latitude/longitude for all 1,541 communes (cross-checked across Wikidata, kossa/algerian-cities, geoalgeria, plus manual corrections). This removes the main reason to buy a commercial MENA dataset or stand up an internal geocoding pipeline just to get commune centroids.
• Location-aware feature bets: Algeria::nearest(), Algeria::distance(), and Commune::distanceTo() make proximity a first-class product primitive — store/branch locator, "nearest agency," delivery-zone assignment, courier dispatch, and serviceability checks at checkout.
• Shipping and pricing logic: distance-based delivery fees or coverage radius rules can be computed in-database instead of calling a paid geocoding/routing vendor per request. That is a direct variable-cost reduction and a simpler unit-economics story for a pricing experiment.
• Roadmap sequencing: the new GET /api/algeria/communes/nearest?lat=&lng=&limit= endpoint is a ready-made contract for mobile and partner integrations. It lets you ship a geo capability to clients without designing a new API surface first, and it is a plausible standalone differentiator for B2B/partner deals.
• Data governance and procurement: THIRD-PARTY-NOTICES.md gives legal and procurement a licensable trail for the data sources. This is the artifact that unblocks signing off on "we own/redistribute this dataset" questions, which typically stalls geo features late.
• Deployment/runbook decisions: the release requires php artisan migrate followed by php artisan algeria:seed. That is an additive change, but it makes seeding a hard dependency of the release — a scheduling and rollback decision for the PM, not just engineering.

When to Consider This Package

Adopt when:

• The product is Algeria-focused, or Algeria is the next market, and you need wilaya/commune reference data without building or licensing it.
• You want proximity features that work without an external maps/geocoding vendor on the request path — in-database distance, no per-call API spend, no third-party uptime dependency.
• You are on Laravel and your team is already comfortable with migrations and seeders in the deploy pipeline (the v1.1.0 → v1.2.0 path is composer update → migrate → algeria:seed).
• You need centroid-level accuracy: "which commune is this point in / near," coverage checks, store lookup, regional analytics.

Look elsewhere when:

• You need multi-country coverage — this is a single-country dataset.
• You need arbitrary address geocoding or autocomplete (street-level, building-level). This package gives commune centroids, not an address parser.
• You need polygons/boundaries rather than points, or point-in-polygon containment.
• You need driving distance, travel time, or routing. distance() is straight-line; anything logistics-grade needs a routing engine.
• You need survey-grade precision or a contractual SLA on the data — provenance here is community and open sources, cross-validated but not a licensed commercial feed.
• Your deploy process cannot run seeders safely (e.g. no idempotent-seed guarantee in your environment), since the upgrade explicitly depends on it.

How to Pitch It (Stakeholders)

To executives: This release turns a static reference list into a location engine. We now have verified coordinates for every commune in Algeria and can answer "what's nearest / how far" inside our own database — no new vendor contract, no per-request geocoding fees, and a documented license trail for the source data. It unlocks store locator, distance-based delivery pricing, and partner geo-APIs as near-term roadmap items rather than new budget lines. Low risk: the upgrade is additive and requires one migration plus a reseed.

To engineering: v1.2.0 is a non-breaking, additive upgrade from v1.1.0. It adds latitude/longitude columns to communes via a new migration, three distance helpers (Algeria::nearest(), Algeria::distance(), Commune::distanceTo()), and a new public route GET /api/algeria/communes/nearest?lat=&lng=&limit=. Upgrade is composer update → php artisan migrate → php artisan algeria:seed. Two things to plan for: the seeder is now a release dependency (put it in the runbook, verify idempotency in staging, and check rollback), and distance is great-circle, not routing — if we later need travel time, that is a separate integration. The API route also needs the usual treatment for rate limiting, input validation on lat/lng/limit, and caching.