Laravel Scout gebruiken om full-text zoeken mogelijk te maken

Het Laravel framework is een go-to bron geworden voor developers die webdiensten bouwen.

Als open-source tool biedt Laravel een groot aantal out-of-the-box functionaliteiten waarmee developers robuuste en functionele applicaties kunnen bouwen.

Een van de functionaliteiten is Laravel Scout, een bibliotheek voor het beheer van zoekindexen voor je applicatie. Door zijn flexibiliteit kunnen developers de configuraties nauwkeurig afstemmen en kiezen uit Algolia, Meilisearch, MySQL of Postgres drivers om de indexen op te slaan.

Hier gaan we dieper in op deze tool en leren we je hoe je ondersteuning voor full-text zoeken toevoegt aan een Laravel applicatie via de driver. Je zult een demo Laravel applicatie modelleren voor het opslaan van de naam van mockup trains en dan Laravel Scout gebruiken om een zoekopdracht aan de applicatie toe te voegen.

Vereisten

Om alles te kunnen volgen moet je beschikken over:

• De PHP compiler op je computer geïnstalleerd hebben. Deze tutorial gebruikt PHP versie 8.1.
• De Docker engine of Docker Desktop – op je computer geïnstalleerd
• Een Algolia cloud account, die je gratis kunt aanmaken

Zo installeer je Scout in een Laravel project

Om Scout te gebruiken moet je eerst een Laravel applicatie maken waarin je van plan bent de zoekfunctionaliteit toe te voegen. Het Laravel-Scout Bash script bevat de commando’s om een Laravel applicatie te genereren binnen een Docker container. Door Docker te gebruiken hoef je geen extra ondersteunende software te installeren, zoals een MySQL database.

Het Laravel-Scout script gebruikt de Bash scripttaal, dus je moet het uitvoeren in een Linux omgeving. Als je Windows draait, zorg er dan voor dat je Windows Subsystem for Linux (WSL) configureert.

Als je WSL gebruikt, voer dan het volgende commando uit in je terminal om de Linux distributie van je voorkeur in te stellen.

wsl -s ubuntu

Navigeer vervolgens naar de locatie op je computer waar je het project wilt plaatsen. Het Laravel-Scout script zal hier een projectmap genereren. In het onderstaande voorbeeld maakt het Laravel-Scout script een map aan binnen de desktop map.

cd /desktop

Voer het onderstaande commando uit om het Laravel-Scout script uit te voeren. Het zal een Dockerized applicatie met de nodige boilerplate code steigeren.

curl -s https://laravel.build/laravel-scout-app | bash

Verander na de uitvoering je map met cd laravel-scout-app. Voer dan het commando sail-up uit binnen de projectmap om de Docker containers voor je applicatie te starten.

Opmerking: Op veel Linux distributies moet je misschien het onderstaande commando uitvoeren met het sudo commando om verhoogde privileges te starten.

./vendor/bin/sail up

Je kunt een foutmelding tegenkomen:

Om dit op te lossen kun je de variabele APP_PORT gebruiken om een poort aan te geven binnen het commando sail up:

APP_PORT=3001 ./vendor/bin/sail up

Voer vervolgens het onderstaande commando uit om de applicatie via Artisan op de PHP server uit te voeren.

php artisan serve

Navigeer vanuit je webbrowser naar de draaiende applicatie op http://127.0.0.1:8000. De applicatie toont de Laravel welkomstpagina op de standaardroute.

Zo voeg je Laravel Scout toe aan de applicatie

Voer in je terminal het commando in om de Composer PHP package manager in te schakelen om Laravel Scout aan het project toe te voegen.

composer require laravel/scout

Publiceer vervolgens het Scout configuratiebestand met het commando vendor:publish. Het commando publiceert het scout.php configuratiebestand naar de config-directory van je applicatie.

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

Wijzig nu het boilerplate .env bestand zodat het een SCOUT_QUEUE boolean waarde bevat.

