Typeahead Bundle Laravel Package

Getting Started

First, calibrate the mismatch: ruben-ruvic/typeahead-bundle is a Symfony bundle, not a Laravel package. There is no service provider, no config/typeahead.php, and no facade. As a Laravel developer you have three realistic entry points:

1. You've inherited or joined a Symfony codebase and need to ship an autocomplete field today.
2. You're evaluating it as a reference implementation before building the Laravel equivalent.
3. You're porting the FormType concept into a Laravel Blade component.

If you're in a pure Laravel app, do not install this — you'll get an autoloadable bundle class that nothing in Laravel knows how to boot. Build the equivalent with a Blade partial + a JSON route (~30 lines) instead.

If you are in a Symfony app, the minimal path:

composer require ruben-ruvic/typeahead-bundle

Register it — Symfony Flex (config/bundles.php):

return [
    // ...
    RubenRuvic\TypeaheadBundle\TypeaheadBundle::class => ['all' => true],
];

…or legacy AppKernel.php: new RubenRuvic\TypeaheadBundle\TypeaheadBundle().

Where to look first: open vendor/ruben-ruvic/typeahead-bundle/ and read two things before the README — the Form/Type/ directory (the actual FQCN of the type you'll reference) and Resources/views/ (the Twig block that renders the markup). With 0 stars and a 2022 last release, the README may lag the code; the source is the contract.

First use case — replace a free-text "search user" field with a remote autocomplete:

use RubenRuvic\TypeaheadBundle\Form\Type\TypeaheadType; // confirm FQCN in vendor/

$builder->add('user', TypeaheadType::class, [
    'source' => $this->router->generate('api_user_search'),
]);

Then wire the JSON endpoint the field calls. Keep the payload to [{id, value}] — most Typeahead builds expect value for display.

Implementation Patterns

Remote source + controller endpoint. The bundle gives you the form type; you still own the JSON contract. The standard loop:

// SearchController::users()
$q = $request->query->get('q', '');
$rows = $repo->createQueryBuilder('u')
    ->where('u.name LIKE :q')
    ->setParameter('q', $q.'%')
    ->setMaxResults(10)
    ->getQuery()
    ->getArrayResult();

return $this->json(array_map(fn($u) => ['id' => $u['id'], 'value' => $u['name']], $rows));

Prefetch vs. remote. Small, bounded lists (< ~500 rows) should be prefetch-ed as a static array so you skip the round-trip and the endpoint entirely. Switch to remote only when the dataset is unbounded or permission-scoped.

Entity-backed fields. If the submitted value must resolve to an entity, wrap the type with a DataTransformer (id ⇄ entity) or a query_builder option on any related EntityType. The typeahead widget is a presentation layer — don't let it become the validation layer.

Asset integration. Publish the bundle assets once (bin/console assets:install --symlink), then either include them in your base layout or, better, pull typeahead.js + jQuery through Webpack Encore and use the bundle only for the form rendering.

The Laravel translation of the same pattern, which is what you'll actually ship in a Laravel codebase:

// routes/web.php
Route::get('/users/search', [UserSearchController::class, 'index'])->name('users.search');

// Blade
<x-typeahead name="user_id" :source="route('users.search')" />

The Blade component owns the <input>, the data-source attribute, and the small typeahead.js init. Same architecture, no Symfony kernel.

Reuse. Extend the type rather than re-specifying options at every call site — a UserTypeaheadType with your route name and display key baked in keeps 15 forms consistent.

Gotchas and Tips

• It will not boot in Laravel. No extra.laravel.providers, no auto-discovery. Installing it just to "try it" is a dead end; vendor the JS and copy the pattern.
• Abandonment risk is real. 0 stars, 0 dependents, last release June 2022. Pin the exact version in composer.json, and expect to fork it the moment a Symfony major bump breaks the FormType signature. Budget a half-day for that.
• Bootstrap 2 vs 3 is the classic trap. Typeahead shipped inside Bootstrap 2 but was removed in Bootstrap 3 — BS3 users must load typeahead.js separately. Loading both copies produces duplicated dropdowns and confusing "two menus" bugs that look like a bundle fault but aren't.
• jQuery ordering. Typeahead depends on jQuery being defined before it loads. With Encore/Vite, use a ProvidePlugin ($/jQuery) or an explicit ordered entry — not a <script> tag jammed into the template.
• The endpoint is the real code you're debugging. When the dropdown is empty, check the Network tab for the JSON response shape first; mismatched keys (label vs value) are the #1 cause. Then check the query for a leading-wildcard LIKE '%…' that's silently full-scanning.
• Index and limit the search column. A typeahead fires on every keystroke; without LIMIT 10 and an index you'll DOS your own DB during a demo.
• CSRF / auth. If your endpoint is POST, remember the token; if it leaks PII (emails, phone numbers), scope the query by the current user — autocomplete endpoints are a classic enumeration hole.
• Extension points: override the Twig block via form_themes in config/packages/twig.yaml rather than editing vendor files; customize the block prefix with getBlockPrefix() if you need a distinct template; a DataTransformer is the clean seam for entity resolution.
• Config quirks: this bundle is thin enough that it likely ships no configuration tree. Don't hunt for config/packages/typeahead.yaml — if it exists, it'll be under Resources/config/ and it will be minimal.
• Debugging order: (1) is the bundle actually in config/bundles.php? (2) does bin/console debug:form list the type? (3) do the JS assets load (Network tab, 200s)? (4) does the endpoint return the right shape? That sequence resolves ~95% of failures with this kind of bundle.