Laravel Scout - Knowledge of Laravel

Einführung

Laravel Scout ist eine einfache, treiber-basierte Lösung, um Eloquent-Modellen Volltextsuche hinzuzufügen. Über Modell-Observer werden Eloquent-Datensätze automatisch mit dem Suchindex synchronisiert. Scout bringt eine integrierte database-Engine mit, die Volltextindizes und LIKE-Klauseln von MySQL/PostgreSQL nutzt – ohne externen Dienst. Für große Produktivumgebungen mit Tippfehler-Toleranz, Facettensuche oder Geo-Suche sind externe Engines im Vorteil.

Übersicht der Engines

Engine	Merkmale	Anwendung
`database`	Volltextindex von MySQL/PostgreSQL	Für die meisten Anwendungen
`collection`	Filterung in PHP (auch SQLite)	Lokale Entwicklung / Tests
Meilisearch	Open Source, tippfehlertolerant, schnell	Produktion
Algolia	Cloud-SaaS mit vielen Funktionen	Produktion
Typesense	Open Source, unterstützt Vektorsuche	Produktion
Turbopuffer	Volltext-, semantische und hybride Suche	Produktion

Installation

Installieren Sie das Paket mit Composer.

composer require laravel/scout

Veröffentlichen Sie die Konfiguration mit vendor:publish. Dabei entsteht config/scout.php.

php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

Ergänzen Sie schließlich das Trait Laravel\Scout\Searchable in jedem Modell, das durchsuchbar sein soll. Das Trait registriert einen Model-Observer und aktiviert die automatische Synchronisation mit dem Suchtreiber.

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;
}

Queues konfigurieren

Für alle Engines außer database und collection empfehlen wir dringend, Queues einzurichten. Ein Worker verlagert Index-Synchronisationen in den Hintergrund und verbessert die Reaktionszeit der Weboberfläche erheblich. Setzen Sie in config/scout.php die Option queue auf true.

'queue' => true,

Verbindung und Queue-Name lassen sich angeben.

'queue' => [
    'connection' => 'redis',
    'queue' => 'scout'
],

Starten Sie einen dedizierten Worker.

php artisan queue:work redis --queue=scout

Unique Jobs verwenden

In schreiblastigen Anwendungen möchten Sie duplizierte Index-Jobs für denselben Datensatz vermeiden. Registrieren Sie in config/scout.php – üblicherweise in der boot-Methode eines Service-Providers – die Job-Klassen MakeSearchableUniquely und RemoveFromSearchUniquely.

use Laravel\Scout\Jobs\MakeSearchableUniquely;
use Laravel\Scout\Jobs\RemoveFromSearchUniquely;
use Laravel\Scout\Scout;

Scout::makeSearchableUsing(MakeSearchableUniquely::class);
Scout::removeFromSearchUsing(RemoveFromSearchUniquely::class);

Diese Jobs nutzen Laravels Unique-Job-Locks, um doppelte Index-Operationen für denselben Datensatz zu vermeiden.

Voraussetzungen der Treiber

Algolia

Für Algolia setzen Sie in config/scout.php id und secret und installieren das Algolia-PHP-SDK.

composer require algolia/algoliasearch-client-php

In der .env:

ALGOLIA_APP_ID=your-app-id
ALGOLIA_SECRET=your-secret-key

Index-Konfiguration

Bei Algolia verwalten Sie Index-Einstellungen in config/scout.php.

use App\Models\User;

'algolia' => [
    'id' => env('ALGOLIA_APP_ID', ''),
    'secret' => env('ALGOLIA_SECRET', ''),
    'index-settings' => [
        User::class => [
            'searchableAttributes' => ['id', 'name', 'email'],
            'attributesForFaceting' => ['filterOnly(email)'],
        ],
    ],
],

Synchronisieren Sie die Konfiguration mit scout:sync-index-settings.

php artisan scout:sync-index-settings

Meilisearch

Meilisearch ist eine schnelle Open-Source-Such-Engine. Am einfachsten läuft sie lokal via Laravel Sail.

# Mit Laravel Sail
./vendor/bin/sail up -d meilisearch

Ohne Sail direkt via Docker:

docker run -it --rm \
    -p 7700:7700 \
    getmeili/meilisearch:latest \
    meilisearch --master-key="masterKey"

Installieren Sie das PHP-SDK.

composer require meilisearch/meilisearch-php http-interop/http-factory-guzzle

.env:

SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_KEY=masterKey

Beim Upgrade von Scout prüfen Sie stets auch die Breaking Changes von Meilisearch selbst.