De SCOUT_QUEUE waarde zal Scout in staat stellen om bewerkingen te enqueuen, waardoor betere reactietijden ontstaan. Zonder deze waarde zullen Scout drivers zoals Meilisearch nieuwe records niet onmiddellijk weergeven.

SCOUT_QUEUE=true

Wijzig ook de variabele DB_HOST in het .env bestand om naar je localhost te wijzen om de MySQL database binnen de Docker containers te gebruiken.

DB_HOST=127.0.0.1

Een model markeren en de index configureren

Scout zet standaard geen doorzoekbare datamodellen aan. Je moet een model expliciet markeren als doorzoekbaar met de property Laravel\Scout\Searchable.

Je begint met het maken van een datamodel voor een demo Train applicatie om deze vervolgens te markeren als doorzoekbaar.

Een model maken

Voor de Train applicatie wil je de placeholder namen van elke beschikbare train opslaan.

Voer het onderstaande Artisan commando uit om de migratie te genereren en geef het de naam create_trains_table.

php artisan make:migration create_trains_table 

De migratie wordt gegenereerd in een bestand waarvan de naam de opgegeven naam combineert met de huidige tijdstempel.

Open het migratiebestand in de map database/migrations/.

Voeg de volgende code toe na de kolom id() in regel 17 om een titelkolom toe te voegen. De code zal een titelkolom toevoegen.

$table->string('title');

Voer het onderstaande commando uit om de migratie toe te passen.

php artisan migrate

Maak na het uitvoeren van de databasemigraties een bestand aan met de naam Train.php in de map app/Models/.

De LaravelScoutSearchable property toevoegen

Markeer het Train model voor zoeken door de LaravelScoutSearchable property aan het model toe te voegen, zoals hieronder getoond.

<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Train extends Model
{
    use Searchable;
    public $fillable = ['title'];

Ook moet je de zoekindexen configureren door de methode searchable te overschrijven. Het standaard gedrag van Scout zou het model persisten om overeen te komen met de naam van de modeltabel.

Voeg dus de volgende code toe aan het bestand Train.php onder de code van het vorige blok.

/**
     * Retrieve the index name for the model.
     *
     * @return string
    */
    public function searchableAs()
    {
        return 'trains_index';
   }
}

Zo gebruik je Algolia met Scout

Voor de eerste full-text zoekopdracht met Laravel Scout gebruik je de Algolia driver. Algolia is een software as a service (SaaS) platform dat gebruikt wordt om grote hoeveelheden gegevens te doorzoeken. Het biedt een webdashboard voor developers om hun zoekindexen te beheren en een robuuste API waartoe je toegang hebt via een software development kit (SDK) in de programmeertaal van je voorkeur.

Binnen de Laravel applicatie gebruik je het Algolia client pakket voor PHP.

Algolia instellen

Eerst moet je het Algolia PHP search client pakket voor je applicatie installeren.

Voer het onderstaande commando uit.

composer require algolia/algoliasearch-client-php

Vervolgens moet je je Application ID en Secret API Key credentials van Algolia instellen in het .env bestand.

Navigeer met je webbrowser naar je Algolia dashboard om de Application ID en Secret API Key credentials te verkrijgen.

Klik op Settings onderaan de linker zijbalk om naar de Settings pagina te navigeren.

Klik vervolgens op API Keys binnen de Team and Access sectie van de Settings pagina om de sleutels voor je Algolia account te bekijken.

Noteer op de API Keys pagina de Application ID en Admin API Key waarden. Je zult deze credentials gebruiken om de verbinding tussen de Laravel applicatie en Algolia te authenticeren.

Voeg de onderstaande code toe aan je .env bestand met je code editor en vervang de placeholders door de corresponderende Algolia API secrets.

ALGOLIA_APP_ID=APPLICATION_ID
ALGOLIA_SECRET=ADMIN_API_KEY

Vervang ook de variabele SCOUT_DRIVER door onderstaande code om de waarde te veranderen van meilisearch in algolia. Het veranderen van deze waarde zal Scout instrueren om de Algolia driver te gebruiken.

SCOUT_DRIVER=algolia

Zo maak je controllers voor je applicatie aan

