Meilisearch Php Laravel Package

Technical Evaluation

Architecture fit

• This is a thin, stateless HTTP SDK — not a Laravel package. There is no service provider, facade, config file, or published migration path. It is a PSR-18 client wrapper around the Meilisearch REST API, which means it drops into any Laravel version cleanly but contributes zero framework glue. A TPM should scope a small internal adapter layer (singleton binding, env-driven config, health check endpoint, SearchService interface) as part of the adoption cost rather than assuming composer require equals "integrated."
• The PSR-18/PSR-17 indirection is a genuine architectural asset: HTTP client choice is swappable (Guzzle 7, Symfony HttpClient, cURL, Buzz), so the package does not dictate our transport, timeout, retry, or middleware story. It also means we can inject a pre-configured client with connection/read timeouts — essential for preventing search from becoming a latency amplifier on page render.
• Two viable integration shapes exist, and they are not equivalent:
  • Via Laravel Scout — Scout owns model-to-index syncing, observers, and queueing; the SDK is an implementation detail. Less code, less control.
  • Direct SDK — full control over document shape, index settings, task handling, and multi-search; we own all sync logic. More code, more control.
  • The choice should be made before estimation, because it changes effort materially.

Integration feasibility

• Low technical friction: Composer install plus an HTTP client/factory pair, an env var for host and key, and a handful of lines to construct the client. A working prototype is a same-day spike.
• The real complexity is not the SDK — it is Meilisearch's operating model, which the SDK faithfully exposes: asynchronous tasks, index settings that trigger rebuilds, and filterableAttributes needing to be declared before filtering works. Teams underestimate this because the API surface looks trivial.

Technical risk

• Version maturity is the headline risk. The most recent release shown is v2.0.0-beta.8, and it contains documented breaking changes from v1.x: Indexes → Index, lazy metadata loading with fetchInfo()/fetchPrimaryKey() removed, non-nullable getters, MultiSearchQuery split out of SearchQuery, and typed stats objects. Adopting a beta SDK in a production Laravel app should require explicit justification; defaulting to the stable ^1.x line and pinning the Meilisearch server version alongside it is the lower-risk position.
• Async-by-default write path. addDocuments() returns a task UID, not a result. Documents are not searchable until the task succeeds. Any product requirement like "user saves a record, then immediately finds it in search" is a design problem, not an SDK call. This affects UX copy, test strategy, and queue design.
• Settings changes are deploy events. Updating filterable/sortable attributes rebuilds the index. Treating these as runtime configuration will cause visible outages on large datasets.
• Read-path hard dependency. Once search backs primary navigation or listing pages, Meilisearch availability becomes a product availability question. The SDK gives no circuit breaker or fallback — that is ours to build.
• Diligence flag: the "dependents: 0" figure is inconsistent with the package's actual role as the engine behind Laravel Scout's Meilisearch integration. Verify against Packagist before repeating it in any decision document; treat the score as a generic popularity heuristic that does not model official-SDK-of-a-platform projects.
• Key handling. The master key must never reach the client. Scoped/tenant API keys or signed tenant tokens are mandatory for any multi-tenant or per-user-filtered search.

Key questions to resolve before commitment

1. Is the server Meilisearch Cloud or self-hosted, and who owns uptime?
2. Stable ^1.x or beta 2.x — and what feature justifies the beta?
3. Scout or direct SDK — and does that decision survive a future engine swap?
4. What is the freshness SLA between a write and searchability?
5. What is the documented degraded-mode behavior when search is unavailable?
6. What are the index size, attribute count, and RAM budget, and who runs the sizing exercise?
7. Do we need multi-tenancy or per-user result scoping, and therefore tenant tokens?

Integration Approach

Stack fit

• Verify the SDK's PHP constraint against our runtime before anything else; v2 beta lines typically raise the floor. Also confirm Guzzle 7 vs. Symfony HttpClient alignment with what the app already ships — installing a second HTTP client purely for search is avoidable dependency debt.
• If Scout is already in the codebase (or acceptable), that is the fastest path and gives model observers, queue integration, and searchable() conventions for free. If search requires custom ranking, federated multi-index queries, or non-Eloquent document shapes, go direct and budget the adapter.

