Elasticsearch Proxy Bundle Laravel Package

Technical Evaluation

What it is. Despite being filed under "Laravel/PHP," xola/elasticsearch-proxy-bundle is a Symfony bundle, not a Laravel package. It is an HTTP-layer authorization proxy that sits between clients and an Elasticsearch cluster, intercepting search requests and rewriting/injecting query constraints so that a caller only sees documents they are entitled to. For a multi-tenant SaaS, this is a tenancy-enforcement component — i.e., a security control, not a convenience library. That framing drives everything below.

Architecture fit. Poor for direct embedding in a Laravel application. A Symfony bundle expects symfony/http-kernel, dependency-injection, config, and event-dispatcher; it boots via Kernel::registerBundles() and a DependencyInjection\Extension. Laravel has an incompatible container, config, and middleware lifecycle. Making it load inside Laravel means pulling in most of the Symfony framework as a second kernel alongside Laravel's — duplication of error handling, logging, and container bootstrapping for no benefit.

The viable architecture is to treat it as intended: a standalone proxy process deployed as a service (container/sidecar) in front of Elasticsearch, with Laravel apps pointing their ES client at the proxy's host. That converts an "integration" problem into a "deploy an extra hop" problem, which is tractable.

Integration feasibility: low. Signals from the repository:

• 0 GitHub stars, 0 dependents, no downstream usage to validate against.
• Last release 2020-11-03 — roughly five years stale. Elasticsearch has since moved through 7.x → 8.x → 9.x, with the default security stack (TLS on by default, API keys, role-based access) and removal of mapping types.
• Composer constraints almost certainly pin Symfony 3/4-era components and an older PHP minor, which will conflict with a modern Laravel (10/11/12) dependency graph. Expect composer require to fail outright, or to succeed only with --ignore-platform-reqs and a broken runtime.

Technical risk: high, and concentrated in the worst place. A query-rewriting authorization proxy is a trust boundary. Its correctness is not "does search work" but "can a crafted query bypass the filter." Concretely:

• DSL coverage must be exhaustive. Query rewriting must handle bool/nested/has_child, terms lookups, _search/template (stored scripts server-side), _msearch, _async_search, scroll/PIT contexts, pagination continuation, and runtime_mappings.
• Aggregations leak. A filtered hit set with unfiltered aggs discloses cross-tenant counts and bucket keys. Any proxy must rewrite aggregation scope, not just hits — verify whether this one does.
• Scripted fields and painless can read documents outside the rewritten filter.
• Unmaintained 2020-era code predates the current ES security model and has no security-advisory coverage. If a filter-bypass CVE is found, you will be the one patching it.
• Failure semantics must be explicit: does the proxy fail open (search breaks / data leaks) or fail closed (search unavailable)? Default behavior is unknown and must be tested before production.

Key questions for the maintainers/repo audit:

1. Which Elasticsearch major versions and which PHP/Symfony versions are supported by the actual composer.json constraints — and does it run at all on PHP 8.2+?
2. What is the enforcement model — does it rewrite the JSON query body, apply index-level filters, or delegate to ES roles? Where is the identity sourced from (header, JWT, session)?
3. Is the filter injection fail-closed when the query is unparseable or uses an unsupported clause?
4. Are aggregations, _msearch, scroll/PIT, and _search/template covered?
5. Is there a test suite demonstrating bypass attempts, and does it run in CI today?
6. Is Xola still maintaining it? Last commit vs. last release, open PR/issue age, and whether the repo is archived.

Integration Approach

Stack fit. Do not attempt library-level reuse. Two realistic options:

• A. Run it as a standalone proxy service (recommended if the rewrite logic proves sound). Containerize on a PHP-FPM + nginx or RoadRunner/Swoole base, deploy in the same network zone as Elasticsearch, terminate TLS at the proxy or at an ingress in front of it. Laravel apps configure their ES client's hosts to the proxy endpoint and authenticate with whatever credential scheme the proxy expects. Laravel's Elasticsearch\ClientBuilder / laravel-scout-elastic config is the only touchpoint — a config change, not a code change.
• B. Reimplement the rewrite rules in Laravel middleware against the existing ES cluster, using the bundle as a reference implementation rather than a dependency. Extracting the query-rewriting logic (likely a small, self-contained set of visitor classes) and porting it to a Laravel middleware or a thin sidecar is often cheaper than supporting a dead Symfony kernel.

Option B is usually the right call given the maintenance signals; option A only if a time-boxed spike proves the logic is complete and you're willing to own a fork.

Migration path. If the current state is "Laravel talks to Elasticsearch with a shared credential and no per-user filtering," the pragmatic path is:

