# Elastica, the PHP client that depends on another client

> Elastica is a PHP client for Elasticsearch that sits above elasticsearch-php and ships a version matrix narrower than its own compatibility claim. What you gain is an API layer; what you take on is a second table to keep in step with your cluster and your runtime.

**ruflin/Elastica** — Elastica is a PHP client for elasticsearch

- Repository: https://github.com/ruflin/Elastica
- Website: http://elastica.io/
- Stars: 2,270 · Forks: 720
- Language: PHP
- License: MIT
- Published: 2026-10-14 · Updated: 2026-10-14 · Language: en
- Canonical page: https://hysenlabs.com/projects/ruflin-elastica

## A PHP client whose README shows no PHP

Elastica is a PHP client for Elasticsearch, packaged on Packagist as `ruflin/elastica` and documented at `http://elastica.io/`. The repository README is short by design: badges, a compatibility paragraph, a version matrix and two support links, with no PHP sample anywhere in it. Every API detail a new user needs sits behind the link to Elastica.io, so the first decision is whether that site answers your question before you take the dependency.

What the repository does show is its shape. `composer.json` holds the package definition, `tests/` holds the suite, `docker/` holds the containers the functional tests need, and `UPGRADE-8.0.md` sits next to `UPGRADE-9.0.md` for people crossing a major version. The repository topics are elasticsearch, php and hacktoberfest, a plain statement that outside contributors are part of the plan.

## The 9.x branch needs elasticsearch-php and PHP 8.1

The 9.x branch pairs with Elasticsearch 9.x, requires `elasticsearch-php` ^9.0 and constrains PHP to `>=8.1 <8.6`. That middle column is the one people skim past. Elastica does not reach Elasticsearch by itself; it depends on the official client and sits above it, and the caret pins both libraries to the same major line. A project already on elasticsearch-php 8.x cannot add Elastica 9.x without changing that dependency too.

Installing it means adding a Composer package and reading a documentation site. No configuration file sits in the top-level tree, and nothing in it needs to be deployed next to your application. The `docker/` directory belongs to the contributor targets in the Makefile rather than to the package a consumer installs.

## One tested Elasticsearch minor behind a promise of onwards

The compatibility paragraph promises a range, and the test setup names a single point. One line declares the code compatible with Elasticsearch 9.0 and every minor that came after it. The next says the testsuite runs against the most recent minor, currently 9.1.0. Those two lines sit next to each other, and the build badge points at a continuous integration workflow scoped to the 9.x branch.

So a broad claim rests on a single tested minor. If your cluster runs 9.1.0, the suite covers that exact version. If it runs a later minor of the same line, nothing in the suite has touched it, and the matrix row that claims compatibility states only which elasticsearch-php and PHP versions were declared, not which Elasticsearch minors were exercised. The README does not document a policy for clusters outside the tested minor.

## PHP ceilings cut newer runtimes out of older branches

Every maintained branch states a PHP window with both ends, and those windows exclude the runtimes people have already upgraded to. Elastica 9.x asks for PHP `>=8.1 <8.6`. Elastica 8.x asks for `>=8.0 <8.4` with `elasticsearch-php` `^8.4`. A team on PHP 8.4 has therefore lost the 8.x branch, and the only row that accepts 8.4 also demands Elasticsearch 9.x and client `^9.0`, so the library upgrade and the client upgrade arrive as one change.

The two older rows are looser on purpose. The 7.x branch takes PHP 7.2 or 8.0, and the 6.x branch takes PHP 7.0 or 8.0, so a service that cannot leave PHP 7 can still sit on a maintained line. The guidance for choosing between them is short: take the latest point version of the branch you need.

## Branch numbers stop matching Elasticsearch majors

The unmaintained table is where the numbering stops lining up. Elastica 3.x is paired with Elasticsearch 2.4.0, and Elastica 2.x with Elasticsearch 1.7.2. A branch label is not an Elasticsearch major version, and no row pairs any branch with Elasticsearch 3.x or 4.x, so someone hunting for the client that matched a 4.x cluster finds a 3.x row pointing at 2.4.0 instead.

Those rows also drop the ceiling style used above: the 5.x row gives PHP `>=5.6` with no upper bound, while every maintained row states both ends. The maintained rows fill the client column with a caret constraint, and the three unmaintained rows leave it as no, meaning those branches declared no dependency on the official client. Read as a version map, that table misleads, and it is the table most readers quote.

## Composer and phive install the toolchain the Makefile drives

The README hands installation off rather than spelling it out. The package resolves through Packagist as `ruflin/elastica`, and the API documentation lives at Elastica.io. Contributors get the same dependency set from the Makefile, whose install target fires only when `vendor/autoload.php` is missing:

```bash
composer install --prefer-dist --no-interaction ${COMPOSER_FLAGS}
```

