Laravel Scout - Knowledge of Laravel

Inleiding

Laravel Scout is een eenvoudige, drivergebaseerde oplossing om full-text zoeken toe te voegen aan je Eloquent-modellen. Met behulp van model observers houdt Scout je Eloquent-records automatisch gesynchroniseerd met de zoekindexen. Scout bevat een ingebouwde database-engine die rechtstreeks in je database zoekt met de full-text indexen van MySQL/PostgreSQL en LIKE-clausules — externe diensten zijn niet nodig. Heb je in een grootschalige productieomgeving typo-tolerantie, facetzoeken of geo-zoeken nodig, dan zijn de externe engines nuttig.

Overzicht van ondersteunde engines

Engine	Kenmerken	Toepassing
`database`	Full-text indexen van MySQL/PostgreSQL	De meeste apps
`collection`	Filteren in PHP (ook SQLite)	Lokale ontwikkeling en tests
Meilisearch	Open source, typo-tolerant, snel	Productie
Algolia	Cloud-SaaS, geavanceerde functies	Productie
Typesense	Open source, ondersteunt vectorzoeken	Productie
Turbopuffer	Full-text, semantisch en hybride zoeken	Productie

Installatie

Installeer het pakket met Composer.

composer require laravel/scout

Publiceer na de installatie het configuratiebestand met het commando vendor:publish. Er wordt een config/scout.php gegenereerd.

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

Voeg tot slot de trait Laravel\Scout\Searchable toe aan de modellen die je doorzoekbaar wilt maken. Deze trait registreert een model observer en schakelt automatische synchronisatie met de zoekdriver in.

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;
}

Queue-configuratie

Gebruik je een andere engine dan database of collection, dan raden we sterk aan om vóór het gebruik van Scout een queuedriver te configureren. Door een queue worker te draaien, worden indexsynchronisaties op de achtergrond uitgevoerd, wat de responssnelheid van je webinterface flink verbetert. Stel de optie queue in config/scout.php in op true.

'queue' => true,

Je kunt ook een verbindingsnaam en queuenaam opgeven.

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

Start na de configuratie een dedicated queue worker.

php artisan queue:work redis --queue=scout

Unieke jobs gebruiken

In applicaties met veel schrijfacties wil je mogelijk voorkomen dat er dubbele queue-jobs voor hetzelfde modelrecord op de queue belanden. Door in config/scout.php de jobklassen MakeSearchableUniquely en RemoveFromSearchUniquely te registreren, gebruik je unieke indexeringsjobs. Meestal stel je dit in via de boot-methode van een service provider.

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

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

Deze jobs gebruiken Laravels unieke job-locks om te voorkomen dat er dubbele indexeringsoperaties worden gedispatcht voor een modelrecord dat al op de queue staat.

Vereisten per driver

Algolia

Gebruik je de Algolia-driver, stel dan de credentials id en secret in via config/scout.php en installeer de Algolia PHP SDK.

composer require algolia/algoliasearch-client-php

Voeg de credentials toe aan je .env-bestand.

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

Indexinstellingen

Bij Algolia kun je de indexinstellingen beheren 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)'],
        ],
    ],
],

Voer na de configuratie het commando scout:sync-index-settings uit om de instellingen naar Algolia te pushen.

php artisan scout:sync-index-settings

Meilisearch

Meilisearch is een snelle open-source zoekengine. Voor lokale ontwikkeling is Docker via Laravel Sail het eenvoudigst.

# Bij gebruik van Laravel Sail
./vendor/bin/sail up -d meilisearch

Gebruik je Sail niet, dan kun je hem rechtstreeks met Docker starten.

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

Installeer de Meilisearch PHP SDK.

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

Stel de driver en host in via je .env-bestand.

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

Controleer bij het upgraden van Scout altijd ook de breaking changes van de Meilisearch-service zelf.

Indexinstellingen (Meilisearch)

Bij Meilisearch moet je kolommen waarop je met where() filtert vooraf registreren in filterableAttributes, en kolommen waarop je met orderBy() sorteert 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'],
        ],
    ],
],

