Geolocation Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require 1001pharmacies/geolocation-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Meup\GeoLocationBundle\MeupGeoLocationBundle::class => ['all' => true],
   ];
   

2. Configuration: Publish the default config:

   php artisan vendor:publish --tag=meup-geolocation-config
   

   Edit config/meup_geolocation.php to enable your preferred provider (e.g., google, nominatim) and set API keys.

3. First Use Case: Locate coordinates from an address:

   use Meup\GeoLocationBundle\Factory\AddressFactory;
   use Meup\GeoLocationBundle\Locator\LocatorInterface;
   
   $addressFactory = $this->container->get(AddressFactory::class);
   $locator = $this->container->get(Locator::class);
   
   $address = $addressFactory->create()->setFullAddress('1600 Amphitheatre Parkway, Mountain View, CA');
   $coordinates = $locator->locate($address);
   
   // Output: Latitude/Longitude (e.g., 37.4220, -122.0841)
   

Implementation Patterns

Core Workflows

1. Address Creation & Validation: Use AddressFactory to create structured addresses:

   $address = $addressFactory->create()
       ->setStreet('123 Main St')
       ->setPostalCode('90210')
       ->setCity('Los Angeles')
       ->setCountry('US');
   

   Validate with:

   if (!$address->isValid()) {
       throw new \InvalidArgumentException('Invalid address');
   }
   

2. Provider-Specific Logic:

   • Fallback Chaining: Configure multiple providers in config/meup_geolocation.php under providers to enable fallback logic:

     providers:
         - { id: google, enabled: true }
         - { id: nominatim, enabled: true, fallback: true }
     

   • Rate Limiting: Use cache settings to avoid hitting API limits:

     cache:
         enabled: true
         ttl: 3600  # Cache results for 1 hour
     

3. Reverse Geocoding: Convert coordinates to addresses:

   $reverseLocator = $this->container->get('meup_geo_location.reverse_locator');
   $address = $reverseLocator->locate(37.4220, -122.0841);
   

4. Batch Processing: Process multiple addresses efficiently:

   $batchLocator = $this->container->get('meup_geo_location.batch_locator');
   $results = $batchLocator->locate([
       $address1, $address2, $address3
   ]);
   

Integration Tips

• Symfony Forms: Bind address fields to a Meup\GeoLocationBundle\Form\Type\AddressType for user input.
• Doctrine Entities: Use Meup\GeoLocationBundle\Doctrine\Types\CoordinatesType for storing lat/lng in databases.
• Event Listeners: Extend functionality via events (e.g., meup_geolocation.locate):

  $dispatcher->addListener('meup_geolocation.locate', function ($event) {
      // Pre/post-process locate requests
  });
  

Gotchas and Tips

Common Pitfalls

1. API Key Management:

   • Never hardcode API keys in config. Use environment variables (e.g., .env):

     MEUP_GEOLOCATION_GOOGLE_API_KEY=your_key_here
     

   • Rotate keys periodically and clear the cache (php artisan cache:clear) after changes.

2. Rate Limits & Quotas:

   • Free tiers (e.g., Nominatim, Google Maps) have strict limits. Monitor usage via provider dashboards.
   • Implement exponential backoff for retries:

     $locator->setRetryStrategy(new \Meup\GeoLocationBundle\Retry\ExponentialBackoff());
     

3. Time Zone & Caching:

   • Cache TTLs (e.g., ttl: 3600) may cause stale data. Adjust based on use case (e.g., shorter TTL for dynamic data).
   • Time zones in addresses can affect geocoding accuracy. Standardize formats (e.g., ISO 8601).

4. Provider-Specific Quirks:

   • Google: Requires billing setup for production use. Use components (e.g., street_number, route) for better accuracy.
   • Nominatim: Free but rate-limited. Use https://nominatim.openstreetmap.org/ for testing; switch to a dedicated instance for production.
   • Bing/MapQuest: May return results in different coordinate systems (e.g., WGS84 vs. custom). Normalize with:

     $coordinates->toWgs84();
     

5. Dependency Injection:

   • Avoid tight coupling by injecting interfaces (LocatorInterface, ReverseLocatorInterface) instead of concrete services.

Debugging Tips

• Enable Logging:

  # config/meup_geolocation.php
  logging: true
  

  Logs appear in var/log/meup_geolocation.log.

• Validate Addresses: Use Address::isValid() to catch malformed inputs early. For custom validation, extend Meup\GeoLocationBundle\Validator\AddressValidator.

• Mock Providers for Testing: Create a custom provider (see Custom Provider Docs) to return mock responses:

  class MockProvider implements ProviderInterface {
      public function locate(Address $address) {
          return new Coordinates(0, 0); // Mock response
      }
  }
  

Extension Points

1. Custom Providers: Implement Meup\GeoLocationBundle\Provider\ProviderInterface and register via config:

   providers:
       - { id: custom, class: App\Provider\CustomProvider, enabled: true }
   

2. Address Components: Extend Meup\GeoLocationBundle\Model\Address to add custom fields (e.g., setFloor, setUnit).

3. Coordinate Transformations: Add custom transformations by implementing Meup\GeoLocationBundle\Transformer\CoordinateTransformerInterface.

4. Event Subscribers: Listen for meup_geolocation.locate or meup_geolocation.reverse_locate to intercept or modify requests/responses.