Laravel Hunt Laravel Package

Getting Started

• Install the package with Composer and publish its config: php artisan vendor:publish --provider="...ServiceProvider" (check the package README for the exact provider tag). Publish first, then edit — the config file is the primary surface area.
• Set the essentials in .env: cluster host(s), index prefix, and — if you are on Amazon Elasticsearch/OpenSearch Service — the region and credentials used for signing. Keep credentials out of the config file; reference env() values so per-environment deploys differ without code changes.
• The service provider binds a configured Elasticsearch client into the container. Resolve it via the container or the package's facade rather than constructing Elasticsearch\Client yourself; that is what makes the new signing option apply everywhere.
• First use case: index one model's records and run a single query end-to-end before wiring up anything else. Confirm the documents land, then run a search. On AWS, this first smoke test is also your signing check — a misconfigured signature fails loudly with a 403, which is a fast feedback loop.

Implementation Patterns

• Environment-driven signing. Enable signing only where it is needed (staging/production AWS) and leave it off for local Docker/Elasticsearch. Driving it from an env var avoids the common trap of local dev trying to sign requests against a non-AWS cluster.
• One client, many consumers. Let the package's container binding be the single source of truth. Repositories, console commands, queued jobs, and health checks should all resolve the same client so the "sign all requests" behaviour is uniform — including the requests you forget about (pings, index existence checks, bulk operations).
• Connection-per-environment. If the package exposes named connections, define local and aws connections and select via env('ELASTIC_CONNECTION'). This keeps host, region, and signing flags together and prevents a half-signed configuration.
• Credential provider chain over static keys. On EC2/ECS/Lambda, prefer the instance/task role. Signing consumes credentials at request time, so role-based credentials rotate transparently and you avoid long-lived secrets in .env. If you must use static keys, scope the IAM policy tightly to the index ARNs the app touches.
• Index lifecycle in code. Keep index creation/mapping/aliases in artisan commands or migrations rather than ad-hoc curl. If signing is on, those commands inherit it automatically — one less place where an unsigned request can slip through.
• Bulk and background work. Indexing jobs benefit most from this change: with signing enabled at the client level, queue workers need no extra plumbing beyond having credentials available in their runtime environment.
• Verify both paths in CI or staging. Run an integration test that hits a real signed endpoint. Unit tests with a mocked client will never catch a signature problem.

Gotchas and Tips

• 403 SignatureDoesNotMatch is almost always region, service name, or host. The signing service is es (not opensearch or elasticsearch) and the region must match the domain exactly. A wrong region produces a valid-looking but rejected signature.
• Host header rewrites break signatures. Proxies, load balancers, or custom HTTP middleware that mutate the Host, Content-Length, or body after signing will invalidate it. If you added Guzzle middleware or a trace header, check it isn't touching signed headers.
• Body mutation after signing. Streaming or gzipping the request body downstream of the signer is a classic cause of intermittent failures on bulk requests while simple GETs succeed.
• Clock skew. SigV4 has a short validity window; containers with drifted clocks fail with RequestTimeTooSkewed rather than a signature error. Ensure NTP is healthy on self-managed hosts.
• Credentials must resolve at worker boot, not just web requests. Queue workers and scheduled commands are long-lived — confirm temporary STS credentials refresh correctly if you're not on an instance role.
• "All requests" includes health checks. If your monitoring or /health endpoint pings the cluster, it now needs credentials too. Make sure the health check runs in an environment where they're available, or you'll get noisy false alarms.
• Local development friction. Developers without AWS credentials will see failures if signing is enabled by default in the published config. Default it to off and turn it on explicitly.
• Extension point for edge cases. If you need custom signing behaviour (custom credential provider, extra headers), look for the client factory or handler-stack hook rather than forking — that keeps future upgrades cheap.
• Pin sensibly. 0.5.x is pre-1.0; read the changelog on each minor bump for config key renames, and keep the published config file diffed against the package's stub after upgrades.