Maak in de map app/Http/Controllers/ een bestand TrainSearchController.php om een controller voor de applicatie op te slaan. De controller zal gegevens opsommen en toevoegen aan het Train model.

Voeg het volgende codeblok toe aan het bestand TrainSearchController.php om de controller te bouwen.

<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use App\Http\Requests;
use App\Models\Train;

class TrainSearchController extends Controller
{
    /**
     * Get the index name for the model.
     *
     * @return string
    */
    public function index(Request $request)
    {
        if($request->has('titlesearch')){
            $trains = Train::search($request->titlesearch)
                ->paginate(6);
        }else{
            $trains = Train::paginate(6);
        }
        return view('Train-search',compact('trains'));
    }

    /**
     * Get the index name for the model.
     *
     * @return string
    */
    public function create(Request $request)
    {
        $this->validate($request,['title'=>'required']);

        $trains = Train::create($request->all());
        return back();
    }
}

Zo maak je de routes aan voor je applicatie

In deze stap maak je de routes voor het listen en toevoegen van nieuwe trains aan de database.

Open je routes/web.php bestand en vervang de bestaande code door het onderstaande blok.

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\TrainSearchController;

Route::get('/', function () {
    return view('welcome');
});

Route::get('trains-lists', [TrainSearchController::class, 'index']) -> name ('trains-lists');

Route::post('create-item', [TrainSearchController::class, 'create']) -> name ('create-item');

De bovenstaande code definieert twee routes in de applicatie. Het GET verzoek voor de /trains-lists route somt alle opgeslagen traindata op. Het POST verzoek voor de /create-item route creëert nieuwe traindata.

Zo maak je de views aan voor je applicatie

Maak een bestand aan in de map resources/views/ en noem het Train-search.blade.php. Het bestand toont de gebruikersinterface voor de zoekfunctie.

Voeg de inhoud van het onderstaande codeblok toe aan het bestand Train-search.blade.php om een enkele pagina te maken voor de zoekfunctionaliteit.

<!DOCTYPE html>
<html>
<head>
    <title>Laravel - Laravel Scout Algolia Search Example</title>
    <link rel="stylesheet" type="text/css" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css">
</head>
<body>
<div class="container">
    <h2 class="text-bold">Laravel Full-Text Search Using Scout </h2><br/>
    <form method="POST" action="{{ route('create-item') }}" autocomplete="off">
        @if(count($errors))
            <div class="alert alert-danger">
                <strong>Whoops!</strong> There is an error with your input.
                <br/>
                <ul>
                    @foreach($errors->all() as $error)
                    <li>{{ $error }}</li>
                    @endforeach
                </ul>
            </div>
        @endif

        <input type="hidden" name="_token" value="{{ csrf_token() }}">

        <div class="row">
            <div class="col-md-6">
                <div class="form-group {{ $errors->has('title') ? 'has-error' : '' }}">
                    <input type="text" id="title" name="title" class="form-control" placeholder="Enter Title" value="{{ old('title') }}">
                    <span class="text-danger">{{ $errors->first('title') }}</span>
                </div>
            </div>
            <div class="col-md-6">
                <div class="form-group">
                    <button class="btn btn-primary">Create New Train</button>
                </div>
            </div>
        </div>
    </form>

    <div class="panel panel-primary">
      <div class="panel-heading">Train Management</div>
      <div class="panel-body">
            <form method="GET" action="{{ route('trains-lists') }}">

                <div class="row">
                    <div class="col-md-6">
                        <div class="form-group">
                            <input type="text" name="titlesearch" class="form-control" placeholder="Enter Title For Search" value="{{ old('titlesearch') }}">
                        </div>
                    </div>
                    <div class="col-md-6">
                        <div class="form-group">
                            <button class="btn btn-primary">Search</button>
                        </div>
                    </div>
                </div>
            </form>

            <table class="table">
                <thead>
                    <th>Id</th>
                    <th>Train Title</th>
                    <th>Creation Date</th>
                    <th>Updated Date</th>
                </thead>
                <tbody>
                    @if($trains->count())
                        @foreach($trains as $key => $item)
                            <tr>
                                <td>{{ ++$key }}</td>
                                <td>{{ $item->title }}</td>
                                <td>{{ $item->created_at }}</td>
                                <td>{{ $item->updated_at }}</td>
                            </tr>
                        @endforeach
                    @else
                        <tr>
                            <td colspan="4">No train data available</td>
                        </tr>
                    @endif
                </tbody>
            </table>
            {{ $trains->links() }}
      </div>
    </div>