Let op het datatype van numerieke kolommen. Meilisearch kan filteroperaties (>, < e.d.) alleen uitvoeren op data van het juiste type.

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

Voer na de configuratie het commando scout:sync-index-settings uit.

php artisan scout:sync-index-settings

Semantisch en hybride zoeken (Meilisearch)

Om semantisch of hybride zoeken te gebruiken met Meilisearch, geef je in de indexinstellingen een embedder op en in de modelinstellingen de embedding-informatie.

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

De methode toSearchableEmbedding van je model geeft de brontekst terug die met de Laravel AI SDK wordt geëmbed, of een vooraf berekende embedding-array. Voer na de configuratie scout:sync-index-settings uit.

Typesense

Typesense is een snelle open-source zoekengine met ondersteuning voor keyword-, semantisch, geo- en vectorzoeken.

composer require typesense/typesense-php

Stel de verbindingsgegevens in via je .env-bestand.

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

Bij gebruik van Typesense moet je in de methode toSearchableArray de primaire sleutel van het model naar een string casten en de aanmaakdatum naar een UNIX-timestamp.

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

Turbopuffer

Turbopuffer is een zoekengine die full-text, semantisch en hybride zoeken ondersteunt. Om de Turbopuffer-driver te gebruiken stel je SCOUT_DRIVER en een API-sleutel in.

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

TURBOPUFFER_REGION is optioneel; de standaard is gcp-us-central1.

Database-/collection-engine

De ideale optie als je zoeken wilt toevoegen zonder externe diensten. De database-engine gebruikt de full-text indexen van MySQL/PostgreSQL en LIKE-clausules. Voor de meeste applicaties is dit voldoende.

SCOUT_DRIVER=database

Semantisch en hybride zoeken

De database-engine ondersteunt semantisch en hybride zoeken op PostgreSQL met de pgvector-extensie ingeschakeld. Voeg aan de tabel van je model een nullable vectorkolom en een full-text index toe. Scout slaat de embedding op ná het opslaan van het model, dus maak de vectorkolom nullable.

Schema::ensureVectorExtensionExists();

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

Definieer op het model de methode toSearchableEmbedding. Deze methode geeft de brontekst terug die Scout embedt, of een vooraf berekende embedding-array. De opslaglocatie is standaard de kolom embedding, maar dat kun je wijzigen met de methode searchableEmbeddingColumn. De collection-engine filtert in PHP en werkt daardoor met alle databases die Laravel ondersteunt, inclusief SQLite. Bedoeld voor lokale ontwikkeling, tests en kleine datasets.

SCOUT_DRIVER=collection

Anders dan bij externe engines is bij de database-engine geen handmatig indexbeheer nodig. Er wordt rechtstreeks in de databasetabel gezocht.

Turbopuffer-configuratie

Bij Turbopuffer definieer je per model de doorzoekbare attributen en het schema in model-settings van 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'],
            ],
        ],
    ],
],

De getallen in searchable-attributes zijn relatieve BM25-gewichten. In het voorbeeld draagt een match in de titel drie keer zoveel bij aan de score als een match in de body. Gebruik je semantisch zoeken, voeg dan een embedding-configuratie en een vectorschema toe, en geef vanuit de methode toSearchableEmbedding van het model de brontekst of embedding-array terug.

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

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

Gebruik je de native embeddings van Turbopuffer, dan zijn de Laravel AI SDK en toSearchableEmbedding niet nodig. Neem het bronattribuut voor de embedding op in de returnwaarde van toSearchableArray en configureer het als volgt.

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

De Searchable-trait

toSearchableArray() aanpassen

Standaard wordt alle data van toArray() van het model in de zoekindex opgeslagen. Wil je aanpassen welke data naar de index wordt gesynchroniseerd, override dan de methode toSearchableArray.

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * Haal de indexeerbare data-array van het model op.
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // Data aanpassen...

        return $array;
    }
}

De indexnaam aanpassen

Standaard wordt de tabelnaam van het model (meervoud) gebruikt als indexnaam. Je kunt dit aanpassen door de methode searchableAs te overriden.

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

Zoekstrategieën voor de database-engine

