README

Unified search for Laravel models using Elasticsearch. Laravel Hunt uses the official Elasticsearch PHP API. To get started, you should have a basic knowledge of how Elasticsearch works (indexes, types, mappings, etc).

Elasticsearch Requirements

You must be running Elasticsearch 5.0 or higher.

Installation

Composer

From the command line run:

$ composer require torann/laravel-hunt

Laravel

Once installed you need to register the service provider with the application. Open up config/app.php and find the providers key.

'providers' => [

    LaravelHunt\LaravelHuntServiceProvider::class,

]

Lumen

For Lumen register the service provider in bootstrap/app.php.

$app->register(LaravelHunt\LaravelHuntServiceProvider::class);

Publish the configurations

Run this on the command line from the root of your project:

$ php artisan vendor:publish --provider="LaravelHunt\LaravelHuntServiceProvider" --tag=config

A configuration file will be publish to config/hunt.php.

Indexes and Mapping

While you can definitely build your indexes and mapping through the Elasticsearch API, you can also use some helper methods to build indexes and types right from your models.

For custom analyzer, you can set an settings property in the config/hunt.php file:

[
    'settings' => [
         'number_of_shards' => 1,
         'analysis' => [
             'filter' => [
                 'autocomplete_filter' => [
                     'type' => 'edge_ngram',
                     'min_gram' => 1,
                     'max_gram' => 20,
                 ],
             ],
             'analyzer' => [
                 'autocomplete' => [
                     'type' => 'custom',
                     'tokenizer' => 'standard',
                     'filter' => [
                         'lowercase',
                         'autocomplete_filter',
                     ],
                 ],
             ],
         ],
     ],
]

For mapping, you can set a mappingProperties property in your model and use some mapping functions from there:

protected $mappingProperties = [
   'title' => [
        'type' => 'string',
        'analyzer' => 'standard'
    ]
];

Artisan Commands

hunt:install

Create the Elasticsearch index.

hunt:uninstall

Remove the Elasticsearch index.

hunt:map <model>

Initialize an Eloquent model map.

Arguments:

 model               Name or comma separated names of the model(s) to initialize

hunt:import <model>

Import all the entries in an Eloquent model. This will also initialize the model's map if one is not already set.

Arguments:

 model               Name or comma separated names of the model(s) to index

hunt:flush <model>

Flush all of the model's records from the index.

Arguments:

 model               Name or comma separated names of the model(s) to index

Indexing

Once you have added the LaravelHunt\Huntable trait to a model, all you need to do is save a model instance and it will automatically be added to your index.

$post = new App\Post;

// ...

$post->save();

Note: if the model record is already in your index, it will be updated. If it does not exist in the index, it will be added.

Updating Records

To update an index model, you only need to update the model instance's properties and `save`` the model to your database. Hunt will automatically persist the changes to your search index:

$post = App\Post::find(1);

// Update the post...

$post->save();

Removing Records

To remove a record from your index, simply delete the model from the database. This form of removal is even compatible with soft deleted models:

$post = App\Post::find(1);

$post->delete();

Searching

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:

$posts = App\Post::search('Kitten fluff')->get();

Since Hunt 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\Post::search($request->search)->get();
});

Pagination

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:

$posts = App\Post::search('Kitten fluff')->paginate();

You may specify how many models to retrieve per page by passing the amount as the first argument to the paginate method:

$posts = App\Post::search('Kitten fluff')->paginate(15);

Once you have retrieved the results, you may display the results and render the page links using Blade just as if you had paginated a traditional Eloquent query:

<div class="container">
    @foreach ($posts as $post)
        {{ $post->title }}
    @endforeach
</div>

{{ $posts->links() }}

Multilingual

This feature is experimental

Laravel Hunt can support multiple languages by appending the language code to the index type, so when the system performs a search it will only look for data that is on in the current system locale suffixed index type. For this to work the model needs to use the LaravelHunt\Localized trait or something similar to it and model needs to have the filed locale.

For more information see the config file for more details.