191 lines
4.6 KiB
Markdown
191 lines
4.6 KiB
Markdown
# Binary Driver
|
|
|
|
Binary-Driver is a set of PHP tools to build binary drivers.
|
|
|
|
[](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.
|