跳轉至內容

Laravel Scout

簡介

Laravel Scout 為向 Eloquent 模型新增全文搜尋提供了一個簡單的、基於驅動的解決方案。利用模型觀察者，Scout 會自動保持搜尋索引與 Eloquent 記錄的同步。

Scout 內建了 database 引擎，它使用 MySQL / PostgreSQL 全文索引和 LIKE 子句來搜尋現有資料庫，無需外部服務。對於大多數應用程式來說，這就足夠了。有關 Laravel 中所有可用搜索選項的概述，請查閱 搜尋文件。

當您需要拼寫糾錯、分面過濾或大規模地理搜尋等功能時，Scout 還提供了 Algolia、Meilisearch 和 Typesense 的驅動程式。此外還提供了一個用於本地開發的“集合”驅動程式，您也可以自由編寫自定義引擎。

安裝

首先，透過 Composer 包管理器安裝 Scout：

1composer require laravel/scout

安裝 Scout 後，應使用 vendor:publish Artisan 命令釋出 Scout 配置檔案。此命令會將 scout.php 配置檔案釋出到應用程式的 config 目錄中：

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

最後，將 Laravel\Scout\Searchable trait 新增到您想要搜尋的模型中。該 trait 將註冊一個模型觀察者，自動保持模型與您的搜尋驅動同步：

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6use Laravel\Scout\Searchable;
 7 
 8class Post extends Model
 9{
10    use Searchable;
11}

佇列化

當使用非 database 或 collection 引擎時，您應該強烈考慮在配置庫之前先配置一個 佇列驅動程式。執行佇列處理器可以使 Scout 將同步模型資訊到搜尋索引的所有操作放入佇列，從而為您的應用程式 Web 介面提供更好的響應速度。

配置好佇列驅動後，將 config/scout.php 配置檔案中的 queue 選項設定為 true：

1'queue' => true,

即使 queue 選項設定為 false，也請記住，某些 Scout 驅動（如 Algolia 和 Meilisearch）始終會非同步索引記錄。換句話說，即使索引操作在您的 Laravel 應用程式中已經完成，搜尋引擎本身可能也不會立即反映出最新和更新後的記錄。

要指定 Scout 作業使用的連線和佇列，您可以將 queue 配置選項定義為陣列：

1'queue' => [
2    'connection' => 'redis',
3    'queue' => 'scout'
4],

當然，如果您自定義了 Scout 作業使用的連線和佇列，則應執行一個佇列處理器來處理該連線和佇列上的作業：

1php artisan queue:work redis --queue=scout

驅動前提條件

Algolia

使用 Algolia 驅動時，您應在 config/scout.php 配置檔案中配置您的 Algolia id 和 secret 憑據。配置完成後，您還需要透過 Composer 包管理器安裝 Algolia PHP SDK：

1composer require algolia/algoliasearch-client-php

Meilisearch

Meilisearch 是一個快速、開源的搜尋引擎。如果您不確定如何在本地機器上安裝 Meilisearch，可以使用 Laravel 官方支援的 Docker 開發環境 Laravel Sail。

使用 Meilisearch 驅動時，您需要透過 Composer 包管理器安裝 Meilisearch PHP SDK：

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

然後，在應用程式的 .env 檔案中設定 SCOUT_DRIVER 環境變數，以及您的 Meilisearch host 和 key 憑據：

1SCOUT_DRIVER=meilisearch
2MEILISEARCH_HOST=http://127.0.0.1:7700
3MEILISEARCH_KEY=masterKey

有關 Meilisearch 的更多資訊，請查閱 Meilisearch 文件。

此外，請透過檢視 Meilisearch 關於二進位制相容性的文件，確保安裝的 meilisearch/meilisearch-php 版本與您的 Meilisearch 二進位制版本相容。

在升級使用 Meilisearch 的應用程式上的 Scout 時，應始終 檢視 Meilisearch 服務本身的任何其他重大變更。

Typesense

Typesense 是一個閃電般快速的開源搜尋引擎，支援關鍵詞搜尋、語義搜尋、地理搜尋和向量搜尋。

