Statamic Live Search Laravel Package

Getting Started

This release is primarily a compatibility drop-in — no new APIs, no config changes. Onboarding is unchanged from v3.x:

1. composer require <vendor>/<package> (requires Laravel 13 / Statamic v6 on this version — see Gotchas for version pinning).
2. Publish the config: php artisan vendor:publish --tag=<package>-config.
3. Add the search driver/connection to config/<package>.php and, if you're indexing Eloquent models, add the searchable trait to the model.
4. Build the index: php artisan <package>:index (or the sync command named in the config).
5. Drop the Search component into a Blade view and hit the route.

First use case: the Search component. It's the fastest path to value — it wires up the query input, pagination and result rendering in one place, and it works identically against Eloquent models and Statamic entries. Get the component rendering results for a single collection before touching the driver config or relevance tuning.

Where to look first: the config file (driver + index name), then the Search component class — that's where the $q property lives and where most customisation requests land.

Implementation Patterns

Component-first search. Treat the Search component as the default integration point rather than hand-rolling a controller. Bind it to a route, pass the collection/model scope in, and let it own the query string, pagination and empty states. This keeps upgrade surface small — the v3.2.0 type declaration on $q confirms the component is the actively maintained path.

Scope by driver, not by branching. When you support both Eloquent and Statamic (increasingly common now that Statamic v6 is supported), keep a single component and switch the driver in config per environment. Branching on instanceof inside the component duplicates logic and tends to break on minor releases.

Livewire integration. The component is designed to be hydrated — bind $q with wire:model.live.debounce.300ms (or your Livewire equivalent) and let the component re-query. Do not re-implement debounce in your own JS; double-debouncing produces dropped keystrokes and confusing "missing result" bug reports.

Index lifecycle in CI/deploy. Add the index/sync command to your deploy pipeline after migrations, not before. For staging, run a full reindex rather than incremental sync — partial indexes make relevance issues unreproducible.

Extension points. Custom drivers and query macros are the sanctioned hooks for relevance tuning. Prefer a macro over forking the component; macros survive minor upgrades, forks don't.

Upgrade pattern for this release. Bump the constraint, run the suite, then grep for extends on the Search component and any $q overrides (see Gotchas). That's the entire migration for v3.2.0.

Gotchas and Tips

The $q type declaration is a potential breaking change for subclasses. Adding a type to a property that previously had none means any class extending the Search component and redeclaring $q without the matching type will fatal with "Type of X::$q must be ... (as in class Y)". This is a compile-time error, not a warning — the page 500s on the first request after deploy. If you extend or override the component, either remove your $q redeclaration or match the upstream type exactly. Grep for \$q before upgrading; this is the only realistic breakage in v3.2.0.

Pin your framework versions deliberately. Laravel 13 and Statamic v6 support arriving together means the v3.2.0 constraint likely excludes older majors. If you're mid-upgrade on Laravel 12 or Statamic v5, stay on the previous v3.x line and upgrade in lockstep — don't let composer update resolve a version your app can't boot. Check composer why-not rather than guessing from the release notes.

"Supports X" ≠ "requires X" — verify before assuming. Release notes say support was added; confirm whether the version constraint is ^13.0 only or ^12.0|^13.0. An overly tight constraint is a common cause of unresolvable dependency graphs on mixed-version teams.

Debug the query before the index. When results look wrong, dump the underlying query (query log or toSql() on the builder) before reindexing. Reindexing is slow and masks the real problem roughly half the time; a WHERE clause scoped to the wrong collection is the usual culprit.

Empty $q behaviour. Components of this shape typically short-circuit on an empty string — verify whether blank input returns nothing or the full set. It changes your empty-state copy and, more importantly, your pagination counts.

Config caching. If results change in php artisan tinker but not on the web, you're on a cached config: php artisan config:clear. Standard Laravel, but people burn an hour on it because it looks like an indexing bug.

Relevance tuning is a config concern, not a component concern. Resist editing the component to reorder results. Driver-level weights and macros survive upgrades; component edits become merge conflicts on every release.