FOSElasticaBundle, the Symfony side of an Elasticsearch integration

A bundle that sits between Symfony, Doctrine and an Elasticsearch client

FOSElasticaBundle provides integration with Elasticsearch and with Elastica in a Symfony application, and the two names in that sentence are not the same thing. Elasticsearch is the search engine. Elastica is the PHP client library, hosted at ruflin/Elastica, that the bundle integrates into a Symfony environment. The bundle does not replace the client, it configures and wires it.

The README lists four features, and they describe the whole shape of the thing. The first is that it integrates the Elastica library into a Symfony environment, which is the bundle's core job and the reason it exists rather than your project writing the client calls directly.

The second is serialization. You can use JMS Serializer or the Symfony Serializer to convert between PHP objects and Elasticsearch data, which is a decision about which of the two serializer stacks your application already has, rather than a third option the bundle imposes.

The third is the index configuration. You can configure the index for Elasticsearch, or send data without configuration to use the dynamic mapping feature of Elasticsearch. Those are two different strategies with different consequences. A configured index means the mapping is declared up front and the field types are stable. Dynamic mapping means the index infers field types from the first documents it sees, which is convenient at the start and a source of surprises later, when a field you thought was a keyword turns out to have been created as a text field with an analysed value.

The fourth feature is listeners for Doctrine events for automatic indexing, which is the part that turns a search index from a thing you refresh by hand into something that follows your database.

The version matrix is one row wide, on purpose

The Versions and Dependencies section is short and the table below it has a single row, which is itself the message. Version 7 of the bundle is compatible with Elasticsearch 8 and 9, requires Symfony 6.4 or greater, and the row pins Elastica to ^8.0 or ^9.0, Elasticsearch to 8.x or 9.x, Symfony to ^6.4, ^7.4 or ^8.0, and PHP to ^8.1.

The prose above the table adds a warning that earlier versions of the bundle are not maintained anymore and only work with older versions of the dependencies. So the bundle supports exactly one generation of its own releases at a time, and if you are on an older line you are on your own for security fixes and compatibility.

That is a reasonable policy for a bundle whose value depends on tracking the shape of Elasticsearch's APIs, but it does have a cost. A project that cannot move to Symfony 6.4 or to Elasticsearch 8 cannot use the current bundle, and the older bundle version it can use is the unmaintained one. That constrains upgrade planning in both directions at once, and it is worth mapping against your own roadmap before you commit to the dependency.

The release cadence is visible in the tags. The recent versions are 7.2.0 from 2026-06-01, 7.1.0 from 2026-04-24 and 7.0.0 from 2025-10-20, and the last push to the repository was on 2026-06-02. The default branch is master, the project homepage is friendsofsymfony.github.io, and the licence is MIT with the LICENSE file in the repository root.

The documentation lives in the repository, in two named files

The README is deliberately a short pointer, and the documentation is in the repository rather than on a separate site. The main entry point is doc/index.md, and the installation instructions are in doc/setup.md, which the README links to instead of repeating the steps. That is a hint about the audience: the bundle is for people who are already in a Symfony project and want the configuration, not for people deciding whether Elasticsearch fits their stack.

The repository layout backs that up. There is a src/ directory for the bundle code, a tests/ directory, a doc/ directory holding the documentation, and a composer.json. The tooling is a normal modern PHP setup: a phpunit.xml.dist for the test suite, a phpstan.dist.neon for static analysis, and a phpstan-baseline.neon alongside it, which is the file that records the known issues the analyser is currently allowed to report. A baseline is a pragmatic choice, since it lets the analysis run in CI while acknowledging that the codebase is not yet clean, and the presence of both files together tells you static analysis is part of the workflow rather than an aspiration.

Formatting is handled by a.php-cs-fixer.dist.php file, and code quality is tracked with a Scrutinizer badge in the README, backed by a.scrutinizer.yml configuration in the root. The CI badge points at a continuous-integration workflow in the.github/ directory.

The changelog history is unusually well kept for a bundle, with separate CHANGELOG files for 5.0, 5.1, 5.2, 6.0 and 7.0 sitting in the repository root. Per-major changelogs are a pattern that helps when you are reading a release note for a version you upgraded through two years ago and the current changelog only covers the latest line.

Automatic indexing is the feature that changes how you work

Of the four listed features, the Doctrine listeners are the one with consequences beyond configuration, so it is worth being clear about what they do and where the edge is.

Without a listener, a search index and the database are two systems that agree only when something makes them agree. A write to the database does not reach the index, so you either run a reindex job on a schedule, accept that search results lag, or write a listener yourself. The bundle ships listeners for Doctrine events for automatic indexing, which means the index follows the entity lifecycle rather than a batch process.

The tradeoff is that the listener runs inside the write path. Every save and delete now does two things, and the second one talks to a different system over the network. That has three practical effects. A failure in the index update can now fail or slow the database write. Indexing adds latency to the request that triggered it, unless the listener is configured to defer. And the consistency model is no longer a single database transaction, because the index write is not part of it.

The alternative approach is to treat the index as a derived store and rebuild it from the database when needed, which is slower to keep current but is much easier to reason about and to recover. For a catalogue with a few thousand records that change rarely, that is often the better trade. For a high-traffic application where stale search results are visible to users, the listeners are the reason to use the bundle at all.

The bundle does not document the exact listener configuration in the README, so the specifics of deferral, batching and failure handling are in doc/index.md and the setup guide. That is the file to read before enabling this in production, because these are the settings that decide whether the feature is a convenience or a source of incidents.

When a bundle like this is the wrong shape of solution

The honest limits follow from what the bundle is. It is an integration layer, not a search product, and it adds a component to a stack that already has several.

If your application does not use Doctrine, the automatic indexing feature does nothing for you, and what remains is a configured Elastica client, which is a small amount of convenience over calling the client directly. That is still worth having for configuration and integration, but it is a much smaller case for the dependency.

If you are choosing a search engine rather than integrating one, this bundle tells you nothing. Its job is to make Elasticsearch work inside Symfony, and it has no opinion about relevance tuning, query design, analyzers, or whether Elasticsearch is the right tool. The same applies to the alternative of using the search facilities of your relational database, which is a different architecture with different tradeoffs and nothing to do with this package.

There is also the cost of the dependency chain to weigh. A Symfony application that adopts this bundle pulls in the Elastica client, the HTTP client it uses, the serializer of your choice, and the Elasticsearch server itself, plus the operational burden of running a cluster. The bundle makes the code side easy; it does nothing for the infrastructure side, and the infrastructure is where search projects usually get expensive.

The practical advice is to evaluate it against the specific question of whether your data lives in Doctrine and whether your users will notice stale search results. If it does and they will, the bundle gives you a maintained path. If it does not, the honest comparison is with a thin wrapper of your own, which may well be less code than the configuration.

Editorial conclusion

FOSElasticaBundle suits a Symfony application that already stores its data in a relational database and wants a search index over it, and it suits teams that want Doctrine to keep the index in step automatically instead of writing their own indexer. It is the wrong choice for a project with no Doctrine layer, because the automatic indexing story is built on Doctrine events, and it is the wrong choice if you need search features Elasticsearch does not have, since this is an integration layer and not a search product. Before adopting it, check the version matrix in the README against the Elasticsearch and Symfony versions you run, since the bundle only supports the row it states and the older lines are not maintained, and read doc/setup.md, which is where the installation instructions live.

Frequently asked questions

Official sources

1. FriendsOfSymfony/FOSElasticaBundle on GitHub
2. License: MIT
3. Project website
4. README
5. Releases