Store and retrieve objects from a search index

EOL-warning

This package has been abandoned on 2016-08-27. Please use Laravel Scout instead.

This is an opinionated Laravel 5.1 package to store and retrieve objects from a search index. Currently Elasticsearch and Algolia are supported.

Once the package is installed objects can be easily indexed and retrieved:

//$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.

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.

Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.

The best postcards will get published on the open source page on our website.

Installation

This package can be installed through Composer.

composer require spatie/searchindex

You must install this service provider.

// 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.

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

You can publish the config-file with:

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.

The next installation steps depend on if you want to use Elasticsearch or Algolia.

###Elasticsearch To use Elasticsearch you must install the official 1.x series low level client:

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.

###Algolia To use Algolia you must install the official low level client:

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.

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:

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.

###Add an object to the index If you are using the facade it couldn't be simpler.

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

SearchIndex::upsertToIndex($product);

###Update an object in the index You probably would have guessed it.

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

SearchIndex::upsertToIndex($product);

###Remove an object from the index Yep. Easy.

//$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:

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

This can be handy when you've already deleted your model.

###Clear the entire index If only you could to this with your facebook account.

SearchIndex::clearIndex();

###Perform a search on the index You can retrieve search results with this method:

SearchIndex::getResults($query);

####Elasticsearch $query should be an array that adheres to the scheme provided by the elasticsearch documentation.

A query to perform a fuzzy like search that operates all fields of the index could look like this:

$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.

####Algolia You can just pass a string to search the index:

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

To perform more advanced queries an array may be passed. Read the official documentation to learn what's possible.

###All other operations For all other operations you can get the underlying client:

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.

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.

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.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

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.