php-shellcommand
php-shellcommand provides a simple object oriented interface to execute shell commands.
Installing
Prerequisites
Your php version must be 5.4 or later.
Installing with composer
This package can be installed easily using composer.
composer require mikehaertl/php-shellcommand
Features
- Catches
stdOut,stdErrandexitCode - Handle argument escaping
- Pass environment vars and other options to
proc_open() - Pipe resources like files or streams into the command
- Timeout for execution
Examples
Basic Example
use mikehaertl\shellcommand\Command;
// Basic example
$command = new Command('/usr/local/bin/mycommand -a -b');
if ($command->execute()) {
echo $command->getOutput();
} else {
echo $command->getError();
$exitCode = $command->getExitCode();
}
Advanced Features
Add Arguments
addArg('--keys', array('key1','key2'));">
$command = new Command('/bin/somecommand');
// Add arguments with correct escaping:
// results in --name='d'\''Artagnan'
$command->addArg('--name=', "d'Artagnan");
// Add argument with several values
// results in --keys key1 key2
$command->addArg('--keys', array('key1','key2'));
Pipe Input Into Command
From string:
execute()) { echo $command->getError(); } else { echo $command->getOutput(); } // Output: // { // "foo": 0 // }">
$command = new ('jq') // jq is a pretty printer
$command->setStdIn('{"foo": 0}');
if (!$command->execute()) {
echo $command->getError();
} else {
echo $command->getOutput();
}
// Output:
// {
// "foo": 0
// }
From file:
$fh = fopen('test.json', 'r');
// error checks left out...
$command = new Command('jq');
$command->setStdIn($fh);
if (!$command->execute()) {
echo $command->getError();
} else {
echo $command->getOutput();
}
fclose($fh);
From URL:
$fh = fopen('https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&hourly=temperature_2m,relativehumidity_2m,windspeed_10m', 'r');
// error checks left out...
$command = new Command('jq');
$command->setStdIn($fh);
if (!$command->execute()) {
echo $command->getError();
} else {
echo $command->getOutput();
}
fclose($fh);
Set Command Instance Options
// Create command with options array
$command = new Command(array(
'command' => '/usr/local/bin/mycommand',
// Will be passed as environment variables to the command
'procEnv' => array(
'DEMOVAR' => 'demovalue'
),
// Will be passed as options to proc_open()
'procOptions' => array(
'bypass_shell' => true,
),
));
API
Properties
$escapeArgs: Whether to escape any argument passed throughaddArg(). Default istrue.$escapeCommand: Whether to escape the command passed tosetCommand()or the constructor. This is only useful if$escapeArgsisfalse. Default isfalse.$useExec: Whether to useexec()instead ofproc_open(). This is a workaround for OS which have problems withproc_open(). Default isfalse.$captureStdErr: Whether to capture stderr whenuseExecis set. This will try to redirect the otherwhise unavailablestderrtostdout, so that both have the same content on error. Default istrue.$procCwd: The initial working dir passed toproc_open(). Default isnullfor current PHP working dir.$procEnv: An array with environment variables to pass toproc_open(). Default isnullfor none.$procOptions: An array ofother_optionsforproc_open(). Default isnullfor none.$nonBlockingMode: Whether to set the stdin/stdout/stderr streams to non-blocking mode whenproc_open()is used. This allows to have huge inputs/outputs without making the process hang. The default isnullwhich will enable the feature on Non-Windows systems. Set it totrueorfalseto manually enable/disable it. Note that it doesn't work on Windows.$timeout: The time in seconds after which the command should be terminated. This only works in non-blocking mode. Default isnullwhich means the process is never terminated.$locale: The locale to (temporarily) set withsetlocale()before running the command. This can be set to e.g.en_US.UTF-8if you have issues with UTF-8 encoded arguments.
You can configure all these properties via an array that you pass in the constructor. You can also pass command, execCommand and args as options. This will call the respective setter (setCommand(), setExecCommand(), etc.).
Methods
__construct($options = null)$options: either a command string or an options array (seesetOptions())
__toString(): The result fromgetExecCommand()setOptions($options): Set command options$options: array of name => value options that should be applied to the object. You can also pass options that use a setter, e.g. you can pass acommandoption which will be passed tosetCommand().
setCommand($command): Set command$command: The command or full command string to execute, likegziporgzip -d. You can still calladdArg()to add more arguments to the command. If$escapeCommandwas set totrue, the command gets escaped throughescapeshellcmd().
getCommand(): The command that was set throughsetCommand()or passed to the constructor.getExecCommand(): The full command string to execute.setArgs($args): Set argument as string$args: The command arguments as string. Note, that these will not get escaped. This will overwrite the args added withaddArgs().
getArgs(): The command arguments that where set throughsetArgs()oraddArg(), as stringaddArg($key, $value=null, $escape=null): Add argument with correct escaping$key: The argument key to add e.g.--featureor--name=. If the key does not end with and=, the (optional)$valuewill be separated by a space. The key will get escaped if$escapeArgsistrue.$value: The optional argument value which will get escaped if$escapeArgsistrue. An array can be passed to add more than one value for a key, e.g.addArg('--exclude', array('val1','val2'))which will create the option "--exclude 'val1' 'val2'".$escape: If set, this overrides the$escapeArgssetting and enforces escaping/no escaping
setStdIn(): String or resource to supply to command via standard input. This enables the same functionality as piping on the command line. It can also be a resource like a file handle or a stream in which case its content will be piped into the command like an input redirection.getOutput(): The command output as string. Empty if none.getError(): The error message, either stderr or internal message. Empty if no error.getStdErr(): The stderr output. Empty if none.getExitCode(): The exit code ornullif command was not executed.getExecuted(): Whether the command was successfully executed.getIsWindows(): Whether we are on a Windows Owe are on a Windows OSexecute(): Executes the command and returnstrueon success,falseotherwhise.
Note:
getError(),getStdErr()andgetOutput()return the trimmed output. You can passfalseto these methods if you need any possible line breaks at the end.
75 Dec 20, 2022
18 Dec 31, 2022
140 Sep 28, 2022
763 Dec 27, 2022
60 Dec 14, 2022
4 Aug 23, 2022
43 Sep 4, 2022
112 Aug 17, 2022
324 Dec 28, 2022
436 Feb 20, 2022
16 Dec 28, 2022
96 Dec 29, 2022
22 Mar 8, 2022
29 Nov 19, 2022
3 Oct 20, 2022
4 Mar 8, 2022
3 May 29, 2022
16 Nov 11, 2022