Elasticsearch Laravel Package

Getting Started

1. Install/update the package and publish its config if you have not already. The 1.3.3 release adds two timeout settings and changes two defaults, so re-publish or diff the config to see the new keys.
2. Set the minimum viable environment values:
   • *_CONNECT_TIMEOUT — how long to wait while establishing the client connection.
   • *_TIMEOUT — how long to wait for an operation after connecting.
   • retry — defaults to 0 in 1.3.3; set explicitly if you need retries.
   • selector — defaults to random in 1.3.3; override if you need deterministic routing.
3. First use case: a read-heavy Laravel endpoint or queue worker where you want fast failure and spread load across available connections. Start with a short connect timeout, a slightly longer operation timeout, retry 0, and the random selector. Measure latency and error rates before increasing retries.

Implementation Patterns

• Layer timeouts deliberately. Keep connect_timeout lower than timeout, and keep both lower than the surrounding HTTP request timeout or queue job timeout. A common pattern is connect_timeout: 0.5, timeout: 1.0, and an application-level deadline of 2–3 seconds.
• Treat retry 0 as the new baseline. With retries disabled by default, failures surface immediately. Wrap idempotent reads in your own bounded retry with backoff, and avoid automatic retries for writes unless the operation is idempotent.
• Use the random selector for stateless reads. It is a good fit for cache reads, health checks, and horizontally scaled read replicas where any node can serve the request. Do not rely on it for read-after-write consistency or session affinity.
• Separate connections by workload. Use distinct connections/configs for cache, queues, and sessions so a timeout or retry setting tuned for one workload does not degrade another.
• Keep queue workers responsive. In Horizon/queue workers, short timeouts plus retry 0 prevent a single slow connection from blocking a worker. Handle the exception in the job and release or fail explicitly.
• Integration tip: after changing config, run php artisan config:cache in environments that cache configuration, and verify the effective values in a tinker session or a small health-check command.

Gotchas and Tips

• Upgrade behavior changes: retry now defaults to 0 and the selector now defaults to random. If your application previously depended on automatic retries or deterministic node selection, audit your config immediately after upgrading.
• Random selector can surprise you: read-after-write flows may observe stale data if the write and read land on different nodes. Pin those reads to a primary/deterministic connection or use a custom selector.
• Timeout units matter: confirm whether the published config expects seconds or milliseconds. A connect timeout that is too close to the operation timeout makes failover debugging difficult.
• Debugging connection issues: log the chosen selector, connect duration, and operation duration separately. Test failover with a proxy such as Toxiproxy rather than waiting for a production incident.
• Config quirks: environment variables are often cast as strings; ensure timeout and retry values are cast to integers/floats in the config file.
• Extension point: if random selection is unsuitable, provide a custom selector class rather than forking the package. Keep the custom selector stateless and cheap to instantiate.