PHP Class mikehaertl\shellcommand\Command

This class represents a shell command.
Author: Michael Härtl ([email protected])
Show file Open project: mikehaertl/php-shellcommand Class Usage Examples

Public Properties

Property Type Description
$captureStdErr whether to capture stderr (2>&1) when useExec is true. This will try to redirect the stderr to stdout and provide the complete output of both in getStdErr() and getError(). Default is true.
$escapeArgs whether to escape any argument passed through addArg(). Default is true.
$escapeCommand whether to escape the command passed to setCommand() or the constructor. This is only useful if $escapeArgs is false. Default is false.
$locale the locale to temporarily set before calling escapeshellargs(). Default is null for none.
$procCwd the initial working dir for proc_open(). Default is null for current PHP working dir.
$procEnv an array with environment variables to pass to proc_open(). Default is null for none.
$procOptions an array of other_options for proc_open(). Default is null for none.
$useExec whether to use exec() instead of proc_open(). This can be used on Windows system to workaround some quirks there. Note, that any errors from your command will be output directly to the PHP output stream. getStdErr() will also not work anymore and thus you also won't get the error output from getError() in this case. You also can't pass any environment variables to the command if this is enabled. Default is false.

Protected Properties

Property Type Description
$_args the list of command arguments
$_command the command to execute
$_error the error message
$_execCommand the full command string to execute
$_executed whether the command was successfully executed
$_exitCode the exit code
$_stdErr the stderr output
$_stdOut the stdout output

Public Methods

Method Description
__construct ( string | array $options = null )
__toString ( ) : string
addArg ( string $key, string | array | null $value = null, boolean | null $escape = null ) : static
execute ( ) : boolean Execute the command
getArgs ( ) : string
getCommand ( ) : string | null
getError ( boolean $trim = true ) : string
getExecCommand ( ) : string | boolean
getExecuted ( ) : string
getExitCode ( ) : integer | null
getIsWindows ( ) : boolean
getOutput ( boolean $trim = true ) : string
getStdErr ( boolean $trim = true ) : string
setArgs ( string $args ) : static
setCommand ( string $command ) : static
setOptions ( array $options ) : static

Method Details

__construct() public method

public __construct ( string | array $options = null )
$options string | array either a command string or an options array (see setOptions())

__toString() public method

public __toString ( ) : string
return string the current command string to execute

addArg() public method

public addArg ( string $key, string | array | null $value = null, boolean | null $escape = null ) : static
$key string the argument key to add e.g. `--feature` or `--name=`. If the key does not end with and `=`, the $value will be separated by a space, if any. Keys are not escaped unless $value is null and $escape is `true`.
$value string | array | null the optional argument value which will get escaped if $escapeArgs is true. 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 boolean | null if set, this overrides the $escapeArgs setting and enforces escaping/no escaping
return static for method chaining

execute() public method

Execute the command
public execute ( ) : boolean
return boolean whether execution was successful. If false, error details can be obtained through getError(), getStdErr() and getExitCode().

getArgs() public method

public getArgs ( ) : string
return string the command args that where set through setArgs() or added with addArg() separated by spaces

getCommand() public method

public getCommand ( ) : string | null
return string | null the command that was set through setCommand() or passed to the constructor. Null if none.

getError() public method

public getError ( boolean $trim = true ) : string
$trim boolean whether to `trim()` the return value. The default is `true`.
return string the error message, either stderr or internal message. Empty if none.

getExecCommand() public method

public getExecCommand ( ) : string | boolean
return string | boolean the full command string to execute. If no command was set with setCommand() or passed to the constructor it will return false.

getExecuted() public method

public getExecuted ( ) : string
return string whether the command was successfully executed

getExitCode() public method

public getExitCode ( ) : integer | null
return integer | null the exit code or null if command was not executed yet

getIsWindows() public method

public getIsWindows ( ) : boolean
return boolean whether we are on a Windows OS

getOutput() public method

public getOutput ( boolean $trim = true ) : string
$trim boolean whether to `trim()` the return value. The default is `true`.
return string the command output (stdout). Empty if none.

getStdErr() public method

public getStdErr ( boolean $trim = true ) : string
$trim boolean whether to `trim()` the return value. The default is `true`.
return string the stderr output. Empty if none.

setArgs() public method

public setArgs ( string $args ) : static
$args string the command arguments as string. Note that these will not get escaped!
return static for method chaining

setCommand() public method

public setCommand ( string $command ) : static
$command string the command or full command string to execute, like 'gzip' or 'gzip -d'. You can still call addArg() to add more arguments to the command. If $escapeCommand was set to true, the command gets escaped through escapeshellcmd().
return static for method chaining

setOptions() public method

public setOptions ( array $options ) : static
$options array 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 a `fileName` option which will be passed to `setFileName()`.
return static for method chaining

Property Details

$_args protected property

the list of command arguments
protected $_args

$_command protected property

the command to execute
protected $_command

$_error protected property

the error message
protected $_error

$_execCommand protected property

the full command string to execute
protected $_execCommand

$_executed protected property

whether the command was successfully executed
protected $_executed

$_exitCode protected property

the exit code
protected $_exitCode

$_stdErr protected property

the stderr output
protected $_stdErr

$_stdOut protected property

the stdout output
protected $_stdOut

$captureStdErr public property

whether to capture stderr (2>&1) when useExec is true. This will try to redirect the stderr to stdout and provide the complete output of both in getStdErr() and getError(). Default is true.
public $captureStdErr

$escapeArgs public property

whether to escape any argument passed through addArg(). Default is true.
public $escapeArgs

$escapeCommand public property

whether to escape the command passed to setCommand() or the constructor. This is only useful if $escapeArgs is false. Default is false.
public $escapeCommand

$locale public property

the locale to temporarily set before calling escapeshellargs(). Default is null for none.
public $locale

$procCwd public property

the initial working dir for proc_open(). Default is null for current PHP working dir.
public $procCwd

$procEnv public property

an array with environment variables to pass to proc_open(). Default is null for none.
public $procEnv

$procOptions public property

an array of other_options for proc_open(). Default is null for none.
public $procOptions

$useExec public property

whether to use exec() instead of proc_open(). This can be used on Windows system to workaround some quirks there. Note, that any errors from your command will be output directly to the PHP output stream. getStdErr() will also not work anymore and thus you also won't get the error output from getError() in this case. You also can't pass any environment variables to the command if this is enabled. Default is false.
public $useExec