babenkoivan/elastic-adapter

Adapter for official PHP Elasticsearch client

v1.17.0 2021-07-19 17:33 UTC

README

Latest Stable Version Total Downloads License Tests Code style Static analysis Donate PayPal

Buy Me A Coffee

Elastic Adapter is an adapter for official PHP Elasticsearch client. It's designed to simplify basic index and document operations.

Contents

Compatibility

The current version of Elastic Adapter has been tested with the following configuration:

  • PHP 7.2-8.0
  • Elasticsearch 7.x

Installation

The library can be installed via Composer:

composer require babenkoivan/elastic-adapter

Index Management

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 list of useful methods, which are listed below.

Create

Create an index, either with the default settings and mapping:

$index = new \ElasticAdapter\Indices\Index('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\Index('my_index', $mapping, $settings);

$indexManager->create($index);

Drop

Delete an index:

$indexManager->drop('my_index');

Put Mapping

Update an index mapping:

$mapping = (new \ElasticAdapter\Indices\Mapping())
    ->text('title', [
        'boost' => 2,
    ])
    ->keyword('tag', [
        'null_value' => 'NULL'
    ])
    ->geoPoint('location');

$indexManager->putMapping('my_index', $mapping);

Put Settings

Update an index settings:

$settings = (new \ElasticAdapter\Indices\Settings())
    ->analysis([
        'analyzer' => [
            'content' => [
                'type' => 'custom',
                'tokenizer' => 'whitespace'    
            ]
        ]
    ]);

$indexManager->putSettings('my_index', $settings);

Exists

Check if an index exists:

$indexManager->exists('my_index');

Open

Open an index:

$indexManager->open('my_index');

Close

Close an index:

$indexManager->close('my_index');

Put Alias

Create an alias:

$alias = new \ElasticAdapter\Indices\Alias('my_alias', [
    'term' => [
        'user_id' => 12,
    ],
]);

$indexManager->putAlias('my_index', $alias);

Get Aliases

Get index aliases:

$indexManager->getAliases('my_index');

Delete Alias

Delete an alias:

$indexManager->deleteAlias('my_index', 'my_alias');

Document Management

Similarly to IndexManager, the DocumentManager class also depends on Elasticsearch client:

$client = \Elasticsearch\ClientBuilder::fromConfig([
  'hosts' => [
      'localhost:9200'
  ]
]);

$documentManager = new \ElasticAdapter\Documents\DocumentManager($client);

Index

Add a document to the index:

$documents = [
    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);

In addition, you can set a custom routing path:

$documentManager->index('my_index', $documents, false, 'my_field');

This will route documents to an Elasticsearch shard based on the document's my_field value. Routing path can be specified using "dot" notation to access nested fields.

Delete

Remove a document from the index:

$documents = [
    new ElasticAdapter\Documents\Document('1', ['title' => 'foo']),
    new ElasticAdapter\Documents\Document('2', ['title' => 'bar']),
];

$documentManager->delete('my_index', $documents);

If you want the index to be refreshed immediately pass true as the third argument:

$documentManager->delete('my_index', $documents, true);

You can also set a custom routing path to delete the document from a specific shard:

$documentManager->delete('my_index', $documents, false, 'my_field');

Finally, you can delete documents using query:

$documentManager->deleteByQuery('my_index', ['match_all' => new \stdClass()]);

Search

Search documents in the index:

// create a search request
$request = new \ElasticAdapter\Search\SearchRequest([
    'match' => [
        'message' => 'test'
    ]
]);

// configure highlighting
$request->setHighlight([
    'fields' => [
        'message' => [
            'type' => 'plain',
            'fragment_size' => 15,
            'number_of_fragments' => 3,
            'fragmenter' => 'simple'
        ]
    ]
]);

// add suggestions
$request->setSuggest([
    'message_suggest' => [
        'text' => 'test',
        'term' => [
            'field' => 'message'
        ]
    ]
]);

// enable source filtering
$request->setSource(['message', 'post_date']);

// collapse fields
$request->setCollapse([
    'field' => 'user'
]);

// aggregate data
$request->setAggregations([
    'max_likes' => [
        'max' => [
            'field' => 'likes'
        ]
    ]
]);

// sort documents
$request->setSort([
    ['post_date' => ['order' => 'asc']],
    '_score'
]);

// rescore documents
$request->setRescore([
    '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->setPostFilter([
    'term' => [
        'cover' => 'hard'
    ]
]);

// track total hits
$request->setTrackTotalHits(true);

// track scores
$request->setTrackScores(true);

// script fields
$request->setScriptFields([
    'my_doubled_field' => [
        'script' => [
            'lang' => 'painless',
            'source' => 'doc[params.field] * params.multiplier',
            'params' => [
                'field' => 'my_field',
                'multiplier' => 2,
            ],
        ],
    ],
]);

// boost indices
$request->setIndicesBoost([
    ['my-alias' => 1.4],
    ['my-index' => 1.3],
]);

// use pagination
$request->setFrom(0)->setSize(20);

// execute the search request and get the response
$response = $documentManager->search('my_index', $request);

// get the total number of matching documents
$total = $response->getHitsTotal(); 

// get the corresponding hits
$hits = $response->getHits();

// 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->getIndexName();
    $score = $hit->getScore();
    $document = $hit->getDocument();
    $highlight = $hit->getHighlight();
    $raw = $hit->getRaw();
}

// get the suggestions
$suggestions = $response->getSuggestions();

// get the aggregations
$aggregations = $response->getAggregations();