Laravel Scout - Knowledge of Laravel

Introduzione

Laravel Scout è una soluzione semplice e basata su driver per aggiungere la ricerca full-text ai modelli Eloquent. Grazie a un model observer sincronizza automaticamente i record Eloquent con l’indice di ricerca. Scout include un engine database integrato che sfrutta gli indici full-text di MySQL/PostgreSQL e la clausola LIKE per cercare direttamente nel database, senza servizi esterni. In produzione, per applicazioni grandi che richiedono tolleranza ai typo, ricerca a faccette o ricerca geografica, sono utili gli engine esterni.

Engine supportati

Engine	Caratteristiche	Uso
`database`	Indici full-text MySQL/PostgreSQL	La maggior parte delle app
`collection`	Filtri in PHP (funziona anche con SQLite)	Sviluppo locale, test
Meilisearch	Open source, tolleranza ai typo, veloce	Produzione
Algolia	SaaS cloud, funzionalità avanzate	Produzione
Typesense	Open source, supporto alla ricerca vettoriale	Produzione
Turbopuffer	Ricerca full-text, semantica e ibrida	Produzione

Installazione

Installa il pacchetto con Composer.

composer require laravel/scout

Dopo l’installazione, pubblica il file di configurazione con vendor:publish. Viene generato config/scout.php.

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

Aggiungi infine il trait Laravel\Scout\Searchable ai modelli che vuoi rendere ricercabili. Il trait registra il model observer e abilita la sincronizzazione automatica con il driver di ricerca.

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;
}

Configurazione della coda

Se usi un engine diverso da database o collection, è fortemente consigliato configurare un driver di coda prima di usare Scout. Con un queue worker attivo le operazioni di sincronizzazione dell’indice avvengono in background e la reattività della UI migliora molto. Imposta a true l’opzione queue in config/scout.php.

'queue' => true,

Puoi anche indicare connection e nome della coda.

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

Poi avvia un worker dedicato.

php artisan queue:work redis --queue=scout

Job unique

Nelle app con molte scritture, potresti voler evitare che vengano accodati job duplicati per lo stesso record. Registrando le classi MakeSearchableUniquely e RemoveFromSearchUniquely in config/scout.php puoi usare job di indicizzazione unique. Di solito lo configuri nel metodo boot di un service provider.

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

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

Questi job usano i lock per job unique di Laravel per impedire il dispatch di operazioni di indicizzazione duplicate per lo stesso record già presente in coda.

Prerequisiti dei driver

Algolia

Se usi il driver Algolia, imposta id e secret in config/scout.php e installa l’SDK PHP di Algolia.

composer require algolia/algoliasearch-client-php

Aggiungi le credenziali nel .env.

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

Configurazione dell’indice

Con Algolia puoi gestire le impostazioni dell’indice da 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)'],
        ],
    ],
],

Dopo la configurazione esegui scout:sync-index-settings per applicarla ad Algolia.

php artisan scout:sync-index-settings

Meilisearch

Meilisearch è un motore di ricerca open source molto veloce. In sviluppo locale il modo più semplice è usarne l’immagine Docker con Laravel Sail.

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

Senza Sail puoi avviarlo direttamente con Docker.

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

Installa l’SDK PHP di Meilisearch.

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

Imposta driver e host nel .env.

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

Quando aggiorni Scout, controlla anche i breaking change di Meilisearch stesso.

Configurazione dell’indice (Meilisearch)

In Meilisearch devi pre-registrare le colonne su cui filtri con where() in filterableAttributes e quelle su cui ordini con 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'],
        ],
    ],
],

Attenzione al tipo dei dati numerici. Meilisearch può fare operazioni di filtro (>, < ecc.) solo su dati del tipo corretto.

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

Dopo la configurazione esegui scout:sync-index-settings.

php artisan scout:sync-index-settings

Ricerca semantica e ibrida (Meilisearch)

Per usare la ricerca semantica o ibrida con Meilisearch, configura un embedder nelle impostazioni dell’indice e le informazioni di embedding nelle impostazioni del modello.

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

Il metodo toSearchableEmbedding del modello restituisce il testo sorgente da trasformare in embedding con il Laravel AI SDK, oppure un array di embedding precalcolato. Dopo aver aggiornato la configurazione, esegui scout:sync-index-settings.

Typesense

Typesense è un motore di ricerca open source veloce che supporta ricerca per keyword, semantica, geografica e vettoriale.

composer require typesense/typesense-php

Configura la connessione nel .env.

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

Con Typesense, in toSearchableArray devi castare la primary key a stringa e la data di creazione a timestamp UNIX.

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

Ricerca semantica e ibrida (Typesense)

Per abilitare la ricerca semantica e ibrida con Typesense, definisci nelle impostazioni Typesense del modello la configurazione embedding e il campo vettoriale. Per impostazione predefinita Scout usa il Laravel AI SDK per generare gli embedding.

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

Il metodo toSearchableEmbedding del modello restituisce il testo sorgente da trasformare in embedding con Scout, oppure un array di embedding precalcolato.

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

