Geotools Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require league/geotools
   

   Add to composer.json:

   "require": {
       "league/geotools": "^0.5"
   }
   

2. Basic Usage:

   use League\Geotools\Geotools;
   use League\Geotools\Coordinate\Coordinate;
   
   $geotools = new Geotools();
   $coordinate = new Coordinate('48.8566, 2.3522'); // Paris
   

3. First Use Case: Calculate distance between two points:

   $paris = new Coordinate('48.8566, 2.3522');
   $london = new Coordinate('51.5074, -0.1278');
   $distance = $geotools->distance($paris, $london, 'km');
   echo $distance; // ~343.5 km
   

Implementation Patterns

Core Workflows

1. Coordinate Handling:

   • Parse diverse formats (DMS, decimal degrees, etc.):

     $coordinate = new Coordinate('48°49′24″N, 2°18′26″E');
     

   • Convert between formats:

     $converted = $geotools->convert($coordinate);
     echo $converted->toDegreesMinutesSeconds();
     

2. Batch Geocoding:

   • Parallel requests with caching:

     $geocoder = new \Geocoder\ProviderAggregator();
     $geocoder->registerProviders([/* ... */]);
     
     $results = $geotools->batch($geocoder)
         ->setCache(new \Cache\Adapter\Filesystem\FilesystemCachePool())
         ->geocode(['Paris', 'London'])
         ->parallel();
     

3. Distance Calculations:

   • Use different algorithms (Haversine, Vincenty):

     $distance = $geotools->distance($paris, $london, 'mi', 'vincenty');
     

4. CLI Integration:

   • Use built-in CLI tools:

     php vendor/bin/geotools distance "48.8566,2.3522" "51.5074,-0.1278" --units=km
     

Laravel-Specific Patterns

1. Service Provider:

   // app/Providers/GeotoolsServiceProvider.php
   public function register()
   {
       $this->app->singleton(Geotools::class, function ($app) {
           return new Geotools();
       });
   }
   

2. Facade:

   // app/Facades/Geotools.php
   public static function distance($coord1, $coord2, $units = 'm', $algorithm = 'haversine')
   {
       return app(Geotools::class)->distance($coord1, $coord2, $units, $algorithm);
   }
   

3. Cached Geocoding:

   // Use Laravel's cache
   $cache = new \League\Geotools\Cache\LaravelCache();
   $geotools->batch($geocoder)->setCache($cache)->geocode(['query']);
   

4. Request Handling:

   • Middleware for geocoding API endpoints:

     public function handle($request, Closure $next)
     {
         $query = $request->input('query');
         $results = app(Geotools::class)->batch($geocoder)->geocode([$query])->serie();
         return response()->json($results);
     }
     

Gotchas and Tips

Pitfalls

1. Provider Limitations:

   • Not all providers support IP geocoding or reverse geocoding. Validate capabilities first:

     if (!$provider->supports('reverse')) {
         throw new \RuntimeException('Provider does not support reverse geocoding');
     }
     

2. Coordinate Normalization:

   • Latitudes are capped (-90 to 90), longitudes wrapped (-180 to 180):

     $coordinate = new Coordinate('91, 181'); // Auto-corrected to 90, -179
     

3. Batch Parallelism:

   • Parallel requests may hit rate limits. Use serie() for controlled execution:

     $results = $geotools->batch($geocoder)->geocode($queries)->serie();
     

4. Ellipsoid Mismatches:

   • Ensure coordinates and ellipsoids align (e.g., WGS84 for most use cases):

     $coordinate = new Coordinate('48.8566, 2.3522', Ellipsoid::WGS84);
     

Debugging Tips

1. CLI for Testing:

   • Use the CLI tools to debug coordinates:

     php vendor/bin/geotools convert "48.8566,2.3522"
     

2. Cache Validation:

   • Clear cache when testing:

     $cache->clear();
     

3. Provider Errors:

   • Handle exceptions gracefully:

     try {
         $results = $geotools->batch($geocoder)->geocode(['invalid']);
     } catch (\Geocoder\Exception\UnsupportedException $e) {
         log::error($e->getMessage());
     }
     

Extension Points

1. Custom Ellipsoids:

   $customEllipsoid = Ellipsoid::createFromArray([
       'name' => 'Custom',
       'a' => 6371000, // Semi-major axis
       'invF' => 298.25
   ]);
   

2. PSR-6 Cache Integration:

   • Implement CacheInterface for custom storage:

     class RedisCache implements CacheInterface {
         public function get($key) { /* ... */ }
         public function set($key, $value, $ttl = null) { /* ... */ }
         public function delete($key) { /* ... */ }
     }
     

3. Distance Algorithm Extensions:

   • Add custom algorithms by extending Distance class:

     class CustomDistance extends \League\Geotools\Distance {
         public function customAlgorithm($coord1, $coord2) { /* ... */ }
     }
     

4. Laravel Events:

   • Dispatch events for geocoding results:

     event(new Geocoded($query, $results));