Laravel-Elasticsearch-Handlers

An even easier way to use the official Elastic Search client in your Laravel applications.

• Installation and Configuration
• Usage
• Creating Handlers
  • Special boot Method
• Pre-Defined Handlers
  • EnvironmentIndexPrefixHandler
• Bugs, Suggestions and Contributions
• Copyright and License

Installation and Configuration

1. Install the cviebrock/laravel-elasticsearch-handlers package via composer:

   $ composer require cviebrock/laravel-elasticsearch-handlers
   

2. Publish the configuration file. For Laravel 5:

   php artisan vendor:publish cviebrock/laravel-elasticsearch-handlers
   

   In order to make this package also work with Laravel 4, we can't do the standard configuration publishing like most Laravel 4 packages do. You will need to simply copy the configuration file into your application's configuration folder:

   cp vendor/cviebrock/laravel-elasticsearch-handlers/config/elasticsearch-handlers.php app/config/
   

3. Add the service provider (config/app.php for Laravel 5 or app/config/app.php for Laravel 4). The service provider needs to come after the LaravelElasticsearch provider, since we "hijack" the Manager class from that package and use our own.

   'providers' => array(
       ...
       'Cviebrock\LaravelElasticSearch\ServiceProvider',
       'Cviebrock\LaravelElasticSearchHandlers\ServiceProvider',
   )
   

Usage

This package extends the laravel-elasticsearch package by returning a "decorated" Elasticsearch client class, instead of the default PHP client. You can configure how the client is decorated on a per-connection basis.

Take the following example elasticsearch-handlers.php configuration:

<?php

return [
	'connections' => [
    	'default' => [
			'clientClass' => 'Cviebrock\LaravelElasticsearchHandlers\Client',
			'handlers' => []
		]
	]
];

When you instantiate an Elasticsearch client with:

$client = Elasticsearch::connection('default');

the package will create a base client (using the base elasticsearch.php configuration) then wrap it in the class defined by the clientClass setting, and inject the handlers array. So, in this case, an instance of Cviebrock\LaravelElasticsearchHandlers\Client is returned.

This class the bare minimum client wrapper. It doesn't do anything except pass-through all commands to the wrapped base Elasticsearch class.

Let's make it more useful ...

Creating Handlers

Pretend you only have one Elasticsearch instance running, but you need it to support indices for several of your Laravel application environments (e.g. "beta", "live", etc.)..

Instead of updating your code so that every time you index a document you make sure the right index name is specified, what if the client automatically prefixed the index name with the name of the current Laravel environment?

First, set up the package configuration like so:

return [

	'defaultClass' => 'Cviebrock\LaravelElasticsearchHandlers\Client',

	'connections' => [
		'default' => [
			'MyEnvironmentIndexPrefixHandler'
		]

	]

];

Then create the Handler class (extending the BaseHandler class):

class MyEnvironmentIndexPrefixHandler extends Cviebrock\LaravelElasticsearchHandlers\Handlers\BaseHandler {

	/**
	 * Auto-prefix the document index name with the current Laravel
	 * environment.
	 * 
	 * @param array $parameters
	 * @return array
	 */
	public function handleIndex($parameters) {

		if ($index = array_get($parameters, 'index')) {
			$environment = mb_strtolower(preg_replace('/[^a-z0-9_\-]+/', '-', \App::environment()));
			$parameters['index'] = trim($environment, '-') . '-_' . $index;
		}

		return $parameters;
	}
}

Now, every time you index a document using the default Elasticsearch connection, the current Laravel environment name will be prefixed to the index key of your data array.

$data = [
    'index' => 'my-index',
    'type' => 'my-doctype',
    'body' => [
        'content' => 'Lorem ipsum',
    ]
];
$return = Elasticsearch::index($data);

This returns:

array (size=5)
  '_index' => string 'local-my-index' (length=14)
  '_type' => string 'my-doctype' (length=10)
  '_id' => string 'AU3U9R3kOpwouG512345' (length=20)
  '_version' => int 1
  'created' => boolean true

The index was prepended automatically, so your application will work across all environments without checks or changes.

Also, you can register more than one handler per connection, which means that the functionality is "chainable". E.g., prepend the environment to the index, and also add some default parameters to the body, etc..

Special boot Method

Handlers can also define a boot method with the following signature:

public function boot(\Cviebrock\LaravelElasticsearchHandlers\Client $client) {}

This is method is run when the handler is registered so it could be used, for example, to alter the behaviour of the client upon instantiation. The client is passed in as the only parameter.

Pre-Defined Handlers

The package ships with a few pre-defined handlers, all of which are in the Cviebrock\LaravelElasticsearchHandlers\Handlers namespace.

EnvironmentIndexPrefixHandler

Operates on the follow methods:

• index

This is basically the same handler as used in the example above. It will take the current Laravel environment, mangles it a bit so it matches Elasticsearch's constraints for index names, and prepends it to the index key in the given document.

Bugs, Suggestions and Contributions

Please use Github for bugs, comments, suggestions.

1. Fork the project.
2. Create your bugfix/feature branch and write your (well-commented) code.
3. Commit your changes (and your tests) and push to your branch.
4. Create a new pull request against the master branch.

Copyright and License

Laravel-Elasticsearch-Handlers was written by Colin Viebrock and released under the MIT License. See the LICENSE file for details.

Copyright 2015 Colin Viebrock