</div>
</body>
</html>

De bovenstaande HTML code bevat een formulierelement met een invoerveld en een knop om de titel van een train in te typen voordat je die opslaat in de database. De code bevat ook een HTML tabel met de id, titel, created_at, en updated_at details van een train entry in de database.

Zo gebruik je de Algolia zoekfunctie

Navigeer naar http://127.0.0.1:8000/trains-lists vanuit je webbrowser om de pagina te bekijken.

De database is momenteel leeg, dus je moet een titel van een demo train invoeren in het invoerveld en op Create New Train klikken om hem op te slaan.

Om de zoekfunctie te gebruiken typ je een trefwoord uit opgeslagen traintitels in het invoerveld Enter Title For Search en klik je op Search.

Zoals de afbeelding hieronder laat zien, worden alleen zoekacties met het trefwoord in de titel getoond.

Meilisearch met Laravel Scout

Meilisearch is een open-source zoekmachine gericht op snelheid, prestaties en een verbeterde ervaring voor developers. Het deelt verschillende functies met Algolia en gebruikt dezelfde algoritmen, gegevensstructuren en onderzoek – maar met een andere programmeertaal.

Developers kunnen een Meilisearch instance aanmaken en zelf hosten binnen hun on-premises of cloud-infrastructuur. Meilisearch heeft ook een beta-cloudaanbod vergelijkbaar met Algolia voor developers die het product willen gebruiken zonder de infrastructuur ervan te beheren.

In de tutorial heb je al een lokale instance van Meilisearch draaien binnen je Docker containers. Je gaat nu de Laravel Scout functionaliteit uitbreiden om de Meilisearch instance te gebruiken.

Om Meilisearch aan de Laravel applicatie toe te voegen, voer je onderstaand commando uit in je projectterminal.

composer require meilisearch/meilisearch-php

Vervolgens moet je de Meilisearch variabelen binnen het .env bestand aanpassen om het te configureren.

Vervang de variabelen SCOUT_DRIVER, MEILISEARCH_HOST, en MEILISEARCH_KEY in het .env bestand door onderstaande.

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

De key SCOUT_DRIVER specificeert de driver die Scout moet gebruiken, terwijl MEILISEARCH_HOST het domein voorstelt waar je Meilisearch instantie draait. Hoewel niet vereist tijdens de ontwikkeling, wordt het toevoegen van de MEILISEARCH_KEY in productie aangeraden.

Opmerking: Je kan een comment out uitvoeren op de Algolia ID en Secret als je Meilisearch als voorkeurdriver gebruikt.

Nadat je de .env configuraties hebt voltooid, moet je je reeds bestaande records indexeren met het Artisan commando hieronder.

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

Laravel Scout met database-engine

De database-engine van Scout is wellicht het meest geschikt voor applicaties die kleinere databases gebruiken of minder intensieve werklasten beheren. Momenteel ondersteunt de database-engine PostgreSQL en MySQL.

Deze engine gebruikt “where-like” clauses en full-text indexen die die uitvoert op je bestaande database, waardoor hij de meest relevante zoekresultaten kan vinden. Je hoeft je records niet te indexeren als je de database-engine gebruikt.

Om de database-engine te gebruiken, moet je je SCOUT_DRIVER .env variabele instellen op de database.

Open het .env bestand binnen de Laravel applicatie en verander de waarde van de SCOUT_DRIVER variabele.

SCOUT_DRIVER = database

Na het veranderen van je driver naar de database, zal Scout overschakelen naar het gebruik van de database engine voor full-text zoeken.

Laravel Scout met collection-engine

