Googleplaces Laravel Package

Getting Started

• Install with composer require nexamerchant/google-places and let Laravel auto-discover the service provider.
• Publish the package config (php artisan vendor:publish --tag=googleplaces-config or the tag listed in the package README) so you have a local config/googleplaces.php to edit.
• Add your credentials to .env — typically GOOGLE_PLACES_API_KEY=... — and confirm the Places API (and any separate Places API (New) / Geocoding API you use) is enabled in the Google Cloud console for that key.
• Clear cached config after the first edit: php artisan config:clear.
• First use case: wire an address/location autocomplete into a form. Resolve the package facade (or inject the client) in a controller or Livewire component and return suggestions as JSON, then fetch place details on selection.

Given the current release line (V1.0.9, compared against V1.0.7), this is a patch-level package — treat the README and the config/googleplaces.php file as the source of truth for method names, since the public API surface may differ from other Google Places wrappers.

Implementation Patterns

• Facade vs. injection. Use the facade for quick scripts, but inject the underlying client/service into constructors for anything you intend to unit test. Bind a mock in the container during tests rather than hitting Google.
• Wrap calls in a small service class. Don't call the package directly from controllers or Blade. A thin PlaceLookupService gives you one place to add caching, retries, and error normalisation, and makes it trivial to swap the package later.
• Two-step autocomplete → details flow. Autocomplete endpoints are cheap; Place Details calls are billed at a higher tier. Only request details when the user actually selects a suggestion, and pass the returned place_id through, not the raw query string.
• Cache aggressively. Place details and geocoding results change slowly. Cache by place_id or normalised address with a TTL of hours-to-days. Use a tagged cache store if you also need to bust it after data imports.
• Proxy the API through your own route. Never expose the API key to the browser. Have your frontend call /api/places/autocomplete?q=..., debounce input (~250–300ms), and abort in-flight requests on new keystrokes.
• Normalise the response. Google returns nested arrays with a status field; map that into a small DTO or array shape your views expect so a package upgrade or API version bump doesn't ripple through your templates.
• Queue non-interactive lookups. Bulk geocoding of an address import belongs in a job with rate limiting (RateLimited middleware or Redis::throttle), not in a request cycle.
• Feature-test the boundary. Use Laravel's Http::fake() with recorded Google responses so tests assert your parsing and error handling without burning quota.

Gotchas and Tips

• Key restrictions are the #1 source of REQUEST_DENIED. A key restricted to HTTP referrers won't work from server-side PHP; use IP restrictions for server calls, or a separate key per platform. Also confirm the specific API is enabled and that billing is active on the project.
• Billing tiers differ per endpoint. Autocomplete, Details, and Nearby/Nearby Search are priced differently, and the SKU depends on which fields you request. Request only the fields you render — field masks materially affect cost on the newer API.
• Session tokens matter for billing. If the package supports a session token for autocomplete→details, pass one; Google bills that pair as a single session. Skipping it can inflate costs significantly.
• Config cache traps. Values read via env() inside the package config are frozen once config:cache runs. Always read settings through config('googleplaces.…') in your own code, never env() directly.
• Response envelope variance. Some responses return OK/ZERO_RESULTS, others an error_message. Handle ZERO_RESULTS as a valid empty state — don't surface it as a 500.
• Photos are references, not URLs. A photo result gives you a photo_reference; you must construct a separate photo request (and typically proxy it) to render an image. Don't cache the reference indefinitely — they can expire.
• Timeouts and retries. Set an explicit HTTP timeout (3–5s is reasonable for interactive lookups) and retry only on 5xx/timeouts, never on 4xx — quota and billing errors will not resolve by retrying.
• Debugging. Log the raw response body at debug level behind a config flag; the package's exception messages are often less informative than Google's error_message. Check storage/logs/laravel.log and the Google Cloud console's quota/metrics page side by side.
• Version note. V1.0.9 is a patch on top of V1.0.7 and carries only a changelog reference (#3). Before upgrading in production, diff the changelog link and run your feature tests against the new tag — even patch bumps in wrappers sometimes alter response parsing or default config keys.