- Introduction
- Installation
- Queueing
- Driver Prerequisites
- Configuration
- Configuration des index de modèle
- Configuration des données consultables
- Configuration de l'ID du modèle
- Identifying Users
- Indexing
- Batch Import
- Adding Records
- Updating Records
- Removing Records
- Pausing Indexing
- Instances de modèle interrogeables de manière conditionnelle
- Searching
- Where Clauses
- Pagination
- Soft Deleting
- Personnaliser les recherches du moteur
- Custom Engines
- Builder Macros
Introduction
Laravel Scout fournit une solution simple basée sur un pilote pour ajouter une recherche en texte intégral à vos modèles Eloquent . À l'aide d'observateurs de modèles, Scout gardera automatiquement vos index de recherche synchronisés avec vos enregistrements Eloquent.
Actuellement, Scout est livré avec un pilote Algolia ; Cependant, l'écriture de pilotes personnalisés est simple et vous êtes libre d'étendre Scout avec vos propres implémentations de recherche.
Installation
Tout d'abord,installez Scout via le gestionnaire de paquets Composer :
composer require laravel/scout Après avoir installé Scout, vous devez publier la configuration Scout à l'aide de la commande vendor:publish Artisan. Cette commande publiera le fichier de configuration scout.php dans votre répertoire de config uration:
php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"
Enfin, ajoutez le trait Laravel\Scout\Searchable au modèle que vous souhaitez rendre consultable. Cette caractéristique enregistrera un observateur de modèle pour garder le modèle synchronisé avec votre moteur de recherche:
<?phpnamespace App\Models;use Illuminate\Database\Eloquent\Model;use Laravel\Scout\Searchable;class Post extends Model{ use Searchable;}
Queueing
Bien qu'il ne soit pas strictement nécessaire d'utiliser Scout, vous devriez fortement envisager de configurer un pilote de file d'attente avant d'utiliser la bibliothèque. L'exécution d'un travailleur de file d'attente permettra à Scout de mettre en file d'attente toutes les opérations qui synchronisent vos informations de modèle avec vos index de recherche, offrant ainsi des temps de réponse bien meilleurs pour l'interface Web de votre application.
Une fois que vous avez configuré un pilote de file d'attente, définissez la valeur de l' option queue dans votre fichier de configuration config/scout.php sur true :
'queue' => true,
Driver Prerequisites
Algolia
Lorsque vous utilisez le pilote Algolia, vous devez configurer votre id entifiant Algolia et vos informations d' identification secret dans votre fichier de configuration config/scout.php . Une fois vos identifiants configurés, vous devrez également installer le SDK PHP Algolia via le gestionnaire de packages Composer :
composer require algolia/algoliasearch-client-php Configuration
Configuration des index de modèle
Chaque modèle Eloquent est synchronisé avec un "index" de recherche donné, qui contient tous les enregistrements interrogeables pour ce modèle. En d'autres termes, vous pouvez considérer chaque index comme une table MySQL. Par défaut, chaque modèle sera conservé dans un index correspondant au nom de "table" typique du modèle. En règle générale, il s'agit du pluriel du nom du modèle; Cependant, vous êtes libre de personnaliser l'index du modèle en remplaçant la méthode searchableAs sur le modèle:
<?phpnamespace App\Models;use Illuminate\Database\Eloquent\Model;use Laravel\Scout\Searchable;class Post extends Model{ use Searchable; /** * Récupère le nom d'index du modèle. * * @ chaîne de retour */ public function searchableAs() { return 'posts_index'; }}
Configuration des données consultables
Par défaut, la totalité de la forme toArray d'un modèle donné sera conservée dans son index de recherche. Si vous souhaitez personnaliser les données synchronisées avec l'index de recherche, vous pouvez remplacer la méthode toSearchableArray sur le modèle:
<?phpnamespace App\Models;use Illuminate\Database\Eloquent\Model;use Laravel\Scout\Searchable;class Post extends Model{ use Searchable; /** * Récupère le tableau de données indexables pour le modèle. * * @return tableau */ public function toSearchableArray() { $array = $this->toArray(); // Personnaliser le tableau... return $array; }}
Configuration de l'ID du modèle
Par défaut, Scout utilisera la clé primaire du modèle comme identifiant unique stocké dans l'index de recherche. Si vous devez personnaliser ce comportement, vous pouvez remplacer les getScoutKey et getScoutKeyName sur le modèle:
<?phpnamespace App\Models;use Illuminate\Database\Eloquent\Model;use Laravel\Scout\Searchable;class User extends Model{ use Searchable; /** * Récupère la valeur utilisée pour indexer le modèle. * * @return mixte */ public function getScoutKey() { return $this->email; } /** * Récupère le nom de la clé utilisée pour indexer le modèle. * * @return mixte */ public function getScoutKeyName() { return 'email'; }}
Identifying Users
Scout vous permet également d'identifier automatiquement les utilisateurs lors de l'utilisation d'Algolia. Associer l'utilisateur authentifié aux opérations de recherche peut être utile lors de l'affichage de vos analyses de recherche dans le tableau de bord d'Algolia. Vous pouvez activer l'identification de l'utilisateur en définissant SCOUT_IDENTIFY sur true dans votre fichier .env :
SCOUT_IDENTIFY=true
En activant cette fonction,l'adresse IP de la demande et l'identifiant principal de votre utilisateur authentifié seront également transmis à Algolia afin que ces données soient associées à toute demande de recherche effectuée par l'utilisateur.
Indexing
Batch Import
Si vous installez Scout dans un projet existant, vous avez peut-être déjà des enregistrements de base de données que vous devez importer dans votre pilote de recherche. Scout fournit une commande import Artisan que vous pouvez utiliser pour importer tous vos enregistrements existants dans vos index de recherche:
php artisan scout:import "App\Models\Post"
La commande flush peut être utilisée pour supprimer tous les enregistrements d'un modèle de vos index de recherche:
php artisan scout:flush "App\Models\Post"
Modifier la requête d'importation
Si vous souhaitez modifier la requête utilisée pour récupérer tous vos modèles pour l'importation par lots, vous pouvez définir une méthode makeAllSearchableUsing sur votre modèle. C'est un endroit idéal pour ajouter tout chargement de relation avide qui peut être nécessaire avant d'importer vos modèles:
/** * Modifier la requête utilisée pour récupérer les modèles lors de la recherche de tous les modèles. * * @param \Illuminate\Database\Eloquent\Builder $query * @return \Illuminate\Database\Eloquent\Builder */protected function makeAllSearchableUsing($query){ return $query->with('author');}
Adding Records
Une fois que vous avez ajouté le trait Laravel\Scout\Searchable à un modèle, il vous suffit d' save une instance de modèle et elle sera automatiquement ajoutée à votre index de recherche. Si vous avez configuré Scout pour utiliser les files d'attente, cette opération sera effectuée en arrière-plan par votre travailleur de file d'attente:
$order = new App\Models\Order;// ...$order->save();
Ajout via une requête
Si vous souhaitez ajouter une collection de modèles à votre index de recherche via une requête Eloquent, vous pouvez enchaîner la méthode de searchable sur une requête Eloquent. La méthode de searchable segmentera les résultats de la requête et ajoutera les enregistrements à votre index de recherche. Encore une fois, si vous avez configuré Scout pour utiliser des files d'attente, tous les morceaux seront ajoutés en arrière-plan par vos travailleurs de file d'attente:
// Ajout via une requête éloquente...App\Models\Order::where('price', '>', 100)->searchable();// Vous pouvez également ajouter des enregistrements via des relations...$user->orders()->searchable();// Vous pouvez également ajouter des enregistrements via des collections...$orders->searchable();
La méthode de searchable peut être considérée comme une opération «upsert». En d'autres termes, si l'enregistrement du modèle est déjà dans votre index, il sera mis à jour. S'il n'existe pas dans l'index de recherche, il sera ajouté à l'index.
Updating Records
Pour mettre à jour un modèle interrogeable, il vous suffit de mettre à jour les propriétés de l'instance de modèle et d' save le modèle dans votre base de données. Scout conservera automatiquement les modifications apportées à votre index de recherche:
$order = App\Models\Order::find(1);// Mettre à jour la commande...$order->save();
Vous pouvez également utiliser la méthode de searchable sur une requête Eloquent pour mettre à jour une collection de modèles. Si les modèles n'existent pas dans votre index de recherche, ils seront créés :
// Mise à jour via la requête Eloquent...App\Models\Order::where('price', '>', 100)->searchable();// Vous pouvez également mettre à jour via les relations...$user->orders()->searchable();// Vous pouvez également mettre à jour via les collections...$orders->searchable();
Removing Records
Pour supprimer un enregistrement de votre index, delete le modèle de la base de données. Cette forme de suppression est même compatible avec les modèles supprimés en douceur:
$order = App\Models\Order::find(1);$order->delete();
Si vous ne souhaitez pas récupérer le modèle avant de supprimer l'enregistrement, vous pouvez utiliser la méthode unsearchable sur une instance de requête ou une collection Eloquent:
// Suppression via une requête éloquente...App\Models\Order::where('price', '>', 100)->unsearchable();// Vous pouvez également supprimer via des relations...$user->orders()->unsearchable();// Vous pouvez également supprimer via les collections...$orders->unsearchable();
Pausing Indexing
Parfois, vous devrez peut-être effectuer un lot d'opérations Eloquent sur un modèle sans synchroniser les données du modèle avec votre index de recherche. Vous pouvez le faire en utilisant la méthode withoutSyncingToSearch . Cette méthode accepte un seul rappel qui sera immédiatement exécuté. Toutes les opérations de modèle qui se produisent dans le rappel ne seront pas synchronisées avec l'index du modèle:
App\Models\Order::withoutSyncingToSearch(function () { // Exécuter les actions du modèle...});
Instances de modèle interrogeables de manière conditionnelle
Parfois, vous devrez peut-être rendre un modèle consultable uniquement sous certaines conditions. Par exemple, imaginez que vous ayez un modèle App\Models\Post qui peut être dans l'un des deux états suivants: «brouillon» et «publié». Vous souhaiterez peut-être autoriser uniquement la recherche des articles «publiés». Pour ce faire, vous pouvez définir une méthode shouldBeSearchable sur votre modèle:
public function shouldBeSearchable(){ return $this->isPublished();}
La méthode shouldBeSearchable n'est appliquée que lors de la manipulation de modèles via la méthode save , les requêtes ou les relations. Rendre directement des modèles ou des collections consultables à l'aide de la méthode de searchable remplacera le résultat de la méthode shouldBeSearchable :
// Respectera "shouldBeSearchable"...App\Models\Order::where('price', '>', 100)->searchable();$user->orders()->searchable();$order->save();// écrasera "shouldBeSearchable"...$orders->searchable();$order->searchable();
Searching
Vous pouvez commencer à rechercher un modèle en utilisant la méthode de search . La méthode de recherche accepte une seule chaîne qui sera utilisée pour rechercher vos modèles. Vous devez ensuite enchaîner la méthode get sur la requête de recherche pour récupérer les modèles Eloquent qui correspondent à la requête de recherche donnée:
$orders = App\Models\Order::search('Star Trek')->get();
Puisque les recherches Scout renvoient une collection de modèles Eloquent,vous pouvez même renvoyer les résultats directement depuis une route ou un contrôleur et ils seront automatiquement convertis en JSON :
use Illuminate\Http\Request;Route::get('/search', function (Request $request) { return App\Models\Order::search($request->search)->get();});
Si vous souhaitez obtenir les résultats bruts avant qu'ils ne soient convertis en modèles éloquents, vous devez utiliser la méthode raw :
$orders = App\Models\Order::search('Star Trek')->raw();
Les requêtes de recherche seront généralement effectuées sur l'index spécifié par la méthode searchableAs du modèle . Cependant, vous pouvez utiliser l' within de méthode pour spécifier un index personnalisé qui devrait être recherché à la place:
$orders = App\Models\Order::search('Star Trek') ->within('tv_shows_popularity_desc') ->get();
Where Clauses
Scout vous permet d'ajouter des clauses "where" simples à vos requêtes de recherche.Actuellement,ces clauses ne prennent en charge que les contrôles d'égalité numériques de base,et sont principalement utiles pour délimiter les requêtes de recherche par un ID de locataire.Comme un index de recherche n'est pas une base de données relationnelle,les clauses "where" plus avancées ne sont pas prises en charge actuellement :
$orders = App\Models\Order::search('Star Trek')->where('user_id', 1)->get();
Pagination
En plus de récupérer une collection de modèles, vous pouvez paginer vos résultats de recherche en utilisant la méthode de paginate . Cette méthode retournera une instance Paginator comme si vous aviez paginé une requête Eloquent traditionnelle :
$orders = App\Models\Order::search('Star Trek')->paginate();
Vous pouvez spécifier le nombre de modèles à récupérer par page en passant le montant comme premier argument à la méthode de paginate :
$orders = App\Models\Order::search('Star Trek')->paginate(15);
Une fois que vous avez récupéré les résultats, vous pouvez afficher les résultats et restituer les liens des pages à l'aide de Blade comme si vous aviez paginé une requête Eloquent traditionnelle:
<div class="container"> @foreach ($orders as $order) {{ $order->price }} @endforeach</div>{{ $orders->links() }} Soft Deleting
Si vos modèles indexés sont en suppression logicielle et que vous devez rechercher vos modèles supprimés soft_delete , définissez l' option config/scout.php fichier de configuration config/scout.php sur true :
'soft_delete' => true,
Lorsque cette option de configuration est true , Scout ne supprime pas les modèles supprimés de l'index de recherche. Au lieu de cela, il définira un attribut __soft_deleted masqué sur l'enregistrement indexé. Ensuite, vous pouvez utiliser les méthodes withTrashed ou onlyTrashed pour récupérer les enregistrements supprimés lors de la recherche:
// Inclut les enregistrements supprimés lors de la récupération des résultats...$orders = App\Models\Order::search('Star Trek')->withTrashed()->get();// Inclut uniquement les enregistrements supprimés lors de la récupération des résultats...$orders = App\Models\Order::search('Star Trek')->onlyTrashed()->get();
Lorsqu'un modèle supprimé définitivement est définitivement supprimé à l'aide de
forceDelete, Scout le supprime automatiquement de l'index de recherche.
Personnaliser les recherches du moteur
Si vous devez personnaliser le comportement de recherche d'un moteur, vous pouvez passer un rappel comme deuxième argument à la méthode de search . Par exemple, vous pouvez utiliser ce rappel pour ajouter des données de géolocalisation à vos options de recherche avant que la requête de recherche ne soit transmise à Algolia:
use Algolia\AlgoliaSearch\SearchIndex;App\Models\Order::search('Star Trek', function (SearchIndex $algolia, string $query, array $options) { $options['body']['query']['bool']['filter']['geo_distance'] = [ 'distance' => '1000km', 'location' => ['lat' => 36, 'lon' => 111], ]; return $algolia->search($query, $options);})->get();
Custom Engines
Rédaction du moteur
Si l'un des moteurs de recherche Scout intégrés ne correspond pas à vos besoins, vous pouvez écrire votre propre moteur personnalisé et l'enregistrer auprès de Scout. Votre moteur doit étendre la classe abstraite Laravel\Scout\Engines\Engine . Cette classe abstraite contient huit méthodes que votre moteur personnalisé doit implémenter:
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);
Vous trouverez peut-être utile de revoir les implémentations de ces méthodes sur la classe Laravel\Scout\Engines\AlgoliaEngine . Ce cours vous fournira un bon point de départ pour apprendre à implémenter chacune de ces méthodes dans votre propre moteur.
Enregistrement du moteur
Une fois que vous avez écrit votre moteur personnalisé, vous pouvez l'enregistrer auprès de Scout en utilisant la méthode d' extend du gestionnaire de moteur Scout. Vous devez appeler la méthode extend à partir de la méthode de boot de votre AppServiceProvider ou de tout autre fournisseur de services utilisé par votre application. Par exemple, si vous avez écrit un MySqlSearchEngine , vous pouvez l'enregistrer comme ceci:
use Laravel\Scout\EngineManager;/** * Amorcer tous les services d'application. * * @return void */public function boot(){ resolve(EngineManager::class)->extend('mysql', function () { return new MySqlSearchEngine; });}
Une fois votre moteur enregistré, vous pouvez le spécifier comme driver Scout par défaut dans votre fichier de configuration config/scout.php :
'driver' => 'mysql',
Builder Macros
Si vous souhaitez définir une méthode de génération personnalisée, vous pouvez utiliser la méthode macro sur la classe Laravel\Scout\Builder . En règle générale, les "macros" doivent être définies dans la méthode de boot un fournisseur de services:
<?phpnamespace App\Providers;use Illuminate\Support\Facades\Response;use Illuminate\Support\ServiceProvider;use Laravel\Scout\Builder;class ScoutMacroServiceProvider extends ServiceProvider{ /** * Enregistrez les macros de reconnaissance de l'application. * * @return void */ public function boot() { Builder::macro('count', function () { return $this->engine->getTotalCount( $this->engine()->search($this) ); }); }}
La fonction macro accepte un nom comme premier argument et une fermeture comme second. La fermeture de la macro sera exécutée lors de l'appel du nom de la macro à partir d'une implémentation Laravel\Scout\Builder :
App\Models\Order::search('Star Trek')->count();