Migration path

• From MySQL LIKE/FULLTEXT: the substantive work is index design — document shape, searchable vs. filterable vs. sortable attributes, ranking rules, typo tolerance. Plan a backfill command and a settings-versioning convention from day one.
• From Algolia (via Scout): mostly a driver swap plus settings re-mapping. Algolia's filter syntax, ranking, and replica concepts do not translate one-to-one; budget a settings-parity review rather than assuming config portability.
• From a bespoke solution: hide the SDK behind an internal interface so the vendor is a replaceable detail.

Compatibility

• Maintain an explicit supported matrix: SDK version ↔ Meilisearch server version ↔ PHP version. The README promises compatibility with Meilisearch v1.x but explicitly notes partial feature coverage, so "compatible" is not "complete."
• Pin both sides in composer.json and in infrastructure config; a server upgrade landing ahead of an SDK upgrade is a realistic skew scenario.

Sequencing

1. Spike: stand up Meilisearch, index a realistic sample, validate typo tolerance, filtering, and ranking against real queries.
2. Adapter: config, container binding, SearchService interface, health check, custom HTTP client with aggressive timeouts.
3. Read path in shadow mode: build the index in parallel, compare result quality offline, no user exposure.
4. Write path: queued indexer jobs plus a backfill/reindex Artisan command; add task-status monitoring before enabling.
5. Cutover behind a feature flag with a fallback path to the legacy query.
6. Decommission the old search and delete obsolete indexes and keys.

Operational Impact

Maintenance

• Vendor-maintained, MIT-licensed, with CI, coverage reporting, and a Docker-based contributor workflow — a materially better maintenance posture than a typical community package. But it is vendor-controlled and moves on the vendor's schedule; an annual major-version review and a quarterly patch cadence should be scheduled, not assumed.
• Budget recurring effort for SDK upgrades (v2 shows these are non-trivial: renames, removed methods, changed nullability) and for Meilisearch server upgrades.

Support

• OSS support is community-only (Discord, GitHub issues) with no SLA. If search is customer-facing, either buy Meilisearch Cloud for a contractual escalation path or accept that we are the escalation path. Name an internal owner for search — an unowned search tier degrades quietly.

Scaling

• Meilisearch holds indexes in memory and is RAM-bound; capacity planning is a function of document count, attribute count, and filterable/sortable cardinality, not request volume alone. Run a sizing exercise on production-shaped data before launch, not after.
• Task queue throughput is its own scaling dimension. Bulk imports and reindexes compete with live indexing; schedule them off-peak or throttle them.
• High availability in the open-source edition is limited to snapshots and dumps — failover and multi-node are the paid/Cloud story. Confirm that our availability target for search is achievable on the chosen deployment.

Failure modes

• Search outage → page errors if unguarded. Mitigate with timeouts, a circuit breaker, and a cached or database-backed fallback for critical paths.
• Silent task failures → documents missing from results with no user-visible error. Mitigate with task-status polling, alerting on failed/canceled tasks, and a periodic reconciliation job comparing source-of-truth row counts to index document counts.
• Index drift from writes that bypass the sync path (direct DB edits, imports, migrations) → mitigate with a scheduled full reindex and a documented runbook.
• Rebuild storms from settings changes → freeze settings during peak, version them, and treat changes as deploys.
• Key exposure in logs or client bundles → master key server-side only; scoped keys for anything else.

Ramp-up

• For a competent Laravel developer, the SDK itself is a one-to-two-day learning curve; the substantive ramp is Meilisearch semantics — documents, indexes, settings, ranking rules, and the task lifecycle — plus the sync architecture.
• Ops ramp-up covers snapshot/restore, reindex execution time on production data, and the degraded-mode runbook. These should be rehearsed before cutover, not discovered during the first incident.