Nova Maps Address Laravel Package

Getting Started

• Requirements: Laravel Nova (the 2.x line targets Nova 4/5; 1.x was the Nova 3 era), PHP 8.1+, and a Google Cloud project with Maps JavaScript API and Places API enabled.
• Install:

  composer require mauricewijnia/nova-maps-address
  

• Publish the config (the exact tag is in the package's service provider — if a tag fails, run vendor:publish and pick the package):

  php artisan vendor:publish --provider="Mauricewijnia\NovaMapsAddress\NovaMapsAddressServiceProvider"
  

• Configure the key in .env / config/nova-maps-address.php (the config file ships with the key name; typically NOVA_MAPS_ADDRESS_KEY, populated into the field on boot).
• First use case: drop the field into a Nova resource that stores a human-entered address — e.g. a Customer or Order billing/shipping address:

  use Mauricewijnia\NovaMapsAddress\Nova\MapsAddress;
  
  public function fields(NovaRequest $request)
  {
      return [
          MapsAddress::make('Address'),
          // ...
      ];
  }
  

  The field renders a text input backed by Google Places autocomplete, so typing surfaces suggestions and selecting one fills the stored string. That's the whole happy path — no custom JS required.

Implementation Patterns

• Single-column storage. The simplest use is one string column on the model. The field's value is the formatted address string returned by Places, so keep the column TEXT/VARCHAR(255) and mark it nullable unless the address is mandatory.
• Coordinates. If you need lat/lng for maps or distance sorting, enable the coordinate option (e.g. ->withCoordinates()) and provide matching columns on the model. Verify the exact option name against the README for your major version — option names have changed between 1.x and 2.x.
• Restricting results. Options to limit by country and/or place type are exposed on the field (e.g. ->countries(['nl','be'])). Use these to avoid users selecting "restaurants" when they need a postal address, and to keep your Places billing focused.
• Validation. Because the field is free-typed until a suggestion is selected, add a server-side rule if the address must be structured (e.g. required and a regex/lookup check). Don't rely on the front-end autocomplete as validation.
• Display on index/detail. The package ships a display component for read-only views; if you combine multiple stored parts (street, city, postcode), build a small accessor or ->displayUsing() to render one line.
• Form composition. Pair it with a separate map/preview field or a lat/lng pair of Number fields if you want users to tweak coordinates after the address is picked.

Gotchas and Tips

• v2.0.1 is the "assets actually ship" release. The only change from v2.0.0 is adding the built JS/CSS to the package. If you installed or tried v2.0.0 and saw a blank/broken field, the fix is simply to upgrade and republish Nova assets:

  composer update mauricewijnia/nova-maps-address
  php artisan nova:publish
  php artisan view:clear && php artisan config:clear
  

  Treat 2.0.0 as effectively unusable; pin ^2.0.1.
• The API key is client-side. The key is injected into the field's JS, so it is visible to anyone with Nova access. Restrict it in Google Cloud by HTTP referrer (your Nova host) and only enable the two APIs you need — do not reuse an unrestricted server key.
• Config caching. In production, remember php artisan config:cache after changing the key; a stale cached config is the most common cause of "no suggestions / 403" reports.
• Google billing & API drift. Places autocomplete is a billed API, and Google has been migrating to the new Places API. If suggestions stop appearing, check the browser console for RefererNotAllowedMapError / ApiNotActivatedMapError and confirm the enabled APIs in Google Cloud before touching package config.
• Nova asset publishing is required per deploy. Nova serves the field's compiled assets from the host app's public assets; a deploy that doesn't run nova:publish (or that caches an old public/vendor/nova) will show the field without JS.
• Major-version breakage. v2 was a substantial rewrite (Nova 4/5, likely Vite-built assets). If you're upgrading from 1.x, re-read the README for renamed options and re-publish the config — don't assume your old MapsAddress::make(...) chain compiles identically.
• Debugging tip: inspect the generated input in the browser — the field's config (key, countries) is passed as a data attribute/JSON blob to the Vue component, which tells you immediately whether the problem is config (key missing) or assets (no component mounted).