Nova Google Autocomplete Laravel Package

Getting Started

Install and prove the field renders before you plan anything around it.

composer require yieldstudio/nova-google-autocomplete:^1.3
php artisan vendor:publish --provider="YieldStudio\NovaGoogleAutocomplete\FieldServiceProvider"
php artisan nova:publish

Pin the exact version ("1.3.0", not ^1.3) — the repo is archived, so there is no future 1.3.x. Then set the Google Places key through config, never inline in a resource:

// config/services.php
'google' => [
    'places_key' => env('GOOGLE_PLACES_KEY'),
],

Where to look first — in this order:

1. vendor/yieldstudio/nova-google-autocomplete/src/ — the whole package is essentially one field class. Read every public method there before writing a line of feature code. The README is thin and the repo is archived, so the class is the docs: method names, defaults, and which model attributes actually get written.
2. dist/js/ — confirm the compiled asset exists. If it is missing or stale after publish, the field renders as a plain text input and never tells you.
3. composer.json — note the Nova/Laravel/PHP constraints declared in 2023. Treat them as a starting hypothesis to verify in staging, not as a guarantee.

First use case. Pick one low-risk internal resource — a Venue, a customer billing address, a JobSite — with a single nullable address string column. Add:

use YieldStudio\NovaGoogleAutocomplete\NovaGoogleAutocomplete;

public function fields(Request $request)
{
    return [
        ID::make()->sortable(),
        Text::make('Name'),
        NovaGoogleAutocomplete::make('Address')
            ->placeholder('Start typing an address…')
            ->help('Pick a suggestion from the list.')
            ->rules('required', 'max:255'),
    ];
}

Save one record by selecting a suggestion, then inspect the row in tinker. The headline claim — that it maps street/city/postal/country onto model attributes — is the single thing most worth verifying empirically before you design a schema or a report around it. What lands in the column determines whether you need one address field or five structured ones.

Implementation Patterns

Single formatted-string column (the common case). One address text column, one autocomplete field, operator picks a suggestion. This is the pattern the package is genuinely good at, and the one to default to:

NovaGoogleAutocomplete::make('Address')
    ->placeholder('Start typing an address…')
    ->help('Select a suggestion — free-typed addresses are saved as-is and are not verified.')
    ->rules('required', 'max:255'),

The ->help() string is data-quality acceptance criteria, not decoration. Operators who type without selecting produce garbage that looks perfectly fine in the index table.

Structured components alongside the formatted string. If you need city/postcode for filtering, keep the autocomplete field and the plain fields, then confirm on three or four international addresses what the package actually populates:

NovaGoogleAutocomplete::make('Address'),
Text::make('City')->hideFromIndex(),
Text::make('Postal Code')->hideFromIndex(),

Do not build exports, segmentation, or geo reporting on the assumption those components are reliably filled. Postcode formats and administrative hierarchies vary enormously by country, and this is a thin widget wrapper, not an address parser.

dontStore() for transient lookups. For a "resolve this address" helper where the operator should see the result but you must not persist it:

NovaGoogleAutocomplete::make('Address lookup')
    ->dontStore()
    ->help('Lookup only — nothing is saved.'),

Scope this tightly. It is a validation aid, not a variant of the normal field, and it comes with an explicit behavioural caveat (see Gotchas). Verify in the database after save that the column is untouched.

Degraded-mode is a legitimate state, so design for it. When the key, quota, or billing lapses, the field still works — it just stops suggesting and accepts free text. Rather than treating that as an error, accept human-typed addresses in your validation and, if data quality is a real objective, add a source column or a "manually entered" flag so you can distinguish operator-typed rows from autocompleted ones in reporting later.

Testing. Google Places JS does not load reliably in CI. Write feature tests against the outcome — the resource saves and the record persists — and never assert on the widget. In browser tests, drive the field with a plain type() and assert persistence; you get degraded-path coverage for free.

Index and detail views. Treat it as a form input. Let Nova render the raw string, or override displayUsing() for a cleaner label. Avoid sortable() — there is no meaningful server-side ordering on a Google-formatted string, and the resulting query behaviour will surprise whoever inherits it.

Gotchas and Tips

The upstream is archived — vendor it, don't depend on it. Last release 2023-08-16, 12 stars, zero dependents, NOASSERTION licence. For anything beyond a throwaway internal resource, copy the field class into App\Nova\Fields\GoogleAutocomplete and reference your own namespace. That makes the next Nova major a merge you control rather than a blocker you discover mid composer update. Write down the fork triggers now: Nova major, PHP major, or an unfixable bug.

NOASSERTION is a legal question, not a technical one. The licence file exists but GitHub cannot identify it. Get it reviewed before this lands in a shared or client-facing repository — much cheaper today than during an audit.

dontStore() breaks preview and clear — documented, not a bug. The 1.3.0 notes state the address preview and the clear control do not work in dontStore mode. Operators will see a field that looks like it should reflect stored state and does not, and will report it as broken. Say so in the help text, and leave a comment so a future maintainer doesn't "fix" it by quietly persisting.

Find out what "clear" writes. null, '', or leave-previous-value — this detail breaks a downstream consumer six months later. Test it once on a real record. If it matters, normalise in a mutator or observer; '' vs null also affects unique, whereNull, and any export that counts empty strings as rows.

Asset publishing is the number one silent failure. After every composer install, nova:publish, or deploy, confirm the JS actually loaded. Symptom: the input renders and saves free text perfectly, no suggestions ever appear, no error anywhere. Check the network tab for the Google Places script and the console for blocked requests. If you run a strict CSP you must allow https://maps.googleapis.com in script-src and connect-src, or autocomplete dies with a console-only error nobody reads.

Restrict the key and own the billing. Places bills per typing session, so a form with three address fields multiplies spend faster than record counts suggest. Referrer-restrict per environment, enable only Places (not the whole Maps suite), set per-key quotas, and put a budget alert on the project. A browser-side key with no restrictions is both a cost and an abuse vector.

Latency presents as "Nova is slow," not as an error. When Google degrades, nobody files a bug about a text box. Log suggestion-request failures or timeouts so you learn about quota exhaustion from your logs rather than from an operator's spreadsheet.

Verify Nova/Laravel/PHP compatibility in staging, not from composer.json. Exercise the full path on your exact versions before the field is in a resource anyone depends on: render → suggest → select → save → preview → clear → dontStore.

Extension points are thin by design. One class, no plugin surface. If you need structured components reliably, geocoding beyond autocomplete, or genuine address verification, this is not the package — fork it for the widget and do the parsing and verification server-side against the Places API directly, where you control caching, retries, and error handling.