Nova4 Google Autocomplete Field Laravel Package

Getting Started

This package wires Google Maps into a Laravel app; v0.2.9 adds a config switch that controls whether the Maps JS is loaded, so the config file is the first place to look.

1. Install and publish config:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   

2. Set credentials in .env (never hard-code in config):

   GOOGLE_MAPS_API_KEY=your-restricted-key
   GOOGLE_MAPS_ENABLED=true
   

3. Confirm the package's service provider is auto-discovered (php artisan about or bootstrap/providers.php on Laravel 11+).
4. First use case: render a single map on a page. Add the package's script include (Blade component/directive/helper — check resources/views and the provider's boot() for what it registers) to your layout, pass coordinates from the controller, and verify the map renders in the browser.

Start by reading, in order: the published config file (every option and its default), the service provider (what it binds/registers), then any Blade component or facade the package exposes.

Implementation Patterns

Config-gated loading. The v0.2.9 option should be treated as the single source of truth for whether the Maps script is emitted. Wrap the include so it follows config rather than being sprinkled into layouts:

@if (config('google-maps.enabled'))
    <x-google-map :center="$center" :markers="$markers" />
@endif

Flip GOOGLE_MAPS_ENABLED=false in testing/CI and local environments where you don't want outbound calls or key usage.

Keep data in the controller, not the view. Resolve coordinates and marker collections in a controller, form request, or view composer, and pass a plain array/collection into the component. This keeps the Blade layer declarative and makes the payload testable.

Layout-level include, per-page opt-in. Put the script tag in your base layout but guard it with a section/stack so only pages that actually render a map pay the cost:

@stack('maps-scripts')

then @push('maps-scripts') from the map view.

Environment-specific keys. Use separate API keys for local, staging, and production via .env, each restricted by HTTP referrer (web) or IP (server-side geocoding). Config keys map cleanly to env() calls in the published config.

Testing. Override config in tests instead of touching .env:

config()->set('google-maps.enabled', false);

Assert the script tag is absent when disabled and present when enabled — that's the cheapest regression test for this feature.

Gotchas and Tips

• Config cache is the #1 trap. After editing the published config or .env, run php artisan config:clear (and config:cache in deploy scripts). A stale cache makes the new v0.2.9 toggle look broken.
• Duplicate script includes. Google Maps throws "You have included the Google Maps JavaScript API multiple times" if the script is loaded twice — common when both the layout and the component emit it. Decide on exactly one owner of the <script> tag and enforce it.
• Key exposure. Any key in a browser-loaded script is public. Restrict it in Google Cloud Console by HTTP referrer and enable only the APIs you use (Maps JavaScript, Places, Geocoding), or a leaked key becomes a billing incident.
• Libraries must be requested up front. If you need Places, Geometry, or Marker clustering, they have to be declared in the load URL (libraries=places) — they cannot be added after the fact without a reload. Check whether the config option exposes a libraries list; if not, that's a candidate extension point.
• Async loading ordering. With loading=async, the Maps API is not guaranteed to be defined at DOMContentLoaded. Use the official callback parameter or importLibrary() rather than assuming google.maps exists.
• Version pinning. Pin a Maps JS version (v=weekly or a numbered release) so a Google-side change doesn't silently break your maps in production.
• Debugging checklist: view rendered HTML for the script tag → Network tab for a 200 and a valid key= param → Console for RefererNotAllowedMapError, InvalidKeyMapError, ApiNotActivatedMapError. Each maps to a distinct Cloud Console fix.
• Extension points: re-publish/override the package's views (php artisan vendor:publish --tag=<package>-views), and prefer config() lookups with sensible defaults so a missing published config file doesn't fatal.
• Version maturity. At v0.2.x the public API is still moving. Pin the exact version in composer.json ("<vendor>/<package>": "0.2.9") and read each release note before upgrading; treat minor bumps as potentially breaking.