PHPackages                             pdphilip/elasticlens - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. pdphilip/elasticlens

ActiveLibrary[Database & ORM](/categories/database)

pdphilip/elasticlens
====================

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

v4.0.1(2mo ago)10427.6k↑100%9[1 PRs](https://github.com/pdphilip/elasticlens/pulls)MITPHPPHP ^8.2CI passing

Since Aug 21Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/pdphilip/elasticlens)[ Packagist](https://packagist.org/packages/pdphilip/elasticlens)[ Docs](https://github.com/pdphilip/elasticlens)[ GitHub Sponsors](https://github.com/pdphilip)[ RSS](/packages/pdphilip-elasticlens/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (14)Versions (28)Used By (0)

[![ElasticLens for Laravel](https://camo.githubusercontent.com/4b0545d3f5af0634e32a19811a91817ae2b19d53f71370489dfe05c85d27226d/68747470733a2f2f63646e2e736e6970666f726d2e696f2f70647068696c69702f656c61737469636c656e732f656c61737469636c656e732d62616e6e65722e737667)](https://camo.githubusercontent.com/4b0545d3f5af0634e32a19811a91817ae2b19d53f71370489dfe05c85d27226d/68747470733a2f2f63646e2e736e6970666f726d2e696f2f70647068696c69702f656c61737469636c656e732f656c61737469636c656e732d62616e6e65722e737667)[![Latest Version on Packagist](https://camo.githubusercontent.com/f8a4984e2b9024c21a37898c791a8821578f013a419fda87bd479a2a4da50b20/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f70647068696c69702f656c61737469636c656e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/pdphilip/elasticlens)[![GitHub Tests Action Status](https://camo.githubusercontent.com/d3c7b07e58c78435b44ca0a177e14bd08af367573d718d056db26fbec0d9a7af/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f70647068696c69702f656c61737469636c656e732f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/pdphilip/elasticlens/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/c27569633f6501aeb17ca1e0d6fa71ffda0fd089d4e2daa74444961d604f3d4c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f70647068696c69702f656c61737469636c656e732f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/pdphilip/elasticlens/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/9e835be8a6ce7fe1d2094f0f6d40f6bccc47551b9370728df026cab839ad826b/687474703a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f70647068696c69702f656c61737469636c656e732e737667)](https://packagist.org/packages/pdphilip/elasticlens)

### Search your **Laravel models** with Eloquent ease and Elasticsearch power

[](#search-your-laravel-models-with-eloquent-ease-and-elasticsearch-power)

Scout's simplicity • Elasticsearch's power • Your rules

```
// Add a trait. Search your models.
User::search('mass donuts');
```

```
// Phrase match + filters + embedded fields + pagination. One query.
User::viaIndex()
    ->searchPhrase('mass donuts')
    ->where('status', 'active')
    ->where('logs.country', 'Norway')
    ->orderByDesc('created_at')
    ->paginate(10);
```

```
// Find every user within 5km who mentioned "espressos" in their profile.
// Sorted by distance. Because priorities.
User::viaIndex()
    ->searchTerm('espressos')
    ->whereGeoDistance('home.location', '5km', [40.7128, -74.0060])
    ->orderByGeo('home.location', [40.7128, -74.0060])
    ->get();
```

Scout gives you a search box behind a black box. ElasticLens gives you a search engine you can open up.

Every index is a real Eloquent model you own. You define the field mappings. You define the schema. You see exactly what's indexed and how. No magic, no guessing, no driver abstractions between you and your data.

Powered by [Laravel-Elasticsearch](https://github.com/pdphilip/laravel-elasticsearch).

---

How It Works
------------

[](#how-it-works)

**1. Add the trait**

```
class User extends Model
{
    use Indexable;
}
```

**2. Generate the index model**

```
php artisan lens:make User
```

Creates `IndexedUser`: a real Elasticsearch model that stays synced with your `User` via observers. Every create, update, delete is reflected automatically.

**3. Search**

```
// Quick search across all fields
User::search('vinyl collecting');

// Full Elasticsearch query builder. Go nuts.
User::viaIndex()->searchTerm('vinyl')->where('state', 'active')->get();
User::viaIndex()->searchFuzzy('elsticsearsh')->get();   // can't even spell it? no problem
User::viaIndex()->whereRegex('hobby', 'sw(im|itch)')->paginate(10);
```

---

Embed Relationships
-------------------

[](#embed-relationships)

Here's where the "oh cool" becomes "holy shit."

You've got a User model. Profiles in one table. Company in another. Logs in a third. Country in a fourth. In SQL, searching across all of that is a JOIN nightmare you pretend doesn't bother you. With ElasticLens, you flatten everything into one searchable document:

```
class IndexedUser extends IndexModel
{
    protected $baseModel = User::class;

    public function fieldMap(): IndexBuilder
    {
        return IndexBuilder::map(User::class, function (IndexField $field) {
            $field->text('first_name');
            $field->text('last_name');
            $field->text('email');
            $field->type('state', UserState::class);

            // Embed the user's profiles as nested objects
            $field->embedsMany('profiles', Profile::class)->embedMap(function ($field) {
                $field->text('bio');
                $field->array('tags');
            });

            // Embed the company they belong to
            $field->embedsBelongTo('company', Company::class)->embedMap(function ($field) {
                $field->text('name');
                $field->text('industry');
            });

            // Last 10 logs only. We're not animals.
            $field->embedsMany('logs', UserLog::class, null, null, function ($query) {
                $query->orderBy('created_at', 'desc')->limit(10);
            })->embedMap(function ($field) {
                $field->text('action');
                $field->text('ip');
            });
        });
    }
}
```

Now search across all of it:

```
// Active users at tech companies whose profiles mention "elasticsearch"
User::viaIndex()
    ->where('state', 'active')
    ->where('company.industry', 'Technology')
    ->where('profiles.bio', 'like', '%elasticsearch%')
    ->get();
```

Six SQL tables. Zero JOINs. One query.

Update a `Profile`? The parent `IndexedUser` rebuilds automatically. The observer chain traces all the way up. You don't have to think about it.

---

Conditional Indexing
--------------------

[](#conditional-indexing)

Not everything deserves an index entry:

```
class User extends Model
{
    use Indexable;

    public function excludeIndex(): bool
    {
        return $this->is_banned; // bye
    }
}
```

Excluded records are tracked as skipped (not failed) in build state and health checks.

---

Index Migrations
----------------

[](#index-migrations)

Define your Elasticsearch mapping with a Blueprint. Same idea as database migrations:

```
public function migrationMap(): callable
{
    return function (Blueprint $index) {
        $index->text('first_name');
        $index->keyword('first_name');
        $index->text('email');
        $index->keyword('email');
        $index->keyword('state');
        $index->nested('profiles');
    };
}
```

```
php artisan lens:migrate User
```

 [![ElasticLens Migrate](https://camo.githubusercontent.com/3de41ea8bf62d52c03ace4bc6b94d515a84f288306d54bebda2960fca4685810/68747470733a2f2f63646e2e736e6970666f726d2e696f2f70647068696c69702f656c61737469636c656e732f6c656e732d6d6967726174652e676966)](https://camo.githubusercontent.com/3de41ea8bf62d52c03ace4bc6b94d515a84f288306d54bebda2960fca4685810/68747470733a2f2f63646e2e736e6970666f726d2e696f2f70647068696c69702f656c61737469636c656e732f6c656e732d6d6967726174652e676966)

---

CLI Tools
---------

[](#cli-tools)

```
php artisan lens:status              # Bird's eye view of all indexes
php artisan lens:health User         # Deep health check for one index
php artisan lens:build User          # Bulk rebuild all records
php artisan lens:migrate User        # Drop, migrate, rebuild. The nuclear option.
php artisan lens:make Profile        # Generate a new index model
```

 [![ElasticLens Status](https://camo.githubusercontent.com/c5716bfc1b1873563074b71cb6a1f143eb891cd8ff634dda118c0fea4774ef8f/68747470733a2f2f63646e2e736e6970666f726d2e696f2f70647068696c69702f656c61737469636c656e732f6c656e732d7374617475732e706e67)](https://camo.githubusercontent.com/c5716bfc1b1873563074b71cb6a1f143eb891cd8ff634dda118c0fea4774ef8f/68747470733a2f2f63646e2e736e6970666f726d2e696f2f70647068696c69702f656c61737469636c656e732f6c656e732d7374617475732e706e67)

 [![ElasticLens Build](https://camo.githubusercontent.com/e4c9a9aa760326fb62b72d6fedd277de0af7fd219766cc6e829caa89b3df33e9/68747470733a2f2f63646e2e736e6970666f726d2e696f2f70647068696c69702f656c61737469636c656e732f6c656e732d6275696c642d76322e676966)](https://camo.githubusercontent.com/e4c9a9aa760326fb62b72d6fedd277de0af7fd219766cc6e829caa89b3df33e9/68747470733a2f2f63646e2e736e6970666f726d2e696f2f70647068696c69702f656c61737469636c656e732f6c656e732d6275696c642d76322e676966)

---

Soft Delete Support
-------------------

[](#soft-delete-support)

Configure globally or per-model whether soft-deleted records keep their index:

```
// config/elasticlens.php
'index_soft_deletes' => true,
```

```
// Or per index model
class IndexedUser extends IndexModel
{
    protected ?bool $indexSoftDeletes = true;
}
```

Restoring a model rebuilds its index automatically.

---

Requirements
------------

[](#requirements)

VersionPHP8.2+Laravel10 / 11 / 12Elasticsearch8.xInstallation
------------

[](#installation)

```
composer require pdphilip/elasticlens
```

```
php artisan lens:install    # Publish config
php artisan migrate         # Create build state + migration log indexes
```

> Requires a configured [Laravel-Elasticsearch](https://github.com/pdphilip/laravel-elasticsearch) connection. [Setup guide ->](https://elasticsearch.pdphilip.com/getting-started/configuration)

---

Documentation
-------------

[](#documentation)

Full docs at **[elasticlens.pdphilip.com](https://elasticlens.pdphilip.com)**

---

Credits
-------

[](#credits)

- [David Philip](https://github.com/pdphilip)

License
-------

[](#license)

The MIT License (MIT). See [License File](LICENSE.md).

###  Health Score

55

—

FairBetter than 98% of packages

Maintenance85

Actively maintained with recent releases

Popularity43

Moderate usage in the ecosystem

Community15

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 88.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~25 days

Recently: every ~43 days

Total

23

Last Release

84d ago

Major Versions

v0.1.0 → v1.0.02024-09-02

v1.3.1 → v2.0.02024-10-21

v2.0.1 → v3.0.02025-03-28

v3.1.2 → v4.0.02026-02-23

### Community

Maintainers

![](https://www.gravatar.com/avatar/d6945e816609fe0d57ad2e073ad9f6ea008ac19636ff439e528c765df6c26230?d=identicon)[pdphilip](/maintainers/pdphilip)

---

Top Contributors

[![pdphilip](https://avatars.githubusercontent.com/u/6921550?v=4)](https://github.com/pdphilip "pdphilip (121 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (8 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (5 commits)")[![Tschucki](https://avatars.githubusercontent.com/u/43211841?v=4)](https://github.com/Tschucki "Tschucki (3 commits)")

---

Tags

elasticsearchlaravelsearchlaravelelasticsearcheloquentPDPhilipelasticlens

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/pdphilip-elasticlens/health.svg)

```
[![Health](https://phpackages.com/badges/pdphilip-elasticlens/health.svg)](https://phpackages.com/packages/pdphilip-elasticlens)
```

###  Alternatives

[dyrynda/laravel-model-uuid

This package allows you to easily work with UUIDs in your Laravel models.

4802.8M8](/packages/dyrynda-laravel-model-uuid)[pdphilip/elasticsearch

An Elasticsearch implementation of Laravel's Eloquent ORM

145360.2k4](/packages/pdphilip-elasticsearch)[sleimanx2/plastic

Plastic is an Elasticsearch ODM and mapper for Laravel. It renders the developer experience more enjoyable while using Elasticsearch by providing a fluent syntax for mapping , querying and storing eloquent models.

508141.9k1](/packages/sleimanx2-plastic)[lacodix/laravel-model-filter

A Laravel package to filter, search and sort models with ease while fetching from database.

17649.9k](/packages/lacodix-laravel-model-filter)[giacomomasseron/laravel-models-generator

Generate Laravel models from an existing database

484.2k](/packages/giacomomasseron-laravel-models-generator)[pdphilip/cf-request

Cloudflare Laravel Request

2725.6k1](/packages/pdphilip-cf-request)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)