ElasticOM – PHP 7 object mapper library for Elasticsearch

January 10, 2017 Jakub Werłos

While working for one of our customers we were challenged with storing millions of rows of dynamically changing data – a task that does not suit relational databases very well. The solution was found in Elasticsearch engine, which turned out to be not only a search engine but also quite a good data storage.

It is no surprise that Elasticsearch brings quite a different approach to storing data compared to any SQL database. Keeping in mind most of PHP developers are experienced with relational databases, we aimed at a solution that would have a low level of entry. With Doctrine ORM being the most popular library for accessing database records as objects, we decided to follow its best practices. ElasticOM (read it as one word) is the result of our efforts.


With tools such as Elastica and official PHP low-level client, we searched for a tool that would provide us with the ability to automate objects mapping from JSON-structured data to PHP entities using just the definition. Unfortunately, both tools require knowledge of Elasticsearch JSON format – the very thing we wanted to avoid, keeping in mind a scenario when someone new joins our team and knowledge of Doctrine ORM should be enough for an easy start within the project. Searching for more open source solutions didn’t bring anything worth our attention. That’s when we decided that we were going to create such tool; and if so, why not to share it with open-source community?

Data storage abstraction

We had two main goals to achieve – abstracting from Elasticsearch query schema and making it as much similar to Doctrine ORM as possible. We agreed that the minimum viable product would include mapping object to Elasticsearch and support one-to-many entities relations. We have chosen Zend’s hydrator library to extract and hydrate the data, following the strategy from Doctrine’s query builder and entity repository.


Code quality and static analysis

As we knew our goal is to create an open-source library, we made no compromise regarding quality – we took advantage of PHP_CodeSniffer, PHP-CS-Fixer, PHPStan and PHP Mess Detector. Moreover, we have used PHPUnit to write all our tests.

Road ahead

With a library being currently stable we are aware that many improvements/extensions could be made. First thing that comes to mind is introducing custom repositories with a new annotation, extend or refactor query builder when more real-life usage will discover it fragile spots and prepare sophisticated functional tests, especially regarding nested entities.


People working with Doctrine ORM won’t have any problem using ElasticOM. Library has no performance overhead and does not require any knowledge of Elasticsearch.

GitHub project: PGS Software / ElasticOM

Company ad: Are you a fan of open source and free software? PGS Software gives you a chance to contribute your effort to open-source projects. Join today!

Credits: Tomek Brzeziński and Kuba Werłos.

Last posts