Elastic Bridge Laravel Package

Product Decisions This Supports

• Search backend choice (build vs. buy vs. which vendor). v2 makes Elasticsearch vs. OpenSearch a one-line config switch (SEARCH_DRIVER) behind the same fluent API. This de-risks the vendor decision: we can standardize on OpenSearch (license cost, AWS-native) or Elasticsearch without a rewrite, and can reverse the call later at near-zero application cost.
• Roadmap sequencing for search-dependent features. Because the upgrade is breaking (env var rename, ConnectionInterface change, BridgeBuilder::all() signature), the decision "when do we ship search features vs. when do we pay the migration tax" is now coupled. Greenfield work should start on v2; in-flight v1 work should either finish on v1 behind a pinned constraint or absorb the upgrade as a scheduled ticket.
• Framework upgrade timing. v2 targets Laravel 10–12 and PHP 8.2/8.3, explicitly not Laravel 13. If our Laravel 13 upgrade is on the roadmap, this package becomes a blocker to sequence around — a real roadmap input, not a footnote.
• Data backfill / reindex strategy. Model::bulk() / Model::upsert() with automatic chunking and a BulkResult DTO (successful(), failed(), hasErrors()) turns "can we reindex 10M documents safely?" from an engineering spike into a parameterized task (bulk.max, bulk.chunk_size). That changes estimates for search-backed migrations and index rebuilds.
• Multi-tenant vs. time-series index topology. Multi-index reads (logs-* wildcard/comma) with a separate $writeIndex plus per-call from()/into() lets us model per-tenant or per-period indices without new infrastructure or a custom abstraction layer. This is a design decision the package now supports directly, and it removes a common reason to build an internal search wrapper.
• Search as a first-class Eloquent citizen (build vs. reuse). Full $casts parity, accessors/mutators, dotted nested attributes, and $appends mean search documents behave like models. That's a direct hit on "how much custom serialization/transformation code do we write?" — likely a meaningful reduction in bespoke DTO code and a reason not to build an in-house layer.
• Test and CI strategy. FakeConnection via ::fake(), now driver-agnostic and no longer broken in non-dev installs, means feature tests don't require a live cluster. That lowers CI cost and shortens the loop on search-touching PRs — an engineering-velocity argument, not just a technical nicety.
• Correctness/defect budget. Query validation (bool, match, terms_set, typed OrderOperator/RangeOperator) plus a batch of real bug fixes (filter-only count() silently counting everything, aggregation results leaking across requests in Octane/queue workers, decimal cast crashes, save() mutating shared builder state) converts classes of silent-wrong-results bugs into loud, early failures. For a PM, that's reduced risk on any feature where search results are user-facing or billing-adjacent.
• Serving topology (Octane / queue workers). The aggregation-state fix removes a genuine correctness hazard in long-lived workers. If we're on or heading to Octane or queue-heavy workers, this is a reason to prioritize the upgrade.
• AI-assisted development. The shipped Boost skill plus llms.txt docs slightly reduce onboarding cost for engineers or agents generating integration code — a modest but real input to "time to first working search feature."

When to Consider This Package

Consider it when:

• We're on Laravel 10–12 / PHP 8.2–8.3 and want search without hand-rolling a client abstraction.
• We need backend portability — OpenSearch today, Elasticsearch tomorrow, or a multi-host cluster — and don't want that choice baked into application code.
• The team already thinks in Eloquent; casting/accessor parity means models and search documents share one mental model.
• Search results must be testable in CI without a cluster.
• We need bulk backfill/reindex and multi-index or time-series reads as first-class, not as workarounds.
• We're greenfield on search, or the v1→v2 migration (env rename with no fallback, config re-publish, custom ConnectionInterface implementations, BridgeBuilder::all() call sites) is small and countable.

Look elsewhere when:

• Laravel 13 is required or imminent — unsupported, and that's a hard gate.
• We need Elasticsearch/OpenSearch capabilities well beyond what the fluent API exposes — vector/kNN tuning, ingest pipelines, transforms, SQL, ML, or fine-grained cluster administration. At that point use the official elasticsearch-php / opensearch-php clients directly and accept the coupling.
• We'd rather buy the search layer outright — managed options (Algolia, Typesense, Meilisearch) with their own Laravel integrations remove index/cluster operations entirely. Different trade-off: less control, higher per-document cost, but far less ops surface.
• The team has significant existing investment in v1 internals (custom connections, subclassed builders). The breaking surface is small in count but touches connection and pagination code paths — audit before committing.
• We're on PHP 8.1 or below, or need Carbon 2 — v2 requires Carbon 3.8.4+.
• No one owns the search cluster operationally. This package is an application-layer client; it doesn't remove the need for index design, shard sizing, and upgrade ownership.

How to Pitch It (Stakeholders)

To executives: ElasticBridge 2.0 removes search vendor lock-in from our architecture. Elasticsearch and OpenSearch become a configuration value rather than a code decision, so we can negotiate on price and switch providers without a rewrite. It also closes several correctness bugs that could have produced wrong search results silently — including a filter bug in count() and state leaking between requests in long-running workers — which reduces risk on any user-facing or reporting feature built on search. The cost is a one-time, well-documented upgrade: renamed environment variables, a config re-publish, and updating custom connection code. No new infrastructure or licensing is required.

To engineering: v2 gives us Eloquent-grade ergonomics on search documents — full $casts, accessors/mutators, dotted nested attributes, $appends — so we stop writing bespoke serialization. Model::bulk()/upsert() with chunking and a BulkResult DTO makes reindex jobs routine. Multi-index reads with a separate write index let us do per-tenant and time-series indices without a custom layer. Queries are validated at build time and throw InvalidQuery instead of failing at the cluster. ::fake() gives us driver-agnostic feature tests with no cluster in CI. The upgrade is breaking but bounded: SEARCH_* env rename (no fallback), re-publish config, implement search()/count()/index()/update()/bulk() on any custom ConnectionInterface, fix BridgeBuilder::all() call sites, and drop the removed from/to range operators in favor of gt/gte/lt/lte. Note the ceiling: Laravel 10–12 only, PHP 8.2/8.3, Carbon 3.8.4+, and illuminate/database is now a runtime dependency (for the casting layer) — worth confirming that's acceptable in any non-full-Laravel service. If we need features beyond the fluent API, we should plan to drop to the official client rather than fight the abstraction.