Download the PHP package pdphilip/elasticlens without Composer

[](https://packagist.org/packages/pdphilip/elasticlens) [](https://github.com/pdphilip/elasticlens/actions?query=workflow%3Arun-tests+branch%3Amain) [](https://github.com/pdphilip/elasticlens/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain) [](https://packagist.org/packages/pdphilip/elasticlens)

Search your Laravel Models with the convenience of Eloquent and the power of Elasticsearch

ElasticLens for Laravel uses Elasticsearch to create and sync a searchable index of your Eloquent models.

Wait, isn't this what Laravel Scout does?

Yes, but mostly no.

ElasticLens is built from the ground up around Elasticsearch.

It integrates directly with the Laravel-Elasticsearch package (Elasticsearch using Eloquent), creating a dedicated Index Model that is fully accessible and automatically synced with your Base Model.

Features

• Zero config setup: Start indexing with minimal configuration.
• Eloquent-Like Querying: Search your models as if you're using Eloquent, with the full power of Elasticsearch.
• mapping model relationships as embedded fields.
• Control Observed models: Tailor which models are observed for changes.
• Manage Elasticsearch Migrations: Define a required blueprint for your index migrations.
• Comprehensive CLI Tools: Manage index health, migrate/rebuild indexes, and more with Artisan commands.
• Built-in IndexableBuildState model: Track the build states of your indexes.
• Built-in Migration Logs: Track the build states of your indexes.

Requirements

• Laravel 10.x & 11.x
• Elasticsearch 8.x

Installation

You can install the package via composer:

Publish the config file and run the migrations with:

Usage

The Walkthrough below will demonstrate all the features by way of an example.

In this example, we'll index a User model.

Step 1: Zero config setup

1. Add the Indexable Trait to Your Base Model:

2. Create an Index Model for Your Base Model:

• ElasticLens expects the Index Model to be named as Indexed + BaseModelName and located in the App\Models\Indexes directory.

• That's it! Your User model will now automatically sync with the IndexedUser model whenever changes occur. You can search your User model effortlessly, like:

Step 2: Search your models

Perform quick and easy full-text searches:

Search for the phrase loves espressos across all fields and return the base User models

Cute. But that's not why we're here...

To truly harness the power of Laravel-Elasticsearch for eloquent-like querying, you can use more advanced queries:

Examples:

1. Basic Term Search:

This searches all users who are active for the term 'nara' across all fields and return the top 3 results.

• https://elasticsearch.pdphilip.com/full-text-search#term-search-term

2. Phrase Search:

Searches all fields for the phrase 'Ice bathing' and returns the 3 newest results. Phrases match exact words in order.

• https://elasticsearch.pdphilip.com/full-text-search#phrase-search-phrase

3. Boosting Terms fields:

Searches for the term 'David', boosts the first_name field by 3, last_name by 2, and also checks the bio field. Results are ordered by score.

• https://elasticsearch.pdphilip.com/full-text-search#boosting-terms
• https://elasticsearch.pdphilip.com/full-text-search#minimum-score

4. Geolocation Filtering:

Finds all active users within a 5km radius from the coordinates [0, 0], ordering them from closest to farthest. Not kidding.

• https://elasticsearch.pdphilip.com/es-specific#geo-point
• https://elasticsearch.pdphilip.com/ordering-and-pagination#order-by-geo-distance

5. Regex Search:

Finds all users whose favourite color is blue or black.

• https://elasticsearch.pdphilip.com/full-text-search#regular-expressions

6. Pagination:

Paginate search results.

• https://elasticsearch.pdphilip.com/ordering-and-pagination

7. Nested Object Search:

Searches nested user_logs for users who logged in from Norway within the last week. Whoa.

• https://elasticsearch.pdphilip.com/nested-queries

8. Fuzzy Search:

No spell, no problem. Search Fuzzy.

• https://elasticsearch.pdphilip.com/full-text-search

9. Highlighting Search Results:

Searches for 'espresso' across all fields and highlights where it was found.

• https://elasticsearch.pdphilip.com/full-text-search#highlighting

10. Phrase prefix search:

Searches for the phrase prefix 'loves espr' across all fields and highlights where it was found.

• https://elasticsearch.pdphilip.com/full-text-search#highlighting

Note on Index Model vs Base Model Results

• Since the viaIndex() taps into the IndexModel, the results will be instances of IndexedUser, not the base User model.
• This can be useful for display purposes, such as highlighting embedded fields.
• However, in most cases you'll need to return and work with the Base Model

To search and return results as Base Models:

1. use asBase()

• Simply chain ->asBase() at the end of your query:

2. use getBase() instead of get()->asBase()

To search and paginate results as Base Models use: paginateBase()

• Complete the query string with ->paginateBase()

Step 3: Create a field Map

You can define the fieldMap() method in your Index Model to control how the index is built during synchronization.

Notes:

• The IndexedUser records will contain only the fields defined in the fieldMap(). The value of $user->id will correspond to $indexedUser->_id.

• Fields can also be derived from attributes in the Base Model. For example, $field->bool('is_active') could be derived from a custom attribute in the Base Model:

• When mapping enums, ensure that you also cast them in the Index Model.
• If a value is not found during the build process, it will be stored as null.

Step 4: Update fieldMap() to Include Relationships as Embedded Fields

You can further customize the indexing process by embedding relationships as nested objects within your Index Model. The builder allows you to define fields and embed relationships, enabling more complex data structures in your Elasticsearch index.

Examples:

1. If a User has many Profiles

2. If a Profile has one ProfileStatus

3. If a User belongs to an Account

4. If a User belongs to a Country and you don't need to observe the Country model:

5. If a User has Many UserLogs and you only want to embed the last 10:

IndexField $field Methods:

• text($field)
• integer($field)
• array($field)
• bool($field)
• type($field, $type) - Set own type (like Enums)
• embedsMany($field, $relatedModelClass, $whereRelatedField, $equalsLocalField, $query)
• embedsBelongTo($field, $relatedModelClass, $whereRelatedField, $equalsLocalField, $query)
• embedsOne($field, $relatedModelClass, $whereRelatedField, $equalsLocalField, $query)

Note: For embeds the $whereRelatedField, $equalsLocalField, $query parameters are optional.

• $whereRelatedField is the foreignKey & $equalsLocalField is the localKey and they will be inferred from the relationship if not provided.
• $query is a closure that allows you to customize the query for the related model.

Embedded Relationship Builder Methods:

• embedMap(function (IndexField $field) {}) - Define the mapping for the embedded relationship
• dontObserve() - Don't observe changes in the $relatedModelClass

Step 5: Fine-tune the Observers

By default, the base model will be observed for changes (saves) and deletions. When the Base Model is deleted, the corresponding Index Model will also be deleted, even in cases of soft deletion.

Handling Embedded Models

When you define a fieldMap() with embedded fields, the related models are also observed. For example:

• A save or delete action on ProfileStatus will trigger a chain reaction, fetching the related Profile and then User, which in turn initiates a rebuild of the index for that user record.

However, to ensure these observers are loaded, you need to reference the User model explicitly:

Customizing Observers

If you want ElasticLens to observe ProfileStatus without requiring a reference to User, follow these steps:

1. Add the HasWatcher Trait to ProfileStatus:

2. Define the Watcher in the elasticlens.php Config File:

Disabling Base Model Observation

If you want to disable the automatic observation of the Base Model, include the following in your Index Model:

Step 6: Define your Index Model's migrationMap()

Elasticsearch automatically indexes new fields it encounters, but it might not always index them in the way you need. To ensure the index is structured correctly, you can define a migrationMap() in your Index Model.

Since the Index Model utilizes the Laravel-Elasticsearch package, you can use IndexBlueprint to customize your migrationMap()

Notes:

• Documentation: For more details on migrations, refer to the: https://elasticsearch.pdphilip.com/migrations
• Running the Migration: To execute the migration and rebuild all your indexed, use the following command:

This command will delete the existing index, run the migration, and rebuild all records.

Step 7: Monitor and administer all your indexes with Artisan commands

Use the following Artisan commands to manage and monitor your Elasticsearch indexes:

1. Check Overall Status:

Displays the overall status of all your indexes and the ElasticLens configuration.

2. Check Index Health:

Provides a comprehensive state of a specific index, in this case, for the User model.

3. Migrate and Build/Rebuild an Index:

Deletes the existing User index, runs the migration, and rebuilds all records.

4. Create a New Index Model for a Base Model:

Generates a new index for the Profile model.

5. Bulk (Re)Build Indexes for a Base Model:

Rebuilds all the IndexedProfile records for the Profile model.

Step 8: Optionally access the built-in IndexableBuild model to track index build states

ElasticLens includes a built-in IndexableBuild model that allows you to monitor and track the state of your index builds. This model records the status of each index build, providing you with insights into the indexing process.

Built-in methods include:

Note: While you can query the IndexableBuild model directly, avoid writing or deleting records within it manually, as this can interfere with the health checks and overall integrity of the indexing process. The model should be used for reading purposes only to ensure accurate monitoring and reporting.

Step 9: Optionally Access the Built-in IndexableMigrationLog Model for Index Migration Status

ElasticLens includes a built-in IndexableMigrationLog model for monitoring and tracking the state of index migrations. This model logs each migration related to an Index Model.

Built-in methods include:

Note: While you can query the IndexableMigrationLog model directly, avoid writing or deleting records within it manually, as this can interfere with versioing of the migrations. The model should be used for reading purposes only to ensure accuracy.

Credits

• David Philip

License

The MIT License (MIT). Please see License File for more information.