Gis.ph Sdk Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require yahaaylabs/gis.ph-sdk-php
   

   Add the SDK to your config/services.php:

   'gisph' => [
       'api_key' => env('GISPH_API_KEY'),
       'base_url' => env('GISPH_BASE_URL', 'https://api.gis.ph/v1'),
   ],
   

2. First Use Case: Fetching a Location Inject the SDK into a service/controller:

   use YahaayLabs\GisPhSdk\GisPhClient;
   
   public function __construct(protected GisPhClient $gisPh)
   {
   }
   
   public function getLocation($address)
   {
       return $this->gisPh->geocode($address);
   }
   

3. Environment Variables Add to .env:

   GISPH_API_KEY=your_api_key_here
   

Implementation Patterns

Common Workflows

1. Geocoding (Address → Coordinates)

   $response = $gisPh->geocode('123 Main St, Manila');
   $latitude = $response->getLatitude();
   $longitude = $response->getLongitude();
   

2. Reverse Geocoding (Coordinates → Address)

   $response = $gisPh->reverseGeocode(14.5995, 120.9842);
   $formattedAddress = $response->getFormattedAddress();
   

3. Distance Matrix (Between Locations)

   $origins = ['123 Main St, Manila', '456 Binondo St, Manila'];
   $destinations = ['789 Makati Ave, Makati'];
   $matrix = $gisPh->distanceMatrix($origins, $destinations);
   

4. Integration with Eloquent Models

   use Illuminate\Database\Eloquent\Model;
   use YahaayLabs\GisPhSdk\GisPhClient;
   
   class Store extends Model
   {
       public function __construct(array $attributes = [])
       {
           parent::__construct($attributes);
           $this->gisPh = app(GisPhClient::class);
       }
   
       public function getCoordinatesAttribute()
       {
           $response = $this->gisPh->geocode($this->address);
           return [
               'lat' => $response->getLatitude(),
               'lng' => $response->getLongitude(),
           ];
       }
   }
   

5. Batch Processing

   $addresses = ['Address 1', 'Address 2', 'Address 3'];
   $results = collect($addresses)->map(fn($addr) => $gisPh->geocode($addr));
   

Error Handling

Wrap API calls in a try-catch:

try {
    $response = $gisPh->geocode($address);
} catch (\YahaayLabs\GisPhSdk\Exceptions\GisPhException $e) {
    Log::error('GISPH Error: ' . $e->getMessage());
    return response()->json(['error' => 'Location not found'], 404);
}

Gotchas and Tips

Pitfalls

1. Rate Limiting

   • The SDK does not auto-retry on rate limits. Implement exponential backoff in your service layer:

     $retryCount = 0;
     while ($retryCount < 3) {
         try {
             return $gisPh->geocode($address);
         } catch (\YahaayLabs\GisPhSdk\Exceptions\RateLimitException $e) {
             sleep(2 ** $retryCount);
             $retryCount++;
         }
     }
     

2. API Key Leaks

   • Never expose GISPH_API_KEY in client-side code. Use Laravel's Sanctum or Passport for secure API access if needed.

3. Floating-Point Precision

   • Coordinates may return values like 14.5995123456789. Round for storage:

     $roundedLat = round($response->getLatitude(), 6);
     

4. Timeouts

   • Default HTTP client timeout (30s) may be too short for slow responses. Configure in config/services.php:

     'gisph' => [
         'timeout' => 60, // seconds
     ],
     

Debugging

1. Enable Debug Mode Set debug: true in config/services.php to log raw API responses:

   'gisph' => [
       'debug' => env('GISPH_DEBUG', false),
   ],
   

2. Mocking for Tests Use Laravel's HTTP mocking:

   $mock = Mockery::mock('overload:' . GisPhClient::class);
   $mock->shouldReceive('geocode')
        ->with('123 Main St')
        ->andReturn(new GisPhResponse(14.5995, 120.9842));
   

Extension Points

1. Custom Response Handling Extend the base response class:

   namespace App\Services;
   
   use YahaayLabs\GisPhSdk\GisPhResponse;
   
   class CustomGisPhResponse extends GisPhResponse
   {
       public function getBarangay()
       {
           return $this->getComponents()['barangay'] ?? null;
       }
   }
   

   Override the SDK's response factory in a service provider:

   public function register()
   {
       $this->app->bind(GisPhResponse::class, CustomGisPhResponse::class);
   }
   

2. Caching Responses Cache geocoding results for 1 hour:

   public function getCoordinates($address)
   {
       return Cache::remember("gisph_{$address}", now()->addHours(1), function() use ($address) {
           return $this->gisPh->geocode($address);
       });
   }
   

3. Fallback Mechanisms Combine with other APIs (e.g., Google Maps) if GIS.PH fails:

   public function resolveLocation($address)
   {
       try {
           return $this->gisPh->geocode($address);
       } catch (\Exception $e) {
           return $this->fallbackGeocoder->geocode($address);
       }
   }