Ajax Autocomplete Bundle Laravel Package

Getting Started

First, calibrate expectations: mawi12345/ajax-autocomplete-bundle is a Symfony bundle, not a Laravel package. It will not auto-register a service provider, it has no config/ajax_autocomplete.php, and its form type is built on Symfony\Component\Form, not Laravel's Form facade. With 2 stars and 0 dependents, treat it as a reference implementation or a component for a Symfony service inside a polyglot architecture — not something you composer require into a Laravel app.

If you are evaluating it as a Laravel developer, the practical starting points are:

1. Read the bundle's form type and its Twig/JS asset first. That is where the actual contract lives: the AJAX endpoint URL, the query parameter name (typically something like q or term), and the expected JSON shape (usually [{ "id": ..., "text": ... }]).
2. Check Resources/config/routing.xml (or the annotated controller) to see what route the bundle expects the host app to provide. This endpoint is the only piece you can reuse verbatim in Laravel.
3. Identify the frontend behavior — the bundle is essentially a thin wrapper around an autocomplete widget plus a form type that renders a hidden ID field and a text input. The JS is the reusable part.

Your first use case in a Laravel codebase is almost always "autocomplete a belongsTo relation" — e.g., pick a Customer by name on an Invoice form. Rather than port the bundle, replicate its contract:

// routes/api.php
Route::get('/autocomplete/customers', function (Request $request) {
    return Customer::query()
        ->where('name', 'like', '%'.$request->string('q').'%')
        ->limit(10)
        ->get(['id', 'name as text']);
});

Then initialize the bundle's JS widget (or any autocomplete library) against that URL. You get the same UX with zero Symfony coupling.

Implementation Patterns

Pattern 1 — Endpoint-first reuse (recommended). Keep Laravel as the data owner. Serve a JSON suggestion endpoint from Laravel and let any frontend (Symfony admin, Blade page, SPA) consume it. Match the bundle's response shape exactly so the widget works unmodified:

return response()->json($results->map(fn ($m) => [
    'id'   => $m->id,
    'text' => $m->name,
]));

Pattern 2 — Blade + fetch / Livewire equivalent. The bundle's day-to-day value in Symfony is "wire a text input to a remote source." In Laravel, that is a Blade partial with data-autocomplete-url and a debounced fetch, or a Livewire component with wire:model.live.debounce.300ms and a computed suggestions property. Use the bundle's UX (debounce, minimum characters, hidden ID field) as the spec.

Pattern 3 — Split-stack integration. If you genuinely run a Symfony app alongside Laravel, install the bundle in the Symfony app (config/bundles.php), define the form type on the entity field, and point its endpoint at a Laravel API route protected by a service token. This is the only scenario where the package is used as-is; treat the Laravel side as a backend-for-frontend.

Pattern 4 — Form-type mimicry. The bundle's form type pattern (hidden id field + visible label field + a data transformer) maps cleanly to a Laravel custom validation rule plus a prepareForValidation() hook on a FormRequest, or to a dedicated AutocompleteInput Blade component that accepts name, endpoint, and initial.

Integration tips:

• Always return a stable id/text pair; don't leak full Eloquent models.
• Cap results (10–20) and require a minimum query length to avoid table scans.
• Add ->when($request->filled('q'), ...) guards and validate the query string.
• If you use the bundle's JS, vendor it under resources/js/vendor/ rather than relying on the bundle's asset pipeline.

Gotchas and Tips

• Don't add this to a Laravel composer.json. There is no Laravel service provider, and its Symfony Form/HttpFoundation dependencies will either conflict or sit unused. The opportunity score (0.38) and zero dependents reflect that it is niche and unmaintained.
• Query parameter mismatch is the #1 failure mode. The bundle's JS and its server-side expectations must agree on q vs term vs query. When integrating against a Laravel endpoint, inspect the network tab and confirm the actual parameter name before writing the controller.
• Response shape is not documented reliably. Confirm whether the widget expects {id, text}, {value, label}, or a bare array. A silent empty dropdown is usually a shape mismatch, not a routing error.
• CSRF and auth differ across frameworks. Symfony's form-token/session model does not translate to Laravel's VerifyCsrfToken. For cross-stack calls, use a signed token or a dedicated API guard, and exclude the endpoint from CSRF only if it is read-only and rate-limited.
• Debugging checklist: (1) hit the endpoint directly with curl; (2) check the browser console for the initialized selector; (3) confirm the input has the expected data-* attributes after render; (4) verify debounce/min-length thresholds.
• Extension points are limited but exist: the form type can be subclassed to swap the data transformer (e.g., to support UUIDs), and the endpoint is entirely yours — that is where you should put authorization and scoping (e.g., restrict customers to the current tenant).
• Long-term risk: with 2 stars and no dependents, assume no security patches. If you adopt the JS, fork it into your repo; if you adopt the concept, reimplement in ~50 lines of Laravel + a small Alpine/Livewire component and own it.