Elasticsearch Transport Thrift Laravel Package

Getting Started

Read this first: the package is archived and marked STOPPED. Thrift was dropped from Elasticsearch at 5.0, and this transport only ever made sense against an Elasticsearch 1.x/2.x node that had the Thrift plugin installed and listening (historically port 9500, while HTTP stayed on 9200). If you are starting a new project, stop here and use elasticsearch/elasticsearch with its default HTTP transport. The guidance below is for teams inheriting a legacy stack and needing to keep it running while they migrate.

Minimal steps to get a legacy install breathing:

1. Pin the whole stack, not just this package. You need a mutually compatible triple: the Elasticsearch server version, the matching Thrift server plugin on every node, and the elasticsearch/elasticsearch client version this transport was built against (v1.x/2.x era). Check composer.json in your lockfile before changing anything.
2. Confirm the node side. The PHP package is only half the story. Verify the Thrift plugin is loaded on the node (GET /_nodes/plugins via the HTTP port) and that 9500 is reachable from your app host. If the plugin is gone, the PHP package cannot help you.
3. Install the Thrift runtime. This transport depends on Apache Thrift bindings (either the thrift composer library or the PECL thrift extension, depending on version). Confirm which one your pinned client expects — mixing them produces confusing protocol errors.
4. Wire the transport into the client, then make one call. Build the client with the Thrift transport and connection params pointing at the Thrift port, then run a single ping()/info() before anything else. If that succeeds, the hard part is done.

Where to look first, in order: your composer.lock, the server's plugin list, the client's transport/connection-pool interfaces (the extension points this package implements), and only then the package source itself.

First real use case: bulk indexing — the workload Thrift was originally adopted for, since binary framing reduced per-request overhead versus JSON-over-HTTP on chatty indexers.

Implementation Patterns

Isolate the client behind your own interface. Because this transport is dead, the single highest-leverage pattern is to never let Elasticsearch\Client (or the Thrift transport) leak into application code. Wrap index/search/bulk calls in a repository or gateway class. That makes the eventual swap to the HTTP transport a one-file change instead of a refactor.

Treat the transport as a pluggable dependency. The client exposes transport and connection-pool extension points; this package supplies a Thrift-flavored implementation. Construct it explicitly and inject it:

// Shape varies by client version — verify against your pinned release.
$transport = new ThriftTransport(/* hosts on :9500, serializer, timeout */);
$client = new Client([
    'transport' => $transport,
    // 'sniffOnStart' => false,  // see Gotchas
]);

Disable sniffing (or override it). Sniffing asks the cluster for node addresses and expects HTTP endpoints. Against a Thrift-only pool this either yields unusable :9200 hosts or throws. Either turn sniffing off and hard-code the Thrift host list, or supply a custom node-pool that rewrites ports.

Keep the pool explicit and static. List every Thrift-enabled node in connectionParams, with round-robin across them. Do not assume every node in the cluster runs the plugin — in mixed fleets, a bad host entry turns into intermittent connection failures under load.

Bulk workloads: batch and back off. Group documents into bounded batches (a few MB / low thousands of docs), then handle partial failures from the bulk response — inspect per-item statuses, retry only the failed items, and apply exponential backoff on EsRejectedExecutionException / overload signals. This logic lives in your code; the transport will not do it for you.

Error translation at the boundary. Thrift surfaces transport-level exceptions (socket, protocol, timeout) separately from Elasticsearch errors. Catch both at your gateway layer and normalize into your own exception types so application code doesn't have to know a Thrift library exists.

Integration testing against a real node. Unit-mocking a Thrift transport tests almost nothing. Stand up a pinned ES container (or VM) with the plugin enabled in CI, and run a smoke test (info, one index, one bulk, one search) on every build. This is the only reliable regression signal for a frozen dependency.

Migration in parallel. Run the HTTP client alongside the Thrift one behind your gateway, shadow a percentage of reads, and cut writes over once parity is confirmed. Because both speak to the same cluster, this is safe and gives you a rollback lever.

Gotchas and Tips

• Archived means archived. No security fixes, no PHP-version compatibility work, no protocol updates. Audit it against your PHP runtime (older Thrift bindings frequently break on modern PHP) and plan to leave.
• Version skew is the #1 failure. The Thrift IDL/generated classes, the PHP Thrift runtime, the server plugin, and the client library must agree. Upgrading any one in isolation usually manifests as opaque deserialization errors, not a clean "version mismatch" message.
• Port confusion. Thrift is 9500, HTTP is 9200. Firewalls, security groups, and service discovery almost always open only 9200; a "connection refused" here is usually infrastructure, not code.
• Sniffing silently poisons the pool. If you leave it on and it works, you may still be talking to an HTTP port with a Thrift client. If it doesn't work, the error is buried. Turn it off explicitly.
• No parity with HTTP for TLS/auth/security. The Thrift transport predates most of the transport-security and auth story. Anything relying on HTTP-layer auth, proxies, or TLS termination needs a different design; assume you're on a trusted network segment.
• Debugging order: (1) is the plugin loaded on the node? (2) is 9500 reachable (nc -vz host 9500)? (3) does a raw Thrift client connect? (4) only then suspect your PHP wiring. Enable Thrift library logging and, if needed, capture traffic on the wire.
• Composer conflicts are expected. This package will fight modern elasticsearch/elasticsearch versions and modern Thrift libraries. Don't try to force it into a current stack — pin the legacy tree in its own service or virtualenv-style boundary.
• Extension points are a trap here. The transport and node-pool interfaces are clean and tempting to extend, but you'd be building on an unmaintained foundation. Invest that effort in the gateway abstraction and the HTTP migration instead.
• Document the exit plan in the repo. A short MIGRATION.md naming the HTTP replacement, the gateway boundary, and the cutover test is the most valuable artifact you can add to a project depending on this package.