Upgrading from V3

One breaking change. Two new opt-in features. Here’s the full picture.

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()

They still work. They’re now aliases for the default behavior:

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

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

No action needed.

If you used get() / paginate() directly

If you relied on viaIndex()->get() returning index models, switch to the 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 - paginator of IndexedUser
User::viaIndex()->searchTerm('david')->paginate(10);

// v4 - use paginateIndex()
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 (Opt-in)

Conditional Indexing

Override excludeIndex() on your base model to skip records:

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

Soft Delete Support

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,

---