https://github.com/mikehaertl/php-shellcommand
A simple object oriented interface to execute shell commands in PHP
https://github.com/mikehaertl/php-shellcommand
Last synced: 8 months ago
JSON representation
A simple object oriented interface to execute shell commands in PHP
- Host: GitHub
- URL: https://github.com/mikehaertl/php-shellcommand
- Owner: mikehaertl
- License: mit
- Created: 2014-07-07T11:52:01.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2023-04-19T08:26:02.000Z (over 2 years ago)
- Last Synced: 2025-04-07T17:06:19.125Z (9 months ago)
- Language: PHP
- Size: 97.7 KB
- Stars: 321
- Watchers: 10
- Forks: 55
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-php - php-shellcommand - A simple object oriented interface to execute shell commands in PHP (命令行( Command Line ))
README
php-shellcommand
================
[](https://github.com/mikehaertl/php-shellcommand/actions)
[](https://packagist.org/packages/mikehaertl/php-shellcommand)
[](https://packagist.org/packages/mikehaertl/php-shellcommand)
[](https://github.com/mikehaertl/php-shellcommand/blob/master/LICENSE)
[](https://packagist.org/packages/mikehaertl/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`, `stdErr` and `exitCode`
* 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
```php
execute()) {
echo $command->getOutput();
} else {
echo $command->getError();
$exitCode = $command->getExitCode();
}
```
### Advanced Features
#### Add Arguments
```php
addArg('--name=', "d'Artagnan");
// Add argument with several values
// results in --keys key1 key2
$command->addArg('--keys', ['key1','key2']);
```
### Pipe Input Into Command
From string:
```php
setStdIn('{"foo": 0}');
if (!$command->execute()) {
echo $command->getError();
} else {
echo $command->getOutput();
}
// Output:
// {
// "foo": 0
// }
```
From file:
```php
setStdIn($fh);
if (!$command->execute()) {
echo $command->getError();
} else {
echo $command->getOutput();
}
fclose($fh);
```
From URL:
```php
setStdIn($fh);
if (!$command->execute()) {
echo $command->getError();
} else {
echo $command->getOutput();
}
fclose($fh);
```
#### Set Command Instance Options
```php
'/usr/local/bin/mycommand',
// Will be passed as environment variables to the command
'procEnv' => [
'DEMOVAR' => 'demovalue'
],
// Will be passed as options to proc_open()
'procOptions' => [
'bypass_shell' => true,
],
]);
```
## 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()`)
* `__toString()`: The result from `getExecCommand()`
* `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. This
will overwrite the args added with `addArgs()`.
* `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 (optional) `$value` will be separated by a space. The key will get
escaped if `$escapeArgs` 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', ['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.
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 or `null` if command was not executed.
* `getExecuted()`: Whether the command was successfully executed.
* `getIsWindows()`: Whether we are on a Windows Owe are on a Windows OS
* `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.