Search Widget Laravel Package

Getting Started

This is a niche Victoire DCMS widget bundle (0 stars, 0 dependents) — treat it as source-first: clone/read the code before relying on any docs, because there almost certainly aren't any.

1. Install via Composer (composer require friendsofvictoire/search-widget — confirm the actual package name in its composer.json), then register the bundle in app/AppKernel.php (Symfony 2/3) or config/bundles.php.
2. Check the Victoire dependency chain first. The bundle won't do anything without Victoire itself plus whatever search backend it expects (most likely Elastica/FOSElasticaBundle, given the era). Read its composer.json require block before anything else.
3. Look here first, in this order:
   • Entity/WidgetSearch.php (or Widget/) — the widget's configurable properties.
   • Form/WidgetSearchType.php — which properties editors can set in the visual editor.
   • Resources/views/ — the Twig templates that actually render the form/results.
   • Resources/config/services.yml and any routing.yml — where the search endpoint lives.
4. First use case: open a Victoire page in the visual editor, drag the "Search" widget into a slot, publish, and confirm the search form renders and submitting it returns results. That single loop tells you whether the bundle is wired correctly.

Implementation Patterns

• Split form vs. results. Most Victoire search widgets render a form in one slot (header) and results in another (main content). Configure the form's action to point at a dedicated "search results" page/route rather than the current page, so results aren't rendered inside the header slot.
• Route + controller pattern. Expect a results route like /search?q=.... Read the term with $request->query->get('q'), guard against empty/blank queries, then run the index query. If the bundle doesn't ship a controller for paginated results, write one and point the widget's form at it.
• Pagination. Wire results through KnpPaginator (or the bundle's own paginator if present) and make sure the paginator preserves q in the query string — this is the single most common customization you'll make.
• Indexing hooks. Keep indexing out of the widget. Index business entities when they're saved/published, either via Doctrine lifecycle listeners or Victoire's business-entity events. The widget should only query; mixing write and read concerns here makes reindexing painful.
• Extend widget properties via the form + entity. Adding things like "results per page", "placeholder text", or "target page" is a three-file change: property on the widget entity, field in WidgetSearchType, and usage in the Twig template. Keep it that simple.
• Override templates in your app, not in vendor. Copy Resources/views/WidgetSearch/*.twig into your app's template override path and edit there, so composer update doesn't wipe your markup.
• Integration tip: if you already have a Symfony search implementation elsewhere, don't duplicate it — make the widget a thin wrapper that delegates to your existing search service, injected via services.yml.

Gotchas and Tips

• Version lock is the real risk. With 0 dependents, the bundle is likely pinned to an old Victoire/Symfony combination. Check composer.json constraints and run composer why-not before upgrading anything; be prepared to fork and patch.
• Caching in Victoire is aggressive. Published pages and rendered widgets get cached. Verify search results aren't cached (they're per-query and must be dynamic) and that the form widget cache is invalidated when you change its properties. Cache a form, never a result set.
• Route collisions. Victoire's page routing can be catch-all; a /search route may get shadowed or shadow a page. Register the search route with higher priority and test against a real published page.
• Highlight markup is HTML. If the backend returns <em> highlights or snippets, escape the surrounding text but carefully allow the highlight tags — naive |raw on user-supplied snippets is an XSS vector. Escape first, then apply highlights, or whitelist tags.
• Reindex after mapping changes. Any change to indexed fields requires a full reindex (fos:elastica:populate or equivalent); otherwise results silently miss new fields.
• Empty query behavior. Decide explicitly: show nothing, show everything, or show a prompt. The bundle may default to something surprising — check the controller.
• Locale/multi-site. Victoire supports multi-language; confirm the index is per-locale or that the query filters by _locale, otherwise you'll get mixed-language results.
• Debugging tip: bypass the widget entirely first — hit the search route directly with ?q=test. If that works but the widget doesn't, the problem is in the form action/template; if the route fails, it's backend/config.
• Extension points to look for: render events/subscribers, a query-builder service you can decorate, and Twig blocks in the templates. With no ecosystem around the bundle, subclassing the widget or decorating its search service is usually cleaner than patching vendor code.
• Pin the version in composer.json ("friendsofvictoire/search-widget": "x.y.*"). Given the package's low activity, an unexpected minor bump is more likely to break than fix.