A set of tools to build binary drivers

Installs: 9 246 393

Dependents: 42

Suggesters: 0

Security: 0

Stars: 188

Watchers: 15

Forks: 62

Open Issues: 17

v5.2.0 2020-02-12 19:35 UTC

This package is auto-updated.

Last update: 2024-04-17 03:56:47 UTC


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

Build Status

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 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


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);


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->on('error', function ($line) {
    echo '[ERROR] ' . $line . PHP_EOL;

// removes 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 ease spawning processes by generating Symfony [Process] ( 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();


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->set('timeout', 20);


Same example using the ArrayAccess interface :

use Alchemy\BinaryDriver\Configuration;

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

echo $conf['timeout'];

if (isset($conf['param'])) {

$conf['timeout'] = 20;


This project is released under the MIT license.