Search Laravel Package

Getting Started

capell-app/search gives you a driver-based search abstraction for Laravel: you mark Eloquent models as searchable, an indexer pushes them into a backend (database/engine-specific), and a single query API stays the same when you swap drivers.

1. composer require capell-app/search and publish the config (php artisan vendor:publish --tag=search-config or whatever tag the README lists).
2. Look here first: the published config/search.php (default driver, per-driver connection/index settings) and the package README's driver table. These two files tell you more about day-to-day behaviour than the source.
3. Set the driver in .env (e.g. SEARCH_DRIVER=database locally, an engine driver in staging/production) — never hardcode the driver in code.
4. First use case: take one small, read-heavy model, add the searchable trait + its index definition, run the package's index command, then query it from a controller and render paginated results. Doing this end-to-end on one model exposes all the config you'll need for the rest.

Implementation Patterns

• Trait on the model, mapping in one place. Keep the "what is searchable" declaration (fields, weights, filters) next to the model or in a dedicated indexer class, not scattered in controllers. When the mapping changes, you reindex — that's a deploy concern, so make it one file to review.
• Wrap the package behind your own service/repository. A thin SearchService (or per-model query objects) that takes validated criteria and returns a paginator means driver swaps, engine downtime, and future package upgrades don't leak into Blade templates and controllers.
• Two-tier indexing strategy. Small datasets: index synchronously on save. Anything large: queue the indexing job, and keep a scheduled full reindex (nightly/weekly) as the source of truth. Synchronous indexing inside a request is the most common cause of slow saves in this kind of package.
• Bulk operations must be followed by a reindex. Model::query()->update([...]), insert(), seeders, and raw SQL all bypass model events, so the index silently goes stale. Put a reindex step in the seeder and in any data-migration path.
• Deploy pipeline order: migrate → reindex → clear caches → restart queue workers. Index commands belong in the deploy script, not in someone's memory.
• Testing: point the test suite at the database driver (or a fake/in-memory equivalent) in phpunit.xml so tests don't need a live search cluster. Assert on your own SearchService return shape rather than on engine-specific scores.
• Filters and pagination: decide early whether filters run in the driver or in SQL after retrieval. Mixing the two produces result counts that don't match the paginator, which is hard to debug later.

Gotchas and Tips

• Driver parity is a real cost. Relevance ranking, fuzzy/prefix matching, and filter syntax differ per driver. The database driver is great for local dev and tests but its ordering won't match the production engine — always smoke-test ranking in staging with production-like data.
• php artisan config:cache will freeze your driver/index settings. After changing search env vars locally or in CI, re-run config:clear, or you'll debug a config that isn't being read.
• Queue workers cache code. After deploying changes to index definitions, queue:restart — otherwise old workers write documents in the old shape.
• Transactions vs. queued indexing. A job dispatched inside a DB transaction can run before commit. Use dispatchAfterResponse/afterCommit (or index in an onSaved hook guarded by commit) so you never index a row that then rolls back.
• Debugging empty results: check in this order — is the record actually in the index (count the index), is the driver correct for this env, does the mapping include the field you're querying, then the query itself. Nine times out of ten it's a stale index from a bulk update.
• Extension points: the driver contract and the indexer/mapping classes are where to hook in custom behaviour (custom analysers, extra filters). Prefer extending those over forking the query builder — forks are what make patch upgrades painful.
• On v1.0.48 specifically: this is a patch release with an empty changelog (just a compare link from v1.0.47). There are no advertised breaking changes, features, or deprecations, so nothing in your day-to-day usage should change. Still, since search sits on a hot path, skim the diff between the two tags before bumping in production, pin the version in composer.json rather than floating on ^1.0, and re-run your index + a sample query after upgrading to confirm index format compatibility.