Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/alchemy-fr/BinaryDriver

Binary driver utilities
https://github.com/alchemy-fr/BinaryDriver

Last synced: 3 months ago
JSON representation

Binary driver utilities

Awesome Lists containing this project

README 

        
# Binary Driver



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



[![Build Status](https://travis-ci.org/alchemy-fr/BinaryDriver.png?branch=master)](https://travis-ci.org/alchemy-fr/BinaryDriver)



## Why ?



You may wonder *Why building a library while I can use `exec` or

[symfony/process](https://github.com/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](https://github.com/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](https://github.com/symfony/Process/tree/master/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 :



```php

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 :



```php

$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](https://github.com/igorw/evenement)

and must implement `Alchemy\BinaryDriver\ListenerInterface`.



```php

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.



```php

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.



```php

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.



```php

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 :



```php

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.