ElasticKit

中文 | English

A PHP Elasticsearch DSL query builder covering queries, aggregations, CRUD, bulk writes, and zero-downtime rebuilds.

Installation

composer require ykan/elastickit:^8

Requires PHP 8.1+ and Elasticsearch 8.x. The elasticsearch-php dependency is installed automatically.

Quick Start

useElasticKit\Index\Index;
// 1. Register the client$client = \Elastic\Elasticsearch\ClientBuilder::create()
->setHosts(['http://localhost:9200'])->build();
Index::setClient($client);
// 2. Define an indexclass ProductIndex extends Index
{
protectedstring$name = 'products';
protectedarray$mappings = [
'properties' => [
'title' => ['type' => 'text'],
'price' => ['type' => 'float'],
'status' => ['type' => 'keyword'],
],
];
}
// 3. Search$results = ProductIndex::query()
->match('title', 'elasticsearch')
->get();
$hits = $results->docs(); // [['title' => '...'], ...]$total = $results->total(); // null unless $trackTotalHits = true (see Pagination & cursor)

DSL Examples

ElasticKit's DSL stays close to the native ES API to minimize cognitive load — if you know ES DSL, the transfer is smooth. Every query type is a dedicated Node class whose method names mirror ES parameters.

Expand

Compound query

$results = ProductIndex::query()
->bool([
'must' => fn ($q) => $q->match('title', 'elasticsearch'),
'filter' => fn ($q) => $q
->range('price', [10, 100])
->when($status, fn ($q) => $q->term('status', $status)), // conditional filter
])
->highlight('title')
->sort('price', 'asc')
->size(20)
->get();

{
"query": {
"bool": {
"must": [{ "match": { "title": "elasticsearch" } }],
"filter": [
{ "range": { "price": { "gte": 10, "lte": 100 } } },
{ "term": { "status": "published" } }
]
}
},
"highlight": { "fields": { "title": {} } },
"sort": [{ "price": "asc" }],
"size": 20
}

OOP style

Build each clause separately, then combine them into a query:

useElasticKit\DSL\Queries\Compound\Boolean;
useElasticKit\DSL\Queries\FullText\Match_;
useElasticKit\DSL\Queries\TermLevel\Range;
useElasticKit\DSL\Queries\TermLevel\Term;
// Build the clauses$status = Term::create('status', 'published')->boost(1.5);
$title = Match_::create('title', 'elasticsearch');
// Combine into a bool query$bool = Boolean::create()->must($title)->filter($status);
if ($filterByPrice) {
$bool->filter(Range::create('price', [10, 100]));
}
// Execute$results = ProductIndex::query()->bool($bool)->size(20)->get();

Aggregations

$results = ProductIndex::query()
->matchAll()
->aggs('status_counts', fn ($agg) => $agg->terms('status'))
->aggs('price_stats', fn ($agg) => $agg->stats('price'))
->size(0)
->get();
$aggs = $results->aggregations();

kNN search

$results = ProductIndex::query()
->knn(fn ($k) => $k
->field('embedding')
->queryVector([0.12, 0.45, 0.78, /* ... */])
->numCandidates(100))
->size(10)
->get();

Raw array

$query = Query::create([
'query' => [
'bool' => [
'must' => fn ($q) => $q->match('title', 'elasticsearch'), // array may nest closures'filter' => fn ($q) => $q->term('status', 'published'),
],
],
'size' => 20,
'sort' => [['price' => 'asc']],
]);

Clause appending (ClausesSupport)

The clauses of a bool query (must / should / filter / must_not) append — repeated calls accumulate, they don't overwrite:

$q->bool(fn ($b) => $b->must($q1)); // must: [q1]$q->bool(fn ($b) => $b->must($q2)); // must: [q1, q2]

dis_max, span_or, span_near and other array-clause containers behave the same way.

Flexible arguments

The same method accepts multiple input forms — use whichever suits:

$q->term('status', 'published'); // string$q->term(['status' => 'published']); // array$q->term(fn ($t) => $t->field('status')->value('published')); // closure$q->term(Term::create('status', 'published')); // object

Index Examples

Around the Index base class, dedicated classes cover routine index operations — pagination, CRUD, bulk writes, index management, zero-downtime rebuilds, and event hooks.

Expand

Pagination & cursor

// pagination$results = ProductIndex::query()
->match('title', 'elasticsearch')
->paginate($page, $perPage);
$results->lastPage();
$results->items();
$results->toPaginator(); // convert to a framework paginator (requires registering a Paginator Resolver)// batch iteration (large exports / batch processing; yields a Results per batch)foreach (ProductIndex::query()->chunk() as$results) {
foreach ($results->docs() as$doc) {
// ...
}
}
// per-hit iteration (exports / per-row processing; yields one hit: _id/_score/_source)foreach (ProductIndex::query()->cursor() as$hit) {
$doc = $hit['_source'];
// ...
}

Pagination needs totals, which are opt-in.Index defaults $trackTotalHits = false, so total()/lastPage() return null and toPaginator() throws. Set protected int|bool $trackTotalHits = true; (or a count cap) on the index for page-count pagination, or use hasMorePages() / chunk() / cursor() for total-less iteration.

Document CRUD

ProductIndex::doc(1)->save(['title' => 'Hello', 'price' => 99.9]);
$doc = ProductIndex::doc(1);
$doc->source(); // ['title' => 'Hello', 'price' => 99.9]$doc->update(['price' => 89.9]);
$doc->delete();

Bulk operations

useElasticKit\Index\Bulk;
$bulk = newBulk(newProductIndex());
$bulk->batchSize(500)
->index(1, ['title' => 'A', 'price' => 10])
->index(2, ['title' => 'B', 'price' => 20])
->update(3, ['price' => 15])
->delete(4)
->flush();

Index management

useElasticKit\Index\Manager;
$manager = newManager(newProductIndex());
$manager->create(); // create the index$manager->exists(); // bool$manager->putMapping(); // update the mapping$manager->delete(); // delete the index

Zero-downtime rebuild

useElasticKit\Index\Rebuild;
// 1. Define the data source in an Index subclassclass ProductIndex extends Index
{
publicfunctionsource(array$context = []): iterable
{
foreach (Db::table('products')->cursor() as$row) {
yield$row['id'] => $row;
}
}
}
// 2. Run the rebuild (creates a new index -> imports -> swaps the alias)$result = (newRebuild(newProductIndex()))
->batchSize(500)
->run();
// $result = ['newIndex' => 'products_20260607_120000', 'oldIndex' => 'products_20260601_090000']// 3. Clean up old indices or roll back
(newRebuild(newProductIndex()))->clean($result['oldIndex']);
(newRebuild(newProductIndex()))->rollback($result['oldIndex']);

Event listening

useElasticKit\Index\Support\Event;
useElasticKit\Index\Support\EventDispatcher;
EventDispatcher::listen('search.query.after', function (Event$e) {
Log::info("Search on {$e->index}", [
'dsl' => $e->dsl,
'duration' => $e->duration,
]);
});
EventDispatcher::listen('search.*', function (Event$e) {
Log::debug($e->name);
});

Documentation

• Guide — an e-commerce order scenario, the full flow from install to production
• Index docs — search, CRUD, bulk operations, zero-downtime rebuild, events
• Changelog
• Elasticsearch official docs — query types and parameter reference

License

MIT