Download the PHP package phpsu/shellcommandbuilder without Composer

ShellCommandBuilder

Creating basic and more complex shell commands in an fluid object-oriented fashion. This makes it very straight forward to abstract the general mechanisms of bash behind a readable and debuggable layer.

The Reference for this library is based on the GNU Bash Reference Manual
If you need more features from that reference in this library, feel free to create an issue or pull request.

Concept

Imagine you want to create the following bash command: a && b | c || d |& f && (g && h) || {i || j;}

You can achieve that by creating a ShellBuilder-Object and then reading the command from left to right as instructions.

Table of Contents

1. Installation
2. Usage
   1. Simple Commands
   2. Pipelines, Lists, and Redirections
   3. Complex Commands
   4. Conditional Expressions
   5. Coprocess
3. Specials
4. Contributing
5. Testing

Installation

You can use this library in your project by adding it with composer:

composer require phpsu/shellcommandbuilder

Then include it in your class/file.

Introduction

This library is boiled down to these three main components:

• ShellBuilder
• ShellCommand
• ShellWord

The ShellBuilder is the glue that holds a collection of commands together. The glue is one of the control operators like || or &&.
Commands are represented by the ShellCommand-Class. The ShellCommand is responsible for the arguments and options etc.
A ShellCommand is composed of ShellWords, they represent the tokens that make up a command.

Let's look at an example:

This entire line is a ShellBuilder-Object containing the two ShellCommands:

• echo "hello world
• grep -e "world"

Those are connected with the |-Operator
Taking apart each of those commands returns the following ShellWords:

Usage

Simple Commands

Much of the API is marked internal, it is meant to be accessed through the ShellBuilder-Class.
This should make it very straight-forward to build simple and more complex commands from one basis.
Additionally, the ShellBuilder has factory-style methods that help building commands top to bottom in an instant.

That means, creating a ShellBuilder can look like this:

or like this:

A ShellCommand can be created like this:

or, if there is already a ShellBuilder-object available, like this

Let's take a look at the command from earlier and build it step by step.

Note: each step is written into the code as comment

Note: Every argument and option is escaped by default.

All methods implement the fluent interface. For this library that means that you can rewrite the example above by chaining everything together:

The createCommand passes the current ShellBuilder into the ShellCommand-Instance. Through addToBuilder that ShellBuilder can be accessed again, and the command is automatically added to the ShellBuilder. This currently only works for and.

Pipelines, Lists, and Redirections

The ShellBuilder is a representation of what holds commands together. Whether it is to execute commands sequentially, or to connect input and output.

Let's look at this following fake example:
a; b && c | d || e |& f 2>&1
It illustrates the various ways of connecting commands together.

Rebuilding this command could look like this:

The full list of methods can be found here: API Docs

Complex Commands

The idea behind this library is to make generating larger and complex shell commands more readable and maintainable.
The following example is taken out of PHPsu. This command syncs a database from a remote source to a local database.

First, we have to think about the components that this command is composed of. This results in these commands:

Now, we build this in PHP:

Next, we take a look at how to achieve process and command substition. The following is again a mock example. It creates a list of all php-files in the current and all below directories, sorted and enriched with the size. This file-list is redirected into a txt-file with the current month-name as filename.

And this is how it could look like in php:

Conditional Expressions

Conditional Expressions are currently a work in progress. The basic API stands, but the overall usage might change, especially when it comes down to escaping.

There are multiple conditional-expression-types that can be used to built expressions. They are build upon the Shell-Syntax Bash Reference.

The following expression-types exist:

• Artihmetic: ArithmeticExpression::class
• File: FileExpression::class
• Shell: ShellExpression::class
• String: StringExpression::class

Let's look at two examples:

• 1: Only executing a command, if a file is not empty
• 2: Only executing a command, if a variable is greater than 5

Coprocess

To run commands in the background, the ShellBuilder class supports the coproc keyword.
This keyword lets the command run asynchronously in a subshell and can be combined with pipes and redirections.

More information on Coprocesses can be found in the Bash Reference.

Let's look at an example: {coproc tee {tee logfile;} >&3 ;} 3>&1
This starts tee in the background and redirects its output to stdout

If you want to direct a single command or a list of commands into the background, you can achieve that by appending an ampersand & at the end of a command.

So maybe you want to do this: ./import-script & ./import-script2 &

Then, this can be achieved like this:

Special

Pattern-Class - ShellWord parsing

The pattern-class validates string inputs as valid Bourne Shellwords. It is based on its equivalent implementations in the Ruby and Rust languages.
It takes a string and applies the word parsing rules of shell to split it into an array.

Pattern::split respects escaping and quoting and only splits outside of these:

The method will throw an exception if there is an invalid input.
For example the following has an unmatched quoting:

Debugging the ShellBuilder

Sometimes there is a need to better understand why the output is rendered the way it is.
For those situations, all classes implement a __toArray()-method, that take the current class-state and print it as an array. The ShellBuilder additionally implements jsonSerializable. It itself calls the __toArray-method and is meant as a shortcut for outputting to a client.

If you call __toArray() on a ShellBuilder, it will go through all commands and turn them into an array too. That way you have a deeply nested structure, that represents the list of commands you want to execute.

Contributing

install for contributing `

Testing

`

You can also check, whether any changes you made are affecting your tests immediately on save: `

Type-Checking is being done with psalm. `

If you see a low Mutation Score Indicator (MSI) value, you can show the mutations that are escaping: `

Security

Email [email protected] if you discover any security related issues.

Credits

• Chris Ben
• Matthias Vogel

License

The MIT License (MIT). Please see License File for more information.