Laravel master Laravel Scout

イントロダクションIntroduction

Laravel Scout（スカウト、斥候）は、Eloquentモデルへ、シンプルなドライバベースのフルテキストサーチを提供します。モデルオブサーバを使い、Scoutは検索インデックスを自動的にEloquentレコードと同期します。Laravel Scout provides a simple, driver based solution for adding full-text search to your Eloquent models[/docs/{{version}}/eloquent]. Using model observers, Scout will automatically keep your search indexes in sync with your Eloquent records.

現在、ScoutはAlgoliaドライバを用意しています。カスタムドライバは簡単に書けますので、独自の検索を実装し、Scoutを拡張できます。Currently, Scout ships with an Algolia[https://www.algolia.com/] driver; however, writing custom drivers is simple and you are free to extend Scout with your own search implementations.

インストールInstallation

最初に、Composerパッケージマネージャを使い、Scoutをインストールします。First, install the Scout via the Composer package manager:

composer require laravel/scout

次に、config/app.php設定ファイルのproviders配列へ、ScoutServiceProviderを追加します。Next, you should add the ScoutServiceProvider to the providers array of your config/app.php configuration file:

Laravel\Scout\ScoutServiceProvider::class,

Scoutサービスプロバイダを登録したら、vendor:publish Artisanコマンドを使い、Scout設定を公開（Laravel用語で、リソースや設定を開発者が変更可能な場所へ用意すること）します。このコマンドは、configディレクトリ下にscout.php設定ファイルを公開します。After registering the Scout service provider, you should publish the Scout configuration using the vendor:publish Artisan command. This command will publish the scout.php configuration file to your config directory:

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

最後に、検索可能にしたいモデルへ、Laravel\Scout\Searchableトレイトを追加します。このトレイトはモデルオブザーバを登録し、サーチドライバとモデルの同期を取り続けます。Finally, add the Laravel\Scout\Searchable trait to the model you would like to make searchable. This trait will register a model observer to keep the model in sync with your search driver:

<?php

namespace App;

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

class Post extends Model
{
    use Searchable;
}

キューQueueing

Scoutを厳格（リアルタイム）に利用する必要が無いのであれば、このライブラリを使用する前にキュードライバの設定を考えてみるべきでしょう。キューワーカの実行により、モデルの情報を検索インデックスに同期する全操作をキューイングでき、アプリケーションのWebインターフェイスのレスポンス時間を改善できるでしょう。While not strictly required to use Scout, you should strongly consider configuring a queue driver[/docs/{{version}}/queues] before using the library. Running a queue worker will allow Scout to queue all operations that sync your model information to your search indexes, providing much better response times for your application's web interface.

キュードライバを設定したら、config/scout.php設定ファイルのqueueオプション値をtrueに設定してください。Once you have configured a queue driver, set the value of the queue option in your config/scout.php configuration file to true:

'queue' => true,

ドライバの事前要件Driver Prerequisites

AlgoliaAlgolia

Algoliaドライバを使用する場合、Algolia idとsecret接続情報をconfig/scout.php設定ファイルで設定する必要があります。接続情報を設定し終えたら、Algolia PHP SDKをComposerパッケージマネージャで、インストールする必要があります。When using the Algolia driver, you should configure your Algolia id and secret credentials in your config/scout.php configuration file. Once your credentials have been configured, you will also need to install the Algolia PHP SDK via the Composer package manager:

composer require algolia/algoliasearch-client-php

設定Configuration

モデルインデックスの設定Configuring Model Indexes

各Eloquentモデルは、検索可能レコードすべてを含む、指定された検索「インデックス」と同期されます。言い換えれば、各インデックスはMySQLテーブルのようなものであると、考えられます。デフォルトで、各モデルはそのモデルの典型的な「テーブル」名に一致するインデックスへ保存されます。通常、モデルの複数形ですが、モデルのsearchableAsメソッドをオーバーライドすることで、このモデルのインデックスを自由にカスタマイズ可能です。Each Eloquent model is synced with a given search "index", which contains all of the searchable records for that model. In other words, you can think of each index like a MySQL table. By default, each model will be persisted to an index matching the model's typical "table" name. Typically, this is the plural form of the model name; however, you are free to customize the model's index by overriding the searchableAs method on the model:

<?php

namespace App;

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

class Post extends Model
{
    use Searchable;

    /**
     * モデルのインデックス名取得
     *
     * @return string
     */
    public function searchableAs()
    {
        return 'posts_index';
    }
}

検索可能データの設定Configuring Searchable Data

デフォルトでは、指定されたモデルのtoArray形態全体が、検索インデックスへ保存されます。検索インデックスと同期するデータをカスタマイズしたい場合は、そのモデルのtoSearchableArrayメソッドをオーバーライドできます。By default, the entire toArray form of a given model will be persisted to its search index. If you would like to customize the data that is synchronized to the search index, you may override the toSearchableArray method on the model:

<?php

namespace App;

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

class Post extends Model
{
    use Searchable;

    /**
     * モデルのインデックス可能なデータ配列の取得
     *
     * @return array
     */
    public function toSearchableArray()
    {
        $array = $this->toArray();

        // 配列のカスタマイズ…

        return $array;
    }
}

インデックスIndexing

バッチ取り込みBatch Import

既存プロジェクトにScoutをインストールする場合、検索ドライバへ取り込むために必要なデータベースレコードは、既に存在しています。Scoutは既存の全レコードを検索インデックスへ取り込むために使用する、import Artisanコマンドを提供しています。If you are installing Scout into an existing project, you may already have database records you need to import into your search driver. Scout provides an import Artisan command that you may use to import all of your existing records into your search indexes:

php artisan scout:import "App\Post"

レコード追加Adding Records

モデルにLaravel\Scout\Searchableトレイトを追加したら、必要なのはモデルインスタンスをsaveすることです。これにより自動的に検索インデックスへ追加されます。Scoutでキューを使用する設定にしている場合は、この操作はキューワーカにより、バックグランドで実行されます。Once you have added the Laravel\Scout\Searchable trait to a model, all you need to do is save a model instance and it will automatically be added to your search index. If you have configured Scout to use queues[#queueing] this operation will be performed in the background by your queue worker:

$order = new App\Order;

// ...

$order->save();

クエリによる追加Adding Via Query

Eloquentクエリにより、検索インデックスへモデルのコレクションを追加したい場合は、Eloquentクエリにsearchableメソッドをチェーンします。searchableメソッドは、クエリの結果をチャンクへ分割し、レコードを検索変人へ追加します。この場合も、Scoutでキューを使用する設定をしていれば、キューワーカが全チャンクをバックグランドで追加します。If you would like to add a collection of models to your search index via an Eloquent query, you may chain the searchable method onto an Eloquent query. The searchable method will chunk the results[/docs/{{version}}/eloquent#chunking-results] of the query and add the records to your search index. Again, if you have configured Scout to use queues, all of the chunks will be added in the background by your queue workers:

// Eloquentクエリにより追加
App\Order::where('price', '>', 100)->searchable();

// リレーションにより、レコードを追加することもできる
$user->orders()->searchable();

// コレクションにより、追加することもできる
$orders->searchable();

searchableメソッドは"upsert(update+insert)"操作と考えられます。言い換えれば、モデルレコードがインデックスへ既に存在していれば、更新されます。検索エンジンに存在していなければ、インデックスへ追加されます。The searchable method can be considered an "upsert" operation. In other words, if the model record is already in your index, it will be updated. If it does not exist in the search index, it will be added to the index.

レコード更新Updating Records

検索可能モデルを更新するには、モデルインスタンスのプロパティを更新し、saveでモデルをデータベースへ保存します。Scoutは自動的に変更を検索インデックスへ保存します。To update a searchable model, you only need to update the model instance's properties and save the model to your database. Scout will automatically persist the changes to your search index:

$order = App\Order::find(1);

// 注文を更新…

$order->save();

モデルのコレクションを更新するためにも、Eloquentクエリのsearchableメソッドを使用します。検索エンジンにモデルが存在していない場合は、作成します。You may also use the searchable method on an Eloquent query to update a collection of models. If the models do not exist in your search index, they will be created:

// Eloquentクエリによる更新
App\Order::where('price', '>', 100)->searchable();

// リレーションによる更新も可能
$user->orders()->searchable();

// コレクションによる更新も可能
$orders->searchable();

レコード削除Removing Records

インデックスからレコードを削除するには、データベースからモデルをdeleteで削除するだけです。この形態による削除は、モデルのソフト削除と互換性があります。To remove a record from your index, simply delete the model from the database. This form of removal is even compatible with soft deleted[/docs/{{version}}/eloquent#soft-deleting] models:

$order = App\Order::find(1);

$order->delete();

レコードを削除する前に、モデルを取得したくない場合は、Eloquentクエリインスタンスかコレクションに対し、unsearchableメソッドを使用します。If you do not want to retrieve the model before deleting the record, you may use the unsearchable method on an Eloquent query instance or collection:

// Eloquentクエリによる削除
App\Order::where('price', '>', 100)->unsearchable();

// リレーションによる削除も可能
$user->orders()->unsearchable();

// コレクションによる削除も可能
$orders->unsearchable();

インデックスの一時停止Pausing Indexing

Eloquentモデルをバッチ処理するが、検索インデックスへモデルデータを同期したくない場合も時々あります。withoutSyncingToSearchメソッドを使用することで可能です。このメソッドは、即時に実行されるコールバックを１つ引数に取ります。コールバック中のモデル操作は、インデックスへ同期されることはありません。Sometimes you may need to perform a batch of Eloquent operations on a model without syncing the model data to your search index. You may do this using the withoutSyncingToSearch method. This method accepts a single callback which will be immediately executed. Any model operations that occur within the callback will not be synced to the model's index:

App\Order::withoutSyncingToSearch(function () {
    // モデルアクションの実行…
});

検索Searching

searchメソッドにより、モデルの検索を開始しましょう。searchメソッドはモデルを検索するために使用する文字列だけを引数に指定します。getメソッドを検索クエリにチェーンし、指定した検索クエリに一致するEloquentモデルを取得できます。You may begin searching a model using the search method. The search method accepts a single string that will be used to search your models. You should then chain the get method onto the search query to retrieve the Eloquent models that match the given search query:

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

Scoutの検索ではEloquentモデルのコレクションが返されるため、ルートやコントローラから直接結果を返せば、自動的にJSONへ変換されます。Since Scout searches return a collection of Eloquent models, you may even return the results directly from a route or controller and they will automatically be converted to JSON:

use Illuminate\Http\Request;

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

Where節Where Clauses

Scoutは検索クエリに対して"WHERE"節を単に追加する方法も提供しています。現在、この節としてサポートしているのは、基本的な数値の一致を確認することだけで、主にIDにより検索クエリを絞り込むために使用します。検索インデックスはリレーショナル・データベースではないため、より上級の"WHERE"節は現在サポートしていません。Scout allows you to add simple "where" clauses to your search queries. Currently, these clauses only support basic numeric equality checks, and are primarily useful for scoping search queries by a tenant ID. Since a search index is not a relational database, more advanced "where" clauses are not currently supported:

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

ペジネーションPagination

コレクションの取得に付け加え、検索結果をpaginateメソッドでページづけできます。このメソッドは、Paginatorインスタンスを返しますので、Eloquentクエリのペジネーションと同様に取り扱えます。In addition to retrieving a collection of models, you may paginate your search results using the paginate method. This method will return a Paginator instance just as if you had paginated a traditional Eloquent query[/docs/{{version}}/pagination]:

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

paginateメソッドの第１引数として、各ページごとに取得したいモデル数を指定します。You may specify how many models to retrieve per page by passing the amount as the first argument to the paginate method:

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

結果が取得できたら、通常のEloquentクエリのペジネーションと同様に、結果を表示し、Bladeを使用してページリンクをレンダーできます。Once you have retrieved the results, you may display the results and render the page links using Blade[/docs/{{version}}/blade] just as if you had paginated a traditional Eloquent query:

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

{{ $orders->links() }}

カスタムエンジンCustom Engines

エンジンのプログラミングWriting The Engine

組み込みのScout検索エンジンがニーズに合わない場合、独自のカスタムエンジンを書き、Scoutへ登録してください。エンジンは、Laravel\Scout\Engines\Engine抽象クラスを拡張してください。この抽象クラスは、カスタムエンジンが実装する必要のある、５つのメソッドを持っています。If one of the built-in Scout search engines doesn't fit your needs, you may write your own custom engine and register it with Scout. Your engine should extend the Laravel\Scout\Engines\Engine abstract class. This abstract class contains five methods your custom engine must implement:

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 map($results, $model);

これらのメソッドの実装をレビューするために、Laravel\Scout\Engines\AlgoliaEngineクラスが役に立つでしょう。このクラスは独自エンジンで、各メソッドをどのように実装すればよいかの、良い取り掛かりになるでしょう。You may find it helpful to review the implementations of these methods on the Laravel\Scout\Engines\AlgoliaEngine class. This class will provide you with a good starting point for learning how to implement each of these methods in your own engine.

エンジンの登録Registering The Engine

カスタムエンジンを書いたら、Scoutエンジンマネージャのextendメソッドを使用し、Scoutへ登録します。AppServiceProviderかアプリケーションで使用している他のサービスプロバイダーのbootメソッドで、extendメソッドを呼び出してください。たとえば、MySqlSearchEngineを書いた場合、次のように登録します。Once you have written your custom engine, you may register it with Scout using the extend method of the Scout engine manager. You should call the extend method from the boot method of your AppServiceProvider or any other service provider used by your application. For example, if you have written a MySqlSearchEngine, you may register it like so:

use Laravel\Scout\EngineManager;

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function boot()
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

エンジンが登録できたら、Scoutのデフォルトdriverとして、config/scout.php設定ファイルで設定します。Once your engine has been registered, you may specify it as your default Scout driver in your config/scout.php configuration file:

'driver' => 'mysql',