Transport Laravel Package

Getting Started

Start by installing the package with Composer:

composer require elastic/transport

If no PSR-18 client is available, elastic/transport will fall back to a built-in cURL-based client (requires ext-curl). For production or async support, explicitly install a PSR-18 client:

composer require guzzlehttp/guzzle
# or
composer require symfony/http-client

Instantiate the transport with minimal config:

use Elastic\Transport\TransportBuilder;

$transport = TransportBuilder::create()
    ->setHosts(['http://localhost:9200'])
    ->build();

Send a basic request:

$request = (new Elastic\Transport\Http\Discovery\Psr17FactoryDiscovery::findRequestFactory())
    ->createRequest('GET', '/_cluster/health');
$response = $transport->sendRequest($request);

Check the last-used node via $transport->lastRequest()->getUri().

Implementation Patterns

• Cluster-aware request routing: Use multiple hosts in setHosts() to distribute load. By default, requests rotate across nodes using a randomized Round-robin selector.
• Retry resilience: Set retries on transient failures:

  $transport->setRetries(2);
  

  Combined with a cluster, this automatically retries on different nodes.
• Custom node pools: For advanced failover or circuit-breaking logic, swap in a custom NodePoolInterface via setNodePool(), specifying a custom SelectorInterface (e.g., latency-based) and ResurrectInterface.
• Async workflows: Use sendAsyncRequest() for non-blocking calls. Handle results with then() callbacks or wait() for blocking resolution — requires a PSR-18 + HttpAsyncClient client (e.g., Guzzle).
• Logging & observability: Inject Monolog or another PSR-3 logger to capture full request/response details. Enable debug logging context including full bodies (v8.5+). For tracing, set OTEL_PHP_INSTRUMENTATION_ELASTICSEARCH_ENABLED=true and leverage OTel spans.
• Client flexibility: Replace the HTTP client via setClient() to integrate with Symfony HttpClient, Guzzle, or custom implementations — useful in frameworks (e.g., Laravel) where PSR-18 clients are already configured.

Gotchas and Tips

• URI host takes precedence: If your PSR-7 request already contains a host (e.g., https://example.com/_cluster/health), the NodePool is bypassed entirely — make sure paths are relative unless you intentionally route elsewhere.
• Async client override: setClient() sets both sync and async unless setAsyncClient() is explicitly called. Use this if your async client (e.g., ReactPHP-based) differs from the sync one.
• Node resurrection: The default NoResurrect strategy never recovers dead nodes. Switch to ElasticsearchResurrect in Elasticsearch contexts: it probes / periodically to revive nodes.
• Path-only URIs are recommended: Always prefer paths like /_nodes/stats instead of full URLs when building requests — lets the transport handle routing and host selection.
• Debugging log noise: Logs include full request/response bodies by default (v8.6+). In high-traffic apps, consider bumping log level to INFO or customizing the handler to avoid performance issues.
• cURL client limitation: The built-in client (src/Client/Curl.php) lacks async capabilities — avoid it for jobs requiring concurrency; always pair with an async-capable HTTP client for production async patterns.
• OpenTelemetry attributes: Pass extra OTel attributes via the optional $opts parameter of sendRequest() for richer instrumentation:

  $transport->sendRequest($request, [
      'elastic.request.method' => 'search',
      'custom.trace_id' => $someId
  ]);