123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552 |
- <?php
- /**
- * Command
- *
- * This class represents a shell command.
- *
- * @author Michael Härtl <haertl.mike@gmail.com>
- * @license http://www.opensource.org/licenses/MIT
- */
- class ShellCommand
- {
- /**
- * @var bool whether to escape any argument passed through `addArg()`.
- * Default is `true`.
- */
- public $escapeArgs = true;
- /**
- * @var bool whether to escape the command passed to `setCommand()` or the
- * constructor. This is only useful if `$escapeArgs` is `false`. Default
- * is `false`.
- */
- public $escapeCommand = false;
- /**
- * @var bool 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 = false;
- /**
- * @var bool 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 = true;
- /**
- * @var string|null the initial working dir for `proc_open()`. Default is
- * `null` for current PHP working dir.
- */
- public $procCwd;
- /**
- * @var array|null an array with environment variables to pass to
- * `proc_open()`. Default is `null` for none.
- */
- public $procEnv;
- /**
- * @var array|null an array of other_options for `proc_open()`. Default is
- * `null` for none.
- */
- public $procOptions;
- /**
- * @var bool|null whether to set the stdin/stdout/stderr streams to
- * non-blocking mode when `proc_open()` is used. This allows to have huge
- * inputs/outputs without making the process hang. The default is `null`
- * which will enable the feature on Non-Windows systems. Set it to `true`
- * or `false` to manually enable/disable it. It does not work on Windows.
- */
- public $nonBlockingMode;
- /**
- * @var int the time in seconds after which a command should be terminated.
- * This only works in non-blocking mode. Default is `null` which means the
- * process is never terminated.
- */
- public $timeout;
- /**
- * @var null|string the locale to temporarily set before calling
- * `escapeshellargs()`. Default is `null` for none.
- */
- public $locale;
- /**
- * @var null|string|resource to pipe to standard input
- */
- protected $_stdIn;
- /**
- * @var string the command to execute
- */
- protected $_command;
- /**
- * @var array the list of command arguments
- */
- protected $_args = array();
- /**
- * @var string the full command string to execute
- */
- protected $_execCommand;
- /**
- * @var string the stdout output
- */
- protected $_stdOut = '';
- /**
- * @var string the stderr output
- */
- protected $_stdErr = '';
- /**
- * @var int the exit code
- */
- protected $_exitCode;
- /**
- * @var string the error message
- */
- protected $_error = '';
- /**
- * @var bool whether the command was successfully executed
- */
- protected $_executed = false;
- /**
- * @param string|array $options either a command string or an options array
- * @see setOptions
- */
- public function __construct($options = null)
- {
- if (is_array($options)) {
- $this->setOptions($options);
- } elseif (is_string($options)) {
- $this->setCommand($options);
- }
- }
- /**
- * @param array $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 a `fileName` option which will be passed to
- * `setFileName()`.
- * @throws \Exception
- * @return static for method chaining
- */
- public function setOptions($options)
- {
- foreach ($options as $key => $value) {
- if (property_exists($this, $key)) {
- $this->$key = $value;
- } else {
- $method = 'set'.ucfirst($key);
- if (method_exists($this, $method)) {
- call_user_func(array($this,$method), $value);
- } else {
- throw new \Exception("Unknown configuration option '$key'");
- }
- }
- }
- return $this;
- }
- /**
- * @param string $command 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 with escapeshellcmd().
- * @return static for method chaining
- */
- public function setCommand($command)
- {
- if ($this->escapeCommand) {
- $command = escapeshellcmd($command);
- }
- if ($this->getIsWindows()) {
- // Make sure to switch to correct drive like "E:" first if we have
- // a full path in command
- if (isset($command[1]) && $command[1]===':') {
- $position = 1;
- // Could be a quoted absolute path because of spaces.
- // i.e. "C:\Program Files (x86)\file.exe"
- } elseif (isset($command[2]) && $command[2]===':') {
- $position = 2;
- } else {
- $position = false;
- }
- // Absolute path. If it's a relative path, let it slide.
- if ($position) {
- $command = sprintf(
- $command[$position - 1] . ': && cd %s && %s',
- escapeshellarg(dirname($command)),
- escapeshellarg(basename($command))
- );
- }
- }
- $this->_command = $command;
- return $this;
- }
- /**
- * @param string|resource $stdIn If set, the string will be piped to the
- * 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.
- * @return static for method chaining
- */
- public function setStdIn($stdIn) {
- $this->_stdIn = $stdIn;
- return $this;
- }
- /**
- * @return string|null the command that was set through setCommand() or
- * passed to the constructor. `null` if none.
- */
- public function getCommand()
- {
- return $this->_command;
- }
- /**
- * @return string|bool the full command string to execute. If no command
- * was set with setCommand() or passed to the constructor it will return
- * `false`.
- */
- public function getExecCommand()
- {
- if ($this->_execCommand===null) {
- $command = $this->getCommand();
- if (!$command) {
- $this->_error = 'Could not locate any executable command';
- return false;
- }
- $args = $this->getArgs();
- $this->_execCommand = $args ? $command.' '.$args : $command;
- }
- return $this->_execCommand;
- }
- /**
- * @param string $args the command arguments as string. Note that these
- * will not get escaped!
- * @return static for method chaining
- */
- public function setArgs($args)
- {
- $this->_args = array($args);
- return $this;
- }
- /**
- * @return string the command args that where set with setArgs() or added
- * with addArg() separated by spaces
- */
- public function getArgs()
- {
- return implode(' ', $this->_args);
- }
- /**
- * @param string $key 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`.
- * @param string|array|null $value 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'`.
- * @param bool|null $escape if set, this overrides the $escapeArgs setting
- * and enforces escaping/no escaping
- * @return static for method chaining
- */
- public function addArg($key, $value = null, $escape = null)
- {
- $doEscape = $escape !== null ? $escape : $this->escapeArgs;
- $useLocale = $doEscape && $this->locale !== null;
- if ($useLocale) {
- $locale = setlocale(LC_CTYPE, 0); // Returns current locale setting
- setlocale(LC_CTYPE, $this->locale);
- }
- if ($value === null) {
- $this->_args[] = $doEscape ? escapeshellarg($key) : $key;
- } else {
- if (substr($key, -1) === '=') {
- $separator = '=';
- $argKey = substr($key, 0, -1);
- } else {
- $separator = ' ';
- $argKey = $key;
- }
- $argKey = $doEscape ? escapeshellarg($argKey) : $argKey;
- if (is_array($value)) {
- $params = array();
- foreach ($value as $v) {
- $params[] = $doEscape ? escapeshellarg($v) : $v;
- }
- $this->_args[] = $argKey . $separator . implode(' ', $params);
- } else {
- $this->_args[] = $argKey . $separator .
- ($doEscape ? escapeshellarg($value) : $value);
- }
- }
- if ($useLocale) {
- setlocale(LC_CTYPE, $locale);
- }
- return $this;
- }
- /**
- * @param bool $trim whether to `trim()` the return value. The default is `true`.
- * @return string the command output (stdout). Empty if none.
- */
- public function getOutput($trim = true)
- {
- return $trim ? trim($this->_stdOut) : $this->_stdOut;
- }
- /**
- * @param bool $trim whether to `trim()` the return value. The default is `true`.
- * @return string the error message, either stderr or an internal message.
- * Empty string if none.
- */
- public function getError($trim = true)
- {
- return $trim ? trim($this->_error) : $this->_error;
- }
- /**
- * @param bool $trim whether to `trim()` the return value. The default is `true`.
- * @return string the stderr output. Empty if none.
- */
- public function getStdErr($trim = true)
- {
- return $trim ? trim($this->_stdErr) : $this->_stdErr;
- }
- /**
- * @return int|null the exit code or null if command was not executed yet
- */
- public function getExitCode()
- {
- return $this->_exitCode;
- }
- /**
- * @return string whether the command was successfully executed
- */
- public function getExecuted()
- {
- return $this->_executed;
- }
- /**
- * Execute the command
- *
- * @return bool whether execution was successful. If `false`, error details
- * can be obtained from getError(), getStdErr() and getExitCode().
- */
- public function execute()
- {
- $command = $this->getExecCommand();
- if (!$command) {
- return false;
- }
- if ($this->useExec) {
- $execCommand = $this->captureStdErr ? "$command 2>&1" : $command;
- exec($execCommand, $output, $this->_exitCode);
- $this->_stdOut = implode("\n", $output);
- if ($this->_exitCode !== 0) {
- $this->_stdErr = $this->_stdOut;
- $this->_error = empty($this->_stdErr) ? 'Command failed' : $this->_stdErr;
- return false;
- }
- } else {
- $isInputStream = $this->_stdIn !== null &&
- is_resource($this->_stdIn) &&
- in_array(get_resource_type($this->_stdIn), array('file', 'stream'));
- $isInputString = is_string($this->_stdIn);
- $hasInput = $isInputStream || $isInputString;
- $hasTimeout = $this->timeout !== null && $this->timeout > 0;
- $descriptors = array(
- 1 => array('pipe','w'),
- 2 => array('pipe', $this->getIsWindows() ? 'a' : 'w'),
- );
- if ($hasInput) {
- $descriptors[0] = array('pipe', 'r');
- }
- // Issue #20 Set non-blocking mode to fix hanging processes
- $nonBlocking = $this->nonBlockingMode === null ?
- !$this->getIsWindows() : $this->nonBlockingMode;
- $startTime = $hasTimeout ? time() : 0;
- $process = proc_open($command, $descriptors, $pipes, $this->procCwd, $this->procEnv, $this->procOptions);
- if (is_resource($process)) {
- if ($nonBlocking) {
- stream_set_blocking($pipes[1], false);
- stream_set_blocking($pipes[2], false);
- if ($hasInput) {
- $writtenBytes = 0;
- $isInputOpen = true;
- stream_set_blocking($pipes[0], false);
- if ($isInputStream) {
- stream_set_blocking($this->_stdIn, false);
- }
- }
- // Due to the non-blocking streams we now have to check in
- // a loop if the process is still running. We also need to
- // ensure that all the pipes are written/read alternately
- // until there's nothing left to write/read.
- $isRunning = true;
- while ($isRunning) {
- $status = proc_get_status($process);
- $isRunning = $status['running'];
- // We first write to stdIn if we have an input. For big
- // inputs it will only write until the input buffer of
- // the command is full (the command may now wait that
- // we read the output buffers - see below). So we may
- // have to continue writing in another cycle.
- //
- // After everything is written it's safe to close the
- // input pipe.
- if ($isRunning && $hasInput && $isInputOpen) {
- if ($isInputStream) {
- $written = stream_copy_to_stream($this->_stdIn, $pipes[0], 16 * 1024, $writtenBytes);
- if ($written === false || $written === 0) {
- $isInputOpen = false;
- fclose($pipes[0]);
- } else {
- $writtenBytes += $written;
- }
- } else {
- if ($writtenBytes < strlen($this->_stdIn)) {
- $writtenBytes += fwrite($pipes[0], substr($this->_stdIn, $writtenBytes));
- } else {
- $isInputOpen = false;
- fclose($pipes[0]);
- }
- }
- }
- // Read out the output buffers because if they are full
- // the command may block execution. We do this even if
- // $isRunning is `false`, because there could be output
- // left in the buffers.
- //
- // The latter is only an assumption and needs to be
- // verified - but it does not hurt either and works as
- // expected.
- //
- while (($out = fgets($pipes[1])) !== false) {
- $this->_stdOut .= $out;
- }
- while (($err = fgets($pipes[2])) !== false) {
- $this->_stdErr .= $err;
- }
- $runTime = $hasTimeout ? time() - $startTime : 0;
- if ($isRunning && $hasTimeout && $runTime >= $this->timeout) {
- // Only send a SIGTERM and handle status in the next cycle
- proc_terminate($process);
- }
- if (!$isRunning) {
- $this->_exitCode = $status['exitcode'];
- if ($this->_exitCode !== 0 && empty($this->_stdErr)) {
- if ($status['stopped']) {
- $signal = $status['stopsig'];
- $this->_stdErr = "Command stopped by signal $signal";
- } elseif ($status['signaled']) {
- $signal = $status['termsig'];
- $this->_stdErr = "Command terminated by signal $signal";
- } else {
- $this->_stdErr = 'Command unexpectedly terminated without error message';
- }
- }
- fclose($pipes[1]);
- fclose($pipes[2]);
- proc_close($process);
- } else {
- // The command is still running. Let's wait some
- // time before we start the next cycle.
- usleep(10000);
- }
- }
- } else {
- if ($hasInput) {
- if ($isInputStream) {
- stream_copy_to_stream($this->_stdIn, $pipes[0]);
- } elseif ($isInputString) {
- fwrite($pipes[0], $this->_stdIn);
- }
- fclose($pipes[0]);
- }
- $this->_stdOut = stream_get_contents($pipes[1]);
- $this->_stdErr = stream_get_contents($pipes[2]);
- fclose($pipes[1]);
- fclose($pipes[2]);
- $this->_exitCode = proc_close($process);
- }
- if ($this->_exitCode !== 0) {
- $this->_error = $this->_stdErr ?
- $this->_stdErr :
- "Failed without error message: $command (Exit code: {$this->_exitCode})";
- return false;
- }
- } else {
- $this->_error = "Could not run command $command";
- return false;
- }
- }
- $this->_executed = true;
- return true;
- }
- /**
- * @return bool whether we are on a Windows OS
- */
- public function getIsWindows()
- {
- return strncasecmp(PHP_OS, 'WIN', 3)===0;
- }
- /**
- * @return string the current command string to execute
- */
- public function __toString()
- {
- return (string) $this->getExecCommand();
- }
- }
|