Typeaheadbundle Laravel Package

Getting Started

Read this first: this is a Symfony 2/3-era bundle (0 stars, 0 dependents, matm/ vendor namespace) that wraps Twitter Typeahead — a JS library abandoned since 2015 (last release 0.11.1). Treat the assessment as "how to survive with it in a legacy app," not "how to adopt it." For anything greenfield, use Symfony UX Autocomplete, Tom Select, or plain <datalist>.

If you're already committed:

1. Install. composer require matm/typeaheadbundle may fail or resolve only to dev-master; check Packagist before assuming. If it isn't resolvable, add the GitHub repo as a VCS repository in composer.json and pin a commit.
2. Register the bundle in app/AppKernel.php (new Matm\TypeAheadBundle\TypeAheadBundle() — confirm the exact namespace from vendor/matm/typeaheadbundle/).
3. Publish assets. php app/console assets:install web --symlink (Symfony 2) or bin/console assets:install public (Symfony 3). The bundle ships typeahead.js + bloodhound.js under Resources/public/. Confirm the shipped version — 0.9 vs 0.10+ changes the entire dataset API.
4. Look first at: Form/Type/ for the type name and supported options, Resources/views/ for the form theme block that wires the JS, and Resources/public/ for the JS version.

First use case: an entity picker — a customer, product, or city field backed by an AJAX endpoint, replacing a <select> with hundreds of options.

$builder->add('customer', TypeaheadType::class, [
    'remote' => ['url' => '/autocomplete/customers', 'wildcard' => '%QUERY'],
]);

Option names above are indicative — verify against the bundle's TypeaheadType before copying.

Implementation Patterns

Endpoint contract. A tiny controller returning JSON is the whole backend:

public function customersAction(Request $request)
{
    $q = trim($request->query->get('q', ''));
    if (mb_strlen($q) < 2) {
        return new JsonResponse([]);
    }

    $rows = $this->getDoctrine()->getRepository(Customer::class)
        ->createQueryBuilder('c')
        ->where('c.name LIKE :q')
        ->setParameter('q', $q.'%')
        ->setMaxResults(15)
        ->getQuery()->getResult();

    return new JsonResponse(array_map(fn ($c) => [
        'id' => $c->getId(),
        'value' => $c->getName(),
        'tokens' => [$c->getName(), $c->getCode()],
    ], $rows));
}

Keep payloads under ~20 rows and return only id/label — this endpoint is unauthenticated-friendly by nature (a GET with a query string).

Local datasets for small taxonomies. Countries, currencies, tags — skip the endpoint entirely and pass a fixed array as a prefetch/local dataset. One less route, one less N+1 risk.

Round-tripping values is on you. The typeahead renders a plain text input. If the form maps to an entity, add a DataTransformer (label → entity) or pair a visible typeahead with a hidden customer_id field that your JS sets when a suggestion is picked. The hidden-id pattern is the safer of the two — a text transformer will silently fail when a user types a near-miss.

Escape hatch for Bloodhound. If the bundle only exposes the 0.9 API but you need prefetch/remote/limit/datumTokenizer, initialize Bloodhound yourself in a small asset file and use the bundle purely for rendering the input. Don't fight the bundle's option schema.

Testing. Assert on rendered attributes and on the JSON endpoint (functional test with $client->request('GET', '/autocomplete/customers?q=ac')). Don't try to browser-test the dropdown — the ROI is terrible for a suggestion list.

Gotchas and Tips

• Version compatibility is the first gate. Symfony 4+ removes AppKernel, uses autowired form types, and expects bin/console. A bundle this old likely relies on XML service definitions with explicit tags. Check Resources/config/ before you invest a day. Porting the ~150 lines of form type into your own src/Form/Type/ is often faster than making the bundle load.
• Your asset pipeline won't see the bundled JS. Webpack Encore / AssetMapper knows nothing about Resources/public. Copy typeahead.js and bloodhound.js into assets/ and load them yourself; leave the bundle for form rendering only.
• Bloodhound is not defined in the console means you loaded typeahead.js without bloodhound.js, or loaded them in the wrong order. typeahead.js depends on jQuery in the 0.9 API and on jQuery+Bloodhound in 0.10+.
• Form theme registration. If nothing renders as a typeahead, the bundle's Twig block probably isn't in your twig.form_themes. Add it in config.yml, and check that assets:install actually wrote to web/bundles/....
• minLength: 0 will hammer your endpoint on focus. Set 2–3 and enable prefetch caching for the common cases.
• Overriding templates in Symfony 2/3 is app/Resources/MatmTypeAheadBundle/views/... — this still works, and is the cleanest place to tweak markup without forking.
• Don't leak your entity table. The endpoint receives a raw q. Parameterize the query, cap maxResults, and don't return fields the UI doesn't need.
• Migration path when you get the chance: keep the server endpoint exactly as-is (it's plain JSON) and swap only the JS layer — Symfony UX Autocomplete consumes the same shape via a Stimulus controller. That's a half-day change with no backend churn.
• Pin whatever you settle on. "matm/typeaheadbundle": "dev-master#<sha>" — an unpinned abandoned dependency is a supply-chain coin flip.