The suite runs from that vendor directory, through a target that forwards an options variable it does not define itself:

```bash
vendor/bin/phpunit ${PHPUNIT_OPTIONS}
```

Style checks use a second toolchain. phive puts php-cs-fixer into `tools/`, and the dry-run target prints the diff before anything is rewritten:

```bash
tools/php-cs-fixer.phar fix --diff --dry-run --allow-risky=yes -v --show-progress=dots
```

Fetching that phar is the part worth copying. The Makefile downloads `tools/phive.phar` and its `.asc` signature from phar.io, pulls key `0x9D8A98B29B2D5D79` from hkps://keys.openpgp.org, verifies the download with gpg, removes the signature and only then makes the file executable. `phive.xml` is the file that pins which tool versions those installs resolve to.

## UPGRADE-9.0.md and rector.php price the major bump

Two files exist for migration alone, `UPGRADE-8.0.md` and `UPGRADE-9.0.md`, so the breaking changes were written down ahead of users hitting them. Static analysis ships with a baseline, `phpstan-baseline.neon`, beside `phpstan.neon`, which means the analysis starts from a recorded set of accepted findings rather than from zero. `rector.php` sits in the same row and applies automated refactors, and `.php-cs-fixer.dist.php` keeps formatting decisions in one config.

Functional tests need a live Elasticsearch, and the Makefile assembles one from three compose files at once, `docker/compose.yaml`, `docker/compose.proxy.yaml` and `docker/compose.es.yaml`, under the fixed project name elastica. Coverage is split by group, so the unit run writes its own report:

```bash
vendor/bin/phpunit --coverage-clover build/coverage/unit-coverage.xml --group unit
```

The functional run writes `build/coverage/functional-coverage.xml` to a second file, so the two suites cannot overwrite each other's report.

## Where the extra client layer is the wrong shape

Two cases argue against it. The first is an application that needs one hand-written query, where a library with its own PHP ceiling, its own Elasticsearch ceiling and its own upgrade document is pure overhead, and `elasticsearch-php` on its own removes one of the two version tables you would otherwise maintain. The second is a cluster you do not control: 9.x is declared compatible with Elasticsearch 9.0 and onwards while the suite runs on 9.1.0, so a cluster on a later minor is covered by a declaration rather than by a test.

Support is public and informal. Questions go to the Stack Overflow tag Elastica and to a Gitter channel, library issues go to the GitHub tracker, and `CONTRIBUTING.md` explains the pull request path. No response time and no support policy appear anywhere in the tree. Elastica is MIT licensed, and the last push was on 2026-09-07. Version 9.0.0 was published on 2025-10-01, with 8.2.0 on 2025-09-23 and 8.1.0 on 2024-11-29 behind it, which leaves 9.x carrying the current line while 8.x keeps its own PHP window.

## Conclusion

Adopt Elastica if your PHP service already talks to a 9.x cluster and you want the layer it builds on top of `elasticsearch-php`. Leave it out for a single hand-written query, where the extra package and its own upgrade document are pure overhead, and check your PHP minor first, because the 9.x branch stops at <8.6 and PHP 8.6 sits outside that window. Before committing, verify that your cluster runs the 9.1.0 minor the testsuite covers, and that the `^9.0` client constraint matches what your application already pins.

## FAQ

### Which Elasticsearch and PHP versions does the Elastica 9.x branch support?

Elastica 9.x pairs with Elasticsearch 9.x, requires `elasticsearch-php` ^9.0 and accepts PHP >=8.1 <8.6. The testsuite runs against Elasticsearch 9.1.0.

### How is Elastica installed in a PHP project?

The package resolves through Packagist as `ruflin/elastica`, and API documentation is hosted at Elastica.io. The README carries no install command of its own; contributors run the `composer-install` target in the Makefile.

### Does Elastica replace elasticsearch-php?

No. The 9.x branch requires `elasticsearch-php` ^9.0, so the official client is installed alongside Elastica rather than instead of it.

### Can I use Elastica 8.x with PHP 8.4?

No. The 8.x branch requires PHP >=8.0 <8.4, so 8.4 falls outside its window. The 9.x branch accepts PHP >=8.1 <8.6 and asks for `elasticsearch-php` ^9.0.

### Where do I ask questions about Elastica?

The README points to the Stack Overflow tag Elastica and a Gitter channel, and asks that library issues go to the GitHub issue tracker. No response time is stated anywhere in the repository.

## Sources

- [License: MIT](https://github.com/ruflin/Elastica/blob/9.x/LICENSE)
- [Project website](http://elastica.io/)
- [README](https://github.com/ruflin/Elastica/blob/9.x/README.md)
- [Releases](https://github.com/ruflin/Elastica/releases)
- [ruflin/Elastica on GitHub](https://github.com/ruflin/Elastica)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ruflin-elastica