ruflin/elastica
Elastica is a PHP client for Elasticsearch, providing a rich, object-oriented API for indexing, searching, and managing indices. Compatible with Elasticsearch 9.x+ (branch-specific support for older versions) and integrates with elasticsearch-php.
Start by installing via Composer: composer require ruflin/elastica. Ensure your environment meets the minimum PHP 8.1 requirement. Instantiate the client by providing Elasticsearch connection details (host, port, optional SSL/auth). The core entry points are Client, Index, and Template (for legacy index templates) or ComponentTemplate (for newer component templates introduced in ES 7.15+). For Elasticsearch 7+, use Index directly — types are deprecated and getType() is obsolete. Your first use case is likely indexing a document — use $index->addDocument($document) where $document is an instance of Elastica\Document. For basic searches, build queries with Elastica\Query (or Elastica\SearchQuery in newer versions), execute via $index->search($query), and inspect results through Elastica\ResultSet.
Note for v9.0.0 upgrade: The third
$methodargument has been removed fromSearchableInterface::search()and::count()inElastica\SearchandElastica\Index. Remove any legacy calls like$index->search($query, 'GET'). TheElastica\Requestclass and its constants have also been removed — no longer needed due to internal refactoring.
Elastica\Query, Elastica\Search, Elastica\Aggregation\Terms, etc.) over raw JSON — it supports autocompletion, type hints, and easier refactoring. Use BoolQuery for compound queries with must/should/must_not clauses. Important fix in v9: BoolQuery::toArray() no longer mutates internal state — safe to call multiple times (e.g., for logging).Index::bulk() for efficient batch indexing/deletions — build an array of Elastica\Document or Elastica\Document\Delete and execute once per batch. Wrap in try/catch and inspect Elastica\Bulk\Response for partial failures.Elastica\ScanAndScroll or manually manage scroll IDs via $search->createScroll() for large datasets. Ensure scroll parameter is set appropriately in your initial search query.Elastica\Template for legacy index templates (ES < 7.8), and Elastica\ComponentTemplate + Elastica\IndexTemplate for modern composite templates (ES ≥ 7.8). IndexTemplate now only works with the new _index_template API — do not confuse with Template.Elastica\Search or implement custom Elastica\Processor/Elastica\Mapper for advanced use cases (e.g., ingest pipelines). For custom endpoints, use Client::request() with Elastica\Request\Method.ResultSet’s structured access — $resultSet->getTotalHits(), $resultSet->getAggregations(), $resultSet->getMaxScore(), and $resultSet->getDocuments() — each Document may include highlights via $doc->getHighlight().composer.json and CI/CD pipelines target PHP 8.1+ (including 8.2/8.3/8.5)._template API), migrate to Elastica\Template explicitly — IndexTemplate no longer supports it. Verify your Elasticsearch version supports the new _index_template API (7.8+).Elastica\Request. Use Client::request($path, $method, $data, $query) for raw API calls, which abstracts low-level concerns.['host' => '...', 'port' => '...', 'scheme' => 'https', 'user' => '...', 'pass' => '...', 'headers' => [...]]. For API keys, include Authorization: ApiKey ... in headers.$query->toArray() or $search->getQuery()->toArray() to inspect the JSON payload. For full request logs, inspect $client->getConnection()->getLastRequest() before execution.new Document($id, $data). To avoid overwrites, set op_type: 'create' via $doc->setOpType('create'). v9 now respects retries => 0 (no retries) — previously, retries had to be ≥ 1.['retries' => 2], but note v9 now correctly allows retries => 0. Monitor Elastica\Exception\ConnectionException and use Elastica\Bulk\Response::hasFailures() for batch-level diagnostics.BoolQuery::toArray() is now side-effect-free (fixed in v9), you can safely reuse query objects for logging, caching, or re-modification without unexpected state changes.How can I help you explore Laravel packages today?