Bij de database-engine geef je per kolom een efficiënte zoekstrategie op via PHP-attributen.

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,
    ];
}

Controleer voordat je SearchUsingFullText gebruikt of de betreffende kolommen een full-text index hebben.

Voorwaardelijk doorzoekbaar maken

Wil je een model alleen onder bepaalde voorwaarden doorzoekbaar maken, definieer dan de methode shouldBeSearchable.

/**
 * Bepaal of dit model doorzoekbaar moet zijn.
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

shouldBeSearchable werkt niet met de database-engine. Gebruik voor vergelijkbaar gedrag met de database-engine where-clausules.

Indexbeheer

De commando’s in deze sectie zijn vooral relevant bij het gebruik van third-party engines zoals Algolia, Meilisearch en Typesense. Bij de database-engine is indexbeheer niet nodig.

Bestaande records importeren

Voer je Scout in bij een bestaand project, importeer dan de bestaande records in de index met het commando scout:import.

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

Je kunt ook via de queue op de achtergrond importeren.

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

De index leegmaken

Om alle records van een model uit de zoekindex te verwijderen gebruik je scout:flush.

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

Indexering pauzeren

Wil je tijdens Eloquent-operaties de synchronisatie met de zoekindex tijdelijk stopzetten, gebruik dan withoutSyncingToSearch.

use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // Modeloperaties hierbinnen worden niet naar de zoekindex gesynchroniseerd
});

Records handmatig toevoegen en verwijderen

Je kunt via een query een collectie modellen aan de index toevoegen.

// Queryresultaten toevoegen
Order::where('price', '>', 100)->searchable();

// Toevoegen via een relatie
$user->orders()->searchable();

Om records uit de index te verwijderen gebruik je unsearchable.

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

Als je een model deletet, wordt het ook automatisch uit de index verwijderd.

Zoeken

Met de search-methode doorzoek je een model. Koppel get erachter om een collectie Eloquent-modellen op te halen.

use App\Models\Order;

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

Geef je het resultaat rechtstreeks terug vanuit een controller of route, dan wordt het automatisch omgezet naar JSON.

use Illuminate\Http\Request;

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

Heb je de ruwe zoekresultaten nodig, gebruik dan de raw-methode.

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

Semantisch zoeken

Met de engines database, Meilisearch en Turbopuffer waarvoor embeddings zijn geconfigureerd, kun je records zoeken op basis van de betekenis van de query. Voeg de semantic-methode toe aan je zoekquery.

$articles = Article::search('hoe je een huis comfortabel houdt zonder elektriciteit')
    ->semantic()
    ->get();

Bij engines die dit ondersteunen kun je ook een minimale gelijkenisdrempel opgeven.

$articles = Article::search('opslag van hernieuwbare energie')
    ->semantic(minSimilarity: 0.6)
    ->get();

Om full-text en semantisch zoeken te combineren gebruik je de hybrid-methode. Via de argumenten geef je de relatieve gewichten van tekst- en semantisch zoeken op.

$articles = Article::search('opslag van hernieuwbare energie')
    ->hybrid(textWeight: 1, semanticWeight: 2)
    ->get();

Paginatie

Met de paginate-methode pagineer je de zoekresultaten. Dit werkt net als paginatie bij gewone Eloquent-query’s.

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

// Aantal items per pagina opgeven
$orders = Order::search('Star Trek')->paginate(15);

Bij de database-engine kun je ook simplePaginate gebruiken. Omdat het totale aantal niet wordt opgehaald, is dit efficiënt bij grote datasets.

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

Een weergavevoorbeeld in een Blade-template:

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

{{ $orders->links() }}

Filteren en sorteren

Met de where-methode voeg je filtervoorwaarden toe aan de zoekquery.

use App\Models\Order;

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

// Match met een van de waarden in de array
$orders = Order::search('Star Trek')->whereIn('status', ['open', 'paid'])->get();

// Match met geen van de waarden in de array
$orders = Order::search('Star Trek')->whereNotIn('status', ['closed'])->get();

Bij gebruik van Meilisearch moet je vóór het gebruik van where de filterbare attributen configureren.

Met de query-methode kun je ook de Eloquent-query aanpassen.

use Illuminate\Database\Eloquent\Builder;

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

Eager loading

Bij het gebruik van Scout wordt eerst een lijst met ID’s opgehaald bij de zoekengine, waarna de modellen via Eloquent worden opgehaald. Om het N+1-probleem te vermijden geef je met de query-methode eager loading op via with().

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

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

Om relaties eager te laden bij een batchimport definieer je de methode makeAllSearchableUsing.

use Illuminate\Database\Eloquent\Builder;

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

makeAllSearchableUsing is mogelijk niet bruikbaar bij batchimports via de queue. Relaties worden niet hersteld wanneer modelcollecties in een queue-job worden verwerkt.

Soft deletes

Als je geïndexeerde modellen soft deletes gebruiken en je ook verwijderde modellen wilt doorzoeken, stel dan de optie soft_delete in config/scout.php in op true.

'soft_delete' => true,

Eenmaal ingeschakeld kun je met withTrashed en onlyTrashed verwijderde records doorzoeken.

// Zoeken inclusief verwijderde records
$orders = Order::search('Star Trek')->withTrashed()->get();

// Alleen verwijderde records doorzoeken
$orders = Order::search('Star Trek')->onlyTrashed()->get();

Custom engines

Als de ingebouwde zoekengines niet aan je behoeften voldoen, kun je een eigen custom engine implementeren. Een custom engine erft van de abstracte klasse Laravel\Scout\Engines\Engine en moet de volgende acht methoden implementeren.

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

Bekijk als referentie voor de implementatie de klasse Laravel\Scout\Engines\AlgoliaEngine. Je registreert je custom engine bij Scout in de boot-methode van App\Providers\AppServiceProvider.

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

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

Na registratie geef je hem op als driver in config/scout.php.

'driver' => 'mysql',

Gerelateerde pagina’s

Eloquent ORM

Bekijk de basisprincipes van Eloquent-modellen.

Eloquent-relaties

Bekijk het definiëren van relaties en eager loading.

Queues

Scout kan samen met queues de index op de achtergrond bijwerken.

​Inleiding

​Overzicht van ondersteunde engines

​Installatie

​Queue-configuratie

​Unieke jobs gebruiken

​Vereisten per driver

​Algolia

​Indexinstellingen

​Meilisearch

​Indexinstellingen (Meilisearch)

​Semantisch en hybride zoeken (Meilisearch)

​Typesense

​Turbopuffer

​Database-/collection-engine

​Semantisch en hybride zoeken

​Turbopuffer-configuratie

​De Searchable-trait

​toSearchableArray() aanpassen

​De indexnaam aanpassen

​Zoekstrategieën voor de database-engine

​Voorwaardelijk doorzoekbaar maken

​Indexbeheer

​Bestaande records importeren

​De index leegmaken

​Indexering pauzeren

​Records handmatig toevoegen en verwijderen

​Zoeken

​Semantisch zoeken

​Paginatie

​Filteren en sorteren

​Eager loading

​Soft deletes

​Custom engines

​Gerelateerde pagina’s

Eloquent ORM

Eloquent-relaties

Queues

Inleiding

Overzicht van ondersteunde engines

Installatie

Queue-configuratie

Unieke jobs gebruiken

Vereisten per driver

Algolia

Indexinstellingen

Meilisearch

Indexinstellingen (Meilisearch)

Semantisch en hybride zoeken (Meilisearch)

Typesense

Turbopuffer

Database-/collection-engine

Semantisch en hybride zoeken

Turbopuffer-configuratie

De Searchable-trait

toSearchableArray() aanpassen

De indexnaam aanpassen

Zoekstrategieën voor de database-engine

Voorwaardelijk doorzoekbaar maken

Indexbeheer

Bestaande records importeren

De index leegmaken

Indexering pauzeren

Records handmatig toevoegen en verwijderen

Zoeken

Semantisch zoeken

Paginatie

Filteren en sorteren

Eager loading

Soft deletes

Custom engines

Gerelateerde pagina’s