Filament Geosearch Laravel Package

Getting Started

This is a front-end autocomplete/suggestion package: you configure a provider, give it an apiKey, choose a style, and it wires up an input with debounced autoComplete requests controlled by autoCompleteDelay.

1. Install and publish

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config   # check `php artisan vendor:publish` for the exact tag
   

2. Set the key in .env, not in code

   AUTOCOMPLETE_PROVIDER=google   # or whatever providers ship in the config
   AUTOCOMPLETE_API_KEY=
   

3. Look here first, in this order

   • The published config/<package>.php — it will show the authoritative list of provider values, style values, and defaults for autoComplete / autoCompleteDelay.
   • The package service provider — reveals whether the config is merged, whether a Blade component/directive is registered, and whether the JS/CSS assets are published or served from the vendor path.
   • The resources/views directory (if published) — the actual markup is usually a thin wrapper around an input plus a <ul> of suggestions.

4. First use case: drop the component into an existing form field and let the browser do the rest.

   <x-autocomplete
       name="address"
       :value="old('address', $user->address)"
       provider="google"
       :auto-complete-delay="300"
   />
   

   Verify in the browser network tab that one request fires per keystroke after the delay, not on every character — that confirms the wiring is live.

Implementation Patterns

Treat config as defaults, props as overrides. The package is built around four knobs (provider, apiKey, style, autoCompleteDelay) plus the on/off autoComplete flag. Keep site-wide defaults in config/ and only override per field where the UX genuinely differs:

// config/autocomplete.php (shape will vary — read the published file)
return [
    'provider'          => env('AUTOCOMPLETE_PROVIDER', 'google'),
    'api_key'           => env('AUTOCOMPLETE_API_KEY'),
    'style'             => 'default',
    'auto_complete'     => true,
    'auto_complete_delay' => 300,
];

Isolate provider differences behind one boundary. Different providers return different payload shapes (Google Places vs. Algolia vs. Mapbox all differ on description vs. place_name vs. formatted_address). If you support more than one, normalise in a single place — a small adapter/service that maps a provider response to {label, value, meta} — rather than sprinkling if ($provider === ...) through views. If the package exposes a provider contract or a container binding, bind your own implementation instead of forking the view.

Pair with a hidden field for the canonical ID. Autocomplete gives you a display label; you usually also need a stable identifier (place ID, postcode, coordinates). Render an <input type="hidden" name="place_id"> and have the selection handler populate both. Validating only the label leads to duplicate/ambiguous records.

Livewire / Inertia. With Livewire, keep the widget out of the reactive re-render path where possible (or use wire:ignore around it) — re-rendering the DOM under an open suggestion list breaks the dropdown. Bind the final selection, not every keystroke, to the component property.

Tune the delay per context. autoCompleteDelay of ~250–400ms is the sweet spot for address fields; a search-as-you-type product/name field can go lower. Very high values make the field feel dead; zero is a billing hazard (see below).

Testing. Never hit a real provider in the test suite. Fake the HTTP client and assert on your adapter's output:

Http::fake(['*' => Http::response(['predictions' => [['description' => '10 Downing St']]])]);

Then assert the form submission persists the value — the JS behaviour itself needs a Dusk/browser test, since PHPUnit can't see it.

Styling. Check whether the style option maps to a CSS class name or to a set of inline/vendor-provided styles. If it's class-based, publish the CSS and override via your own stylesheet rather than editing vendor assets — otherwise composer update silently reverts your tweaks.

Gotchas and Tips

• The API key is in the page. Any front-end autocomplete key is public. Use a provider key that is domain/referrer-restricted and, where the provider supports it, a separate browser key from your server key. Never reuse a server-side key here.
• php artisan config:cache will bite you. After changing the key or provider in .env in a cached-config environment, the old value persists. php artisan config:clear (or re-cache) is the first debugging step when "nothing changed".
• autoCompleteDelay: 0 is a billing and rate-limit incident. Every keystroke becomes a billable request, and providers will start 429-ing on shared office IPs. Set a floor and don't expose the delay as a user-editable setting.
• Rate limiting and quotas. Add server-side throttling or caching if you proxy requests; a single power user with a fast connection can consume a free-tier quota in an afternoon. Consider caching common suggestions keyed on the query prefix.
• Escape suggestion labels. Provider responses are third-party strings. If you render them with {!! !!} or innerHTML, you've introduced an XSS vector. Use text interpolation.
• Accessibility is usually the gap in v1 packages. Confirm keyboard navigation (arrow keys, Enter, Escape), role="combobox" / aria-expanded / aria-activedescendant, and that the visible <label> is still associated. If the package doesn't handle it, plan to patch the published view.
• Progressive enhancement. The field must still work as a plain text input with JS disabled or when the provider errors — never let a failed request leave the form unsubmittable. Validate server-side that the submitted string is plausible; don't trust that it came from a suggestion.
• Extension points to check before forking: publishable views/config, any provider contract bound in the container, and whether assets are published vs. served from vendor/. Using these keeps you upgrade-safe; editing files under vendor/ does not.
• Version 1.0.0 caveat. This is a first release with a small option surface, so expect the config keys, provider names, and view structure to shift in 1.x. Pin the version in composer.json and read the changelog before minor bumps.