Index-Konfiguration (Meilisearch)

Für Filter mit where() müssen Sie die Spalten in filterableAttributes eintragen; für Sortierungen mit orderBy() in sortableAttributes.

use App\Models\User;

'meilisearch' => [
    'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
    'key' => env('MEILISEARCH_KEY', null),
    'index-settings' => [
        User::class => [
            'filterableAttributes' => ['id', 'name', 'email'],
            'sortableAttributes' => ['created_at'],
        ],
    ],
],

Beachten Sie die Datentypen numerischer Spalten. Meilisearch führt Filteroperationen (>, < etc.) nur bei korrekt typisierten Werten aus.

public function toSearchableArray(): array
{
    return [
        'id' => (int) $this->id,
        'name' => $this->name,
        'price' => (float) $this->price,
    ];
}

Anschließend scout:sync-index-settings ausführen.

php artisan scout:sync-index-settings

Semantische und hybride Suche (Meilisearch)

Um semantische oder hybride Suche mit Meilisearch zu verwenden, konfigurieren Sie einen Embedder in den Index-Einstellungen und die Embedding-Angaben in den Modell-Einstellungen.

'meilisearch' => [
    'index-settings' => [
        Article::class => [
            'embedders' => [
                'default' => [
                    'source' => 'userProvided',
                    'dimensions' => 1536,
                ],
            ],
        ],
    ],
    'model-settings' => [
        Article::class => [
            'embedding' => [
                'embedder' => 'default',
                'dimensions' => 1536,
            ],
        ],
    ],
],

Die Methode toSearchableEmbedding des Modells gibt entweder den Quelltext zurück, den Scout mit dem Laravel AI SDK einbettet, oder ein vorberechnetes Embedding-Array. Führen Sie nach der Konfiguration scout:sync-index-settings aus.

Typesense

Typesense ist eine schnelle Open-Source-Such-Engine mit Keyword-, semantischer, Geo- und Vektorsuche.

composer require typesense/typesense-php

.env:

SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

Bei Typesense müssen Sie in toSearchableArray den Primärschlüssel als String und created_at als Unix-Timestamp casten.

public function toSearchableArray(): array
{
    return array_merge($this->toArray(), [
        'id' => (string) $this->id,
        'created_at' => $this->created_at->timestamp,
    ]);
}

Semantische und hybride Suche (Typesense)

Um in Typesense semantische oder hybride Suche zu aktivieren, definieren Sie in den Typesense-Einstellungen des Modells die Option embedding sowie ein Vektor-Feld. Standardmäßig erzeugt Scout die Embeddings mit dem Laravel AI SDK.

use App\Models\Article;

'model-settings' => [
    Article::class => [
        'collection-schema' => [
            'fields' => [
                ['name' => 'title', 'type' => 'string'],
                ['name' => 'embedding', 'type' => 'float[]', 'num_dim' => 1536],
            ],
        ],
        'search-parameters' => ['query_by' => 'title'],
        'embedding' => [
            'attribute' => 'embedding',
            'dimensions' => 1536,
        ],
    ],
],

Die Methode toSearchableEmbedding des Modells gibt entweder den Quelltext zurück, den Scout einbettet, oder ein vorberechnetes Embedding-Array.

public function toSearchableEmbedding(): string|array
{
    return $this->title.' '.$this->body;
}

Wenn Sie die nativen Embedding-Funktionen von Typesense nutzen, können Sie Embeddings auch ohne das Laravel AI SDK erzeugen. Details finden Sie in der offiziellen Typesense-Dokumentation.

Turbopuffer

Turbopuffer ist eine Such-Engine, die Volltext-, semantische und hybride Suche unterstützt. Um den Turbopuffer-Treiber zu verwenden, setzen Sie SCOUT_DRIVER und Ihren API-Schlüssel.

SCOUT_DRIVER=turbopuffer
TURBOPUFFER_API_KEY=tpuf_...
TURBOPUFFER_REGION=gcp-us-central1

TURBOPUFFER_REGION ist optional und steht standardmäßig auf gcp-us-central1.

Datenbank-/Collection-Engine

Ideal, wenn Sie ohne externen Dienst suchen möchten. Die Datenbank-Engine nutzt Volltextindizes und LIKE-Klauseln von MySQL/PostgreSQL und reicht für die meisten Anwendungen.

SCOUT_DRIVER=database

Semantische und hybride Suche

