Elasticsearch Client Bundle Laravel Package

Getting Started

• Install and confirm the runtime. composer require open-dxp/elasticsearch-client-bundle. Despite the "client" name, this is an OpenDXP/Symfony bundle — it registers services through a *Bundle class and a DependencyInjection extension, not a Laravel service provider. Read composer.json, the bundle class, and DependencyInjection/Configuration.php before writing any code; the config tree is the authoritative list of connection options (hosts, credentials, timeouts, retries).
• Configure the connection first. Add the bundle config (hosts, auth, TLS, timeouts) in your app config. The whole point of the package is that the configured client is registered in the container once and reused by other bundles — so do not instantiate Elasticsearch\Client yourself in application code.
• First end-to-end use case. Inject the client into a small service, index one document, then run one match query against it. That single round trip validates connection config, auth, and mapping assumptions before you build anything larger.
• On Laravel specifically: you will not load the Symfony extension. Treat the bundle as a reference implementation and bind the client yourself, mirroring the bundle's config keys:

$this->app->singleton(Client::class, fn () => ClientBuilder::create()
    ->setHosts(config('elasticsearch.hosts'))
    ->build());

• Where to look next: the client factory (how the client is constructed and configured) and any normalizer/serializer classes. Those are the pieces worth reusing even if you skip the bundle wiring.

Implementation Patterns

• Inject, don't construct. Resolve the client from the container in your services/repositories. This is the bundle's core value: one configured client shared across bundles instead of each module reading env vars and building its own.
• Thin internal wrapper. Put the client behind your own SearchService / repository interface. Controllers and jobs call your interface, not Elasticsearch\Client directly. This is what makes client upgrades or a swap to Scout/another driver a contained change.
• Index on model events, asynchronously. Hook created/updated/deleted into a queued SyncToElasticsearch job. Synchronous indexing on the request path is the fastest way to make writes fragile and latency-sensitive.
• Bulk for backfills. Accumulate documents and flush via the bulk API in chunks of ~500–1000. Always inspect the top-level errors flag and per-item statuses.
• Alias-based index management. Write to a versioned index (posts_v3) and point a posts alias at it. Mapping changes become reindex-then-flip instead of downtime. Wrap this in a repeatable command (search:reindex) so every environment can run it.
• Query DSL as objects. Keep queries in dedicated classes (app/Search/Queries/*) driven by a DTO built from request input. Unit-testable, and keeps raw arrays out of controllers.
• Test without a cluster where possible. Bind a fake client or assert on the generated query body in unit tests; reserve a real cluster (Testcontainers or a CI service) for a small integration suite.
• Health check as a scheduled command. ->ping() plus cluster status gives you alerting for free and catches connectivity/config regressions early.
• Reuse across bundles the way the package intends. If you have several OpenDXP bundles needing search, configure the connection once and let each bundle inject the shared client — that is the supported integration path.

Gotchas and Tips

• v1.0.1 is a maintenance release. It is a branding/naming pass, PHP 8.5 support, and CI workflow cleanups — no breaking changes and no new features. Action items: (a) verify PHP 8.5 compatibility of your other dependencies before bumping your platform constraint, and (b) grep your config, service IDs, and class references for anything touched by the rename, since examples in older docs may have shifted.
• DI mismatch is the main trap on Laravel. Symfony config keys, service tags, and parameter names do not map 1:1 to Laravel's container. Do not try to load the bundle's extension; translate its settings manually.
• Pin the version. ^1.0. A patch release can still rename identifiers during a branding pass; review changelogs on minor bumps.
• Client/engine compatibility matrix. The elasticsearch-php major must match your cluster major. Check which client major the bundle pulls in — an accidental cross-major composer update is a silent runtime break.
• Refresh semantics. Writes are near-real-time (~1s). For tests and read-after-write flows use refresh=wait_for or accept the flake; never set refresh=true on production writes.
• Dynamic mapping is a footgun. One stray string in a numeric field poisons the mapping. Define explicit mappings and consider "dynamic": "strict" on critical indices so bad documents fail at index time rather than silently at query time.
• Bulk partial failures are silent by default. HTTP 200 does not mean every document indexed — always parse the response body.
• Set timeouts and retries explicitly. Connect timeout, request timeout, and retry count. The defaults are optimistic and surface as hung workers under cluster pressure.
• Gate query-body logging behind an env flag. DSL bodies frequently contain user PII.
• Extension points worth using instead of forking: custom normalizers (date formats, geo shapes), client decorators for tracing/metrics, and event subscribers for slow-query logging.
• Bus factor. Small maintainer set — keep the thin internal wrapper so the client can be swapped without rewriting query code.