您可以 自託管 Typesense 或使用 Typesense Cloud。

要開始在 Scout 中使用 Typesense，請透過 Composer 包管理器安裝 Typesense PHP SDK：

1composer require typesense/typesense-php

然後，在應用程式的 .env 檔案中設定 SCOUT_DRIVER 環境變數，以及您的 Typesense 主機和 API 金鑰憑據：

1SCOUT_DRIVER=typesense
2TYPESENSE_API_KEY=masterKey
3TYPESENSE_HOST=localhost

如果您使用的是 Laravel Sail，您可能需要調整 TYPESENSE_HOST 環境變數以匹配 Docker 容器名稱。您還可以選擇指定安裝的埠、路徑和協議：

1TYPESENSE_PORT=8108
2TYPESENSE_PATH=
3TYPESENSE_PROTOCOL=http

關於 Typesense 集合的其他設定和模式定義，可以在應用程式的 config/scout.php 配置檔案中找到。有關 Typesense 的更多資訊，請查閱 Typesense 文件。

配置

配置可搜尋資料

預設情況下，給定模型的完整 toArray 形式將被持久化到其搜尋索引中。如果您想自定義同步到搜尋索引的資料，可以覆蓋模型上的 toSearchableArray 方法：

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6use Laravel\Scout\Searchable;
 7 
 8class Post extends Model
 9{
10    use Searchable;
11 
12    /**
13     * Get the indexable data array for the model.
14     *
15     * @return array<string, mixed>
16     */
17    public function toSearchableArray(): array
18    {
19        $array = $this->toArray();
20 
21        // Customize the data array...
22 
23        return $array;
24    }
25}

配置模型引擎

搜尋時，Scout 通常會使用應用程式 scout 配置檔案中指定的預設搜尋引擎。但是，可以透過覆蓋模型上的 searchableUsing 方法來更改特定模型的搜尋引擎：

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6use Laravel\Scout\Engines\Engine;
 7use Laravel\Scout\Scout;
 8use Laravel\Scout\Searchable;
 9 
10class User extends Model
11{
12    use Searchable;
13 
14    /**
15     * Get the engine used to index the model.
16     */
17    public function searchableUsing(): Engine
18    {
19        return Scout::engine('meilisearch');
20    }
21}

資料庫 / 集合引擎

資料庫引擎

資料庫引擎目前支援 MySQL 和 PostgreSQL，兩者均支援快速的全文列索引。

database 引擎使用 MySQL / PostgreSQL 全文索引和 LIKE 子句直接搜尋現有資料庫。對於許多應用程式來說，這是新增搜尋功能最簡單且最實用的方法，無需任何外部服務或額外基礎設施。

要使用資料庫引擎，請將 SCOUT_DRIVER 環境變數設定為 database：

1SCOUT_DRIVER=database

配置完成後，您可以 定義可搜尋資料 並開始 針對模型執行搜尋查詢。與第三方引擎不同，資料庫引擎不需要單獨的索引步驟，它直接搜尋您的資料庫表。

自定義資料庫搜尋策略

預設情況下，資料庫引擎會對您 配置為可搜尋 的每個模型屬性執行 LIKE 查詢。但是，您可以為特定列分配更高效的搜尋策略。SearchUsingFullText 屬性將使用資料庫的全文索引，而 SearchUsingPrefix 將僅匹配字串的開頭 (example%) 而不是在整個字串中進行搜尋 (%example%)。

要定義此行為，請將 PHP 屬性分配給模型的 toSearchableArray 方法。任何沒有屬性的列將繼續使用預設的 LIKE 策略：

 1use Laravel\Scout\Attributes\SearchUsingFullText;
 2use Laravel\Scout\Attributes\SearchUsingPrefix;
 3 
 4/**
 5 * Get the indexable data array for the model.
 6 *
 7 * @return array<string, mixed>
 8 */
 9#[SearchUsingPrefix(['id', 'email'])]