Die Datenbank-Engine unterstützt semantische und hybride Suche mit PostgreSQL und aktivierter pgvector-Erweiterung. Fügen Sie der Tabelle des Modells eine nullable Vektor-Spalte und einen Volltextindex hinzu. Da Scout die Embeddings erst nach dem Speichern des Modells ablegt, muss die Vektor-Spalte nullable sein.

Schema::ensureVectorExtensionExists();

Schema::table('articles', function (Blueprint $table) {
    $table->vector('embedding', dimensions: 1536)->nullable();
    $table->vectorIndex('embedding');
    $table->fullText(['title', 'body']);
});

Definieren Sie im Modell eine toSearchableEmbedding-Methode. Diese Methode gibt den Quelltext zurück, den Scout einbettet, oder ein vorberechnetes Embedding-Array. Standardmäßig speichert Scout die Embeddings in der Spalte embedding; mit der Methode searchableEmbeddingColumn können Sie eine andere Spalte festlegen. Die Collection-Engine filtert in PHP und funktioniert auf allen von Laravel unterstützten Datenbanken (auch SQLite). Ideal für lokale Entwicklung, Tests und kleine Datensätze.

SCOUT_DRIVER=collection

Anders als bei externen Engines müssen Sie bei der Datenbank-Engine keinen Index manuell pflegen. Es wird direkt in der Tabelle gesucht.

Turbopuffer konfigurieren

Bei Turbopuffer definieren Sie die durchsuchbaren Attribute und ein Schema für jedes Modell im Array model-settings von config/scout.php.

'turbopuffer' => [
    'model-settings' => [
        Article::class => [
            'searchable-attributes' => [
                'title' => 3,
                'body' => 1,
            ],
            'schema' => [
                'title' => ['type' => 'string', 'full_text_search' => true],
                'body' => ['type' => 'string', 'full_text_search' => true],
                'status' => ['type' => 'string'],
            ],
        ],
    ],
],

Die numerischen Werte in searchable-attributes sind relative BM25-Gewichte. Im Beispiel trägt ein Treffer im Titel dreimal so stark zum Score bei wie einer im Text. Für semantische Suche fügen Sie eine embedding-Einstellung sowie ein Vektor-Schema hinzu und geben aus der toSearchableEmbedding-Methode des Modells den Quelltext oder ein Embedding-Array zurück.

'embedding' => [
    'attribute' => 'embedding',
    'dimensions' => 1536,
],

'schema' => [
    'embedding' => ['type' => '[1536]f32', 'ann' => true],
],

Wenn Sie die nativen Embeddings von Turbopuffer verwenden, benötigen Sie weder das Laravel AI SDK noch toSearchableEmbedding. Nehmen Sie das Quellattribut für das Embedding in den Rückgabewert von toSearchableArray auf und konfigurieren Sie Folgendes:

'embedding' => [
    'driver' => 'turbopuffer',
    'attribute' => 'embedding_text',
],

Das Trait `Searchable`

`toSearchableArray()` anpassen

Standardmäßig werden alle Daten aus toArray() in den Suchindex geschrieben. Um die Daten zu steuern, überschreiben Sie toSearchableArray.

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * Gibt die für den Index vorgesehenen Daten des Modells zurück.
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // Daten anpassen...

        return $array;
    }
}

Indexnamen anpassen

Standardmäßig wird der Tabellenname (in der Pluralform) als Index verwendet. Über searchableAs passen Sie ihn an.

public function searchableAs(): string
{
    return 'posts_index';
}

Suchstrategie für die Datenbank-Engine

Bei der Datenbank-Engine legen Sie pro Spalte über PHP-Attribute eine effiziente Suchstrategie fest.

use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;

#[SearchUsingPrefix(['id', 'email'])]
#[SearchUsingFullText(['bio'])]
public function toSearchableArray(): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'bio' => $this->bio,
    ];
}

Bevor Sie SearchUsingFullText verwenden, achten Sie darauf, dass die Zielspalte einen Volltextindex besitzt.

Bedingt durchsuchbar

Um ein Modell nur unter bestimmten Bedingungen durchsuchbar zu machen, definieren Sie shouldBeSearchable.

