ORIGINAL_ALCHEMY_README.md

Binary Driver

Binary-Driver is a set of PHP tools to build binary drivers.

Why ?

You may wonder Why building a library while I can use exec or symfony/process ?.

Here is a simple answer :

• If you use exec, passthru, system, proc_open or any low level process handling in PHP, you should have a look to symfony/process component that will provide an OO portable, testable and secure interface to deal with this. It seems easy at first approach, but if you look at this component unit tests, you will see that handling process in a simple interface can easily become a nightmare.

• If you already use symfony/process, and want to build binary drivers, you will always have the same common set of methods and objects to configure, log, debug, and generate processes. This library is a base to implement any binary driver with this common set of needs.

AbstractBinary

AbstractBinary provides an abstract class to build a binary driver. It implements BinaryInterface.

Implementation example :

use Alchemy\BinaryDriver\AbstractBinary;

class LsDriver extends AbstractBinary
{
    public function getName()
    {
        return 'ls driver';
    }
}

$parser = new LsParser();

$driver = Driver::load('ls');
// will return the output of `ls -a -l`
$parser->parse($driver->command(array('-a', '-l')));

Binary detection troubleshooting

If you are using Nginx with PHP-fpm, executable detection may not work because of an empty $_ENV['path']. To avoid having an empty PATH environment variable, add the following line to your fastcgi_params config file (replace /your/current/path/ with the output of printenv PATH) :

fastcgi_param    PATH    /your/current/path

Logging

You can log events with a Psr\Log\LoggerInterface by passing it in the load method as second argument :

$logger = new Monolog\Logger('driver');
$driver = Driver::load('ls', $logger);

Listeners

You can add custom listeners on processes. Listeners are built on top of Evenement and must implement Alchemy\BinaryDriver\ListenerInterface.

use Symfony\Component\Process\Process;

class DebugListener extends EventEmitter implements ListenerInterface
{
    public function handle($type, $data)
    {
        foreach (explode(PHP_EOL, $data) as $line) {
            $this->emit($type === Process::ERR ? 'error' : 'out', array($line));
        }
    }

    public function forwardedEvents()
    {
        // forward 'error' events to the BinaryInterface
        return array('error');
    }
}

$listener = new DebugListener();

$driver = CustomImplementation::load('php');

// adds listener
$driver->listen($listener);

$driver->on('error', function ($line) {
    echo '[ERROR] ' . $line . PHP_EOL;
});

// removes listener
$driver->unlisten($listener);

Bundled listeners

The debug listener is a simple listener to catch stderr and stdout outputs ; read the implementation for customization.

use Alchemy\BinaryDriver\Listeners\DebugListener;

$driver = CustomImplementation::load('php');
$driver->listen(new DebugListener());

$driver->on('debug', function ($line) {
    echo $line;
});

ProcessBuilderFactory

ProcessBuilderFactory ease spawning processes by generating Symfony [Process] (http://symfony.com/doc/master/components/process.html) objects.

use Alchemy\BinaryDriver\ProcessBuilderFactory;

$factory = new ProcessBuilderFactory('/usr/bin/php');

// return a Symfony\Component\Process\Process
$process = $factory->create('-v');

// echoes '/usr/bin/php' '-v'
echo $process->getCommandLine();

$process = $factory->create(array('-r', 'echo "Hello !";'));

// echoes '/usr/bin/php' '-r' 'echo "Hello !";'
echo $process->getCommandLine();

Configuration

A simple configuration object, providing an ArrayAccess and IteratorAggregate interface.

use Alchemy\BinaryDriver\Configuration;

$conf = new Configuration(array('timeout' => 0));

echo $conf->get('timeout');

if ($conf->has('param')) {
    $conf->remove('param');
}

$conf->set('timeout', 20);

$conf->all();

Same example using the ArrayAccess interface :

use Alchemy\BinaryDriver\Configuration;

$conf = new Configuration(array('timeout' => 0));

echo $conf['timeout'];

if (isset($conf['param'])) {
    unset($conf['param']);
}

$conf['timeout'] = 20;

License

This project is released under the MIT license.