10#[SearchUsingFullText(['bio'])]
11public function toSearchableArray(): array
12{
13    return [
14        'id' => $this->id,
15        'name' => $this->name,
16        'email' => $this->email,
17        'bio' => $this->bio,
18    ];
19}

在指定某列應使用全文查詢約束之前，請確保該列已分配了 全文索引。

集合引擎

“集合”引擎旨在用於快速原型設計、極小資料集（幾百條記錄）或執行測試。它會從資料庫中檢索所有可能的記錄，並使用 Laravel 的 Str::is 輔助函式在 PHP 中進行過濾，因此不需要任何索引或資料庫特定的功能。對於除簡單用例之外的任何情況，您都應該使用 資料庫引擎。

要使用集合引擎，只需將 SCOUT_DRIVER 環境變數的值設定為 collection，或直接在應用程式的 scout 配置檔案中指定 collection 驅動：

1SCOUT_DRIVER=collection

指定集合驅動為首選驅動後，即可開始 針對模型執行搜尋查詢。使用集合引擎時，無需進行搜尋引擎索引（例如為 Algolia、Meilisearch 或 Typesense 索引建立種子所需的索引）。

與資料庫引擎的區別

資料庫引擎使用全文索引和 LIKE 子句高效查詢匹配記錄，而集合引擎會拉取所有記錄並在 PHP 中進行過濾。集合引擎是最具移植性的選項，因為它適用於 Laravel 支援的所有關係型資料庫（包括 SQLite 和 SQL Server）；但是，它的效率遠低於資料庫引擎，不應用於大資料集。

第三方引擎配置

以下配置選項僅在您使用 Algolia、Meilisearch 或 Typesense 等第三方搜尋引擎時才相關。如果您使用的是 資料庫引擎，則可以跳過此部分。

配置模型索引

使用第三方引擎時，每個 Eloquent 模型都會與一個給定的搜尋“索引”同步，其中包含該模型的所有可搜尋記錄。預設情況下，每個模型都將持久化到與模型“表”名稱匹配的索引中。通常，這是模型名稱的複數形式；但是，您可以自由透過覆蓋模型上的 searchableAs 方法來自定義模型的索引：

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6use Laravel\Scout\Searchable;
 7 
 8class Post extends Model
 9{
10    use Searchable;
11 
12    /**
13     * Get the name of the index associated with the model.
14     */
15    public function searchableAs(): string
16    {
17        return 'posts_index';
18    }
19}

當使用資料庫引擎時，searchableAs 方法無效，因為資料庫引擎總是直接搜尋模型的資料庫表。

配置模型 ID

預設情況下，Scout 將使用模型的主鍵作為儲存在搜尋索引中的唯一 ID/鍵。如果在使用第三方引擎時需要自定義此行為，可以覆蓋模型上的 getScoutKey 和 getScoutKeyName 方法：

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6use Laravel\Scout\Searchable;
 7 
 8class User extends Model
 9{
10    use Searchable;
11 
12    /**
13     * Get the value used to index the model.
14     */
15    public function getScoutKey(): mixed
16    {
17        return $this->email;
18    }
19 
20    /**
21     * Get the key name used to index the model.
22     */
23    public function getScoutKeyName(): mixed
24    {
25        return 'email';
26    }
27}

當使用資料庫引擎時，getScoutKey 和 getScoutKeyName 方法無效，因為資料庫引擎總是使用模型的主鍵。

Algolia

索引設定

有時您可能想在 Algolia 索引上配置其他設定。雖然您可以透過 Algolia UI 管理這些設定，但直接從應用程式的 config/scout.php 配置檔案中管理索引配置的期望狀態有時更高效。

這種方法允許您透過應用程式的自動化部署流水線部署這些設定，避免手動配置並確保多環境之間的一致性。您可以配置可過濾屬性、排名、分面或 任何其他支援的設定。

