[BC] Upgraded dependencies, dropped support for anything below PHP 8.0. (#849)
* GitHub actions + style fixes + updated packages * Fixed workflows dir * Support for PHP 8.1 (#1) * Update README.md * Revert some changes from upstream
This commit is contained in:
parent
72c946dc7d
commit
111c153428
335 changed files with 4394 additions and 28116 deletions
190
ORIGINAL_ALCHEMY_README.md
Normal file
190
ORIGINAL_ALCHEMY_README.md
Normal file
|
|
@ -0,0 +1,190 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue