Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/spatie/searchindex
Store and retrieve objects from Algolia or Elasticsearch
https://github.com/spatie/searchindex
Last synced: 6 days ago
JSON representation
Store and retrieve objects from Algolia or Elasticsearch
- Host: GitHub
- URL: https://github.com/spatie/searchindex
- Owner: spatie
- License: mit
- Created: 2015-01-15T16:41:31.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2022-03-21T15:17:58.000Z (almost 3 years ago)
- Last Synced: 2024-08-30T18:51:38.296Z (4 months ago)
- Language: PHP
- Homepage: https://murze.be/2015/08/using-algolia-in-laravel/
- Size: 89.8 KB
- Stars: 443
- Watchers: 23
- Forks: 48
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-laravel-framework - SearchIndex - Store and retrieve objects from Algolia or Elasticsearch (Popular Packages)
- laravel-awesome - SearchIndex - Store and retrieve objects from Algolia or Elasticsearch (Popular Packages)
- awesome-laravel - SearchIndex - Store and retrieve objects from Algolia or Elasticsearch (Popular Packages)
README
[
](https://supportukrainenow.org)
Store and retrieve objects from a search index
=================
[](https://github.com/spatie/searchindex/releases)
[](LICENSE.md)
[](https://travis-ci.org/spatie/searchindex)
[](https://scrutinizer-ci.com/g/spatie/searchindex)
[](https://styleci.io/repos/29306962)
[](https://packagist.org/packages/spatie/searchindex)
This is an opinionated Laravel 5.1 package to store and retrieve objects from a search index.
Currently [Elasticsearch](http://www.elasticsearch.org) and [Algolia](https://www.algolia.com) are supported.
Once the package is installed objects can be easily indexed and retrieved:
```php
//$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](https://spatie.be/opensource).
## Support us
Learn how to create a package like this one, by watching our premium video course:
[](https://laravelpackage.training)
We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
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](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).
## Postcardware
You're free to use this package (it's [MIT-licensed](LICENSE.md)), 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, Kruikstraat 22, 2018 Antwerp, Belgium.
The best postcards will get published on the open source page on our website.
## Installation
This package can be installed through Composer.
```bash
composer require spatie/searchindex
```
You must install this service provider.
```php
// 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.
```php
// config/app.php
'aliases' => [
...
'SearchIndex' => Spatie\SearchIndex\SearchIndexFacade::class,
]
```
You can publish the config-file with:
```bash
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:
```bash
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](https://github.com/fideloper/Vaprobash/blob/master/scripts/elasticsearch.sh)
from the excellent [Vaprobash repo](https://github.com/fideloper/Vaprobash).
### Algolia
To use Algolia you must install the official low level client:
```bash
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.
```php
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:
```php
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.
```php
//$product is an object that implements the Searchable interface
SearchIndex::upsertToIndex($product);
```
### Update an object in the index
You probably would have guessed it.
```php
//$product is an object that implements the Searchable interface
SearchIndex::upsertToIndex($product);
```
### Remove an object from the index
Yep. Easy.
```php
//$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:
```php
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.
```php
SearchIndex::clearIndex();
```
### Perform a search on the index
You can retrieve search results with this method:
```php
SearchIndex::getResults($query);
```
#### Elasticsearch
```$query``` should be an array that adheres to the scheme provided
by [the elasticsearch documentation](http://www.elasticsearch.org/guide/en/elasticsearch/client/php-api/current/_search_operations.html).
A query to perform a fuzzy like search that operates all fields of the index could
look like this:
```php
$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](http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html)
in the official elasticsearch documentation.
#### Algolia
You can just pass a string to search the index:
```php
SearchIndex::getResults('look for this');
```
To perform more advanced queries an array may be passed. Read
the [official documentation](https://github.com/algolia/algoliasearch-client-php#search) to learn what's possible.
### All other operations
For all other operations you can get the underlying client:
```php
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.
```php
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](https://travis-ci.org) 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](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.
## Security
If you discover any security related issues, please email [[email protected]](mailto:[email protected]) instead of using the issue tracker.
## Credits
- [Freek Van der Herten](https://github.com/freekmurze)
- [All Contributors](../../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](https://spatie.be/opensource).