首先，在應用程式的 config/scout.php 配置檔案中為每個索引新增設定：

 1use App\Models\User;
 2use App\Models\Flight;
 3 
 4'algolia' => [
 5    'id' => env('ALGOLIA_APP_ID', ''),
 6    'secret' => env('ALGOLIA_SECRET', ''),
 7    'index-settings' => [
 8        User::class => [
 9            'searchableAttributes' => ['id', 'name', 'email'],
10            'attributesForFaceting'=> ['filterOnly(email)'],
11            // Other settings fields...
12        ],
13        Flight::class => [
14            'searchableAttributes'=> ['id', 'destination'],
15        ],
16    ],
17],

如果給定索引底層的模型支援軟刪除且包含在 index-settings 陣列中，Scout 將自動為該索引上的軟刪除模型包含分面支援。如果您沒有其他要為軟刪除模型索引定義的分面屬性，只需為該模型在 index-settings 陣列中新增一個空條目即可。

1'index-settings' => [
2    Flight::class => []
3],

配置好應用程式的索引設定後，必須呼叫 scout:sync-index-settings Artisan 命令。此命令將通知 Algolia 您當前配置的索引設定。為了方便起見，您可能希望將此命令作為部署過程的一部分。

1php artisan scout:sync-index-settings

識別使用者

Scout 允許您在使用 Algolia 時自動識別使用者。將已認證使用者與搜尋操作關聯起來，有助於在檢視 Algolia 控制面板內的搜尋分析時進行跟蹤。您可以透過在應用程式的 .env 檔案中定義 SCOUT_IDENTIFY 環境變數為 true 來啟用使用者識別：

1SCOUT_IDENTIFY=true

啟用此功能還會將請求的 IP 地址和已認證使用者的唯一識別符號傳遞給 Algolia，以便此資料與使用者發起的任何搜尋請求相關聯。

Meilisearch

索引設定

Meilisearch 要求您預先定義索引搜尋設定，例如可過濾屬性、可排序屬性和 其他支援的設定欄位。

可過濾屬性是您計劃在呼叫 Scout 的 where 方法時過濾的任何屬性，而可排序屬性是您計劃在呼叫 Scout 的 orderBy 方法時進行排序的任何屬性。要定義索引設定，請在應用程式 scout 配置檔案的 meilisearch 配置條目中調整 index-settings 部分：

 1use App\Models\User;
 2use App\Models\Flight;
 3 
 4'meilisearch' => [
 5    'host' => env('MEILISEARCH_HOST', 'https://:7700'),
 6    'key' => env('MEILISEARCH_KEY', null),
 7    'index-settings' => [
 8        User::class => [
 9            'filterableAttributes'=> ['id', 'name', 'email'],
10            'sortableAttributes' => ['created_at'],
11            // Other settings fields...
12        ],
13        Flight::class => [
14            'filterableAttributes'=> ['id', 'destination'],
15            'sortableAttributes' => ['updated_at'],
16        ],
17    ],
18],

如果給定索引底層的模型支援軟刪除且包含在 index-settings 陣列中，Scout 將自動為該索引上的軟刪除模型包含過濾支援。如果您沒有其他要為軟刪除模型索引定義的可過濾或可排序屬性，只需為該模型在 index-settings 陣列中新增一個空條目即可。

1'index-settings' => [
2    Flight::class => []
3],

配置好應用程式的索引設定後，必須呼叫 scout:sync-index-settings Artisan 命令。此命令將通知 Meilisearch 您當前配置的索引設定。為了方便起見，您可能希望將此命令作為部署過程的一部分。

1php artisan scout:sync-index-settings

可搜尋資料型別

Meilisearch 僅會對正確型別的資料執行過濾操作 (>, < 等)。在自定義可搜尋資料時，應確保數值被轉換為正確的型別。

1public function toSearchableArray()
2{
3    return [
4        'id' => (int) $this->id,
5        'name' => $this->name,
6        'price' => (float) $this->price,
7    ];
8}

Typesense

準備可搜尋資料