Se usi la funzione di embedding nativa di Typesense, puoi generare gli embedding anche senza il Laravel AI SDK. Per i dettagli consulta la documentazione ufficiale di Typesense.

Turbopuffer

Turbopuffer è un motore di ricerca che supporta la ricerca full-text, semantica e ibrida. Per usare il driver Turbopuffer, imposta SCOUT_DRIVER e la tua API key.

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

TURBOPUFFER_REGION è facoltativa e il valore predefinito è gcp-us-central1.

Engine database / collection

Se non vuoi introdurre servizi esterni, sono le opzioni migliori. L’engine database usa gli indici full-text di MySQL/PostgreSQL e la clausola LIKE. Per la maggior parte delle applicazioni è sufficiente.

SCOUT_DRIVER=database

Ricerca semantica e ibrida

L’engine database supporta la ricerca semantica e ibrida con PostgreSQL e l’estensione pgvector. Aggiungi alla tabella del modello una colonna vettoriale nullable e un indice full-text. Scout salva gli embedding dopo il salvataggio del modello, quindi la colonna vettoriale deve essere nullable.

Schema::ensureVectorExtensionExists();

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

Definisci sul modello un metodo toSearchableEmbedding che restituisca il testo sorgente da trasformare in embedding oppure un array di embedding precalcolato. Di default Scout salva gli embedding nella colonna embedding; per usare un’altra colonna definisci il metodo searchableEmbeddingColumn. L’engine collection filtra in PHP, quindi funziona con qualsiasi database supportato da Laravel, incluso SQLite. Adatto a sviluppo locale, test e piccoli dataset.

SCOUT_DRIVER=collection

Con l’engine database, a differenza degli engine esterni, non serve gestire manualmente l’indice: la ricerca avviene direttamente sulla tabella.

Configurazione di Turbopuffer

Con Turbopuffer, definisci per ogni modello gli attributi ricercabili e uno schema nell’array model-settings di 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'],
            ],
        ],
    ],
],

I valori numerici in searchable-attributes sono pesi relativi BM25: nell’esempio, una corrispondenza nel titolo contribuisce al punteggio tre volte più di una nel corpo. Per usare la ricerca semantica, aggiungi la configurazione embedding e lo schema del vettore, e fai restituire al metodo toSearchableEmbedding del modello il testo sorgente o un array di embedding.

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

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

Se usi gli embedding nativi di Turbopuffer, il Laravel AI SDK e toSearchableEmbedding non sono necessari: includi l’attributo sorgente dell’embedding nel valore restituito da toSearchableArray e configura come segue.

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

Trait Searchable

Personalizzare toSearchableArray()

Per default, l’intero risultato di toArray() viene salvato nell’indice. Per personalizzare i dati sincronizzati, sovrascrivi toSearchableArray.

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * Restituisce l'array di dati indicizzabili del modello.
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // personalizza i dati...

        return $array;
    }
}

Personalizzare il nome dell’indice

Di default viene usato il nome della tabella (plurale) come nome dell’indice. Puoi personalizzarlo sovrascrivendo searchableAs.

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

Strategie di ricerca per l’engine database

Con l’engine database puoi indicare, tramite attributi PHP, una strategia di ricerca efficiente per colonna.

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

Prima di usare SearchUsingFullText verifica che sulla colonna sia presente un indice full-text.

Rendere ricercabili condizionalmente

Per rendere ricercabile un modello solo in certe condizioni, definisci shouldBeSearchable.

