🎅🏻 Ho ho ho! Christmas is coming! Please consider supporting and starring the project! ⭐️
Elastic Adapter is an adapter for official PHP Elasticsearch client. It's designed to simplify basic index and document operations.
The current version of Elastic Adapter has been tested with the following configuration:
- PHP 7.3-8.0
- Elasticsearch 7.x
- Laravel 6.x-8.x
The library can be installed via Composer:
composer require babenkoivan/elastic-adapter
IndexManager
can be used to manipulate indices. It uses Elasticsearch client as a dependency,
therefore you need to initiate the client before you create an IndexManager
instance:
$client = \Elasticsearch\ClientBuilder::fromConfig([
'hosts' => [
'localhost:9200'
]
]);
$indexManager = new \ElasticAdapter\Indices\IndexManager($client);
The manager provides a set of useful methods, which are listed below.
Create an index, either with the default settings and mapping:
$index = new \ElasticAdapter\Indices\IndexBlueprint('my_index');
$indexManager->create($index);
or configured according to your needs:
$mapping = (new \ElasticAdapter\Indices\Mapping())
->text('title', [
'boost' => 2,
])
->keyword('tag', [
'null_value' => 'NULL'
])
->geoPoint('location')
->dynamicTemplate('no_doc_values', [
'match_mapping_type' => '*',
'mapping' => [
'type' => '{dynamic_type}',
'doc_values' => false,
],
]);
$settings = (new \ElasticAdapter\Indices\Settings())
->index([
'number_of_replicas' => 2,
'refresh_interval' => -1
]);
$index = new \ElasticAdapter\Indices\IndexBlueprint('my_index', $mapping, $settings);
$indexManager->create($index);
Alternatively, you can create an index using raw input:
$mapping = [
'properties' => [
'title' => [
'type' => 'text'
]
]
];
$settings = [
'number_of_replicas' => 2
];
$indexManager->createRaw('my_index', $mapping, $settings);
Delete an index:
$indexManager->drop('my_index');
Update an index mapping using builder:
$mapping = (new \ElasticAdapter\Indices\Mapping())
->text('title', [
'boost' => 2,
])
->keyword('tag', [
'null_value' => 'NULL'
])
->geoPoint('location');
$indexManager->putMapping('my_index', $mapping);
or using raw input:
$mapping = [
'properties' => [
'title' => [
'type' => 'text'
]
]
];
$indexManager->putMappingRaw('my_index', $mapping);
Update an index settings using builder:
$settings = (new \ElasticAdapter\Indices\Settings())
->analysis([
'analyzer' => [
'content' => [
'type' => 'custom',
'tokenizer' => 'whitespace'
]
]
]);
$indexManager->putSettings('my_index', $settings);
or using raw input:
$settings = [
'number_of_replicas' => 2
];
$indexManager->putSettingsRaw('my_index', $settings);
Check if an index exists:
$indexManager->exists('my_index');
Open an index:
$indexManager->open('my_index');
Close an index:
$indexManager->close('my_index');
Create an alias:
$alias = new \ElasticAdapter\Indices\Alias('my_alias', [
'term' => [
'user_id' => 12,
],
]);
$indexManager->putAlias('my_index', $alias);
Get index aliases:
$indexManager->getAliases('my_index');
Delete an alias:
$indexManager->deleteAlias('my_index', 'my_alias');
Similarly to IndexManager
, the DocumentManager
class also depends on Elasticsearch client:
$client = \Elasticsearch\ClientBuilder::fromConfig([
'hosts' => [
'localhost:9200'
]
]);
$documentManager = new \ElasticAdapter\Documents\DocumentManager($client);
Add a document to the index:
$documents = collect([
new ElasticAdapter\Documents\Document('1', ['title' => 'foo']),
new ElasticAdapter\Documents\Document('2', ['title' => 'bar']),
]);
$documentManager->index('my_index', $documents);
There is also an option to refresh index immediately:
$documentManager->index('my_index', $documents, true);
Finally, you can set a custom routing:
$routing = (new ElasticAdapter\Documents\Routing())
->add('1', 'value1')
->add('2', 'value2');
$documentManager->index('my_index', $documents, false, $routing);
Remove a document from the index:
$documentIds = ['1', '2'];
$documentManager->delete('my_index', $documentIds);
If you want the index to be refreshed immediately pass true
as the third argument:
$documentManager->delete('my_index', $documentIds, true);
You can also set a custom routing:
$routing = (new ElasticAdapter\Documents\Routing())
->add('1', 'value1')
->add('2', 'value2');
$documentManager->delete('my_index', $documentIds, false, $routing);
Finally, you can delete documents using query:
$documentManager->deleteByQuery('my_index', ['match_all' => new \stdClass()]);
Search documents in the index:
// create a search request
$request = new \ElasticAdapter\Search\SearchRequest([
'match' => [
'message' => 'test'
]
]);
// configure highlighting
$request->highlight([
'fields' => [
'message' => [
'type' => 'plain',
'fragment_size' => 15,
'number_of_fragments' => 3,
'fragmenter' => 'simple'
]
]
]);
// add suggestions
$request->suggest([
'message_suggest' => [
'text' => 'test',
'term' => [
'field' => 'message'
]
]
]);
// enable source filtering
$request->source(['message', 'post_date']);
// collapse fields
$request->collapse([
'field' => 'user'
]);
// aggregate data
$request->aggregations([
'max_likes' => [
'max' => [
'field' => 'likes'
]
]
]);
// sort documents
$request->sort([
['post_date' => ['order' => 'asc']],
'_score'
]);
// rescore documents
$request->rescore([
'window_size' => 50,
'query' => [
'rescore_query' => [
'match_phrase' => [
'message' => [
'query' => 'the quick brown',
'slop' => 2,
],
],
],
'query_weight' => 0.7,
'rescore_query_weight' => 1.2,
]
]);
// add a post filter
$request->postFilter([
'term' => [
'cover' => 'hard'
]
]);
// track total hits
$request->trackTotalHits(true);
// track scores
$request->trackScores(true);
// script fields
$request->scriptFields([
'my_doubled_field' => [
'script' => [
'lang' => 'painless',
'source' => 'doc[params.field] * params.multiplier',
'params' => [
'field' => 'my_field',
'multiplier' => 2,
],
],
],
]);
// boost indices
$request->indicesBoost([
['my-alias' => 1.4],
['my-index' => 1.3],
]);
// use pagination
$request->from(0)->size(20);
// execute the search request and get the response
$response = $documentManager->search('my_index', $request);
// get the total number of matching documents
$total = $response->total();
// get the corresponding hits
$hits = $response->hits();
// every hit provides an access to the related index name, the score, the document and the highlight
// in addition, you can get a raw representation of the hit
foreach ($hits as $hit) {
$indexName = $hit->indexName();
$score = $hit->score();
$document = $hit->document();
$highlight = $hit->highlight();
$raw = $hit->raw();
}
// get the suggestions
$suggestions = $response->suggestions();
// get the aggregations
$aggregations = $response->aggregations();