Filagora Search Laravel Package

Product Decisions This Supports

• Search feature scoping: Enables a Laravel product team to add search without designing indexing lifecycle, engine abstraction, filtering, failover, and health checks from scratch. The package supports a pragmatic MVP path: start with the DatabaseEngine fallback for low-risk search surfaces, then enable Meilisearch when relevance/latency requirements justify the operational cost.
• Build vs. buy: Strong argument for buying/adopting rather than building the undifferentiated glue: model save/delete/restore hooks, queued SyncSearchDocument, post-commit indexing, reindex/backfill commands, circuit breaker, database fallback, and an engine conformance suite. These are costly to build correctly and easy to get subtly wrong.
• Roadmap sequencing: Supports a phased search roadmap: (1) register indexes and expose database-backed search, (2) enable Meilisearch with settings sync and filter compilation, (3) add grouped/partial updates for large documents, (4) evaluate additional engines through the SearchEngine contract, (5) operationalize via filagora:search:check-health and filagora:doctor.
• Reliability decisions: The circuit breaker plus database fallback is a product-level reliability lever. PMs can decide which search surfaces may degrade to database results during engine outages and which must fail loudly.
• Operational model choices: The package exposes meaningful product/ops trade-offs: synchronous vs. queued indexing, after-commit vs. immediate indexing, batch size/pause/limit for reindex, and index prefixes for environment isolation. These map directly to launch readiness and incident-response decisions.
• Use cases: Product catalog search, CMS/content search, internal admin search, SaaS tenant search where indexes can be prefixed, and any Laravel domain with model-backed searchable records. Less suitable as a differentiator for advanced semantic/vector search or complex relevance tuning without additional engine work.
• Testing and CI decisions: ArrayEngine, EngineConformance, and CI/DDEV-started Meilisearch reduce the cost of validating search behavior. PMs can require conformance tests before swapping engines or upgrading.

When to Consider This Package

Consider adoption when:

• The product is Laravel/PHP and search is a real but not yet highly differentiated capability.
• The team wants Meilisearch-backed search with a database fallback rather than building indexing, filtering, health checks, and failover glue.
• Index freshness on model save/delete/restore matters, and the team wants queued, post-commit indexing with failures logged rather than breaking writes.
• The product needs a portable filter tree (Equals, In, Range, All, Any, Not) rather than engine-specific filter syntax scattered through application code.
• Ops can run Meilisearch or accept database fallback behavior, and can wire health checks into deployment/monitoring.
• The team values testability via ArrayEngine and an engine conformance suite.
• A pilot or non-critical search surface is acceptable while the package matures.

Look elsewhere or wait when:

• The product needs a mature, stable 1.0 API with long-term compatibility guarantees. This is v0.1.0 and should be treated as early.
• Required engines are not Meilisearch, database, or in-memory array. The SearchEngine contract exists, but additional adapters are adoption work.
• Advanced search capabilities are core differentiators: semantic/vector search, sophisticated relevance tuning, complex faceting/aggregations, typo tolerance controls, document-level security, or multi-language analyzers are not evidenced here.
• The team cannot operate Meilisearch and cannot tolerate database fallback semantics.
• Very large-scale indexing, cross-region search, or strict SLA/search SLO requirements exist without further operational validation.
• The product needs rich search UI features not covered by the current filter/query/result contracts.

How to Pitch It (Stakeholders)

For executives: This package lets us ship Laravel search faster with less bespoke infrastructure. It handles the boring-but-risky parts—keeping indexes fresh, reindexing, health checks, filtering, and falling back to the database if the search engine is down—so search outages degrade instead of breaking core workflows. The main caveat is maturity: v0.1.0 is an early release, so we should pilot it on a non-critical search surface before making it a platform dependency.

For engineering: It provides a clean SearchEngine/SearchIndex contract, a registry, portable filter tree, Meilisearch adapter without an SDK dependency, queued post-commit indexing, reindex/backfill commands, circuit breaker with database fallback, and a conformance suite for engine adapters. It reduces glue code and gives us test seams (ArrayEngine, DatabaseEngine) plus operational checks (filagora:search:check-health, filagora:doctor). Risks: 0.x API churn, only Meilisearch is production-oriented today, and we must validate indexing semantics, queue behavior, and fallback behavior under load.

Ask: Approve a bounded pilot on one search surface, with Meilisearch run in a controlled environment, health checks wired into monitoring, and an explicit exit plan if the 0.x API or operational model proves unstable.