Getting Started

ElasticLens for Laravel is a package that uses Laravel-Elasticsearch to create and sync a searchable index of your SQL models.

ElasticLens, like scout, is a package that allows you to do full text search on your SQL models.

ElasticLens integrates directly with the Laravel-Elasticsearch package, creating a dedicated Index Model that is fully accessible and automatically synced with your SQL Base Model

Note

ElasticLens is a separate package from Laravel-Elasticsearch. Laravel-Elasticsearch is Eloquent for Elasticsearch. ElasticLens is a package that uses Laravel-Elasticsearch to create and sync a searchable index of your SQL models.

Installation

• Laravel 10/11/12
• Elasticsearch 8.x

NB: Before you start, set the Laravel-Elasticsearch DB Config (click to expand)

See Laravel-Elasticsearch for more details

Update .env

ES_AUTH_TYPE=http
ES_HOSTS="http://localhost:9200"
ES_USERNAME=
ES_PASSWORD=
ES_CLOUD_ID=
ES_API_ID=
ES_API_KEY=
ES_SSL_CA=
ES_INDEX_PREFIX=my_app_
# prefix will be added to all indexes created by the package with an underscore
# ex: my_app_user_logs for UserLog model
ES_SSL_CERT=
ES_SSL_CERT_PASSWORD=
ES_SSL_KEY=
ES_SSL_KEY_PASSWORD=
# Options
ES_OPT_ID_SORTABLE=false
ES_OPT_VERIFY_SSL=true
ES_OPT_RETRIES=
ES_OPT_META_HEADERS=true
ES_ERROR_INDEX=
ES_OPT_BYPASS_MAP_VALIDATION=false
ES_OPT_DEFAULT_LIMIT=1000

Update config/database.php

'elasticsearch' => [
   'driver' => 'elasticsearch',
   'auth_type' => env('ES_AUTH_TYPE', 'http'), //http or cloud
   'hosts' => explode(',', env('ES_HOSTS', 'http://localhost:9200')),
   'username' => env('ES_USERNAME', ''),
   'password' => env('ES_PASSWORD', ''),
   'cloud_id' => env('ES_CLOUD_ID', ''),
   'api_id' => env('ES_API_ID', ''),
   'api_key' => env('ES_API_KEY', ''),
   'ssl_cert' => env('ES_SSL_CA', ''),
   'ssl' => [
       'cert' => env('ES_SSL_CERT', ''),
       'cert_password' => env('ES_SSL_CERT_PASSWORD', ''),
       'key' => env('ES_SSL_KEY', ''),
       'key_password' => env('ES_SSL_KEY_PASSWORD', ''),
   ],
   'index_prefix' => env('ES_INDEX_PREFIX', false),
   'options' => [
       'bypass_map_validation' => env('ES_OPT_BYPASS_MAP_VALIDATION', false),
       'logging' => env('ES_OPT_LOGGING', false),
       'ssl_verification' => env('ES_OPT_VERIFY_SSL', true),
       'retires' => env('ES_OPT_RETRIES', null),
       'meta_header' => env('ES_OPT_META_HEADERS', true),
       'default_limit' => env('ES_OPT_DEFAULT_LIMIT', 1000),
       'allow_id_sort' => env('ES_OPT_ID_SORTABLE', false),
   ],
],

composer require pdphilip/elasticlens

Publish the config file and run the migrations with:

php artisan lens:install

Run the migrations to create the index build and migration logs indexes:

php artisan migrate

Optional Configuration

lens:install will publish the config file to config/elasticlens.php and create the migration files build and migration logs.

You can customize the configuration in config/elasticlens.php

config/elasticlens.php

return [
    'database' => 'elasticsearch',

    'queue' => null, // Set queue to use for dispatching index builds, ex: default, high, low, etc.

    // Watchers map changes to a given model to tigger an index build
    // By default the base model is observed and will trigger an index build
    // In some cases you may want to observe a different model
    // For example when a relation is updated
    'watchers' => [
        //  \App\Models\Profile::class => [
        //      \App\Models\Indexes\IndexedUser::class,
        //  ],
    ],

    'index_build_state' => [
        'enabled' => true, // Recommended to keep this enabled
        'log_trim' => 2, // If null, the logs field will be empty
    ],

    'index_migration_logs' => [
        'enabled' => true, // Recommended to keep this enabled
    ],
    'namespaces' => [
        'App\Models' => 'App\Models\Indexes',
    ],

    'index_paths' => [
        'app/Models/Indexes/' => 'App\Models\Indexes',
    ],
];

How it works

The Index Model acts as a separate Elasticsearch model managed by ElasticLens, yet you retain full control over it, just like any other Laravel model. In addition to working directly with the Index Model, ElasticLens offers tools for

• Full-text searching of your Base Models using the full feature set of the Larevel-Elasticsearch package
• Mapping fields (with embedded relationships) during the build process
• Define Index Model migrations.
• CLI tools to view sync status and manage your Index Models

For Example, a base User Model will sync with an Elasticsearch IndexedUser Model that provides all the features from Laravel-Elasticsearch to search your base User Models