Statamic Live Search Laravel Package

Getting Started

This release is a compatibility drop: it adds Statamic v6 and Laravel 13 support and types the $q property on the Search component. There are no new APIs and no deprecations, so the getting-started path is unchanged whether you're on v3.1 or v3.2.

1. composer require <vendor>/<package> — the constraint now resolves against statamic/cms:^6.0 and laravel/framework:^13.0. On Statamic 5 / Laravel 11–12, pin ^3.1 until you upgrade the host app.
2. Publish the config (php artisan vendor:publish --tag=<package>-config) and read it first — the index/collection handles live there, and that's the file that answers 80% of "why isn't my entry showing up" questions.
3. Rebuild the search index with the addon's Artisan/Please command. Do this immediately after upgrading. The index is persisted, and stale documents from a pre-v6 Statamic install are the most likely source of odd results after this release.
4. First use case: drop the Search component (or Antlers tag) into a layout, bind the query input to $q, and render results. That single-wire-up is the fastest way to confirm the install is healthy before you customize anything.

Where to look first: the component class itself (it's the public contract for anything you extend), then the config, then the indexing code path.

Implementation Patterns

Component-per-surface, not per-page. Instantiate the Search component once in the layout and pass context (collection handle, filters, result limit) as props. Re-instantiating per template fragments your query state and makes $q resets feel random.

Bind $q live, debounce in the input. wire:model.live.debounce.300ms="q" is the sane default. Keep the component's updatedQ() hook as the single place results are recomputed — don't scatter query logic across Blade and PHP.

Treat $q as the untrusted-input boundary. Trim, length-cap, and sanitize it before it hits the index driver. Search endpoints are the classic place where a raw user string becomes a wildcard query that scans the whole corpus.

Index on the write path, rebuild on deploy. If the package exposes events on entry save/publish, subscribe to them rather than running a full re-index on a schedule. Add the full rebuild to your deploy script so content-model changes (new fields, new collections) don't silently drop out of results.

Extend by subclassing the component, not forking it. Add typed properties and methods to your own subclass; keep the render view override in your theme. This is what makes the Laravel 13 / Statamic 6 jump survivable.

Test the search contract, not the index. Assert that a known entry for a known term appears in the top N — run it against a small fixture index in CI. Full-corpus assertions are flaky and slow.

Gotchas and Tips

• The $q type declaration can break your subclass. PHP property types are invariant: if you extended the Search component and redeclared public $q; (untyped) or typed it as ?string, v3.2 is a fatal error, not a warning. Grep your codebase for $q overrides before upgrading. If you must redeclare, match the parent type exactly.
• Typed properties make null a TypeError. If $q is now string, any wire:model binding, query string (?q=), or programmatic $component->q = null that previously worked on an untyped property will now throw. Coerce at the boundary: $this->q = (string) $request->query('q', '').
• Statamic v6 is a major bump. Budget for: Antlers/runtime behavior changes, addon-level compatibility across your other addons (the search addon being ready doesn't mean the rest of your stack is), and a PHP version floor increase. Upgrade Statamic and Laravel in separate commits so a failure is attributable.
• Laravel 13 means Laravel 13's deprecations. Anything this package touches indirectly — service provider boot order, queue serialization of the Search component (Livewire components get serialized into queued jobs), container bindings — can surface as a runtime failure well away from the package.
• Rebuild the index after the upgrade. Schema and document serialization can drift between Statamic majors. A stale index often presents as "results work but ranking is wrong", which is much harder to diagnose than a hard error.
• Cache is the other invisible culprit. If results are cached by raw $q, either version the cache key by package version or flush the search cache on deploy; otherwise a working upgrade looks broken for hours.
• Debug in this order: is the document in the index (query the driver directly) → does the component receive $q (dump it) → does the driver return hits → does the view render them. Most "search is broken" reports stop at step one.
• Extension points to prefer: config (index handles, field weights), events on content save, and view overrides. Avoid overriding the component's protected internals — this release is proof that internal signatures move.

Verdict: low-risk upgrade if you don't subclass the component. Ship it, but pair it with an index rebuild and a smoke test on your most common query.