Geobundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require e-commerce-tetradka/geobundle
   

   Publish the configuration (if available):

   php artisan vendor:publish --provider="Nitra\GeoBundle\GeoBundleServiceProvider"
   

2. Service Provider & Facade Ensure the service provider is registered in config/app.php under providers:

   Nitra\GeoBundle\GeoBundleServiceProvider::class,
   

   Use the facade for quick access:

   use Nitra\GeoBundle\Facades\GeoBundle;
   

3. First Use Case: Geo Data Sync Sync a basic geographic dataset (e.g., countries, regions, or cities) via CLI:

   php artisan geo:sync --type=countries
   

   Verify sync status in the database (check geo_* tables).

Implementation Patterns

Workflows

1. Data Synchronization

   • Scheduled Syncs: Use Laravel’s task scheduling (app/Console/Kernel.php) to run syncs periodically:

     $schedule->command('geo:sync')->dailyAt('2:00');
     

   • Custom Sync Logic: Extend the sync process by creating a custom command:

     php artisan make:command CustomGeoSync
     

     Override handle() to integrate with your workflow:

     public function handle() {
         GeoBundle::sync('custom_regions', ['source' => 'your_api']);
     }
     

2. API Integration

   • Fetch external geo data (e.g., from OpenStreetMap or a custom API) and transform it:

     $response = Http::get('https://api.example.com/geo');
     $data = GeoBundle::transform($response->json(), 'cities');
     GeoBundle::store($data);
     

3. Querying Geo Data

   • Use Eloquent models (if provided) or query builder:

     $regions = GeoBundle::getRegionsByCountry('US');
     $coordinates = GeoBundle::getCoordinates('New York');
     

Integration Tips

• Laravel Scout: Index geo data for fast searches:

  GeoBundle::indexWithScout('cities');
  

• Laravel Echo/Pusher: Push real-time geo updates to clients:

  GeoBundle::onUpdate(function ($data) {
      broadcast(new GeoUpdated($data))->toOthers();
  });
  

• API Resources: Format geo data for APIs:

  GeoBundle::setResource('CityResource');
  

Gotchas and Tips

Pitfalls

1. Database Conflicts

   • Avoid duplicate entries during syncs. Use upsert or unique constraints:

     GeoBundle::sync('countries', ['upsert' => true]);
     

   • Check for existing data before syncing:

     if (!GeoBundle::exists('countries')) {
         GeoBundle::sync('countries');
     }
     

2. Rate Limiting

   • External APIs may throttle requests. Implement retries with exponential backoff:

     GeoBundle::setRetryPolicy(5, 1000); // Retry 5 times with 1s delay
     

3. Time Zones

   • Ensure time-sensitive operations (e.g., sync scheduling) account for timezone differences:

     $schedule->command('geo:sync')->timezone('America/New_York');
     

Debugging

• Log Syncs: Enable verbose logging for sync operations:

  php artisan geo:sync --verbose
  

• Check Config: Validate config/geobundle.php for correct API keys, endpoints, and cache settings.
• Test Locally: Use a staging database to test syncs before production:

  php artisan geo:sync --env=staging
  

Extension Points

1. Custom Data Sources

   • Override the default data source by binding a custom provider:

     GeoBundle::extend('custom_source', function () {
         return new CustomGeoProvider();
     });
     

2. Transformers

   • Create custom transformers for non-standard data formats:

     GeoBundle::transformer('custom_format', CustomTransformer::class);
     

3. Events

   • Listen for geo data events (e.g., GeoSynced, GeoUpdated):

     GeoBundle::onSync(function ($type) {
         Log::info("Synced {$type} data");
     });
     

4. Caching

   • Cache frequently accessed geo data to reduce DB load:

     GeoBundle::cache('regions', 3600); // Cache for 1 hour