Nova Google Autocomplete Field Laravel Package

Getting Started

First, acknowledge the elephant: this package is archived. Before installing, check its composer.json for the Nova constraint and whether its compiled Vue component targets Vue 2 (Nova ≤3) or Vue 3 (Nova 4+). If you're on current Nova, expect the JS component to need a rebuild or a fork — budget time for that, or skip straight to vendoring the source into nova-components/.

Minimal path:

1. composer require emilianotisato/nova-google-autocomplete-field
2. Enable Places API and Maps JavaScript API in Google Cloud Console, with billing attached. Neither works without a billing account.
3. Publish/configure the key. Check the package's config/ and README for the env var name (typically GOOGLE_MAPS_API_KEY or similar) — if no config exists, the key may be passed per-field via ->withMeta() or ->apiKey(). Read the field class source to confirm; the README on a 20-star archived package is often stale.
4. Add the field to a Nova resource:

use Emilianotisato\NovaGoogleAutocompleteField\GoogleAutocomplete;

public function fields(Request $request)
{
    return [
        GoogleAutocomplete::make('Address'),
    ];
}

First use case: a single address string column on a Location or Order model where operators type a destination and you want the canonical formatted address plus lat/lng. Don't start with multi-column decomposition — get the simplest single-field autocomplete rendering, confirm the map/key works in the browser, then extend to metadata extraction.

Implementation Patterns

Single-column vs. multi-column. The field's selling point is "full metadata available," but where it lands depends on the package: some versions dump a JSON payload into one column, others let you ->storeAs() sub-keys. Two robust patterns:

• JSON column + accessors: store the whole Places result in a json column, add ->casts(['address' => 'array']) (or a custom cast), and expose $model->lat, $model->lng, $model->place_id as accessors. This survives package abandonment because the data is yours.
• Split on save: keep the field ->onlyOnForms() and use fillUsing or a saving observer to decompose geometry.location into latitude/longitude columns and address_components into street/city/postal_code. Downside: editing an existing record won't re-hydrate the autocomplete widget unless the package supports re-initialization from a stored value — check whether it resolves from place_id or plain text.

Canonical place_id as the source of truth. Store Google's place_id. On display or re-save, you can re-fetch Place Details server-side (via googlemaps/php-google-maps-services or a thin HTTP client) rather than trusting a stale formatted_address. This also gives you a migration path off the package entirely.

Pair with a map preview. Since the package returns geometry, wire a read-only Nova Detail field or a custom card that renders the coordinates. This is the highest-value addition for ops teams verifying addresses.

Restrict to countries/types. If the field exposes ->countries(['us']) or ->components(...), use it. Unconstrained autocomplete produces ambiguous results (e.g., "Springfield") and inconsistent address_components shape across regions.

Cache and debounce. Every keystroke can bill a Places request. If the package doesn't implement session tokens (most small ones don't), wrap the field in a form where users are likely to select from the dropdown, and consider a debounce meta option or a fork of the Vue component.

Gotchas and Tips

• Nova version drift is the real risk. Archived packages break silently on Nova majors — the field registers, the form renders blank, and nothing logs. Pin your Nova version in composer.json and smoke-test the field immediately after any Nova upgrade. Fork the repo into nova-components/google-autocomplete so you control the build.
• API key exposure. Autocomplete is client-side, so the key ships to the browser no matter what. Restrict it by HTTP referrer and by API (Places API + Maps JS only, nothing else). A leaked unrestricted key is a classic runaway-billing incident.
• Manual entry bypasses metadata. Users can type an address and submit without selecting a suggestion. You get a string with no place_id/geometry. Guard with validation (required plus a check that place_id is present if coordinates are mandatory) or fall back to server-side geocoding on save.
• address_components shape is not stable. Do not index into [0]/[1] — match on types (route, locality, postal_code, administrative_area_level_1). Long/short names differ by country.
• JSON storage requires the right column. If the field emits an object and your column is varchar(255), saves truncate or throw. Use json or text and cast it.
• Debugging checklist: 500s from the Google API in the browser console usually mean billing is off or Places API isn't enabled on that key; RefererNotAllowedMapError means the referrer restriction doesn't match your local host; a blank widget with no console errors usually means the compiled component targets the wrong Vue version.
• Config caching: if the key comes from a config file, run php artisan config:cache after changing it, and remember .env changes are invisible while cached.
• Extension points: withMeta() is your escape hatch for passing options the field doesn't expose. For anything deeper (session tokens, debounce, map preview), the Vue component in resources/js/ is the only lever — another reason to vendor the source.
• Exit strategy: because this is a thin wrapper over the Places API, plan to replace it with a first-party field. A 100-line custom Field + a small Vue component using @googlemaps/js-api-loader is maintainable and removes the archived-dependency liability entirely.