deminy/shellwrap

Use any command-line tool as a PHP function.

0.4.1 2013-12-23 04:05 UTC

Requires

• php: >=5.3.0
• d11wtq/boris: 1.0.*

MIT

• James Hall

• api
• command
• shell
• command-line
• exec

README

What is it?

It's a beautiful way to use powerful Linux/Unix tools in PHP. Easily and logically pipe commands together, capture errors as PHP Exceptions and use a simple yet powerful syntax. Works with any command line tool automagically.

Features

• Flexible and sexy syntax.
• Exceptions are thrown if the executable returns an error.
• Paths to binaries are automatically resolved.
• All arguments are properly escaped.
• Callback functions for streaming output.

Examples

<?php 
require_once 'vendor/autoload.php';
use MrRio\ShellWrap as sh;

// List all files in current dir
echo sh::ls();

// Checkout a branch in git
sh::git('checkout', 'master');

// You can also pipe the output of one command, into another
// This downloads example.com through cURL, follows location, then pipes through grep to 
// filter for 'html'
echo sh::grep('html', sh::curl('http://example.com', array(
	'location' => true
)));

// Touch a file to create it
sh::touch('file.html');

// Remove file
sh::rm('file.html');

// Remove file again (this fails, and throws an exception because the file doesn't exist)

try {
	sh::rm('file.html');
} catch (ShellWrapException $e) {
	echo 'Caught failing sh::rm() call';
}


// This throws an exception, as 'invalidoption' is not a valid argument
try {
	echo sh::ls(array('invalidoption' => true));
} catch (ShellWrapException $e) {
	echo 'Caught failing sh::ls() call';
}

// Commands can be written multiple ways
sh::git('reset', array('hard' => true), 'HEAD');
sh::git('reset', '--hard', 'HEAD');
sh::git(array('reset', '--hard', 'HEAD'));

// Arguments passed in are automatically escaped, this expands to
// date --date '2012-10-10 10:00:00'
echo sh::date(array(
	'date' => '2012-10-10 10:00:00'
));

// If arg keys are one letter, is assumes one dash prefixing it
// date -d '2012-10-10 10:00:00'
echo sh::date(array(
	'd' => '2012-10-10 10:00:00'
));


?>

Example: Tailing a file and adding timestamps to output

You can stream the output of a command into a callback function. For example:

sh::tail('-f log', function($in) {
	echo "\033[32m" . date('Y-m-d H:i:s') . "\033[39m " . $in;
});

Make sure the file 'log' exists. This will output a timestamp, and the input. Try echoing into the log file.

The escape codes are to add a little colour to the terminal.

Interactive Shell

ShellWrap also ships with an interactive shell mode. You can access this by typing:

./bin/shellwrap

Warning

Don't use any user inputted data with these commands. Even with very paranoid filtering, you can't know all the potential pitfalls of each command you're using. Use your noggin.

Acknowledgements

Inspired by the Python project sh by Andrew Moffat