Naast de database-engine biedt Scout ook een collection-engine. Deze engine gebruikt “where” clauses en collectionfiltering om de meest relevante zoekresultaten eruit te halen.

In tegenstelling tot de database-engine, ondersteunt de collection-engine alle relationele databases die Laravel ook ondersteunt.

Je kunt de collection-engine gebruiken door de SCOUT_DRIVER omgevingsvariabele in te stellen op collection of door handmatig de collection driver op te geven in het Scout configuratiebestand.

SCOUT_DRIVER = collection

Explorer met Elasticsearch

Met de kracht van Elasticsearch queries is Explorer een moderne Elasticsearch driver voor Laravel Scout. Het biedt een compatibele Scout driver en voordelen zoals het opslaan, doorzoeken en analyseren van enorme hoeveelheden data in real time. Elasticsearch met Laravel geeft je resultaten in milliseconden.

Om de Elasticsearch Explorer driver in je Laravel applicatie te gebruiken, moet je het boilerplate docker-compose.yml bestand configureren dat het Laravel-Scout script genereerde. Je voegt de extra configuraties voor Elasticsearch toe en herstart de containers.

Open je docker-compose.yml bestand en vervang de inhoud door het volgende.

# For more information: https://laravel.com/docs/sail
version: '3'
services:
    laravel.test:
        build:
            context: ./vendor/laravel/sail/runtimes/8.1
            dockerfile: Dockerfile
            args:
                WWWGROUP: '${WWWGROUP}'
        image: sail-8.1/app
        extra_hosts:
            - 'host.docker.internal:host-gateway'
        ports:
            - '${APP_PORT:-80}:80'
            - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
        environment:
            WWWUSER: '${WWWUSER}'
            LARAVEL_SAIL: 1
            XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
            XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'
        volumes:
            - '.:/var/www/html'
        networks:
            - sail
        depends_on:
            - mysql
            - redis
            - meilisearch
            - mailhog
            - selenium
            - pgsql
            - elasticsearch

    mysql:
        image: 'mysql/mysql-server:8.0'
        ports:
            - '${FORWARD_DB_PORT:-3306}:3306'
        environment:
            MYSQL_ROOT_PASSWORD: '${DB_PASSWORD}'
            MYSQL_ROOT_HOST: "%"
            MYSQL_DATABASE: '${DB_DATABASE}'
            MYSQL_USER: '${DB_USERNAME}'
            MYSQL_PASSWORD: '${DB_PASSWORD}'
            MYSQL_ALLOW_EMPTY_PASSWORD: 1
        volumes:
            - 'sail-mysql:/var/lib/mysql'
            - './vendor/laravel/sail/database/mysql/create-testing-database.sh:/docker-entrypoint-initdb.d/10-create-testing-database.sh'
        networks:
            - sail
        healthcheck:
            test: ["CMD", "mysqladmin", "ping", "-p${DB_PASSWORD}"]
            retries: 3
            timeout: 5s
            
    elasticsearch:
        image: 'elasticsearch:7.13.4'
        environment:
            - discovery.type=single-node
        ports:
            - '9200:9200'
            - '9300:9300'
        volumes:
            - 'sailelasticsearch:/usr/share/elasticsearch/data'
        networks:
            - sail
    kibana:
        image: 'kibana:7.13.4'
        environment:
            - elasticsearch.hosts=http://elasticsearch:9200
        ports:
            - '5601:5601'
        networks:
            - sail
        depends_on:
            - elasticsearch
    redis:
        image: 'redis:alpine'
        ports:
            - '${FORWARD_REDIS_PORT:-6379}:6379'
        volumes:
            - 'sail-redis:/data'
        networks:
            - sail
        healthcheck:
            test: ["CMD", "redis-cli", "ping"]
            retries: 3
            timeout: 5s
    pgsql:
        image: 'postgres:13'
        ports:
            - '${FORWARD_DB_PORT:-5432}:5432'
        environment:
            PGPASSWORD: '${DB_PASSWORD:-secret}'
            POSTGRES_DB: '${DB_DATABASE}'
            POSTGRES_USER: '${DB_USERNAME}'
            POSTGRES_PASSWORD: '${DB_PASSWORD:-secret}'
        volumes:
            - 'sailpgsql:/var/lib/postgresql/data'
        networks:
            - sail
        healthcheck:
            test: ["CMD", "pg_isready", "-q", "-d", "${DB_DATABASE}", "-U", "${DB_USERNAME}"]
            retries: 3
            timeout: 5s
    meilisearch:
        image: 'getmeili/meilisearch:latest'
        ports:
            - '${FORWARD_MEILISEARCH_PORT:-7700}:7700'
        volumes:
            - 'sail-meilisearch:/meili_data'
        networks:
            - sail
        healthcheck:
            test: ["CMD", "wget", "--no-verbose", "--spider",  "http://localhost:7700/health"]
            retries: 3
            timeout: 5s
    mailhog:
        image: 'mailhog/mailhog:latest'
        ports:
            - '${FORWARD_MAILHOG_PORT:-1025}:1025'
            - '${FORWARD_MAILHOG_DASHBOARD_PORT:-8025}:8025'
        networks:
            - sail
    selenium:
        image: 'selenium/standalone-chrome'
        extra_hosts:
            - 'host.docker.internal:host-gateway'
        volumes:
            - '/dev/shm:/dev/shm'
        networks:
            - sail
