Search Laravel Package

Getting Started

lunarphp/search is Lunar's search abstraction layer — it indexes your product models into a search engine and exposes a single query API regardless of backend. This alpha (0.1.0-alpha.16) now ships a Meilisearch driver, so you have more than one engine to choose from out of the box.

Minimal setup:

1. composer require lunarphp/search:0.1.0-alpha.16
2. Publish the config (php artisan vendor:publish --tag=lunar-search-config — check the package's service provider for the exact tag) and set the default driver.
3. Point the package at your engine. For Meilisearch add the Composer client (meilisearch/meilisearch-php) and set:

   // config/search.php (or config/lunar/search.php)
   'driver' => 'meilisearch',
   'meilisearch' => [
       'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
       'key'  => env('MEILISEARCH_KEY'),
   ],
   

4. Run the indexer: php artisan lunar:search:index (verify the actual command name with php artisan list | grep search), or trigger indexing via the provided model observers/jobs.
5. First use case: a product listing/search page. Register your searchable models, index them, then query through the package's facade so you can swap drivers later without touching controllers.

Look first at: the package's config file, the SearchEngine contract / driver classes, and any Searchable trait or indexer classes — that's where the day-to-day extension points live.

Implementation Patterns

Driver-based querying. Always query through the package's manager/facade rather than instantiating Meilisearch\Client yourself. That's the whole point of the abstraction — switching from the database driver in dev to Meilisearch in production should be a config change, not a code change.

use Lunar\Search\Facades\Search; // confirm the actual facade FQCN

$results = Search::products()
    ->where('status', 'published')
    ->search($request->input('q'))
    ->paginate(24);

Keep indexing out of the request cycle. Register the package's indexer as a queued job in your model observers (created, updated, deleted) so a product save in the admin panel doesn't block on an HTTP call to Meilisearch. Batch re-indexing belongs in a scheduled command.

Per-environment drivers. Use the database driver for local/tests (fast, no external service, deterministic) and Meilisearch for staging/production. Add a search service to your docker-compose.yml/Sail so local can opt in when you need to reproduce ranking behaviour.

Filters vs. query string. Treat free-text (search()) and structured filters (brand, collection, price range, stock) as separate concerns. Structured filters map cleanly to Meilisearch's filterable attributes; make sure you declare them as filterable in the index settings or they'll be silently ignored.

Integration with Lunar models. Bind the package's searchable interface/trait onto your Product (and any variant/collection models you want surfaced). If you have custom attributes, ensure they're included in the indexable document payload — the default mapping will only cover core fields.

Testing. In tests, force the database/array driver via config()->set() in your base TestCase so CI doesn't need a Meilisearch instance. Add a separate, opt-in integration test suite for the Meilisearch path.

Gotchas and Tips

• Alpha software. 0.1.0-alpha.* means the config keys, contracts, and even command names can change between patch releases. Pin the exact version in composer.json ("lunarphp/search": "0.1.0-alpha.16") and read the changelog before every bump. This release is a good example: a whole new engine landed in a patch-level alpha bump.
• Upgrading to this release. The Meilisearch engine is additive, but confirm (a) whether the config file gained new keys that need re-publishing — run vendor:publish --force and diff rather than blindly overwriting, and (b) whether meilisearch/meilisearch-php is a suggested/optional dependency you need to add yourself. Alpha packages frequently ship new drivers without pulling the client in.
• Meilisearch-specific setup is required, not optional. Create the index, push your filterable/searchable/sortable attribute settings, and only then index documents. Indexing before settings are applied is the #1 cause of "filters don't work" confusion. Also check your Meilisearch version against the PHP client's supported range.
• Filterable attributes are a hard requirement. Meilisearch errors (or returns nothing) if you filter on an attribute not declared filterable. The database driver won't catch this for you, so test the Meilisearch path explicitly in staging.
• Stale indexes are silent. There's no automatic reconciliation. Add a scheduled search:index (or equivalent) as a safety net, and log failures from the indexing jobs — a failed job leaves the document stale with no user-facing error.
• Debugging. Start with the driver: dump config('search.driver') to confirm which engine actually ran, then php artisan tinker a raw client call against Meilisearch to isolate whether the problem is in the package's query builder or the engine itself.
• Extension points. If you need a custom engine (Algolia, Typesense, Elasticsearch), implement the package's engine contract and register it in the manager rather than forking — the new Meilisearch driver is the reference implementation to copy.
• Watch the repo, not just Packagist. With a single-maintainer, fast-moving alpha, tracking lunarphp/search releases and the PR list directly is more reliable than waiting for docs to catch up — Meilisearch support in particular may be under-documented at the time of release.