Elasticsearch Client Laravel Package

Getting Started

v2026.3.0 is a housekeeping release with exactly two things that can affect your application: the raised minimum Elasticsearch version (8.12.2) and a new central Symfony 8 compatibility check. Everything else is CI/workflow plumbing (renamed new-* workflows, PR guardrails, PR policy thin callers, a maintenance-branch doc fix, and a synced pimcore/platform-version file). There are no new features and no API deprecations, so there is nothing new to learn — but there is something to verify.

1. Check your cluster version first. This is the only breaking-ish change:

curl -s https://your-es-host:9200 | jq '.version.number'

If you are below 8.12.2, either upgrade the cluster or pin pimcore/elasticsearch-client:v2026.2.0. The client now targets APIs finalised in 8.12; running against 7.x or early 8.x tends to fail on specific API calls deep inside a query rather than at connection time, which makes the failure look like your query's fault.

2. Check your Composer constraints before upgrading. The pimcore/platform-version sync means this release ships an updated platform-version constraint file. If you are on a Pimcore core or a mixed Symfony stack with tight composer.json constraints, run composer update pimcore/elasticsearch-client --dry-run first and read the constraint resolution carefully.

3. composer update pimcore/elasticsearch-client

4. Smoke test the three things you touch daily: create a versioned index + alias, bulk-index a handful of documents, run a match query and fetch a hit back. This is the fastest way to catch an 8.12 API mismatch.

Where to look first if you haven't used the package before: the client factory / connection config (in Pimcore, config/config.yaml under the elasticsearch node; in plain Laravel, a service provider binding for the client factory), then the index management classes, then the query builder.

Implementation Patterns

Index lifecycle as code. Keep index definitions in versioned classes rather than creating them ad hoc. Name indices with a version suffix (products_v1) and expose a stable alias (products) so you can reindex without downtime: build products_v2, verify document counts, then atomically swap the alias. Retrofitting this later is the most painful refactor in the whole package, so do it on day one.

Repository/service wrapper per aggregate. Wrap the client in a ProductSearchRepository exposing index(), delete(), search(), bulkIndex(). Controllers and jobs never see raw ES payloads. When the next minimum-version bump lands, this is your one-place change.

Bulk over single writes. Chunk model IDs and push them through the bulk API from a queued job. This is the single biggest performance lever and the one most commonly skipped until a nightly reindex takes six hours.

Event-driven sync. Hook model events (saved, deleted) to dispatch indexing jobs. Keep ES writes out-of-band so a slow or degraded cluster never blocks a user request — the client's default timeouts are optimistic and will happily hang a web worker.

Query construction via the builder. Prefer the package's query builder over hand-rolled arrays; it keeps filter/aggregation structure consistent and makes highlighting, pagination, and sorting uniform across repositories.

CI version guardrails. This release makes the minimum load-bearing. Add a job that runs an elasticsearch:8.12.2 (or newer) service container and runs your integration tests against it, so a developer's local 7.x or early-8.x box can't silently pass. Also add the Symfony 8 constraint check to CI if you're on a mixed Symfony/Pimcore/Laravel stack.

Upgrade routine for chore-only releases like this one. Read the release notes for the two or three non-CI lines, diff the changed config/constraint files, then run the smoke test. Don't skip it just because the changelog looks like plumbing — this one hid a minimum-version bump in a PR title.

Gotchas and Tips

Version pinning is now load-bearing. Because the client targets 8.12.2+, mismatches surface as confusing errors mid-query ("query malformed", unknown field, unsupported parameter) rather than a clean connection failure. When debugging anything new, check the cluster version before you check your query.

Refresh semantics. Writes are near-real-time but not immediate. Index-then-search in the same request (tests, "save and show" flows) will show stale results. Use refresh=true in tests and dev only; in production accept the delay or design the UI around it.

Mapping changes require reindex. You cannot change an existing field's type in place. If you rely on aliases from the start, this is a ten-minute operation; if you don't, it's an outage.

Bulk partial failures return HTTP 200. A bulk response is a success at the transport level even when individual documents fail. Always iterate items[] and check per-document error entries, and log them. Silently dropped documents are the classic "why is search missing records" bug.

Log the final JSON body. Most ES errors are only diagnosable by reading the exact payload that went out, not the exception message. Log the request body at debug level in non-production and keep it behind a flag in production.

Timeouts must be set explicitly per use case. Indexing/bulk jobs need a much higher timeout than user-facing searches; the defaults are optimistic for both. Configure them separately in your client factory wrapper.

Composer constraint friction from the platform-version sync. Because this release carries a synced pimcore/platform-version file, upgrading the client can pull in tighter platform constraints. If composer update wants to move your Pimcore core version, stop and read the diff — that's a core upgrade, not a client bump, and should be planned separately.

Symfony 8 note. The new central Symfony 8 compatibility check is a signal of intent, not a guarantee for every mixed framework combination. Verify your own constraint matrix before upgrading on a hybrid Symfony/Pimcore/Laravel stack.

Extension points. Subclass or compose the client factory and index classes rather than monkey-patching. Mappings and custom analyzers are the usual customisation surface — keep analyzers defined in your index templates so they survive a reindex into _v2.

Don't over-rotate on workflow churn. Most of the PRs in this release rename and re-wire GitHub Actions callers. If you fork or vendor this package, those filenames changed and your downstream CI references may need updating; if you consume it via Composer, ignore them entirely.