1atdev/yii2-shell-wrapper

An object oriented wrapper for shell commands

1.0.7 2024-03-21 21:17 UTC

Requires

• php: ^8.2
• composer-plugin-api: ^2.0
• 1atdev/yii2-env: ^1.0

Requires (Dev)

• composer/composer: ^2.2
• mockery/mockery: ^1.5
• phploc/phploc: ^7
• phpmd/phpmd: @stable
• phpunit/phpunit: ^9
• sebastian/phpcpd: ^6
• squizlabs/php_codesniffer: 3.*
• yiisoft/yii2: ^2.0

GPL-3.0+

• Mirdani Handoko

README

This package based on adambrett/shell-wrapper

PHP Shell Wrapper

PHP Shell Wrapper is a high level object-oriented wrapper for accessing the program execution functions in PHP.

Its primary purpose is to abstract away low level program execution functions in your application, allowing you to mock PHP Shell Wrapper in your tests, making applications which call shell functions easily testable.

Installation

Using composer:

composer require isatdev/yii2-shell-wrapper '^1.0'

Basic Usage

Hello World

Import the required classes into your namespace:

use IsAtDev\ShellWrapper\Command;
use IsAtDev\ShellWrapper\Command\Param;
use IsAtDev\ShellWrapper\Runners\Exec;

Instantiate a new shell runner:

$shell = new Exec();

Create the command:

$command = new Command('echo');

Add some parameters:

$command->addParam(new Param('Hello World'));

Now run the command:

$shell->run($command);

Which would run the command:

echo 'Hello World'

Command Builder

Whilst this library is highly object-oriented behind the scenes, you may not want to use it that way, what's where the Command Builder comes in. The command builder constructs a Command object behind the scenes, and then constructs the correct class for each method called, so you don't have to worry about it.

The Command Builder also has a fluent interface for extra syntactical sugar. Here's the above example re-written using the Command Builder:

use IsAtDev\ShellWrapper\Runners\Exec;
use IsAtDev\ShellWrapper\Command\Builder as CommandBuilder;

$shell = new Exec();
$command = new CommandBuilder('echo');
$command->addParam('Hello World');
$shell->run($command);

And here's a slightly less trivial example:

use IsAtDev\ShellWrapper\Runners\Exec;
use IsAtDev\ShellWrapper\Command\Builder as CommandBuilder;

$shell = new Exec();
$command = new CommandBuilder('phpunit');
$command->addFlag('v')
    ->addArgument('stop-on-failure')
    ->addArgument('configuration', '~/phpunit.xml')
    ->addParam('~/tests/TestCase.php');
$shell->run($command);

Which would run:

phpunit -v --stop-on-failure --configuration '~/phpunit.xml' '~/tests/TestCase.php'

and another:

use IsAtDev\ShellWrapper\Runners\Exec;
use IsAtDev\ShellWrapper\Command\Builder as CommandBuilder;

$shell = new Exec();
$command = new CommandBuilder('/usr/bin/jekyll');
$command->addSubCommand('serve')
    ->addArgument('watch');
$shell->run($command);

Which would run:

/usr/bin/jekyll serve --watch

Runners

Runners are paths directly in to the PHP program execution functions, and map to them by name exactly. Runners should all implement \IsAtDev\ShellWrapper\Runners\Runner, which means you can type hint on that whenever you need to use a shell and they should then all be interchangeable.

Some runners will also implement \IsAtDev\ShellWrapper\Runners\ReturnValue, but only where that is appropriate to the low level function.

Some runners (marked *) only emulate command running. This feature useful for testing.

Runner	Returns	Flush	getOutput	getReturnValue
Exec	Last Line		x	x
Passthru		x		x
ShellExec	Full Output or null
System	Last Line or false	x		x
Dry*	Exit code		x	x
Fake*	Exit code		x	x

You can use FakeRunner in your unit tests to emulate running a command. You can use DryRunner for debugging purposes, or when your application uses a --dry-run type argument and you want to echo the command rather than run it.

SubCommands

Usage

use IsAtDev\ShellWrapper\Command\SubCommand;

$shell->addSubCommand(new SubCommand($subCommand));

Sub commands will not be escaped or modified in anyway, they are intended for use like so:

use IsAtDev\ShellWrapper\Command\Command;
use IsAtDev\ShellWrapper\Command\SubCommand;

$command = new Command('jekyll')
$shell->addSubCommand(new SubCommand('build'));

Which would run the command jekyll build.

Arguments

Usage

use IsAtDev\ShellWrapper\Command\Argument;

$shell->addArgument(new Argument($name, $value));

$value will be automatically escaped behind the scenes, but $name will not, so make sure you never have user input in $name, or if you do, escape it yourself.

If you want multiple arguments of the same name, then $value can be an array, like so:

use IsAtDev\ShellWrapper\Command\Argument;

$shell->addArgument(new Argument('exclude', ['.git*', 'cache']));

Which would result in the following:

somecommand --exclude '.git*' --exclude 'cache'

Flags

Usage

use IsAtDev\ShellWrapper\Command\Flag;

$shell->addFlag(new Flag($flag));

$flag will not be escaped, but can be a string rather than a single character, so new Flag('lla') is perfectly valid.

Params

Usage

use IsAtDev\ShellWrapper\Command\Param;

$shell->addParam(new Param($param));

$param will be automatically escaped behind the scenes, but will otherwise be un-altered.

Requirements

• PHP >= 8.3