1. Prefer the platform. Elasticsearch 8.x ships free-tier security: API keys, roles, document-level security, and role templates with templated queries. OpenSearch has the equivalent security plugin. If your tenancy model maps to a document field, native DLS may eliminate the need for this proxy entirely — evaluate this first, because it removes an entire component from your architecture.
2. If native DLS doesn't fit (e.g., dynamic, attribute-based filters), build the proxy layer yourself in Laravel middleware or a small Go/PHP sidecar. It is a bounded problem and you keep the security-critical code on your own release cadence.
3. Only adopt this bundle if a spike (step below) shows it is complete, testable, and small enough to fork confidently.

Compatibility. Audit composer.json before anything else. Expect Symfony 4.x and PHP 7.x constraints. Elasticsearch client version must match the cluster major — a 2020-era elasticsearch/elasticsearch client will not speak to ES 8.x reliably (content-type headers, product check, security defaults). This is a likely hard blocker, not a nuisance.

Sequencing.

1. Read, don't run (1–2 days). Clone, read the query-rewriting code, enumerate supported clauses. This is a code-review exercise, not an install exercise, and it's the cheapest way to reach a go/no-go.
2. Bypass test harness (3–5 days). Stand up a two-tenant fixture index; attempt a battery of escape queries (nested, aggs, msearch, script, template). Anything that returns tenant B's data is disqualifying.
3. Decision gate. If the rewrite logic is complete → fork, modernize dependencies, add tests, containerize. If not → discard and go native-DLS or build-in-house.
4. Shadow traffic. Run the proxy in front of a read replica, mirror production queries, diff result counts against the current path.
5. Cut over read paths first, write paths second, with a feature flag and a tested fail-closed rollback.

Operational Impact

Maintenance: this is a fork-and-own commitment. With zero dependents and the last release in 2020, there is no upstream to lean on. Budget for: dependency modernization (Symfony 5/6+, PHP 8.2+), Elasticsearch client upgrades, and ongoing security review of the query rewriter. Realistically 0.25–0.5 FTE of a backend engineer with Symfony familiarity, plus security review time. If that staffing isn't available, do not proceed — an unmaintained auth proxy is worse than the status quo because it creates false confidence.

Support. No community, no vendor SLA, no dependents to compare notes with. Xola is a real company but this repo shows every sign of being an abandoned internal utility. Treat every question as one you answer yourself.

Scaling. The proxy is an added network hop on every search request. It must scale horizontally and stay stateless; verify it holds no per-request state and that its ES connection handling (keep-alive, pooling) is sane under Laravel's concurrency. Expect single-digit-millisecond overhead per request for the extra hop, plus the cost of JSON parse/serialize on the body — meaningful for large _msearch batches. It also becomes a throughput bottleneck and a capacity-planning component you didn't previously have: it must scale with search QPS, and it needs its own health checks, autoscaling, and load-shedding.

Failure modes — the important section.

• Fail-open on filter error (catastrophic). If the proxy cannot determine the caller's identity or cannot parse the query, and it forwards the request unmodified, tenant data leaks silently. Test this explicitly; if the code fails open, patch it before any traffic.
• Fail-closed on proxy outage (availability). The dependency-correct behavior — but it means a proxy bug takes down all search, not just one feature. Needs its own SLO, alerting, and a documented degraded mode.
• Silent partial filtering. The worst case operationally: no errors, no alerts, just incomplete filtering on a clause nobody tested (nested, has_child, aggregations). Only a bypass test suite catches this, which is why the harness in step 2 is non-negotiable.
• Version drift. Cluster upgrade breaks the stale client — an unplanned outage on your ES upgrade critical path.
• Timeouts and retries. Proxy timeouts must be tuned below client timeouts, and retries must not duplicate or reorder requests in ways that bypass filtering.
• Observability gap. Determine whether it emits structured logs, metrics, and trace context. If not, add it — a proxy you can't see into is a proxy you can't debug during an incident.

Ramp-up. Requires PHP + Symfony idiom familiarity (kernel boot, DI extension, config tree) that a Laravel team typically doesn't have. Estimate 1–2 weeks for an engineer to be productive in the codebase, on top of the Elasticsearch query DSL depth needed to evaluate correctness — arguably the scarcer skill. Plan for one engineer to own it end-to-end rather than spreading it across the team.

Bottom line. The package's stated purpose is legitimate and the problem it solves is real, but at 0 stars, 0 dependents, and a five-year-old last release, it is not an adoptable dependency. Use it as a reference design: read the rewrite logic, then either lean on native Elasticsearch 8 document-level security or implement a small, tested enforcement layer you own. The 0.35 score is consistent with the underlying evidence — technically interesting, operationally unsupportable as-is.