README

Introduction

Focus of this library is to make it easier to manage elastic indices (wit mappings / settings), create reusable query building (manual or from request).

Adds ability to manage elasticsearch indices with wrapper class which will help to you create/update index write documents (with bulk mode) etc.
Adds ability to create a query builder with query filters for each index.
Adds ability to build a query builder from request data (reusable component).

Requirements

Composer
PHP 7.4+

Installation

1. Add custom repository to composer.json

"repositories": {
    {
        "type": "git",
        "url": "https://github.com/pionl/elasticsearch-query-builder.git"
    }
}

2. Install via composer

composer require pion/laravel-lelastico

3. Add the service provider (Laravel 5.4 and below - supports Auto discovery)

\Lelastico\LelasticoServiceProvider::class,

Dependencies

erichard/elasticsearch-query-builder - at this moment forked version with additional functions.
elasticsearch/elasticsearch, version 7 and above (tested with 7.5).

Usage

Set elastic hosts

For development, you can use default value in the config without password: localhost:9200

Use ELASTICSEARCH_HOSTS environment for setting elastic search hosts. Format.

Resolve elastic search client

$client = resolve(\Elasticsearch\Client::class);

$client = $container->make(\Elasticsearch\Client::class);

Mapping types constants

Property mappings types using constants like:

MappingTypes::KEYWORD
MappingTypes::TEXT
MappingTypes::TEXT_WITH_KEYWORD
MappingTypes::SHORT
MappingTypes::SHORT_WITH_KEYWORD
MappingTypes::LONG
MappingTypes::LONG_WITH_KEYWORD
MappingTypes::INTEGER
MappingTypes::INTEGER_WITH_KEYWORD
MappingTypes::DATE
MappingTypes::BOOLEAN
MappingTypes::FLOAT
MappingTypes::textWithAnalyzer(string $analyzer, string $searchAnalyzer), builds

Adding indices

Create your indices by extending AbstractElasticIndex and implementing createIndexName for elastic index

Implement propertyMappings for custom mappings.

protected function propertyMappings(): array
{
  return [
      'id' => MappingTypes::KEYWORD,
      'name' => MappingTypes::TEXT_WITH_KEYWORD,
      'is_verified' => MappingTypes::BOOLEAN,
      'email' => MappingTypes::textWithAnalyzer('fulltext'),
      'created_at' => MappingTypes::DATE,
      'updated_at' => MappingTypes::DATE,
      'deleted_at' => MappingTypes::DATE,
  ];
}

Implement settings for custom index settings

protected function settings(): array
{
  // Add support for partial text search
  return [
      'index' => [
          'analysis' => [
              'filter' => [
                  'fulltext_filter' => [
                      // Always from start of beginning of each token
                      'type' => 'edge_ngram',
                      'min_gram' => 3,
                      'max_gram' => 20,
                  ],
              ],
              'analyzer' => [
                  'fulltext' => [
                      'type' => 'custom',
                      'tokenizer' => 'standard',
                      'filter' => ['lowercase', 'fulltext_filter'],
                  ],
              ],
          ],
      ],
  ];
}

Create or update lelastico.php config with indices classes.

return [
    'indices' => [
        \App\ElasticSearch\Indices\UsersIndex::class,
    ],
];

Update or create indices in elastic (stores settings / mapping) using php artisan elastic:indices

Updates the elastic indices
        --only="only", handle only given index
        --f, will delete the index and data. Will new index with mappings
        --d, will delete the index and data
        --skip-settings-update, when upadting, the index is closed / opened due the settings update. You can skip it
        by provided this option.

Sorting

By default we are sorting by _id after any HasSorting logic to ensure that pagination is correct.

You can turn this feature by using $builder->setSortById(false);

To enable sortable behavior add HasSorting trait to your instance of AbstractBuilder and implement method allowedSortFields.

/**
 * Allowed fields for sorting.
 *
 * Key is the name of the field in the query.
 * Value is the name of the field in the index.
 *
 * @return array
 */
public function allowedSortFields(): array
{
    return [
        'goals' => 'goals_count',
        'minutes' => 'played_minutes',
    ];
}

With sorting enabled you can sort the results using sort request query parameter. This parameter accepts list of fields for sorting in format {field_name}:{sort_direction}.

Available directions for sorting are asc and desc and if not specified the default sort direction is set to asc.

Examples:

sort[]=goals

sort[]=goals:asc&sort[]=minutes:desc

Configuration

log_measurement Logs every query to log (default false). You can use ELASTICSEARCH_LOG_MEASUREMENT env.
log_debug Debug logs every query data to a log (true in local environment). You can use ELASTICSEARCH_LOG_DEBUG env.
service Enables to change available indices (implement IndicesServiceContract or extend IndicesService)
prefix Used prefix for index names - uses APP_NAME and replace '-' to '_', converts name to slug variant.
hosts A list of IPS for your elastic search - https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/configuration.html. Use ; separator. Default localhost:9200.

TODO

improve documentation
add make console.

Changelog

Can be found in releases.

Contribution or extending

See CONTRIBUTING.md for how to contribute changes. All contributions are welcome.

Copyright and License

laravel-elastico was written by Martin Kluska and is released under the MIT License.

pion / laravel-lelastico

Maintainers

Details