Upgrading from V3

Upgrading from ElasticLens v3 to v4 is straightforward. Most changes are additive; the core breaking change is how viaIndex() returns results.

Update Composer

composer require pdphilip/elasticlens:^4.0

Breaking Change: viaIndex() Return Type

In v3, viaIndex()->get() returned Index Models. In v4, it returns Base Models.

If you used getBase() / paginateBase()

These still work. They’re now aliases for the default behavior through viaIndex():

// v3 (still works in v4, just redundant)
User::viaIndex()->searchTerm('david')->getBase();

// v4 equivalent
User::viaIndex()->searchTerm('david')->get();

No action required; your existing getBase() / paginateBase() calls continue to work.

If you used get() / paginate() directly

If you relied on viaIndex()->get() returning index models, switch to the new explicit methods:

// v3 - returned IndexedUser models
User::viaIndex()->searchTerm('david')->get();

// v4 - use getIndex() for index models
User::viaIndex()->searchTerm('david')->getIndex();

Same for pagination:

// v3 - returned paginator of IndexedUser
User::viaIndex()->searchTerm('david')->paginate(10);

// v4 - use paginateIndex() for index models
User::viaIndex()->searchTerm('david')->paginateIndex(10);

If you used asBase() on collections

Still works:

// v3 (still works)
User::viaIndex()->searchTerm('david')->getIndex()->asBase();

// v4 - simpler
User::viaIndex()->searchTerm('david')->get();

New Features (No Action Required)

Conditional Indexing

New opt-in feature. Override excludeIndex() on your base model to skip records:

public function excludeIndex(): bool
{
    return $this->status === 'banned';
}

Soft Delete Support

New opt-in feature. Configure in config/elasticlens.php:

'index_soft_deletes' => true,

Or per-model on your Index Model:

protected ?bool $indexSoftDeletes = true;

New Config Option

The config file has a new index_soft_deletes key. Re-publish to get it:

php artisan vendor:publish --tag=elasticlens-config

Or add it manually:

config/elasticlens.php

'index_soft_deletes' => false,

---