php-shellcommand

by mikehaertl

mikehaertl / php-shellcommand

A simple object oriented interface to execute shell commands in PHP

214 Stars 42 Forks Last release: 2 months ago (1.6.2) MIT License 93 Commits 22 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

php-shellcommand

Build Status Latest Stable Version Total Downloads Latest Unstable Version License

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
    ,
    stdErr
    and
    exitCode
  • Handle argument escaping
  • Pass environment vars and other options to
    proc_open()

Examples

Basic Example

// 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

// 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,
),

));

// 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'));

// Add string to pipe to command on standard input $command->setStdIn('string');

API

Properties

  • $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
    .
  • $useExec
    : Whether to use
    exec()
    instead of
    proc_open()
    . This is a workaround for OS which have problems with
    proc_open()
    . Default is
    false
    .
  • $captureStdErr
    : Whether to capture stderr when
    useExec
    is set. This will try to redirect the otherwhise unavailable
    stderr
    to
    stdout
    , so that both have the same content on error. Default is
    true
    .
  • $procCwd
    : The initial working dir passed to
    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.
  • $nonBlockingMode
    : 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. 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 is
    null
    which means the process is never terminated.
  • $locale
    : The locale to (temporarily) set with
    setlocale()
    before running the command. This can be set to e.g.
    en_US.UTF-8
    if 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 (see
      setOptions()
      )
  • 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 a
      command
      option which will be passed to
      setCommand().
  • setCommand($command)
    : Set command
    • $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 through
      escapeshellcmd()
      .
  • getCommand()
    : The command that was set through
    setCommand()
    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!
  • getArgs()
    : The command arguments that where set through
    setArgs()
    or
    addArg()
    , as string
  • addArg($key, $value=null, $escape=null)
    : Add argument with correct escaping
    • $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
      .
    • $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'".
    • $escape
      : If set, this overrides the
      $escapeArgs
      setting and enforces escaping/no escaping
  • setStdIn()
    : String or resource to supply to command via standard input.
  • 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.
  • getExecuted()
    : Whether the command was successfully executed.
  • execute()
    : Executes the command and returns
    true
    on success,
    false
    otherwhise.

Note:

getError()
,
getStdErr()
and
getOutput()
return the trimmed output. You can pass
false
to these methods if you need any possible line breaks at the end.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.