Download the PHP package ncuesta/clinner without Composer

Clinner

Clinner is a PHP 5.3+ Command-Line Interface commands execution abstraction.

Advantages

Clinner has the following benefits:

• Minimalistic.
• Simple and easy to use.
• Clinner uses Composer.
• Fluent API.
• Higher-level and object oriented interface to commands.
• Command pipes, regardless of the underlying OS.
• Commands might be actual command-line executables or PHP code.
• Yes, you can mix commands and PHP code in an OO way!
• Easily extendable through Interface implementation.
• MIT Licensed.

Usage

Simple usage

The most basic use of Clinner consists of installing it as a dependency via Composer and then including Composer's autoloader.php in your code:

1. Create (if needed) a composer.json file or add an entry to your existing one:

2. Include Composer's autoload.php file on your code:

3. Start using commands right away!

Passing arguments

Commands crave for arguments, so Clinner offers a way to satisfying them. By passing in a second argument to the factory method or the constructor, or using the dedicated setter method setArguments().

Arguments can either be key-value pairs or just values. Key value pairs will be joined using a delimiter (see Options section for more information).

Options

Options allow customization of different Command behaviors. They can be passed in as a third argument for the factory method or constructor, or set via the setOptions() method.

Currently there's only one thing that can be customized for the Command class, but it's worth noting it: you might specify the delimiter, a string that will be used to join key-value pairs of arguments. If not specified, it will default to the equals sign (=).

Let's see an example:

Advanced usage: Commands pipes

Commands can be piped just like in any Unix shell. The basics of command pipes is that the output of a command is sent to the one that is piped to it.

For example, if you want to run ls -a | grep -i clinner, you can:

Command pipes are not limited to a number of commands, you only need at least two commands.

See next section for a more complex example involving 3 commands in a pipeline.

Advanced usage: Mixing PHP with commands

Apart from Command class, Clinner ships with a Callback command class that enables to mix both commands and PHP code in a command pipe. Pretty cool, huh?

Callback class only takes a Closure or a function reference in its constructor and then is ready to run. That Closure function will receive the command's input as its first argument and is expected to return an exit code. Any information output by the function (either via echo or print or any other output method) will be considered as the command output and will be sent to the next command in the pipe, if any.

Creating commands from string

As of 0.1.2 it is possible to create a Command instance from a string, using the command as if you had written it in a CLI.

For instance, the following command could be run on the CLI:

Would output all the lines in the /etc/hosts file that contain the string localhost with any tab (\t) indent replaced by a single blank space ( ).

This very same command can be passed as a string to \Clinner\Command\Command::fromString() and a new Command instance representing this commands chain will be returned:

And then you can work with the newly created Command instance as usual, and pipe other Commands or even Callbacks to it.

Requirements

The only requirement for Clinner is PHP version >= 5.3.

Contributing

Please, feel free to fork this repo and improve it in any way you consider useful -- Pull Requests are welcome!