PHPackages                             adambrett/shell-wrapper - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. adambrett/shell-wrapper

ActiveLibrary[Utility & Helpers](/categories/utility)

adambrett/shell-wrapper
=======================

An object oriented wrapper for shell commands

1.0.2(1y ago)6262.0k—1.6%3[4 issues](https://github.com/adambrett/php-shell-wrapper/issues)8BSD-3-ClausePHP

Since Nov 26Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/adambrett/php-shell-wrapper)[ Packagist](https://packagist.org/packages/adambrett/shell-wrapper)[ RSS](/packages/adambrett-shell-wrapper/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (12)Versions (14)Used By (8)

PHP Shell Wrapper
=================

[](#php-shell-wrapper)

PHP Shell Wrapper is a high level object-oriented wrapper for accessing the [program execution functions](http://php.net/exec) 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
============

[](#installation)

Using [composer](https://getcomposer.org/):

```
composer require adambrett/shell-wrapper '~1.0'
```

Basic Usage
===========

[](#basic-usage)

Hello World
-----------

[](#hello-world)

Import the required classes into your namespace:

```
use AdamBrett\ShellWrapper\Command;
use AdamBrett\ShellWrapper\Command\Param;
use AdamBrett\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
---------------

[](#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 AdamBrett\ShellWrapper\Runners\Exec;
use AdamBrett\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 AdamBrett\ShellWrapper\Runners\Exec;
use AdamBrett\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 AdamBrett\ShellWrapper\Runners\Exec;
use AdamBrett\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)

Runners are paths directly in to the PHP [program execution functions](http://php.net/exec), and map to them by name exactly. Runners should all implement `\AdamBrett\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 `\AdamBrett\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.

RunnerReturnsFlushgetOutputgetReturnValueExecLast LinexxPassthruxxShellExecFull Output or `null`SystemLast Line or `false`xxDry\*Exit codexxFake\*Exit codexxYou 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
-----------

[](#subcommands)

### Usage

[](#usage)

```
use AdamBrett\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 AdamBrett\ShellWrapper\Command\Command;
use AdamBrett\ShellWrapper\Command\SubCommand;

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

Which would run the command `jekyll build`.

Arguments
---------

[](#arguments)

### Usage

[](#usage-1)

```
use AdamBrett\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 AdamBrett\ShellWrapper\Command\Argument;

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

Which would result in the following:

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

Flags
-----

[](#flags)

### Usage

[](#usage-2)

```
use AdamBrett\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
------

[](#params)

### Usage

[](#usage-3)

```
use AdamBrett\ShellWrapper\Command\Param;

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

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

Requirements
============

[](#requirements)

- PHP >= 8.1

Contributing
============

[](#contributing)

Pull Requests
-------------

[](#pull-requests)

1. Fork the php-shell-wrapper repository
2. Create a new branch for each feature or improvement
3. Send a pull request from each feature branch to the **master** branch

Style Guide
-----------

[](#style-guide)

This package is compliant with [PSR-4](https://www.php-fig.org/psr/psr-4/) and [PSR-12](https://www.php-fig.org/psr/psr-12/). If you notice compliance oversights, please send a patch via pull request.

Tests
-----

[](#tests)

The library is developed using test driven development. All pull requests should be accompanied by passing unit tests with 100% coverage. [phpunit](http://phpunit.de/manual/current/en/index.html) is used for testing and [mockery](https://github.com/padraic/mockery) is used for mocks.

###  Health Score

50

—

FairBetter than 95% of packages

Maintenance51

Moderate activity, may be stable

Popularity41

Moderate usage in the ecosystem

Community25

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 74.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~330 days

Recently: every ~778 days

Total

13

Last Release

641d ago

Major Versions

0.8 → 1.02022-11-30

### Community

Maintainers

![](https://www.gravatar.com/avatar/63ea7e262dbf76721f12e2e5d6e84fe0285096252475810f56f25aebeb673bcd?d=identicon)[adambrett](/maintainers/adambrett)

---

Top Contributors

[![adambrett](https://avatars.githubusercontent.com/u/145340?v=4)](https://github.com/adambrett "adambrett (35 commits)")[![karlhorky](https://avatars.githubusercontent.com/u/1935696?v=4)](https://github.com/karlhorky "karlhorky (4 commits)")[![dfelton](https://avatars.githubusercontent.com/u/2659558?v=4)](https://github.com/dfelton "dfelton (3 commits)")[![ingria](https://avatars.githubusercontent.com/u/2178368?v=4)](https://github.com/ingria "ingria (1 commits)")[![j13k](https://avatars.githubusercontent.com/u/1084378?v=4)](https://github.com/j13k "j13k (1 commits)")[![kduma](https://avatars.githubusercontent.com/u/1062582?v=4)](https://github.com/kduma "kduma (1 commits)")[![Bukharovsi](https://avatars.githubusercontent.com/u/932921?v=4)](https://github.com/Bukharovsi "Bukharovsi (1 commits)")[![frenchcomp](https://avatars.githubusercontent.com/u/1397905?v=4)](https://github.com/frenchcomp "frenchcomp (1 commits)")

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/adambrett-shell-wrapper/health.svg)

```
[![Health](https://phpackages.com/badges/adambrett-shell-wrapper/health.svg)](https://phpackages.com/packages/adambrett-shell-wrapper)
```

###  Alternatives

[byjg/singleton-pattern

A lightweight PHP implementation of the Design Pattern Singleton using trait.

1057.0k2](/packages/byjg-singleton-pattern)[duoshuo/uuid

A PHP 5.4+ library for generating RFC 4122 version 1, 3, 4, and 5 universally unique identifiers (UUID)

1039.4k](/packages/duoshuo-uuid)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)