使用 Typesense 時，您的可搜尋模型必須定義一個 toSearchableArray 方法，將模型的主鍵轉換為字串，並將建立日期轉換為 UNIX 時間戳：

 1/**
 2 * Get the indexable data array for the model.
 3 *
 4 * @return array<string, mixed>
 5 */
 6public function toSearchableArray(): array
 7{
 8    return array_merge($this->toArray(),[
 9        'id' => (string) $this->id,
10        'created_at' => $this->created_at->timestamp,
11    ]);
12}

您還應在應用程式的 config/scout.php 檔案中定義 Typesense 集合模式。集合模式描述了每個可透過 Typesense 搜尋的欄位的資料型別。有關所有可用模式選項的更多資訊，請查閱 Typesense 文件。

如果需要在定義 Typesense 集合模式後對其進行更改，您可以執行 scout:flush 和 scout:import，這將刪除所有現有索引資料並重新建立模式。或者，您可以使用 Typesense 的 API 修改集合模式而不刪除任何索引資料。

如果您的可搜尋模型支援軟刪除，您應該在應用程式 config/scout.php 配置檔案的模型對應 Typesense 模式中定義一個 __soft_deleted 欄位。

 1User::class => [
 2    'collection-schema' => [
 3        'fields' => [
 4            // ...
 5            [
 6                'name' => '__soft_deleted',
 7                'type' => 'int32',
 8                'optional' => true,
 9            ],
10        ],
11    ],
12],

動態搜尋引數

Typesense 允許您在透過 options 方法執行搜尋操作時動態修改 搜尋引數：

1use App\Models\Todo;
2 
3Todo::search('Groceries')->options([
4    'query_by' => 'title, description'
5])->get();

第三方引擎索引

本節介紹的索引功能主要在您使用第三方引擎（Algolia、Meilisearch 或 Typesense）時相關。資料庫引擎直接搜尋您的資料庫表，因此不需要手動索引管理。

批次匯入

如果您將 Scout 安裝到現有專案中，您可能已經有需要匯入到索引中的資料庫記錄。Scout 提供了一個 scout:import Artisan 命令，您可以使用它將所有現有記錄匯入到搜尋索引中：

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

scout:queue-import 命令可用於使用 佇列作業 匯入所有現有記錄：

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

flush 命令可用於從搜尋索引中刪除模型的所有記錄：

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

修改匯入查詢

如果您想修改用於批次匯入所有模型的查詢，可以在模型上定義 makeAllSearchableUsing 方法。這是新增匯入模型前可能需要的任何關聯預載入的好地方：

1use Illuminate\Database\Eloquent\Builder;
2 
3/**
4 * Modify the query used to retrieve models when making all of the models searchable.
5 */
6protected function makeAllSearchableUsing(Builder $query): Builder
7{
8    return $query->with('author');
9}

當使用佇列批次匯入模型時，makeAllSearchableUsing 方法可能不適用。當作業處理模型集合時，關聯關係 不會被還原。

新增記錄

一旦將 Laravel\Scout\Searchable trait 新增到模型中，您只需要 save 或 create 一個模型例項，它就會自動新增到您的搜尋索引中。如果您已配置 Scout 使用佇列，此操作將由您的佇列處理器在後臺執行：

1use App\Models\Order;
2 
3$order = new Order;
4 
5// ...
6 
7$order->save();

透過查詢新增記錄

如果您想透過 Eloquent 查詢將一組模型新增到搜尋索引中，可以在 Eloquent 查詢上鍊式呼叫 searchable 方法。searchable 方法會 分塊處理 查詢結果並將記錄新增到搜尋索引。同樣，如果您已配置 Scout 使用佇列，所有分塊都將由佇列處理器在後臺匯入：

1use App\Models\Order;
2 
3Order::where('price', '>', 100)->searchable();

您也可以在 Eloquent 關聯例項上呼叫 searchable 方法：

1$user->orders()->searchable();

或者，如果您已經在記憶體中擁有 Eloquent 模型集合，則可以在集合例項上呼叫 searchable 方法，將模型例項新增到對應的索引中：

1$orders->searchable();

