Laravel Scout Relations

Automatically re-index Scout-searchable related models when an Eloquent model is saved or deleted.

When a parent model changes (e.g. an Author), its related Searchable models (e.g. Post) are automatically queued for re-indexing, keeping your search index consistent without any manual intervention.

See the full documentation (or browse docs/ directly): Installation, Usage, Configuration, Artisan Command.

Requirements

• PHP 8.4+
• Laravel 12+
• Laravel Scout

Installation

Install the package via Composer:

composer require foxws/laravel-scout-relations

[!TIP] Let your AI agent do the hard parts. This package ships a Laravel Boost skill, scout-relations-development, that teaches your agent how to install, configure and use Laravel Scout Relations. Install Boost and select the skill when prompted:

composer require laravel/boost --dev
php artisan boost:install

Already using Boost? Run php artisan boost:update --discover to pick up the skill. Then just ask, for example: "Re-index an author's posts in Scout whenever the author is saved."

Usage

Add the HasSearchableRelations trait to any Eloquent model whose changes should trigger re-indexing of related models. Then override searchableRelations() to return the relationship names to watch.

use Foxws\ScoutRelations\Concerns\HasSearchableRelations;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

class Author extends Model
{
    use HasSearchableRelations;

    /**
     * Relationships whose models should be re-indexed when this model changes.
     *
     * @return array<int, string>
     */
    public function searchableRelations(): array
    {
        return ['posts'];
    }

    public function posts(): HasMany
    {
        return $this->hasMany(Post::class);
    }
}

The related Post model must use Laravel Scout's Searchable trait:

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;

    public function toSearchableArray(): array
    {
        return [
            'id'          => $this->id,
            'title'       => $this->title,
            'author_name' => $this->author->name, // kept fresh on every re-index
        ];
    }
}

Now whenever an Author is saved with changes or deleted, all of its Post records are automatically re-indexed.

How it works

The trait hooks into Eloquent's saved and deleted model events:

• saved — re-indexes relations only when wasChanged() is true, avoiding unnecessary indexing on no-op saves.
• deleted — re-indexes relations unconditionally so the search index reflects the parent's removal.

Re-indexing is performed in chunks via chunkById. If the related model defines makeAllSearchableUsing(), it is applied to the chunk query, preventing N+1 queries.

A per-class re-entry guard prevents infinite cascades when mutual relationships exist.

Configuration

Publish the config file with:

php artisan vendor:publish --tag="scout-relations-config"

Available options in config/scout-relations.php:

Key	Env variable	Default	Description
enabled	SCOUT_RELATIONS_ENABLED	true	Disable all automatic relation syncing
chunk.searchable	SCOUT_RELATIONS_CHUNK_SEARCHABLE	500	Chunk size for searchable() calls
chunk.unsearchable	SCOUT_RELATIONS_CHUNK_UNSEARCHABLE	500	Chunk size reserved for future use

Artisan command

To manually force re-indexing of all relations for a model (ignoring the enabled flag), use:

php artisan scout:index-relations "App\Models\Author"

This runs Scout's makeAllSearchable() once for each distinct searchable model class referenced by the model's searchableRelations(), so a relation shared by many records is only imported once.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• francoism90
• All Contributors

License

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