README

Development branch:

Elodex provides an easy way to implement synchronization of your Laravel Eloquent models with an Elasticsearch index.

Your Eloquent database will remain your main data source while you can use the full capacity of Elasticsearch for any index based search on your models.

Requirements
Branching Model
Installation
Laravel Integration
- Configuration
- Extending your Eloquent Model Classes
Index Repositories
Elasticsearch Client
Documentation
Changelog
License

Requirements

Elodex requires Elasticsearch 2.0 or higher, PHP v5.6+ and Laravel 5.1+.

Besides the technical requirements you should have a profound knowledge of Eloquent and you should be familiar with the basic Elasticsearch terms and how Elasticsearch works in general.

Branching Model

This project uses the Gitflow branching model:

the master branch contains the latest stable version
the develop branch contains the latest unstable development version
all stable versions are tagged using semantic versioning

Installation

Elodex can be directly added to your project via Composer:

$ composer require "elodex/elodex=~1.0"

Or you can manually add the required entry to your composer.json file in the require section :

"require": {
  "elodex/elodex": "~1.0"
}

Laravel Integration

To integrate Elodex into your Laravel application you first need to add the IndexServiceProvider to the list of service providers in the application configuration.

This can be done by editing the app.php file in the config folder. Search for the providers section and add a new entry:

  /*
    |--------------------------------------------------------------------------
    | Autoloaded Service Providers
    |--------------------------------------------------------------------------
    |
  */
  'providers' => [
    ...
    \Elodex\IndexServiceProvider::class,
  ],

Configuration

Even though Elodex does ship with a default configuration which should work for standard Elasticsearch installations you usually want to specify your own settings. You can do so by publishing the standard config file to your application:

$ php artisan vendor:publish --provider="Elodex\IndexServiceProvider"

This will copy a standard config to config/elodex.php. Make sure your Elasticsearch host configuration is correct and that you specify a default index name for your application which will be used for all your indexed Eloquent models by default.

  /*
    |--------------------------------------------------------------------------
    | Default Index Name
    |--------------------------------------------------------------------------
    |
  */
  'default_index' => 'my_app_index',

Extending your Eloquent Model Classes

There are two possibilities to add indexing capabilities to your Eloquent model classes.

1. Using the IndexedModel Trait

To add the basic indexing functionality to your existing Eloquent models you can include the IndexedModel trait which automatically implements the needed Contracts\IndexedModel interface for you.

<?php

namespace App;

use Illuminate\Database\Eloquent\Model as BaseModel;
use Elodex\Contracts\IndexedModel as IndexedModelContract;
use Elodex\IndexedModel as IndexedModelTrait;

class Model extends BaseModel implements IndexedModelContract
{
    use IndexedModelTrait;

Note that the trait implements the newCollection method. You must make sure your Eloquent class doesn't overwrite this method, otherwise you're going to lose the convenient way to use indexing operations on the collections returned by model queries.

The IndexedModel trait does three things for you:

it implements the Contracts\IndexedModel interface and thus makes the model capable of being added to an index repository.
it adds a convenient way to access the default index manager and the default index repository for your model class.
it adds the methods to interact with the index repository. This includes adding your model instances to the index repository, removing them and performing an index based search.

2. Deriving from the Elodex Model Class

Deriving from the abstract Elodex Model class is a better approach than the trait if your existing model directly inherits from the Eloquent base model class. It gives you the possibility to override and thus extend the existing methods added by the IndexedModel trait without having to rewrite them completely.

A common use case would be if you want to change the document creation of your model.

Index Repositories

All indexed model documents are managed in a repository with the type IndexRepository. Each model class has its own default index repository using its own type in the index.

This means you can't share an index repository with different model classes, trying to do so will result in exceptions during runtime.

The default index repository used for a class can be accessed through the getClassIndexRepository static method.

$repository = User::getClassIndexRepository();

There's usually no need to access the index repository directly since the indexed model classes provide a more convenient method to manage the repository entries.

Elasticsearch Client

Elodex uses the official PHP low-level client for Elasticsearch. There's usually no need to access this client directly but Elodex makes a client instance globally available in case you need to perform some custom or raw queries.

$client = app('elodex.client');

You may also use dependency injection with the ElasticsearchClientManager class to get a client instance.

Documentation

A detailed Elodex documentation can be found here.

Changelog

The changelog can be found here.

License

Elodex is an open source project licensed under the the MIT license. Please see the License File for further information.

elodex / elodex

Maintainers

Details