Autocompleter Bundle Laravel Package

Getting Started

The first thing to establish is that this is a Symfony bundle, not a Laravel package. There is no service provider, no facade, and nothing that will auto-register under bootstrap/providers.php. composer require pugx/autocompleter-bundle inside a Laravel app installs files that will never be loaded. So "getting started" splits into two paths.

If you are actually working in the Symfony codebase this targets (the realistic case if you inherit a project):

1. composer require pugx/autocompleter-bundle and register PUGX\AutoCompleterBundle\PUGXAutoCompleterBundle (Flex does it for you; otherwise add it to config/bundles.php).
2. Look first at the bundle's form type in vendor/pugx/autocompleter-bundle/Form/Type/ — that is the entire public surface. Everything else is your code.
3. Create one JSON endpoint that accepts a term query parameter and returns a list of {value, label} objects.
4. Add the bundle's autocomplete form type to one field — a "find user by name" input on an admin form is the canonical first use case.

If you are a Laravel developer evaluating it as a pattern to copy, the useful takeaway is much smaller than the package: a TextType extension that stamps a data-autocomplete-url attribute onto the input, plus a JSON search route. You can reproduce the whole idea in Laravel with a Blade partial and a single Route::get('/autocomplete/users', ...) in well under an hour — see the patterns below.

Implementation Patterns

The bundle's contract. The form type is a thin wrapper over Symfony's TextType. You pass a route name and (depending on version) an entity class and a property; the type renders a normal <input type="text"> with a data attribute pointing at your endpoint. The bundle does not query your database and generally does not ship the JavaScript — you wire up jQuery UI Autocomplete (or Select2) yourself against that attribute. That separation is the one design decision worth stealing.

Endpoint pattern. Your controller reads term, delegates to a repository method, and returns JSON:

$term = $request->query->get('term', '');
$users = $userRepository->searchByName($term, 10);
return $this->json(array_map(fn ($u) => [
    'value' => $u->getId(),
    'label' => $u->getFullName(),
], $users));

Keep the shape stable (value/label) — the front-end library and any "select this record" callback both depend on it, and changing it later breaks every form that used the widget.

Repository pattern. Push the search into a repository method that applies LIMIT and an ordered LIKE term% or LIKE %term% clause. Never let the controller build the query inline; you will end up duplicating it for every autocompleted entity and diverging on limits and escaping.

The Laravel translation. If you are porting rather than installing, the idiomatic Laravel version is:

• A Blade component (<x-autocomplete :url="route('users.search')" name="user_id" />) that renders the input plus a small Alpine or vanilla fetch handler with debounce and abort-on-new-keystroke.
• A dedicated route returning response()->json(...), kept out of your resource controllers.
• A FormRequest or explicit validation that the term is a string and length-bounded.
• Optionally a Livewire component if you want the selected record to round-trip through a form object — Livewire removes the need for the package entirely for most CRUD screens.

Integration tips. Add an id-vs-label split so the input can display a human name while posting a machine ID. If the field is pre-filled on edit, hydrate it server-side and disable the autocomplete until the user actually types, otherwise the widget clears the existing value on focus in some jQuery UI versions.

Gotchas and Tips

• The Symfony/Laravel mismatch is the headline gotcha. No Laravel adapter exists, dependents are listed as zero, and the package is a 92-star, low-activity bundle. Do not plan a Laravel feature around it; budget for a hand-rolled replacement.
• LGPL-3.0 is unusual for PHP and worth a legal glance. For normal server-side usage where you simply depend on the unmodified package it is generally fine, but if your organisation's policy treats LGPL as viral you will want approval before shipping.
• The bundle doesn't do the search. A frequent source of confusion is expecting the entity/property options to produce results automatically. They only feed markup; the query, the limit, and the escaping are all yours.
• Front-end dependencies are on you. jQuery UI Autocomplete is assumed. If your app is on Alpine, Vue, or React, you will be ignoring the package's assumptions and only using its data attribute — at which point the dependency earns very little.
• Missing LIMIT is the classic production bug. Unbounded LIKE '%term%' scans are fine on a dev fixture and fatal on a real table. Always cap results and add an index or a pg_trgm/fulltext fallback.
• Auth and CSRF on the endpoint. The JSON route must sit behind the same firewall as the form. It is easy to define it as anonymous while debugging and forget to restore it; also confirm whether your stack expects the token as a header or a query param.
• Escaping in the dropdown. The front-end renders label as HTML in several configurations. Escape the label server-side or restrict it to plain text, otherwise a user's display name becomes an XSS vector.
• Debugging a dead widget. If the input renders but never queries, check the rendered data-* attribute first, then the network tab: a 302 to a login page from an expired session looks identical to "autocomplete broken."
• Extension point is the JS, not the PHP. Since the PHP side is a two-line form type, all meaningful customisation — debounce timing, minimum characters, rendering a secondary line in the dropdown, multi-select — happens in the JavaScript layer. Fork the snippet rather than the bundle.
• Config caching. The route name is resolved through the container; after renaming an autocomplete route, clear the cache or you will spend an hour chasing a stale reference.
• Pin your version. With a sparse changelog and this few users, a minor release is unlikely to be well-trodden. Lock the constraint and read the diff before bumping.