spatie/searchindex

Store and retrieve objects from Elasticsearch or Algolia

, _(*1)

Store and retrieve objects from a search index

, _(*2)

This is an opinionated Laravel 5.1 package to store and retrieve objects from a search index. Currently Elasticsearch and Algolia are supported., _(*3)

Once the package is installed objects can be easily indexed and retrieved:, _(*4)

//$product is an object that implements the Searchable interface
SearchIndex::upsertToIndex($product);

SearchIndex::getResults('look for this');

Spatie is a webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website., _(*5)

Support us

Learn how to create a package like this one, by watching our premium video course:, _(*6)

, _(*7)

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products., _(*8)

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall., _(*9)

Postcardware

You're free to use this package (it's MIT-licensed), but if it makes it to your production environment you are required to send us a postcard from your hometown, mentioning which of our package(s) you are using., _(*10)

Our address is: Spatie, Kruikstraat 22, 2018 Antwerp, Belgium., _(*11)

The best postcards will get published on the open source page on our website., _(*12)

Installation

This package can be installed through Composer., _(*13)

composer require spatie/searchindex

You must install this service provider., _(*14)

// config/app.php
'providers' => [
    ...
    Spatie\SearchIndex\SearchIndexServiceProvider::class,
];

This package also comes with a facade, which provides an easy way to call the the class., _(*15)

// config/app.php
'aliases' => [
    ...
    'SearchIndex' => Spatie\SearchIndex\SearchIndexFacade::class,
]

You can publish the config-file with:, _(*16)

php artisan vendor:publish --provider="Spatie\SearchIndex\SearchIndexServiceProvider"

The options in the config file are set with sane default values and they should be self-explanatory., _(*17)

The next installation steps depend on if you want to use Elasticsearch or Algolia., _(*18)

Elasticsearch

To use Elasticsearch you must install the official 1.x series low level client:, _(*19)

composer require elasticsearch/elasticsearch "^1.3"

You also should have a server with Elasticsearch installed. If you want to install it on your local development machine you can use these instructions from the excellent Vaprobash repo., _(*20)

Algolia

To use Algolia you must install the official low level client:, _(*21)

composer require algolia/algoliasearch-client-php

Usage

Prepare your object

Objects that you want to store in the index should implement the provided Spatie\SearchIndex\Searchable- interface., _(*22)

namespace Spatie\SearchIndex;

interface Searchable {

    /**
     * Returns an array with properties which must be indexed
     *
     * @return array
     */
    public function getSearchableBody();

    /**
     * Return the type of the searchable subject
     *
     * @return string
     */
    public function getSearchableType();

    /**
     * Return the id of the searchable subject
     *
     * @return string
     */
    public function getSearchableId();

Here is an example how you could implement it with an Eloquent model:, _(*23)

class Product extends Eloquent implements Searchable
{

    ...

    /**
     * Returns an array with properties which must be indexed
     *
     * @return array
     */
    public function getSearchableBody()
    {
        $searchableProperties = [
            'name' => $this->name,
            'brand' => $this->brand->name,
            'category' => $this->category->name
        ];

        return $searchableProperties;

    }

    /**
     * Return the type of the searchable subject
     *
     * @return string
     */
    public function getSearchableType()
    {
        return 'product';
    }

    /**
     * Return the id of the searchable subject
     *
     * @return string
     */
    public function getSearchableId()
    {
        return $this->id;
    }
}

The searchindex will use the returned searchableType and searchableId to identify an object in the index., _(*24)

Add an object to the index

If you are using the facade it couldn't be simpler., _(*25)

//$product is an object that implements the Searchable interface

SearchIndex::upsertToIndex($product);

Update an object in the index

You probably would have guessed it., _(*26)

//$product is an object that implements the Searchable interface

SearchIndex::upsertToIndex($product);

Remove an object from the index

Yep. Easy., _(*27)

//$product is an object that implements the Searchable interface

SearchIndex::removeFromIndex($product);

Alternatively you can remove an object from the index by passing type and id:, _(*28)

SearchIndex::removeFromIndexByTypeAndId('product', 1);

This can be handy when you've already deleted your model., _(*29)

Clear the entire index

If only you could to this with your facebook account., _(*30)

SearchIndex::clearIndex();

Perform a search on the index

You can retrieve search results with this method:, _(*31)

SearchIndex::getResults($query);

Elasticsearch

$query should be an array that adheres to the scheme provided by the elasticsearch documentation., _(*32)

A query to perform a fuzzy like search that operates all fields of the index could look like this:, _(*33)

$query =
    [
        'body' =>
            [
                'from' => 0,
                'size' => 500,
                'query' =>
                    [
                        'fuzzy_like_this' =>
                            [
                                '_all' =>
                                    [
                                        'like_text' => 'look for this',
                                        'fuzziness' => 0.5,
                                    ],
                            ],
                    ],
            ]
    ];

The search results that come back are simply elasticsearch response elements serialized into an array. You can see an example of a response in the official elasticsearch documentation., _(*34)

Algolia

You can just pass a string to search the index:, _(*35)

SearchIndex::getResults('look for this');

To perform more advanced queries an array may be passed. Read the official documentation to learn what's possible., _(*36)

All other operations

For all other operations you can get the underlying client:, _(*37)

SearchIndex::getClient(); // will return the Elasticsearch or Algolia client.

Query helpers

If you're using Algolia you can use a SearchQuery-object to perform searches., _(*38)

use Spatie\SearchIndex\Query\Algolia\SearchIndex();

$searchQuery = new SearchQuery();
$searchQuery->searchFor('my query')
            ->withFacet('facetName', 'facetValue');

//a searchQuery object may be passed to the getResults-function directly.
SearchIndex::getResults($searchQuery);

Tests

This package comes with a set of unit tests. Every time the package gets updated Travis CI will automatically run them., _(*39)

You can also run them manually. You'll have first run composer install --dev to install phpspec. After that's out of the way you can run the tests with vendor/bin/phpspec run., _(*40)

Contributing

Please see CONTRIBUTING for details., _(*41)

Security

If you discover any security related issues, please email security@spatie.be instead of using the issue tracker., _(*42)

Credits

• Freek Van der Herten
• All Contributors

About Spatie

Spatie is a webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website., _(*43)