Enterprise Search Laravel Package

Technical Evaluation

Architecture fit

• The package is the official PHP client for Elastic Enterprise Search — the service layer that fronts App Search and Workplace Search. It is not a general-purpose Elasticsearch client; its value is namespaced, typed access to appSearch(), workplaceSearch(), and entSearch() endpoint groups on top of a shared transport.
• Under the hood it composes elastic/elasticsearch and elastic/transport. That is architecturally convenient (one retry/auth/connection story, PSR-18 pluggable HTTP) but it also means the package is a thin veneer: roughly 90% of the capability is reachable with elasticsearch-php plus a base URI, which is exactly why the standalone client has minimal adoption.
• For a Laravel monolith it fits the "backend service client" slot cleanly, not the "framework package" slot. There is no service provider, no config publish, no facade, no Scout driver. That is not a defect — it is a ~100-line integration we own — but it must be costed as custom glue rather than a dependency install.
• Fit is best where search relevance is a product surface (catalog search, document/knowledge search with curations and synonyms) and weakest where search is incidental filtering.

Integration feasibility

• Straightforward technically: Composer install, a singleton binding in a service provider, credentials from config/services.php and env, and a thin SearchService interface in front of it. A competent Laravel engineer reaches a working vertical slice in one to three days.
• The only real technical wrinkle is dependency alignment: the client pins compatible ranges of elasticsearch/elasticsearch and elastic/transport. If the application already uses elasticsearch-php for other indices, expect a resolution conflict or a forced upgrade. Verify in a branch before committing.
• No Laravel-version coupling beyond PHP and PSR-18, so a Laravel 9–12 floor is safe as long as PHP is 8.1+.

Technical risk

• Product lifecycle is the dominant risk, not code quality. Elastic has deprecated Enterprise Search as a product line and folded relevance features into Elasticsearch itself; Workplace Search has reached end-of-life. Adopting this client is a bet on a sunset surface. Any roadmap that assumes a multi-year horizon on App Search needs explicit sign-off, and the architecture must assume a future migration to elasticsearch-php + Search Applications / vector search.
• Adoption signal is weak. 25 stars and zero dependents means almost no community corpus: no blog posts for the failure you will hit, no Scout driver you can lean on, no third-party patches. Support is effectively "read the generated source and the API docs."
• Version lockstep. Client releases track the server release train; a cluster upgrade and a Composer bump must be coordinated. Silent drift between client and server is a plausible production incident.
• Low blast radius, though. The surface is a handful of HTTP calls behind our own interface. Worst case is a contained rewrite, not an architectural unwind — provided we do not let vendor response objects leak into domain code.

Key questions

1. Is the search surface strategic for the next 24 months, or a feature we could satisfy with database search or a managed SaaS?
2. Which Enterprise Search capability do we actually need — App Search relevance tuning (curations, synonyms, engines), or just document retrieval? If the latter, the client is overkill.
3. Do we already depend on elasticsearch-php anywhere? What is the resolution outcome?
4. Do we hold an Elastic subscription (support, ent-search entitlement), or is this unlicensed self-managed?
5. Who owns the eventual migration off Enterprise Search, and on what trigger?

Integration Approach

Stack fit

• Laravel 10/11/12, PHP 8.1+, Composer. Bind Elastic\EnterpriseSearch\Client as a singleton in a dedicated SearchServiceProvider; expose it only through our own SearchEngine contract so no controller or model ever touches a vendor object.
• Credentials in config/services.php, secrets in the environment/secret manager, never in the repo. App Search uses API-key/token auth — treat keys as per-environment and rotate them.
• Queue all writes. Indexing belongs in jobs with retries and dead-letter handling; only reads happen in the request path, with a short timeout and a fallback.

Migration path

• If greenfield: start behind the interface, not against the client. Define SearchEngine (index, delete, search, suggest) before installing anything.
• If replacing raw cURL or a hand-rolled ent-search wrapper: swap implementation behind the same interface, run both in parallel for a sprint on shadow traffic, then cut over per search surface.
• If the eventual destination is Elasticsearch-native: keep the interface search-shaped (query in, ranked IDs + highlights out) so the replacement is one class, not a refactor.

Compatibility

• Confirm PHP and Guzzle/PSR-18 adapter compatibility; run composer why-not elastic/enterprise-search in a scratch branch early.
• Pin the client minor version and the cluster version together in the runbook; treat them as a single upgrade unit.
• Verify against the actual cluster version in staging — this is the one compatibility check that matters.

Sequencing

1. Spike (≤1 week): Composer resolution, auth, one index + one query against staging. Kills the dependency-conflict risk cheaply.
2. Foundation (1 sprint): provider, config, SearchEngine contract, one adapter, health check command.
3. First surface (1–2 sprints): one search experience end to end, including indexing jobs, relevance tuning, and observability.
4. Gate review: measure relevance quality and latency against a baseline; decide whether to expand or stop. Do not commit to surfaces two and three before this gate.
5. Rollout: remaining surfaces, then decommission the old path and remove dead config.

Operational Impact

Maintenance

• Low day-to-day code maintenance — it is a thin, generated client and Elastic ships releases regularly (latest April 2025). The burden is not patching; it is governance: tracking the Enterprise Search deprecation notice, coordinating client/server upgrades, and keeping the migration exit viable.
• Budget a recurring line item for "vendor lifecycle review" — a quarterly check on Elastic's roadmap is cheaper than discovering the EOL date during a security audit.

Support

• No community safety net. Support comes from Elastic's commercial subscription or from our own team reading generated source. Assume the on-call engineer has never seen this package and write the runbook accordingly.
• Local development requires running the ent-search Docker image (memory-hungry, license-gated) or pointing at a shared staging cluster. That is a real friction cost for onboarding and a testing constraint — integration tests will be environment-dependent, so keep unit tests behind the SearchEngine interface with a fake.

Scaling

• The client is not the bottleneck; it is stateless and horizontally trivial. Scaling is a function of the Enterprise Search cluster (nodes, heap, index sizing) and is largely an infrastructure/cost conversation, not an application one.
• Application-side scaling concerns are connection reuse (singleton client), timeouts, and keeping bulk indexing off the request path. All standard, all cheap.

Failure modes

• Cluster unreachable / slow: search degrades. Must be a caught, logged, degraded-path failure (fallback to database search or empty results with a flag), never a 500 on the primary user journey.
• Token expiry or rotation: 401s that look like outages. Alert on auth failures distinctly.
• Version drift: client and cluster diverge after an uncoordinated upgrade — subtle schema/response mismatches.
• Index drift: documents silently missing because an indexing job dead-lettered. Needs a reconciliation/count check, not just job retries.
• Vendor EOL event: the strategic failure mode; mitigated only by the interface boundary and a documented migration target.

Ramp-up

• Engineer ramp-up is short for the mechanics (one to two days: auth, endpoints, indexing jobs) and longer for the domain (App Search's engine/schema/curation model, relevance tuning, query-time behavior) — call it one to two weeks to productive, one sprint to confident.
• TPM ramp-up is mostly roadmap context: knowing that Enterprise Search is a deprecated line and that this decision will need revisiting is more valuable than knowing the API surface.
• Given the low opportunity score and thin adoption, treat this as a contained, reversible bet: approve for a bounded scope with the interface boundary and the gate review as conditions, and require a named owner for the eventual migration path.