A lightweight PHP 7.0+ client for Elasticsearch, providing features over Elasticsearch-PHP
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
doc
scripts
src
test
.atoum.php
.bootstrap.atoum.php
.gitignore
.travis.yml
LICENSE
Makefile
README.md
behat.yml
composer.json
docker-compose.yml

README.md

Novaway ElasticSearch Client

A lightweight PHP 7.0+ client for Elasticsearch, providing features over Elasticsearch-PHP

Installation

Install using composer:

$ composer require novaway/elasticsearch-client

Usage

Create an index

The first thing you'll need to do to use this library is to instatiate an index. This will be the keystone of the client.

$index = new \Novaway\ElasticsearchClient\Index(
	['127.0.0.1:9200'],  	# elasticsearch hosts
	'main_index',				# index name
	[
        'settings' => [
            'number_of_shards' => 3,
            'number_of_replicas' => 2
        ],
        'mappings' => [
            'my_type' => [
                '_source' => [
                    'enabled' => true
                ],
                'properties' => [
                    'first_name' => [
                        'type' => 'string',
                        'analyzer' => 'standard'
                    ],
                    'age' => [
                        'type' => 'integer'
                    ]
                ]
            ]
        ]
    ]    
);

Index an object

In order to be searched, objects should be indexed as a serialized version. In order to be indexed, Object should implement \Novaway\ElasticsearchClient\Indexable interface.

By default, objects are serialized with Elasticsearch-PHP's SmartSerializer, but you can choose to use a custom serializer.

$objectIndexer = new \Novaway\ElasticsearchClient\ObjectIndexer($index);
$objectIndexer->index($object, 'my_type');

Remove an object from index

To remove an object from the index, the process is still

$objectIndexer = new \Novaway\ElasticsearchClient\ObjectIndexer($index);
$objectIndexer->remove($object, 'my_type');

// Alternatively, you can remove an indexed object knowing only it's ID.
$objectIndexer->removeById($objectId, 'my_type');

Search the index

Basic match query

First, create a QueryExecutor.

$queryExecutor = new \Novaway\ElasticsearchClient\QueryExecutor($index);

Use the QueryBuilder to build your query and execute it.

use Novaway\ElasticsearchClient\Query\CombiningFactor;

$queryBody = QueryBuilder::createNew()
					->match('first_name', 'John', CombiningFactor::MUST)
					->getQueryBody()
;
$queryExecutor->execute($queryBody, 'my_type');

The QueryBuilder allow you to define a limit and an offset for a search result, and choose the minimum score to display.

const MIN_SCORE = 0.4;
const OFFSET = 0;
const LIMIT = 10;

$queryBuilder = QueryBuilder::createNew(0, 10, 0.3);

Advanced Querying

This client provide several ways to improve querying :

  • Filtering (missing documentation)
  • Aggregations
  • Result Formating (missing documentation)

Clear the index

You might want, for some reason, to purge an index. The reload method drops and recreates the index.

$index->reload();

Recommended usage with Symfony

If you are using this library in a symfony project, we recommend to use it as service.

# services.yml
parameters:
    myapp.search.myindex.config:
        settings:
            number_of_shards : 1
            number_of_replicas : 1
        mappings:
            my_type:
                _source : { enabled : true }
                properties:
                    first_name:
                        type: string
                        analyzer: standard
                    age:
                        type: integer
                        
services:
    myapp.search.index:
        class: Novaway\ElasticsearchClient\Index
        arguments:
            - ['127.0.0.1:9200'] #define it in the parameter.yml file
            - 'myapp_myindex_%kernel.environment%'
            - 'myapp.search.myindex.config'

    myapp.search.object_indexer:
        class: Novaway\ElasticsearchClient\ObjectIndexer
        arguments:
            - '@myapp.search.index'

    myapp.search.query_executor:
        class: Novaway\ElasticsearchClient\QueryExecutor
        arguments:
            - '@myapp.search.index'

Then you'll only have to work with the myapp.search.object_indexer and myapp.search.query_executor services.

Testing

A testing environment is provided using a dockerized version of elasticsearch.

Testing is done using the Atoum framework for unit testing and the Behat framework for behavior testing.

A Makefile provide useful commands for testing, so you can run the full test suite by running :

$ make test

License

This library is published under MIT license