/**
 * Determina se il modello deve essere ricercabile.
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

shouldBeSearchable non funziona con l’engine database. Per ottenere lo stesso comportamento con l’engine database, usa una clausola where.

Gestione dell’indice

I comandi di questa sezione riguardano principalmente engine di terze parti come Algolia, Meilisearch, Typesense. Con l’engine database non serve gestire l’indice.

Importare record esistenti

Quando introduci Scout in un progetto esistente, importa i record con scout:import.

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

Puoi importare in background usando la coda.

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

Svuotare l’indice

Per rimuovere tutti i record del modello dall’indice usa scout:flush.

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

Pausa dell’indicizzazione

Per interrompere temporaneamente la sincronizzazione con l’indice durante operazioni Eloquent, usa withoutSyncingToSearch.

use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // le operazioni dentro qui non vengono sincronizzate con l'indice
});

Aggiunta / rimozione manuale

Puoi aggiungere all’indice una collezione di modelli tramite query.

// aggiungi i risultati di una query
Order::where('price', '>', 100)->searchable();

// aggiungi tramite relazione
$user->orders()->searchable();

Per rimuovere dall’indice usa unsearchable.

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

Il delete di un modello lo rimuove automaticamente anche dall’indice.

Ricerca

Con search cerchi sul modello. Concatena get per ottenere una collezione di modelli Eloquent.

use App\Models\Order;

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

Restituendola direttamente da un controller o una route viene convertita automaticamente in JSON.

use Illuminate\Http\Request;

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

Se ti servono i risultati grezzi usa raw.

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

Ricerca semantica

Con gli engine database, Meilisearch, Typesense e Turbopuffer configurati per gli embedding puoi cercare i record in base al significato della query. Aggiungi il metodo semantic alla query di ricerca. Quando è Scout a generare gli embedding, la ricerca semantica e quella ibrida richiedono il Laravel AI SDK. Se invece usi gli embedding nativi di Typesense, gli embedding nativi di Turbopuffer o vettori di query precalcolati, il Laravel AI SDK non è necessario.

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

Con gli engine che lo supportano puoi anche indicare una soglia minima di similarità.

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

Per combinare ricerca full-text e semantica usa il metodo hybrid. Gli argomenti controllano i pesi relativi dei risultati testuali e semantici.

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

Paginazione

Con paginate puoi paginare i risultati come nelle query Eloquent normali.

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

// indica quanti per pagina
$orders = Order::search('Star Trek')->paginate(15);

Con l’engine database puoi usare anche simplePaginate, più efficiente su grandi dataset perché non calcola il totale.

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

Esempio in Blade:

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

{{ $orders->links() }}

Filtri e ordinamento

Con where aggiungi condizioni di filtro alla query di ricerca.

use App\Models\Order;

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

// uno dei valori dell'array
$orders = Order::search('Star Trek')->whereIn('status', ['open', 'paid'])->get();

// nessuno dei valori dell'array
$orders = Order::search('Star Trek')->whereNotIn('status', ['closed'])->get();

Con Meilisearch, prima di usare where devi configurare gli attributi filtrabili.

Con query puoi personalizzare la query Eloquent.

use Illuminate\Database\Eloquent\Builder;

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

Eager Loading

Scout prima ottiene la lista di ID dal motore di ricerca, poi recupera i modelli con Eloquent. Per evitare il problema N+1, indica l’eager loading in query con with().

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

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

Per fare eager load delle relazioni durante l’import in blocco, definisci makeAllSearchableUsing.

use Illuminate\Database\Eloquent\Builder;

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

makeAllSearchableUsing può non funzionare con l’import batch tramite code: le relazioni non vengono ripristinate quando i modelli sono processati come job in coda.

Soft delete

Se il modello indicizzato usa il soft delete e vuoi cercare anche i modelli cancellati, imposta l’opzione soft_delete in config/scout.php a true.

'soft_delete' => true,

Attivandola, con withTrashed o onlyTrashed puoi includere i record cancellati.

// cerca anche tra i cancellati
$orders = Order::search('Star Trek')->withTrashed()->get();

// cerca solo tra i cancellati
$orders = Order::search('Star Trek')->onlyTrashed()->get();

Engine personalizzati

Se gli engine di default non ti bastano, puoi implementarne uno personalizzato. Un engine personalizzato estende la classe astratta Laravel\Scout\Engines\Engine e deve implementare questi otto metodi.

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

Come riferimento per l’implementazione, consulta la classe Laravel\Scout\Engines\AlgoliaEngine. L’engine personalizzato si registra su Scout nel metodo boot di App\Providers\AppServiceProvider.

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

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

Poi indicalo come driver in config/scout.php.

'driver' => 'mysql',

Pagine correlate

Eloquent ORM

Uso di base dei modelli Eloquent.

Relazioni Eloquent

Definizione delle relazioni ed eager loading.

Code

Scout può aggiornare l’indice in background grazie alle code.

​Introduzione

​Engine supportati

​Installazione

​Configurazione della coda

​Job unique

​Prerequisiti dei driver

​Algolia

​Configurazione dell’indice

​Meilisearch

​Configurazione dell’indice (Meilisearch)

​Ricerca semantica e ibrida (Meilisearch)

​Typesense

​Ricerca semantica e ibrida (Typesense)

​Turbopuffer

​Engine database / collection

​Ricerca semantica e ibrida

​Configurazione di Turbopuffer

​Trait Searchable

​Personalizzare toSearchableArray()

​Personalizzare il nome dell’indice

​Strategie di ricerca per l’engine database

​Rendere ricercabili condizionalmente

​Gestione dell’indice

​Importare record esistenti

​Svuotare l’indice

​Pausa dell’indicizzazione

​Aggiunta / rimozione manuale

​Ricerca

​Ricerca semantica

​Paginazione

​Filtri e ordinamento

​Eager Loading

​Soft delete

​Engine personalizzati

​Pagine correlate

Eloquent ORM

Relazioni Eloquent

Code

Introduzione

Engine supportati

Installazione

Configurazione della coda

Job unique

Prerequisiti dei driver

Algolia

Configurazione dell’indice

Meilisearch

Configurazione dell’indice (Meilisearch)

Ricerca semantica e ibrida (Meilisearch)

Typesense

Ricerca semantica e ibrida (Typesense)

Turbopuffer

Engine database / collection

Ricerca semantica e ibrida

Configurazione di Turbopuffer

Trait Searchable

Personalizzare toSearchableArray()

Personalizzare il nome dell’indice

Strategie di ricerca per l’engine database

Rendere ricercabili condizionalmente

Gestione dell’indice

Importare record esistenti

Svuotare l’indice

Pausa dell’indicizzazione

Aggiunta / rimozione manuale

Ricerca

Ricerca semantica

Paginazione

Filtri e ordinamento

Eager Loading

Soft delete

Engine personalizzati

Pagine correlate