Meilisearch Laravel Package

Getting Started

This is Lunar's Meilisearch driver — an RC-stage companion package that plugs Meilisearch in as the search engine behind Lunar's product search. It is not a standalone search package; it assumes a working lunarphp/lunar install with products already in the database.

Minimum setup:

1. composer require lunarphp/meilisearch:0.1.0-rc.2 — pin the exact RC. Because it's pre-1.0, don't rely on ^0.1 resolving to something stable.
2. Run a compatible Meilisearch server (Docker is simplest) and set MEILISEARCH_HOST / MEILISEARCH_KEY in .env. This release bumps meilisearch-php to ^0.26.1, so match your server image to that client's supported server range rather than pulling latest.
3. Publish the package config (php artisan vendor:publish) and read it first — that's where the index name/prefix, searchable attributes, and filterable/sortable attribute lists live. This config file is the single most important thing to understand before touching code.
4. Register the driver/service provider if it isn't auto-discovered, then run the package's index command to push your catalog into Meilisearch.

First use case: index the existing product catalog, then wire a storefront product listing to Lunar's search facade so the listing page reads from Meilisearch instead of Eloquent. Verify with a few known products that hits, filters, and sorting return what the database says they should.

Implementation Patterns

Full index vs. incremental. The package's index command is a batch operation — run it on deploy or as a queued job after catalog imports. Day-to-day correctness comes from model observers keeping documents in sync on create/update/delete. Treat a full reindex as the repair path, not the normal path.

Queue everything. Indexing and document updates should run through queue workers. On a large catalog, a synchronous full index will time out the request or exhaust memory; chunk the source query and let workers drain the queue.

Attribute config drives everything. If a filter or sort works in the database but not in search, the cause is almost always a missing entry in the filterableAttributes / sortableAttributes settings. Change those lists and you must re-apply settings and reindex — they are not derived from your models automatically.

Multi-store / multi-channel. If you run several channels or stores, use distinct index names (a config prefix) per channel rather than filtering one shared index. This keeps channel-specific visibility rules and pricing from leaking across storefronts.

Testing. Swap the search driver to the collection/null driver in the test suite where possible. Where you genuinely need Meilisearch, use a per-test index prefix and truncate between tests; otherwise you'll get cross-test bleed that looks like flaky relevance.

CI. Add a Meilisearch service container (or docker-compose service), pin the image tag explicitly, and poll the /health endpoint before running tests. Unpinned images are the classic cause of a green build turning red overnight with no code change.

Gotchas and Tips

• RC stability. 0.1.0-rc.2 is a dependency-maintenance release — the only change is the meilisearch/meilisearch-php constraint moving to ^0.26.1. No breaking changes for your code, but it does mean your resolved client version moves; if you'd pinned meilisearch-php yourself, reconcile the two constraints rather than letting Composer pick.
• Client/server version drift. meilisearch-php versions track server versions closely. Pin your Docker image to match the client, and upgrade them together. Upgrading the server ahead of the client is a reliable source of confusing 400s.
• Async tasks. Document writes are queued as Meilisearch tasks. Code that writes and immediately reads will intermittently see stale results. In tests and in any user-facing "save then view" flow, wait on the task (or accept eventual consistency) instead of asserting instantly.
• Visibility leaks. Soft-deleted, unpublished, and out-of-stock products are the usual culprits for "ghost" search results. Confirm the indexer's source query applies the same scopes and channel constraints as your storefront listings.
• Pagination limits. Meilisearch caps the number of retrievable hits (maxTotalHits). If your catalog is large, a "show all / deep pagination" UI will silently stop returning results past the cap — set the limit explicitly in index settings and reflect it in the UI.
• Debugging. When results look wrong, inspect the Meilisearch task list (GET /tasks) first — failed indexing tasks explain most "the document isn't there" reports. Then dump the actual document and compare against the model.
• Extension points. The indexer and the config's attribute lists are the two intended seams: add custom searchable fields by extending the indexer/document payload and mirroring them in the settings. Prefer that over editing vendor code, since RC releases will move.
• Upgrade hygiene. Read the changelog on every RC. These releases are small and frequent, and the dependency constraints are the part most likely to affect you.