Download the PHP package fadion/bouncy without Composer
On this page you can find all versions of the php package fadion/bouncy. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download fadion/bouncy
More information about fadion/bouncy
Files in fadion/bouncy
Package bouncy
Short Description Map Elasticsearch results to Eloquent models
License MIT
Informations about the package bouncy
To use it in Laravel 5, please see the
l5
branch.
Bouncy
Elasticsearch is a great search engine, but it takes some work to transform its results to an easy to use dataset. Bouncy does exactly that: it maps Elasticsearch results to Eloquent models, so you can keep using the same logic with some special enhancements. In addition, it handles indexing, either manually or automatically on model creation, update or deletion.
This package was created for a personal project and it's still a work in progress. I don't expect it's API to change however.
I was inspired and most of the implementation is based on Elasticquent. Basically, it's a rewritten fork of that package. Kudos to the developers.
Table of Contents
- Installation
- Setting Up
- Indexes
- Indexing
- Updating Indexes
- Removing Indexes
- Re-indexing
- Concurrency Control
- Automatic Indexes
- Mappings
- Searching
- Pagination
- Limit
- Results Information
- Document Information
- Highlights
- Searching Shorthands
- Customizing Document Fields
- Custom Collection
- Elasticsearch Client Facade
Installation
-
Add the package to your
composer.json
file and runcomposer update
: -
Add the service provider to your
app/config/app.php
file, inside theproviders
array:'Fadion\Bouncy\BouncyServiceProvider'
-
Publish the config file by running the following command in the terminal:
php artisan config:publish fadion/bouncy
- Edit the config files (located in
app/config/packages/bouncy/
) and set the Elasticsearch index name, server configuration, etc.
Setting Up
There's only one step to tell your models that they should use Bouncy. Just add a trait! I'll be using a fictional Product
model for the examples.
Index and Type Name
The index can be set in the configuration file, while the type name is retrieved automatically from the model's table name. This is generally a good way to structure your documents, as you configure it once and forget about it.
When you need to set the index or type name specifically, just add the following attributes to your models:
Indexing
Before doing any search query, Elasticsearch needs an index to work on. What's normally a tedious task, is rendered as easy as it gets.
Index all records:
Index a collection of models:
Index an individual model:
Collection indexes will be added in bulk, which Elasticsearch handles quite fast. However, keep in mind that indexing a big collection is an exhaustive process. Hitting the SQL database and iterating over each row needs time and resources, so try to keep the collection relatively small. You'll have to experiment with the number of data you can index at a time, depending on your server resources and configuration.
Updating Indexes
Updating is the safe way, in version conflict terms, to reindex an existing document. When the model exists and any of it's attributes have changed, it's index will be updated. Otherwise, it will be added to the index as if calling the index()
method.
Updating a model's index:
Updating a model's index using custom attributes. There are few use cases for this, as it's preferable to keep models and indexes in sync, but it's there when needed.
Removing Indexes
When you're done with a model's index, obviously you can remove it.
Removing the indexes of a collection:
Removing the index of a single model:
The method is intentionally called 'remove' instead of 'delete', so you don't mistake it with Eloquent's delete() method.
Re-indexing
A convenience method that actually removes and adds the index again. It is most useful when you want a document to get a fresh index, resetting version information.
Reindexing a collection:
Reindexing a single model:
Concurrency Control
Elasticsearch assumes that no document conflict will arise during indexing and as such, it doesn't provide automatic concurrency control. However, it does provide version information on documents that can be used to ensure that an older document doesn't override a newer one. This is the suggested technique described in the manual.
Bouncy provides a single method for indexing by checking the version. It will only update the index if the version specified matches the one in the document, or return false otherwise. Obviously, it is concurrency-safe.
Automatic Indexes
Bouncy knows when a model is created, saved or deleted and it will reflect those changes to the indexes. Except for the initial index creation of an existing database, you'll generally won't need to use the above methods to manipulate indexes. Any new model's index will be added automatically, will be updated on save and removed when the model is deleted.
You can disable automatic indexes altogether by setting the auto_index
config option to false
. Doing so, it is up to you to sync your database to the index.
The only cases where Bouncy can't update or delete indexes are when doing mass updates or deletes. Those queries run directly on the query builder and it's impossible to override them. I'm investigating for a good way of doing this, but for now, the following queries don't reflect changes on indexes:
You can still call the indexing methods manually and work the limitation. It will add an extra database query, but at least it will keep your data in sync.
Mappings
Mappings can be created as easily as anything you've seen until now. They are defined as a class property of a model and handled using some simple methods.
Add mapping properties to a model:
Put those mappings:
Get mappings:
Delete mappings:
Rebuild (delete and put again) mappings:
Check if mappings exist:
Searching
Now on the real deal! Searching is where Elasticsearch shines and why you're bothering with it. Bouncy doesn't get in the way, allowing you to build any search query you can imagine in exactly the same way you do with Elasticsearch's client. This allows for great flexibility, while providing your results with a collection of Eloquent models.
An example match query:
The $params
array is exactly as Elasticsearch expects for it to build a JSON request. Nothing new here! You can easily build whatever search query you want, be it a match, multi_match, more_like_this, etc.
Pagination
Paginated results are important in an application and it's generally a pain with raw Elasticsearch results. Another good reason for using Bouncy! It paginates results in exactly the same way as Eloquent does, so you don't have to learn anything new.
Paginate to 15 models per page (default):
Paginate to an arbitrary number:
In your views, you can show pagination links exactly as you've done before:
Limit
For performance, limiting your search results should be done on the Elasticsearch parameter list with the size
keyword. However, for easy limiting, Bouncy provides that functionality.
Limit to 50 results:
Results Information
Elasticsearch provides some information for the query, as the total number of hits or time taken. Bouncy's results collections have methods for easily accessing that information.
Document Information
Elasticsearch documents have some information such as score and version. You can access those data using the following methods:
Highlights
Highlights are a nice visual feature to enhance your search results. Bouncy makes it really easy to access the highlighted fields.
The highlight()
method will access any highlighted field with the provided name or fail silently (actually, returns false) if it doesn't find one.
Searching Shorthands
Having flexibility and all is great, but there are occassions when you just need to run a simple match query and get the job done, without writting a full parameters array. Bouncy offers some shorthand methods for the most common search queries. They work and handle results in the same way as search()
does, so all of the above applies to them too.
match query:
multi_match query:
fuzzy query:
geoshape query:
ids query:
more_like_this query
Customizing Document Fields
Bouncy will use your model's attributes while indexing and that should be fine for most cases. However, if you want to have control over the Elasticsearch documents structure, you can customize the fields by adding a $documentFields
method to your model:
Custom Collection
If you are using a custom collection for Eloquent, you can still keep using Bouncy's methods. You'll just need to add a trait to your collection class.
Elasticsearch Client Facade
Finally, when you'll need it, you can access Elasticsearch's native client in Laravel fashion using a Facade. For this step to work, you'll need to add an alias in app/config/app.php
in the aliases array: 'Elastic' => 'Fadion\Bouncy\Facades\Elastic'
.
All versions of bouncy with dependencies
illuminate/support Version 4.2.*
illuminate/database Version 4.2.*
elasticsearch/elasticsearch Version ~1.0