/**
 * Entscheidet, ob das Modell durchsuchbar sein soll.
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

shouldBeSearchable funktioniert nicht mit der Datenbank-Engine. Verwenden Sie dort where-Klauseln.

Index verwalten

Die Befehle in diesem Abschnitt sind vor allem für externe Engines (Algolia, Meilisearch, Typesense, Turbopuffer) relevant. Bei der Datenbank-Engine ist keine Index-Verwaltung nötig.

Vorhandene Datensätze importieren

Wenn Sie Scout in ein bestehendes Projekt einführen, importieren Sie vorhandene Datensätze mit scout:import.

php artisan scout:import "App\Models\Post"

Der Import kann auch als Queue-Job laufen.

php artisan scout:queue-import "App\Models\Post" --chunk=500

Index leeren

Mit scout:flush entfernen Sie alle Datensätze eines Modells aus dem Suchindex.

php artisan scout:flush "App\Models\Post"

Index-Synchronisation pausieren

Um während Eloquent-Operationen die Sync mit dem Index zu unterbrechen, nutzen Sie withoutSyncingToSearch.

use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // Die Modell-Operationen darin synchronisieren nicht in den Index.
});

Datensätze manuell hinzufügen/entfernen

Sie können anhand einer Abfrage Modelle in den Index aufnehmen.

// Ergebnisse einer Abfrage
Order::where('price', '>', 100)->searchable();

// Über eine Beziehung
$user->orders()->searchable();

Mit unsearchable entfernen Sie Datensätze wieder.

Order::where('price', '>', 100)->unsearchable();

Beim Aufruf von delete wird der Datensatz automatisch aus dem Index entfernt.

Suche

Mit search durchsuchen Sie Modelle. Hängen Sie get an, um eine Eloquent-Collection zu erhalten.

use App\Models\Order;

$orders = Order::search('Star Trek')->get();

Aus Controllern oder Routen direkt zurückgegeben, wird das Ergebnis automatisch als JSON serialisiert.

use Illuminate\Http\Request;

Route::get('/search', function (Request $request) {
    return Order::search($request->search)->get();
});

Für die Rohdaten der Suche verwenden Sie raw.

$orders = Order::search('Star Trek')->raw();

Semantische Suche

Mit den Engines database, Meilisearch, Typesense und Turbopuffer können Sie nach konfigurierten Embeddings Datensätze anhand der Bedeutung einer Suchanfrage finden. Hängen Sie dazu die Methode semantic an die Suche an. Wenn Scout die Embeddings erzeugt, wird für die semantische und hybride Suche das Laravel AI SDK benötigt. Bei Nutzung der nativen Embeddings von Typesense oder Turbopuffer sowie bei vorberechneten Query-Vektoren ist das Laravel AI SDK nicht erforderlich.

$articles = Article::search('how to keep a house comfortable without electricity')
    ->semantic()
    ->get();

Bei Engines, die dies unterstützen, können Sie zusätzlich einen minimalen Ähnlichkeits-Schwellenwert angeben.

$articles = Article::search('renewable energy storage')
    ->semantic(minSimilarity: 0.6)
    ->get();

Um Volltextsuche und semantische Suche zu kombinieren, verwenden Sie die Methode hybrid. Über die Argumente steuern Sie die relative Gewichtung von Text- und semantischen Ergebnissen.

$articles = Article::search('renewable energy storage')
    ->hybrid(textWeight: 1, semanticWeight: 2)
    ->get();

Pagination

Mit paginate paginieren Sie Ergebnisse wie sonst auch.

$orders = Order::search('Star Trek')->paginate();

// Datensätze pro Seite
$orders = Order::search('Star Trek')->paginate(15);

Mit der Datenbank-Engine ist auch simplePaginate verfügbar. Da keine Gesamtzahl ermittelt wird, ist das bei großen Datenmengen effizienter.

$orders = Order::search('Star Trek')->simplePaginate(15);

Anzeige in Blade:

<div class="container">
    @foreach ($orders as $order)
        {{ $order->price }}
    @endforeach
</div>

{{ $orders->links() }}

Filtern und sortieren

Mit where schränken Sie die Suche ein.

use App\Models\Order;

// Gleichheit
$orders = Order::search('Star Trek')->where('user_id', 1)->get();

// In einer Menge
$orders = Order::search('Star Trek')->whereIn('status', ['open', 'paid'])->get();

// Nicht in einer Menge
$orders = Order::search('Star Trek')->whereNotIn('status', ['closed'])->get();

Bei Meilisearch müssen Sie vor dem Einsatz von where die filterbaren Attribute definieren.

Mit query passen Sie die Eloquent-Abfrage an.

use Illuminate\Database\Eloquent\Builder;

$orders = Order::search('Star Trek')
    ->query(fn (Builder $query) => $query->with('invoices'))
    ->get();

Eager Loading

Scout holt zunächst die IDs aus der Such-Engine und dann die Modelle über Eloquent. Um N+1-Probleme zu vermeiden, geben Sie in query mit with() Eager Loading an.

use App\Models\Order;
use Illuminate\Database\Eloquent\Builder;

$orders = Order::search('Star Trek')
    ->query(fn (Builder $query) => $query->with(['invoices', 'user']))
    ->get();

Für Eager Loading bei Batch-Imports definieren Sie makeAllSearchableUsing.

use Illuminate\Database\Eloquent\Builder;

protected function makeAllSearchableUsing(Builder $query): Builder
{
    return $query->with('author');
}

Bei queue-basierten Batch-Imports kann makeAllSearchableUsing nicht immer verwendet werden. Beziehungen werden im Queue-Job für eine Modell-Collection ggf. nicht wiederhergestellt.

Soft Deletes

Verwendet Ihr indiziertes Modell Soft Deletes und wollen Sie auch gelöschte Datensätze suchen, setzen Sie in config/scout.php soft_delete auf true.

'soft_delete' => true,

Danach nutzen Sie withTrashed bzw. onlyTrashed.

// Auch gelöschte
$orders = Order::search('Star Trek')->withTrashed()->get();

// Nur gelöschte
$orders = Order::search('Star Trek')->onlyTrashed()->get();

Eigene Engines

Reichen die eingebauten Engines nicht aus, implementieren Sie eine eigene. Erben Sie von der abstrakten Klasse Laravel\Scout\Engines\Engine und implementieren Sie folgende Methoden:

use Laravel\Scout\Builder;

abstract public function update($models);
abstract public function delete($models);
abstract public function search(Builder $builder);
abstract public function paginate(Builder $builder, $perPage, $page);
abstract public function mapIds($results);
abstract public function map(Builder $builder, $results, $model);
abstract public function getTotalCount($results);
abstract public function flush($model);

Als Vorlage können Sie sich die Klasse Laravel\Scout\Engines\AlgoliaEngine ansehen. Registrieren Sie die Engine in der boot-Methode Ihres AppServiceProvider.

use App\ScoutExtensions\MySqlSearchEngine;
use Laravel\Scout\EngineManager;

public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

Nach der Registrierung wählen Sie sie in config/scout.php als Treiber aus.

'driver' => 'mysql',

Eloquent ORM

Grundlagen der Eloquent-Modelle.

Eloquent-Beziehungen

Definition von Beziehungen und Eager Loading.

Queues

Scout kann Indizes zusammen mit Queues im Hintergrund aktualisieren.

​Einführung

​Übersicht der Engines

​Installation

​Queues konfigurieren

​Unique Jobs verwenden

​Voraussetzungen der Treiber

​Algolia

​Index-Konfiguration

​Meilisearch

​Index-Konfiguration (Meilisearch)

​Semantische und hybride Suche (Meilisearch)

​Typesense

​Semantische und hybride Suche (Typesense)

​Turbopuffer

​Datenbank-/Collection-Engine

​Semantische und hybride Suche

​Turbopuffer konfigurieren

​Das Trait Searchable

​toSearchableArray() anpassen

​Indexnamen anpassen

​Suchstrategie für die Datenbank-Engine

​Bedingt durchsuchbar

​Index verwalten

​Vorhandene Datensätze importieren

​Index leeren

​Index-Synchronisation pausieren

​Datensätze manuell hinzufügen/entfernen

​Suche

​Semantische Suche

​Pagination

​Filtern und sortieren

​Eager Loading

​Soft Deletes

​Eigene Engines

​Verwandte Seiten

Eloquent ORM

Eloquent-Beziehungen

Queues

Einführung

Übersicht der Engines

Installation

Queues konfigurieren

Unique Jobs verwenden

Voraussetzungen der Treiber

Algolia

Index-Konfiguration

Meilisearch

Index-Konfiguration (Meilisearch)

Semantische und hybride Suche (Meilisearch)

Typesense

Semantische und hybride Suche (Typesense)

Turbopuffer

Datenbank-/Collection-Engine

Semantische und hybride Suche

Turbopuffer konfigurieren

Das Trait `Searchable`

`toSearchableArray()` anpassen

Indexnamen anpassen

Suchstrategie für die Datenbank-Engine

Bedingt durchsuchbar

Index verwalten

Vorhandene Datensätze importieren

Index leeren

Index-Synchronisation pausieren

Datensätze manuell hinzufügen/entfernen

Suche

Semantische Suche

Pagination

Filtern und sortieren

Eager Loading

Soft Deletes

Eigene Engines

Verwandte Seiten