Nova Places Laravel Package

Getting Started

• Install with composer require hnassr/nova-places. The service provider is auto-discovered; if assets are not served by Nova's asset pipeline, publish them with php artisan vendor:publish --provider="Hnassr\NovaPlaces\FieldServiceProvider" (check the provider name in src/ for this repo).
• Confirm the Nova version constraint in composer.json before installing. The last release (May 2020) targets Nova 2/3-era APIs; it will not install against Nova 4+ without patching composer.json and porting the Vue component.
• Credentials first: the field talks to Algolia Places from the browser, so it needs an Algolia application ID and search-only API key. Look for a published config file (typically config/nova-places.php) or env vars like ALGOLIA_PLACES_APP_ID / ALGOLIA_PLACES_API_KEY, and set them before touching any resource.
• Where to look first: src/NovaPlaces.php for the fluent setters/meta it exposes, and resources/js/components/Field.vue (or dist/js/field.js) to see exactly how the places() instance is created, which event sets the field value, and whether it writes only the formatted string.
• First use case — a single address input on a Resource:

use Hnassr\NovaPlaces\NovaPlaces;

public function fields(Request $request)
{
    return [
        ID::make()->sortable(),
        NovaPlaces::make('Address'),
    ];
}

• Load the edit form and type a partial address. If you get a plain text input with autocomplete never firing, that is the signal to check the browser console (see Gotchas) before debugging your resource code.

Implementation Patterns

• Constrain the autocomplete per field. Use the field's fluent setters (or withMeta()) to restrict by country, place type, and language so results match your data model — e.g. cities only, one country, site locale. This is the most common day-to-day configuration and belongs in a small helper or a base resource method rather than copy-pasted on every field.
• Form-only display. Address autocomplete is a UX affordance, not an index column. Pair it with ->onlyOnForms() (or ->hideFromIndex()) and render the stored string with a plain Text field on detail/index views. This also avoids shipping the Algolia JS to index pages.
• Splitting a formatted address. Algolia Places returns a human-readable value; the field typically persists that single string. If your schema stores street, city, postal_code, country separately, either:
  • use ->fillUsing(fn ($request, $model, $attribute, $requestAttribute) => ...) to parse/split the submitted value, or
  • keep NovaPlaces as a "search assist" field mapped to a virtual attribute and hydrate the real columns in the model's setter/observer.
• Persisting coordinates. Places suggestions carry latlng; the default field usually does not store it. If you need geo data, add hidden latitude/longitude fields and either extend the Vue component's change handler to populate them, or geocode once server-side on save (do not geocode on every read).
• Validation and normalization. Combine ->rules('required', 'string', 'max:255') with a prepareForValidation/fillUsing normalization step so manually typed values (users can ignore suggestions) match the same shape as autocompleted ones.
• Reuse across resources. Wrap the field construction in a trait or static factory (AddressField::make()) that applies your standard countries/type/language meta, so a future swap to another provider is a one-file change.
• Testing. Assert the persisted value server-side with a normal field test; for the browser behavior use Dusk and explicitly wait for the suggestion list (.ap-dropdown/.ap-suggestion in places.js) before clicking — race conditions here are the usual source of flaky tests.

Gotchas and Tips

• The backend service is gone. Algolia Places was discontinued (shut down in 2022); the places.js CDN endpoint and its API no longer work. The field's autocomplete will not function regardless of your credentials, and the repo was archived without a migration path. Treat this package as a UI starting point, not a working dependency — budget for replacing the provider (Google Places, Mapbox, or a self-hosted geocoder) before relying on it in production.
• Archived means frozen. No Nova 4 compatibility, no PHP 8 fixes, no security updates. Fork it or vendor the component if you must keep it; do not expect issues or PRs to be addressed.
• Frontend asset staleness. The compiled dist/js/field.js is what actually ships. If you edit resources/js you must rebuild (npm install && npm run dev inside the package) and re-publish/copy the dist output; editing the source alone changes nothing.
• API keys are public by design. Only ever use an Algolia search-only key here. It is embedded in the page; an admin/write key in this config is a credential leak. (Moot once you drop Algolia, but relevant if you reuse the component pattern with another provider.)
• Silent failure mode. A missing/blocked CDN script or bad key usually degrades to a plain text input with a console error, not a visible Nova error. First debugging step is always the browser network/console tab, then verify the config actually resolved (config('nova-places...') returning null on cached config is common — run php artisan config:clear).
• Locale/country mismatch. Restricting countries but leaving the browser language/language option unset produces odd formatted strings; set both consistently or your stored values will vary by user.
• Single-attribute by default. Don't assume the field hydrates related columns or coordinates out of the box — verify in Field.vue what gets emitted on change before designing your schema around it.
• Extension points. withMeta() for provider options, fillUsing() for persistence logic, and resolveUsing() for display are the three hooks you will actually need when adapting this to a live geocoder.