Search Laravel Package

Getting Started

This is the first assessment for guavacz/search, so treat 1.0.0-alpha.3 as the baseline. It is an alpha — pin the exact version in composer.json ("guavacz/search": "1.0.0-alpha.3") rather than using ^1.0.

1. Confirm the platform first. The only change in alpha.3 is Laravel 11 compatibility. If you are on Laravel 10, stay on alpha.2; if you are on Laravel 11, alpha.3 is the first usable release. Check the illuminate/* constraints in composer.json against your app before anything else.
2. Install and publish.

   composer require guavacz/search:1.0.0-alpha.3
   php artisan vendor:publish --provider="Guava\Search\SearchServiceProvider"
   

   Read the published config (config/search.php) end-to-end before writing code — in an alpha package the config is the most reliable description of what the package actually supports.
3. Where to look first, in order: the README usage example → src/Drivers/ (what drivers ship and what each supports) → the model trait/interface in src/Concerns/ (the contract you implement) → the Artisan commands registered by the service provider.
4. First use case: start with the simplest driver available (typically a database-backed one) and a single small model. Add the searchable trait, run the package's index command, and confirm you can round-trip: write a record → index it → query it back. Only move to an external engine once that loop is green.

Because this is a 0.x alpha, budget an hour to read the source of the driver you intend to use. It is small and it will save you guessing at behaviour later.

Implementation Patterns

• Trait-on-model, index-per-model. The usual shape is a Searchable-style trait (or interface) on each Eloquent model you want indexed, plus per-model index configuration. Keep index definitions in the model or in a dedicated Search config class, not scattered in controllers.
• Driver abstraction as a seam. Configure the driver in config, not in code, so tests and local dev can run the database driver while staging/production use the real engine. Always resolve the driver through the container rather than instantiating it.
• Keep writes and indexing separate. Rather than relying purely on model events, prefer explicit indexing in a queued job or a scheduled artisan search:index-style command. This gives you a re-runnable path when the index drifts, which it will.
• Query composition. Build queries through the package's builder so driver-specific syntax stays out of your application code, and keep the resulting query objects in a repository/action class — this makes it trivial to swap drivers or fall back to plain Eloquent if the alpha bites.
• Testing. Use the database driver plus RefreshDatabase in feature tests, and index inside the test setup. If the package ships a fake/null driver, use it for unit tests that assert what was searched rather than what came back.
• Scheduling. Wire reindexing into routes/console.php / the scheduler so a nightly full reindex is the safety net behind incremental updates.

Gotchas and Tips

• Laravel 11 is the story of this release. alpha.3 exists solely to support Laravel 11. Upgrading your app to L11 without bumping this package (or vice versa) will produce dependency-resolution failures or runtime errors from changed framework internals. Bump them together.
• Alpha churn is the dominant risk. There is no upgrade guide and no deprecation policy yet. Before each alpha bump, diff the src/ tree — signature changes to the trait, config keys, and driver contracts are the things that will silently break you.
• Config caching. After editing the search config, run php artisan config:clear. A stale cached config is the most common cause of "my driver change did nothing."
• Index drift. Records created before installation, or written via raw queries/insert() (which bypass model events), will be missing from the index. Always have a full-reindex command ready and know how to run it.
• Driver parity is not guaranteed. Features present on the database driver may be absent or behave differently on external engines (fuzzy matching, ordering, pagination totals). Verify each query feature against every driver you deploy.
• Queues. If indexing is queued, a failed job means a silently unsearchable record. Log index failures and monitor them; do not let them fail quietly.
• Debugging: drop to the database driver first to isolate whether a bug is in your query or in the engine integration, and log the raw query the driver emits before it hits the engine.
• Extension points: the driver contract and the service provider bindings are the intended extension surfaces — implement a custom driver rather than forking if you need a different engine.