Sherlock's requirements are fairly minimal, and easily installed if you use composer:

• PHP >= 5.3
• ElasticSearch (no surprise here!)
• Composer

If you don't wish to use Composer, you will have to manually download and install several dependencies:

• Analog (Version 1.0.2-stable)
• Symfony EventDispatcher (Version >= 2.1, < 3.0)

We highly recommend installation through Composer.

Composer makes installation super easy, automatically managing dependencies and version numbers. Since Sherlock is still in alpha state, the library updates very rapidly and may abruptly change dependencies, dependency versions or both. Composer manages all of this with a single command.

To get started, create a composer.json file in your project's root directory (or add to it, if you already have a composer file). Add this to composer.json

{
    "require": {
        "sherlock/sherlock": "~0.1"
    }
}

This instructs Composer to download a version of Sherlock that is >= 0.1 and < 1.0. Although not terribly useful right now since Sherlock is still alpha, this scheme will become important when Sherlock reaches a 1.0 state and maintains strict semantic versioning.. Next, install Composer:

curl -s http://getcomposer.org/installer | php

This downloads and installs a composer.phar file into your root directory. You can install Composer globally, but a local version is usually easier to work with. Finally, install Sherlock:

php composer.phar install

You'll see Composer print out a number of lines detailing the download progress. When Composer finishes, you'll notice that a new /vendor/ folder has been added to your root directory. This is where Sherlock (and dependencies) live.

Now that Sherlock has been downloaded, you'll probably want to include it in your PHP project. Sherlock uses the autoloader that Composer generates, so simply do this:

require 'vendor/autoload.php';
use \Sherlock\Sherlock;

$sherlock = new Sherlock();

Congrats! You've just installed Sherlock!

Manually installing Sherlock is possible, but not recommended.

Sherlock can be installed even if you don't use Composer, using a built-in autoloader instead of the one provided by Composer. Download Sherlock and include the following in your index.php or equivalent:

<?php
require 'Sherlock/Sherlock.php';
\Sherlock\Sherlock::registerAutoloader();

However, this only loads Sherlock, and not any of the dependencies that Sherlock uses. You'll have to ensure they are properly loaded before Sherlock will function.

Who needs defaults anyway?

Sherlock comes with a number of good defaults, but in case you want to change them, it's super easy. Just pass an array of settings into the constructor of Sherlock and they will automatically over-ride the defaults. For example, logging is disabled by default (more details below). To enable logging, simply over-ride the default setting:

$settings['log.enabled'] = true;
$sherlock = new Sherlock($settings);

Here is a full list of Sherlock settings that may be changed or accessed:

If you ever need to check what settings are in effect at runtime, you may use this method:

//currently active settings
$settings = $sherlock->getSherlockSettings();

//default settings
$settings = Sherlock::getDefaultSettings();

Add a node, Sherlock will track down the rest.

ElasticSearch clusters are naturally gossipy - every node knows about all the other nodes. This makes it connecting to the full cluster very easy. Specify (at least) one node and Sherlock will sniff out the rest. You can also specify more, if you wish to hardcode the values or don't want to risk automatic detection failing.

$sherlock = new Sherlock();
$sherlock->addNode("localhost");

//Ports default to 9200, if you use something else, specify it:
$sherlock->addNode("localhost", 10200);

Because something always goes wrong.

Logging can save the day when something goes wrong, or to help you troubleshoot problems. By default, logging is disabled because it can add additional overhead. But in development environments, it may be a good idea to enable logging:

$settings['log.enabled'] = true;
$sherlock = new Sherlock($settings);

Sherlock defaults to a log file located at vendor/sherlock/sherlock/src/sherlock.log. For obvious reasons, you may want to change this location. Over-ride the path like so:

$settings['log.enabled'] = true;

//path is relative to vendor/sherlock/sherlock/src/sherlock/Sherlock.php
$settings['log.file'] = '../../newlogfile.log';

//Alternatively, just specify an absolute path
$settings['log.file'] = '/var/log/sherlock/newlogfile.log';
$sherlock = new Sherlock($settings);

Sherlock defaults to logging Error messages and above. However, you may want to turn on all Debug messages too, to help assist troubleshooting:

$settings['log.enabled'] = true;
$settings['log.file'] = '/var/log/sherlock/newlogfile.log';
$settings['log.level'] = 'debug';
$sherlock = new Sherlock($settings);

Finally, Sherlock exposes the underlying Analog handler, so that you can specify a new handler (such as a Syslog handler) or write your own. Here is an example of enabling logging to Syslog:

$syslogHandler = \Analog\Handler\Syslog::init ('analog', 'user');

$settings['log.enabled'] = true;
$settings['log.handler'] = $syslogHandler;
$settings['log.level'] = 'debug';
$sherlock = new Sherlock($settings);