aviationcode/elasticsearch

Laravel elasticsearch and eloquent integration

v0.15.0 2024-05-17 12:02 UTC

Requires

• ext-json: *
• elasticsearch/elasticsearch: ^6.0|^7.0
• illuminate/support: ^11.0

Requires (Dev)

• mockery/mockery: ^1.1
• nunomaduro/larastan: ^2.0
• orchestra/testbench: ^9.0
• phpcompatibility/php-compatibility: ^9.3
• phpunit/phpunit: ^10.0
• sempro/phpunit-pretty-print: ^1.0
• squizlabs/php_codesniffer: ^3.8

MIT

• author name

• elasticsearch
• laravel

README

This package wraps the elasticsearch/elasticsearch composer package with laravel integration. Adding support to easily use your eloquent models with elastic search.

Installation

Via Composer

$ composer require aviationcode/elasticsearch

Configuration

By default, we use localhost:9200 to search your elasticsearch instance. If this is the case no configuration is required at all. You can use the following .env settings to configure how we connect to your elasticsearch instance.

Name	Type	Default	Description
ELASTIC_HOST	string	localhost	The IP or host to connect to
ELASTIC_PORT	integer	9200	The port used to connect
ELASTIC_SCHEME	string	http	Use of HTTP or HTTPS
ELASTIC_USER	string	null	The Basic auth username
ELASTIC_PASSWORD	string	null	The Basic auth password

Usage

Configure a model to use elasticsearch by using the ElasticSearchable trait or extend using ElasticsearchModel.

use AviationCode\Elasticsearch\Model\ElasticSearchable;
use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    use ElasticSearchable;
}

Custom mapping properties

We attempt to detect the elasticsearch mapping fields from your $dates array and primary key. We are unable to correctly detect other fields.

Elasticsearch will in this case attempt to guess the mapping field automatically however it is recommended to explicitly define these fields as the correct type.

use AviationCode\Elasticsearch\Model\ElasticSearchable;
use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    use ElasticSearchable;
    
    public $mapping = [
        'category' => ['type' => 'keyword'],
        'properties' => ['type' => 'object', 'dynamic' => true],
        'ip' => ['type' => 'ip'],
    ];
}

Use the elasticsearch documentation to find all options available.

Non numeric keys

When using UUID's or other non numeric keys make sure you configure your model correctly. This will make sure we use the correct mapping inside your model mapping.

use AviationCode\Elasticsearch\Model\ElasticSearchable;
use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    use ElasticSearchable;

    protected $keyType = 'string';    
}

Custom index name

You may want to use a custom name or use existing index name with your eloquent model. Just like you can define the database table used you can also define the index named used.

use AviationCode\Elasticsearch\Model\ElasticSearchable;
use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    use ElasticSearchable;
    
    public $indexName = 'my_custom_index_name';
}

Note: You can still use $indexVersion to add vX at the end of your index.

Versioned index

If you like to version your index names you can use the $indexVersion name. This will add _vX at the end of your index name where X is the index version.

use AviationCode\Elasticsearch\Model\ElasticSearchable;
use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    use ElasticSearchable;
    
    public $indexVersion = 2;
}

Query

namespace App\Http\Controllers;

use App\Article;
use AviationCode\Elasticsearch\Facades\Elasticsearch;
use AviationCode\Elasticsearch\Query\Dsl\Boolean\Filter;
use AviationCode\Elasticsearch\Query\Dsl\Boolean\Must;
use Illuminate\Http\Request;

class ArticleController 
{
    public function index(Request $request)
    {
        return Elasticsearch::forModel(Article::class)
            ->query()
            ->filter(function (Filter $filter) use ($request) {
                if ($user = $request->query('user')) {
                    $filter->term('user', $user); 
                }
            })
            ->must(function (Must $must) use ($request) {
                if ($query = $request->query('q')) {
                    $must->queryString($query); 
                }        
            })
            ->get();
    }
}

Without an eloquent model.

namespace App\Http\Controllers;

use App\Article;
use AviationCode\Elasticsearch\Facades\Elasticsearch;
use AviationCode\Elasticsearch\Query\Dsl\Boolean\Filter;
use AviationCode\Elasticsearch\Query\Dsl\Boolean\Must;
use Illuminate\Http\Request;

class ArticleController 
{
    public function index(Request $request)
    {
        return Elasticsearch::query('article')
            ->filter(function (Filter $filter) use ($request) {
                if ($user = $request->query('user')) {
                    $filter->term('user', $user); 
                }
            })
            ->must(function (Must $must) use ($request) {
                if ($query = $request->query('q')) {
                    $must->queryString($query); 
                }        
            })
            ->get();
    }
}

Aggregations

Using aggregations with model.

namespace App\Http\Controllers;

use App\Article;
use AviationCode\Elasticsearch\Facades\Elasticsearch;

class ArticlesPerUserPerDayController 
{
    public function index()
    {
        $qb = Elasticsearch::forModel(Article::class)->query();

        $qb->aggregations()
            ->dateHistogram('date', 'created_at', '1d')
            ->terms('date.users', 'user');

        return $qb->get()->aggregations;
    }
}

Using aggregations without an eloquent model.

namespace App\Http\Controllers;

use App\Article;
use AviationCode\Elasticsearch\Facades\Elasticsearch;

class ArticlesPerUserPerDayController 
{
    public function index()
    {
        $qb = Elasticsearch::query('article');

        $qb->aggregations()
            ->dateHistogram('date', 'created_at', '1d')
            ->terms('date.users', 'user');

        return $qb->get()->aggregations;
    }
}

Console Commands

elastic:create-index Creating elasticsearch index

Change log

Please see the changelog for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see contributing.md for details and a todolist.

Security

If you discover a security vulnerability within elasticsearch package, please send an e-mail to Ken Andries at [e-mail]. All security vulnerabilities will be promptly addressed.

Credits

• Ken Andries
• All Contributors

License

license. Please see the license file for more information.