searchable 方法可以被視為“更新插入”（upsert）操作。換句話說，如果模型記錄已經在您的索引中，它將被更新；如果它不存在於搜尋索引中，它將被新增到索引中。

更新記錄

要更新可搜尋模型，您只需要更新模型例項的屬性並 save 模型到資料庫。Scout 會自動將更改持久化到您的搜尋索引中：

1use App\Models\Order;
2 
3$order = Order::find(1);
4 
5// Update the order...
6 
7$order->save();

您也可以在 Eloquent 查詢例項上呼叫 searchable 方法來更新一組模型。如果模型不存在於搜尋索引中，它們將被建立：

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

如果您想更新關聯中所有模型的搜尋索引記錄，可以對關聯例項呼叫 searchable：

1$user->orders()->searchable();

或者，如果您已經在記憶體中擁有 Eloquent 模型集合，則可以在集合例項上呼叫 searchable 方法，更新對應索引中的模型例項：

1$orders->searchable();

匯入前修改記錄

有時您可能需要在模型集合變為可搜尋之前對其進行準備。例如，您可能想要預載入一個關聯，以便關聯資料可以有效地新增到您的搜尋索引中。要實現這一點，請在對應模型上定義 makeSearchableUsing 方法：

1use Illuminate\Database\Eloquent\Collection;
2 
3/**
4 * Modify the collection of models being made searchable.
5 */
6public function makeSearchableUsing(Collection $models): Collection
7{
8    return $models->load('author');
9}

有條件地更新搜尋索引

預設情況下，無論修改了哪些屬性，Scout 都會重新索引更新後的模型。如果您想自定義此行為，可以在模型上定義 searchIndexShouldBeUpdated 方法：

1/**
2 * Determine if the search index should be updated.
3 */
4public function searchIndexShouldBeUpdated(): bool
5{
6    return $this->wasRecentlyCreated || $this->wasChanged(['title', 'body']);
7}

移除記錄

要從索引中刪除記錄，只需從資料庫中 delete 模型即可。即使您使用的是 軟刪除 模型，也可以這樣做：

1use App\Models\Order;
2 
3$order = Order::find(1);
4 
5$order->delete();

如果您不想在刪除記錄之前檢索模型，可以使用 Eloquent 查詢例項上的 unsearchable 方法：

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

如果您想刪除關聯中所有模型的搜尋索引記錄，可以對關聯例項呼叫 unsearchable：

1$user->orders()->unsearchable();

或者，如果您已經在記憶體中擁有 Eloquent 模型集合，則可以在集合例項上呼叫 unsearchable 方法，從對應的索引中刪除模型例項：

1$orders->unsearchable();

要從對應的索引中刪除所有模型記錄，可以呼叫 removeAllFromSearch 方法：

1Order::removeAllFromSearch();

暫停索引

有時您可能需要對模型執行一批 Eloquent 操作，而不將模型資料同步到搜尋索引。您可以使用 withoutSyncingToSearch 方法來完成此操作。此方法接受一個立即執行的閉包。在閉包內發生的任何模型操作都不會同步到模型的索引：

1use App\Models\Order;
2 
3Order::withoutSyncingToSearch(function () {
4    // Perform model actions...
5});

條件搜尋模型例項

有時您可能只需要在特定條件下使模型可搜尋。例如，假設您有一個 App\Models\Post 模型，它可能處於“草稿”和“已釋出”兩種狀態之一。您可能只想允許“已釋出”的帖子可搜尋。要實現這一點，可以在模型上定義 shouldBeSearchable 方法：

1/**
2 * Determine if the model should be searchable.
3 */
4public function shouldBeSearchable(): bool
5{
6    return $this->isPublished();
7}

shouldBeSearchable 方法僅在透過 save 和 create 方法、查詢或關聯操作模型時應用。直接使用 searchable 方法使模型或集合可搜尋將覆蓋 shouldBeSearchable 方法的結果。

在使用 Scout 的“資料庫”引擎時，shouldBeSearchable 方法不適用，因為所有可搜尋資料始終儲存在資料庫中。在使用資料庫引擎時要實現類似行為，應改用 where 子句。

