Google Places Api Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Laravel-Native Integration: The package is explicitly designed for Laravel (v10/11/12/13) with a published config file, reducing boilerplate and aligning with Laravel’s service container and configuration patterns.
  • Dual API Support: Supports both Places API (Original) and Places API (New), allowing gradual migration to Google’s newer endpoints without rewriting logic.
  • Saloon Backend: Built on Saloon, a modern HTTP client for Laravel, ensuring clean request/response handling, retries, and middleware support (e.g., rate limiting, logging).
  • Field-Level Control: Enables granular field selection (e.g., fields=['name', 'rating']) to optimize payload size and reduce API costs.
  • Response Flexibility: Returns Saloon Response objects, compatible with Laravel’s collect(), json(), or raw arrays, and supports custom headers/SSL settings.

• Cons:

  • Breaking Changes in v3: The rewrite introduces incompatibilities with v2.x, requiring a migration effort (though backward compatibility is maintained until the next major release).
  • Google API Dependency: Tight coupling to Google’s Places API means changes in their endpoints/quota limits may require package updates.
  • No Built-in Caching: Requires manual caching (e.g., Laravel’s Cache facade) for frequent or expensive queries.

Integration Feasibility

• Laravel Ecosystem Fit:
  • Seamless integration via service provider and config publishing.
  • Supports dependency injection (e.g., bind GooglePlaces to the container in AppServiceProvider).
  • Works with Laravel’s queue/job system for async API calls (e.g., GooglePlaces::dispatch()->nearbySearch(...)).
• Third-Party Compatibility:
  • Compatible with Laravel Scout (for geospatial search) or custom geocoding pipelines.
  • Can integrate with packages like spatie/laravel-geocoder for hybrid geocoding workflows.
• Testing:
  • Mockable via Saloon’s MockClient or Laravel’s HTTP tests.
  • Supports API key rotation via config or environment variables.

Technical Risk

• Migration Risk:
  • v2 → v3: Requires updating method signatures (e.g., nearbySearch(lat,lng,radius) vs. nearbySearch('lat,lng')). Use a feature flag or adapter pattern to phase out v2.
  • Google API Deprecations: Monitor Google’s deprecation schedule for proactive updates.
• Performance:
  • Rate Limits: Google’s Places API has usage limits (e.g., 40 queries/sec). Implement retries with exponential backoff (Saloon supports this).
  • Payload Size: Large field sets (e.g., fields=['*']) increase response size. Optimize with minimal fields.
• Security:
  • API Key Exposure: Keys should be stored in .env (not config) and restricted via Google Cloud IAM.
  • SSL Verification: Disable only in development (verifySSL: false).

Key Questions

1. API Key Management:
   • How will API keys be rotated/revoked? (Use Laravel’s config('services.google.key') + environment variables.)
2. Error Handling:
   • Should errors (e.g., quota exceeded) trigger Laravel’s Reportable exceptions or be logged silently?
3. Caching Strategy:
   • Will responses be cached? If so, use Cache::remember() or Redis with TTLs (e.g., 1 hour for autocomplete).
4. Testing:
   • Will integration tests mock Google’s API or use a test key with a sandbox environment?
5. Cost Optimization:
   • Are there plans to implement request deduplication (e.g., cache identical queries)?
6. Monitoring:
   • How will API usage/errors be monitored? (Use Laravel’s Log::channel('google') or a dedicated queue worker.)

Integration Approach

Stack Fit

• Laravel Core:
  • Service Provider: Publish the config file (php artisan vendor:publish --provider="SKAgarwal\GoogleApi\ServiceProvider") and bind the client to the container:

    $this->app->singleton(GooglePlaces::class, function ($app) {
        return GooglePlaces::make(config('services.google.key'));
    });
    

  • Config: Store API key, SSL settings, and default headers in config/google.php:

    'key' => env('GOOGLE_PLACES_API_KEY'),
    'verify_ssl' => env('APP_ENV') !== 'local',
    'headers' => [
        'Accept' => 'application/json',
    ],
    

• Saloon Integration:
  • Leverage Saloon’s connections for shared configurations (e.g., retry logic):

    GooglePlaces::connection('google')->withHeaders(['X-Custom-Header' => 'value']);
    

  • Use request macros for reusable query builders:

    GooglePlaces::macro('searchRestaurants', function ($lat, $lng) {
        return $this->nearbySearch($lat, $lng, 500, ['type' => 'restaurant']);
    });
    

Migration Path

1. Assessment Phase:
   • Audit existing Places API usage (v2 vs. v3 methods).
   • Identify high-priority endpoints (e.g., autocomplete, nearby search).
2. Pilot Migration:
   • Update a single feature (e.g., address autocomplete) to v3, using a feature flag:

     if (config('features.use_google_places_v3')) {
         return GooglePlaces::make()->autocomplete($query);
     }
     return GooglePlacesLegacy::make()->placeAutocomplete($query);
     

3. Full Cutover:
   • Deprecate v2 methods post-migration (use @deprecated PHPDoc).
   • Remove v2 dependency in the next major release.
4. Testing:
   • Write Pest/Laravel tests for both v2/v3 responses:

     public function test_nearby_search_returns_expected_fields() {
         $response = GooglePlaces::make()->nearbySearch(40.748817, -73.985428, 500);
         $response->assertSuccessful();
         $response->assertHasField('results.0.name');
     }
     

Compatibility

• Laravel Versions:
  • Supported: v10–v13 (v3.x). v9 with v2.2 (deprecated).
  • Upgrade Path: Use Laravel’s upgrade guides and the package’s changelog.
• PHP Versions:
  • Supported: PHP 8.1+ (v3.x). PHP 8.0.2+ (v2.2).
  • Polyfill: Use laravel-shift/laravel-13-compatibility if needed.
• Google API Changes:
  • Monitor Google’s release notes for schema changes (e.g., new fields in placeDetails).

Sequencing

1. Phase 1: Setup
   • Publish config, configure API key, and set up basic error handling.
2. Phase 2: Core Features
   • Implement autocomplete, nearby search, and place details (v3).
3. Phase 3: Advanced Features
   • Add photo fetching, custom headers, and Saloon middleware (e.g., logging).
4. Phase 4: Optimization
   • Implement caching, rate limiting, and monitoring.
5. Phase 5: Deprecation
   • Phase out v2 methods and remove legacy code.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor Saloon (v4+) and Guzzle updates for security patches.
  • Pin package versions in composer.json to avoid breaking changes:

    "skagarwal/google-places-api": "^3.2"
    

• API Key Rotation:
  • Use Laravel’s env() + config() to switch keys without code changes.
  • Implement a google-places:rotate-key Artisan command to update the config file.
• Documentation:
  • Maintain a GOOGLE_PLACES_API.md in /docs with:
    • Endpoint usage examples.
    • Rate limit thresholds.
    • Error codes and responses.

Support

• Error Handling:
  • Centralize Google API errors in a GooglePlacesException class:

    class GooglePlacesException extends \Exception {
        public static function fromResponse(SaloonResponse $response) {
            return new self($response->body()['error_message'] ?? 'Unknown