networks:
    sail:
        driver: bridge
volumes:
    sail-mysql:
        driver: local
    sail-redis:
        driver: local
    sail-meilisearch:
        driver: local
    sailpgsql:
        driver: local
    sailelasticsearch:
        driver: local 

Voer vervolgens onderstaand commando uit om de nieuwe Elasticsearch image die je hebt toegevoegd aan het docker-compose.yml bestand op te halen.

docker-compose up

Voer dan onderstaand Composer commando uit om Explorer in het project te installeren.

composer require jeroen-g/explorer

Je moet ook een configuratiebestand maken voor de Explorer driver.

Voer het onderstaande Artisan commando uit om een explorer.config bestand te genereren voor het opslaan van de configuraties.

php artisan vendor:publish --tag=explorer.config

Het hierboven gegenereerde configuratiebestand zal beschikbaar zijn in de map /config.

In je config/explorer.php bestand kun je naar je model verwijzen met de indexes sleutel.

'indexes' => [
        \App\Models\Train::class
],

Verander de waarde van de variabele SCOUT_DRIVER in het .env bestand in elastic om Scout te configureren om de Explorer driver te gebruiken.

SCOUT_DRIVER = elastic

Op dit punt gebruik je Explorer binnen het Train model door de Explorer interface te implementeren en de methode mappableAs() te overschrijven.

Open het bestand Train.php in de map App > Models en vervang de bestaande code door onderstaande code.

<?php
namespace App\Models;
 
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use JeroenG\Explorer\Application\Explored;
use Laravel\Scout\Searchable;
 
class Train extends Model implements Explored
{
    use HasFactory;
    use Searchable;
 
    protected $fillable = ['title'];
 
    public function mappableAs(): array
    {
        return [
        	'id'=>$this->Id,
        	'title' => $this->title,
        ];
    }
} 

Met de code die je hierboven hebt toegevoegd, kun je Explorer nu gebruiken om tekst te zoeken binnen het Train model.

Samenvatting

Voor PHP developers maken Laravel en add-ons als Scout het super eenvoudig om snelle, robuuste full-text zoekfunctionaliteit te integreren. Met de database-engine, collection-engine, en de mogelijkheden van Meilisearch en Elasticsearch kun je in luttele milliseconden communiceren met de database van je app en geavanceerde zoekmechanismen implementeren.

Het naadloos beheren en bijwerken van je database betekent dat je gebruikers een optimale ervaring krijgen, terwijl je code strak en efficiënt blijft.

Met onze Applicatie en Database Hosting oplossingen is Kinsta je one-stop shop voor al je moderne Laravel ontwikkelingsbehoeften. De eerste 20 dollar krijg je van ons.