搜尋

您可以使用 search 方法開始搜尋模型。search 方法接受一個字串，該字串將用於搜尋您的模型。然後，您應該在搜尋查詢上鍊式呼叫 get 方法來檢索與給定搜尋查詢匹配的 Eloquent 模型：

1use App\Models\Order;
2 
3$orders = Order::search('Star Trek')->get();

由於 Scout 搜尋返回的是 Eloquent 模型集合，您甚至可以直接從路由或控制器返回結果，它們將自動轉換為 JSON：

1use App\Models\Order;
2use Illuminate\Http\Request;
3 
4Route::get('/search', function (Request $request) {
5    return Order::search($request->search)->get();
6});

如果您想在轉換為 Eloquent 模型之前獲取原始搜尋結果，可以使用 raw 方法：

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

自定義索引

使用第三方引擎搜尋時，搜尋查詢通常會在模型 searchableAs 方法指定的索引上執行。但是，您可以使用 within 方法來指定應該搜尋的自定義索引：

1$orders = Order::search('Star Trek')
2    ->within('tv_shows_popularity_desc')
3    ->get();

Where 子句

Scout 允許您向搜尋查詢新增簡單的 “where” 子句。目前，這些子句僅支援基本的等值檢查，主要用於透過所有者 ID 限定搜尋查詢範圍：

1use App\Models\Order;
2 
3$orders = Order::search('Star Trek')->where('user_id', 1)->get();

此外，whereIn 方法可用於驗證給定列的值是否包含在給定陣列中：

1$orders = Order::search('Star Trek')->whereIn(
2    'status', ['open', 'paid']
3)->get();

whereNotIn 方法驗證給定列的值是否不包含在給定陣列中：

1$orders = Order::search('Star Trek')->whereNotIn(
2    'status', ['closed']
3)->get();

如果您的應用程式正在使用 Meilisearch，在使用 Scout 的 “where” 子句之前，必須先配置應用程式的 可過濾屬性。

自定義 Eloquent 結果查詢

在 Scout 從搜尋引擎檢索到匹配的 Eloquent 模型列表後，Eloquent 會被用於透過主鍵檢索所有匹配的模型。您可以透過呼叫 query 方法自定義此查詢。query 方法接受一個閉包，該閉包將接收 Eloquent 查詢構建器例項作為引數：

1use App\Models\Order;
2use Illuminate\Database\Eloquent\Builder;
3 
4$orders = Order::search('Star Trek')
5    ->query(fn (Builder $query) => $query->with('invoices'))
6    ->get();

使用第三方引擎時，此回撥在相關模型已從搜尋引擎檢索後呼叫，因此不應將其用於“過濾”結果——請改用 Scout where 子句。但是，當使用資料庫引擎時，query 方法的約束直接應用於資料庫查詢，因此您也可以將其用於過濾。

分頁

除了檢索模型集合外，您還可以使用 paginate 方法對搜尋結果進行分頁。此方法將返回一個 Illuminate\Pagination\LengthAwarePaginator 例項，就像您 分頁傳統 Eloquent 查詢 一樣：

1use App\Models\Order;
2 
3$orders = Order::search('Star Trek')->paginate();

您可以透過將頁碼作為 paginate 方法的第一個引數傳遞，來指定每頁檢索多少個模型：

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

使用資料庫引擎時，您也可以使用 simplePaginate 方法。與 paginate 不同（它會檢索總記錄數以便顯示頁碼），simplePaginate 僅確定當前頁面之外是否還有更多結果，這對於只需要“上一頁”和“下一頁”連結的大型資料集更有效：

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

檢索到結果後，您可以使用 Blade 顯示結果並渲染頁面連結，就像分頁傳統 Eloquent 查詢一樣：

1<div class="container">
2    @foreach ($orders as $order)
3        {{ $order->price }}
4    @endforeach
5</div>
6 
7{{ $orders->links() }}

當然，如果您想將分頁結果作為 JSON 檢索，可以直接從路由或控制器返回分頁器例項：

