Algeria Geo Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require kazistm/algeria-geo
   

   Publish the package config (if needed):

   php artisan vendor:publish --provider="Kazistm\AlgeriaGeo\AlgeriaGeoServiceProvider"
   

2. First Use Case Retrieve all Algerian wilayas (provinces):

   use Kazistm\AlgeriaGeo\Facades\AlgeriaGeo;
   
   $wilayas = AlgeriaGeo::wilayas();
   // Returns a collection of all wilayas with IDs, names, and codes.
   

   Fetch communes (municipalities) for a specific wilaya:

   $wilayaId = 1; // Algiers
   $communes = AlgeriaGeo::wilaya($wilayaId)->communes();
   

3. Where to Look First

   • Facade: Kazistm\AlgeriaGeo\Facades\AlgeriaGeo (primary entry point).
   • Service Class: Kazistm\AlgeriaGeo\AlgeriaGeo (for direct instantiation).
   • Data Files: Check vendor/kazistm/algeria-geo/src/Data/ for raw JSON/array structures.

Implementation Patterns

Core Workflows

1. Data Retrieval

   • Wilayas: Get all or filter by ID/name/code.

     $wilayas = AlgeriaGeo::wilayas()->where('code', '16'); // Get only Tizi Ouzou
     

   • Communes: Fetch by wilaya ID or name.

     $communes = AlgeriaGeo::wilaya('Algiers')->communes();
     // or
     $communes = AlgeriaGeo::wilaya(1)->communes()->where('name', 'like', '%Dar%');
     

2. Integration with Eloquent Add a wilaya() accessor to a model (e.g., User):

   public function getWilayaAttribute()
   {
       return AlgeriaGeo::wilaya($this->wilaya_id)->name ?? null;
   }
   

3. Form Validation Validate wilaya/commune inputs:

   use Kazistm\AlgeriaGeo\Rules\ValidWilaya;
   
   $request->validate([
       'wilaya_id' => ['required', new ValidWilaya],
       'commune_id' => ['required', 'exists:communes,id,wilaya_id,'.$request->wilaya_id],
   ]);
   

4. Caching Cache wilayas/communes to reduce DB queries (if storing locally):

   $wilayas = Cache::remember('algeria_wilayas', now()->addHours(1), function () {
       return AlgeriaGeo::wilayas();
   });
   

Advanced Patterns

• Dynamic Select Fields: Generate <select> options for wilayas/communes:

  $options = AlgeriaGeo::wilayas()->pluck('name', 'id')->toArray();
  

• Geospatial Queries: Combine with Laravel Scout or PostGIS for location-based features:

  // Example: Find users near a commune's centroid (requires additional setup).
  

Gotchas and Tips

Pitfalls

1. Data Mutability

   • The package provides read-only data. Avoid modifying the returned collections directly (e.g., ->first()->name = 'New Name'). Clone if needed:

     $wilayaCopy = AlgeriaGeo::wilaya(1)->toArray();
     

2. Case Sensitivity

   • Wilaya/commune names are case-sensitive in comparisons. Normalize inputs:

     $wilaya = AlgeriaGeo::wilayas()->firstWhere('name', strtolower($request->wilaya));
     

3. Missing Data

   • Some communes may lack coordinates or codes. Handle null values:

     $commune = AlgeriaGeo::wilaya(1)->communes()->first();
     $latitude = $commune->latitude ?? 0;
     

4. Performance

   • Avoid eager-loading all wilayas/communes in routes/middleware. Fetch only what’s needed:

     // Bad: Loads all data globally.
     AlgeriaGeo::wilayas();
     
     // Good: Load only for specific requests.
     if ($request->has('wilaya')) { AlgeriaGeo::wilaya($request->wilaya); }
     

Debugging

• Verify Data Integrity: Check if the package’s data matches official sources (e.g., ONS Algeria). Update manually if needed by editing vendor/kazistm/algeria-geo/src/Data/wilayas.php.
• Log Missing IDs: Add a helper to debug invalid IDs:

  function debugAlgeriaGeo($id, $type = 'wilaya')
  {
      $data = $type === 'wilaya'
          ? AlgeriaGeo::wilayas()
          : AlgeriaGeo::wilaya($id)->communes();
      dd($data->pluck('id', 'name'), "ID $id not found in $type data.");
  }
  

Extension Points

1. Custom Data Sources Override the default data provider by binding your own:

   $app->bind(Kazistm\AlgeriaGeo\Contracts\GeoDataProvider::class, function () {
       return new CustomAlgeriaGeoDataProvider();
   });
   

2. Add Metadata Extend the data model by creating a decorator:

   class ExtendedWilaya extends \Kazistm\AlgeriaGeo\Wilaya
   {
       public function region()
       {
           return $this->code >= 27 ? 'East' : 'West';
       }
   }
   

   Then replace the facade binding in AppServiceProvider.
3. Localization Add translated names by extending the Wilaya/Commune classes:

   public function getNameAttribute()
   {
       return app()->getLocale() === 'ar'
           ? $this->attributes['name_ar'] ?? $this->attributes['name']
           : $this->attributes['name'];
   }
   

Config Quirks

• No Config File: The package has no published config. All behavior is hardcoded in the service class.
• Default Locale: Assumes Arabic/Latin names are stored as-is. Override the name attribute if your app uses a different format.