1use App\Models\Order;
2use Illuminate\Http\Request;
3 
4Route::get('/orders', function (Request $request) {
5    return Order::search($request->input('query'))->paginate(15);
6});

由於搜尋引擎無法識別您的 Eloquent 模型全域性作用域定義，因此您不應在利用 Scout 分頁的應用程式中使用全域性作用域。或者，您應該在透過 Scout 搜尋時重新建立全域性作用域的約束。

軟刪除

如果您的索引模型正在進行 軟刪除 並且您需要搜尋已軟刪除的模型，請將 config/scout.php 配置檔案的 soft_delete 選項設定為 true：

1'soft_delete' => true,

當此配置選項為 true 時，Scout 不會從搜尋索引中刪除已軟刪除的模型。相反，它會在索引記錄上設定一個隱藏的 __soft_deleted 屬性。然後，您可以在搜尋時使用 withTrashed 或 onlyTrashed 方法來檢索已軟刪除的記錄：

1use App\Models\Order;
2 
3// Include trashed records when retrieving results...
4$orders = Order::search('Star Trek')->withTrashed()->get();
5 
6// Only include trashed records when retrieving results...
7$orders = Order::search('Star Trek')->onlyTrashed()->get();

當使用 forceDelete 永久刪除軟刪除模型時，Scout 會自動將其從搜尋索引中刪除。

自定義引擎搜尋

如果您需要對引擎的搜尋行為進行高階自定義，可以將閉包作為 search 方法的第二個引數傳遞。例如，您可以在搜尋查詢傳遞給 Algolia 之前，使用此回撥將地理位置資料新增到搜尋選項中：

 1use Algolia\AlgoliaSearch\SearchIndex;
 2use App\Models\Order;
 3 
 4Order::search(
 5    'Star Trek',
 6    function (SearchIndex $algolia, string $query, array $options) {
 7        $options['body']['query']['bool']['filter']['geo_distance'] = [
 8            'distance' => '1000km',
 9            'location' => ['lat' => 36, 'lon' => 111],
10        ];
11 
12        return $algolia->search($query, $options);
13    }
14)->get();

自定義引擎

編寫引擎

如果內建的 Scout 搜尋引擎不能滿足您的需求，您可以編寫自己的自定義引擎並將其註冊到 Scout。您的引擎應繼承 Laravel\Scout\Engines\Engine 抽象類。此類包含您的自定義引擎必須實現的八個方法：

 1use Laravel\Scout\Builder;
 2 
 3abstract public function update($models);
 4abstract public function delete($models);
 5abstract public function search(Builder $builder);
 6abstract public function paginate(Builder $builder, $perPage, $page);
 7abstract public function mapIds($results);
 8abstract public function map(Builder $builder, $results, $model);
 9abstract public function getTotalCount($results);
10abstract public function flush($model);

檢視 Laravel\Scout\Engines\AlgoliaEngine 類對這些方法的實現可能會有所幫助。此類將為您學習如何在自己的引擎中實現這些方法提供一個良好的起點。

註冊引擎

一旦編寫了自定義引擎，就可以使用 Scout 引擎管理器的 extend 方法將其註冊到 Scout 中。Scout 的引擎管理器可以從 Laravel 服務容器中解析。您應該從 App\Providers\AppServiceProvider 類或應用程式使用的任何其他服務提供者的 boot 方法中呼叫 extend 方法：

 1use App\ScoutExtensions\MySqlSearchEngine;
 2use Laravel\Scout\EngineManager;
 3 
 4/**
 5 * Bootstrap any application services.
 6 */
 7public function boot(): void
 8{
 9    resolve(EngineManager::class)->extend('mysql', function () {
10        return new MySqlSearchEngine;
11    });
12}

註冊引擎後，可以在應用程式的 config/scout.php 配置檔案中將其指定為預設的 Scout driver：

1'driver' => 'mysql',

Laravel 是構建、部署和監控軟體
 最高效的方式。

產品

Packages

資源

合作伙伴