{"id":16316527,"url":"https://github.com/mikehaertl/php-shellcommand","last_synced_at":"2025-05-15T14:08:22.228Z","repository":{"id":18387763,"uuid":"21568784","full_name":"mikehaertl/php-shellcommand","owner":"mikehaertl","description":"A simple object oriented interface to execute shell commands in PHP","archived":false,"fork":false,"pushed_at":"2023-04-19T08:26:02.000Z","size":100,"stargazers_count":321,"open_issues_count":5,"forks_count":55,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-07T17:06:19.125Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikehaertl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2014-07-07T11:52:01.000Z","updated_at":"2025-01-14T10:42:03.000Z","dependencies_parsed_at":"2024-01-12T10:26:06.347Z","dependency_job_id":"b2a02fc7-f288-4aa3-8112-e41713790add","html_url":"https://github.com/mikehaertl/php-shellcommand","commit_stats":{"total_commits":84,"total_committers":16,"mean_commits":5.25,"dds":0.3214285714285714,"last_synced_commit":"e79ea528be155ffdec6f3bf1a4a46307bb49e545"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikehaertl%2Fphp-shellcommand","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikehaertl%2Fphp-shellcommand/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikehaertl%2Fphp-shellcommand/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikehaertl%2Fphp-shellcommand/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikehaertl","download_url":"https://codeload.github.com/mikehaertl/php-shellcommand/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254355335,"owners_count":22057354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T22:04:53.889Z","updated_at":"2025-05-15T14:08:17.214Z","avatar_url":"https://github.com/mikehaertl.png","language":"PHP","funding_links":[],"categories":["命令行( Command Line )"],"sub_categories":[],"readme":"php-shellcommand\n================\n\n[![GitHub Tests](https://github.com/mikehaertl/php-shellcommand/workflows/Tests/badge.svg)](https://github.com/mikehaertl/php-shellcommand/actions)\n[![Packagist Version](https://img.shields.io/packagist/v/mikehaertl/php-shellcommand?label=version)](https://packagist.org/packages/mikehaertl/php-shellcommand)\n[![Packagist Downloads](https://img.shields.io/packagist/dt/mikehaertl/php-shellcommand)](https://packagist.org/packages/mikehaertl/php-shellcommand)\n[![GitHub license](https://img.shields.io/github/license/mikehaertl/php-shellcommand)](https://github.com/mikehaertl/php-shellcommand/blob/master/LICENSE)\n[![Packagist PHP Version Support](https://img.shields.io/packagist/php-v/mikehaertl/php-shellcommand)](https://packagist.org/packages/mikehaertl/php-shellcommand)\n\nphp-shellcommand provides a simple object oriented interface to execute shell commands.\n\n## Installing\n\n### Prerequisites\n\nYour php version must be `5.4` or later.\n\n### Installing with composer\n\nThis package can be installed easily using composer.\n\n```\ncomposer require mikehaertl/php-shellcommand\n```\n\n## Features\n\n * Catches `stdOut`, `stdErr` and `exitCode`\n * Handle argument escaping\n * Pass environment vars and other options to `proc_open()`\n * Pipe resources like files or streams into the command\n * Timeout for execution\n\n## Examples\n\n### Basic Example\n\n```php\n\u003c?php\nuse mikehaertl\\shellcommand\\Command;\n\n// Basic example\n$command = new Command('/usr/local/bin/mycommand -a -b');\nif ($command-\u003eexecute()) {\n    echo $command-\u003egetOutput();\n} else {\n    echo $command-\u003egetError();\n    $exitCode = $command-\u003egetExitCode();\n}\n```\n\n### Advanced Features\n\n#### Add Arguments\n```php\n\u003c?php\n$command = new Command('/bin/somecommand');\n// Add arguments with correct escaping:\n// results in --name='d'\\''Artagnan'\n$command-\u003eaddArg('--name=', \"d'Artagnan\");\n\n// Add argument with several values\n// results in --keys key1 key2\n$command-\u003eaddArg('--keys', ['key1','key2']);\n```\n\n### Pipe Input Into Command\n\nFrom string:\n```php\n\u003c?php\n$command = new ('jq'); // jq is a pretty printer\n$command-\u003esetStdIn('{\"foo\": 0}');\nif (!$command-\u003eexecute()) {\n    echo $command-\u003egetError();\n} else {\n    echo $command-\u003egetOutput();\n}\n// Output:\n// {\n//   \"foo\": 0\n// }\n```\n\nFrom file:\n```php\n\u003c?php\n$fh = fopen('test.json', 'r');\n// error checks left out...\n$command = new Command('jq');\n$command-\u003esetStdIn($fh);\nif (!$command-\u003eexecute()) {\n    echo $command-\u003egetError();\n} else {\n    echo $command-\u003egetOutput();\n}\nfclose($fh);\n```\nFrom URL:\n```php\n\u003c?php\n$fh = fopen('https://api.open-meteo.com/v1/forecast?latitude=52.52\u0026longitude=13.41\u0026hourly=temperature_2m,relativehumidity_2m,windspeed_10m', 'r');\n// error checks left out...\n$command = new Command('jq');\n$command-\u003esetStdIn($fh);\nif (!$command-\u003eexecute()) {\n    echo $command-\u003egetError();\n} else {\n    echo $command-\u003egetOutput();\n}\nfclose($fh);\n```\n\n#### Set Command Instance Options\n```php\n\u003c?php\n// Create command with options array\n$command = new Command([\n    'command' =\u003e '/usr/local/bin/mycommand',\n\n    // Will be passed as environment variables to the command\n    'procEnv' =\u003e [\n        'DEMOVAR' =\u003e 'demovalue'\n    ],\n\n    // Will be passed as options to proc_open()\n    'procOptions' =\u003e [\n        'bypass_shell' =\u003e true,\n    ],\n]);\n```\n\n## API\n\n### Properties\n\n * `$escapeArgs`: Whether to escape any argument passed through `addArg()`. Default is `true`.\n * `$escapeCommand`: Whether to escape the command passed to `setCommand()` or the constructor.\n    This is only useful if `$escapeArgs` is `false`. Default is `false`.\n * `$useExec`: Whether to use `exec()` instead of `proc_open()`. This is a workaround for OS which\n   have problems with `proc_open()`. Default is `false`.\n * `$captureStdErr`: Whether to capture stderr when `useExec` is set. This will try to redirect\n   the otherwhise unavailable `stderr` to `stdout`, so that both have the same content on error.\n   Default is `true`.\n * `$procCwd`: The initial working dir passed to `proc_open()`. Default is `null` for current\n    PHP working dir.\n * `$procEnv`: An array with environment variables to pass to `proc_open()`. Default is `null` for none.\n * `$procOptions`: An array of `other_options` for `proc_open()`. Default is `null` for none.\n * `$nonBlockingMode`: Whether to set the stdin/stdout/stderr streams to non-blocking\n    mode when `proc_open()` is used. This allows to have huge inputs/outputs\n    without making the process hang. The default is `null` which will enable\n    the feature on Non-Windows systems. Set it to `true` or `false` to manually\n    enable/disable it. Note that it doesn't work on Windows.\n * `$timeout`: The time in seconds after which the command should be\n    terminated. This only works in non-blocking mode. Default is `null` which\n    means the process is never terminated.\n * `$locale`: The locale to (temporarily) set with `setlocale()` before running the command.\n   This can be set to e.g. `en_US.UTF-8` if you have issues with UTF-8 encoded arguments.\n\nYou can configure all these properties via an array that you pass in the constructor. You can also\npass `command`, `execCommand` and `args` as options. This will call the respective setter (`setCommand()`,\n`setExecCommand()`, etc.).\n\n### Methods\n\n * `__construct($options = null)`\n    * `$options`: either a command string or an options array (see `setOptions()`)\n * `__toString()`: The result from `getExecCommand()`\n * `setOptions($options)`: Set command options\n    * `$options`: array of name =\u003e value options that should be applied to the object.\n       You can also pass options that use a setter, e.g. you can pass a `command` option which\n       will be passed to `setCommand().`\n * `setCommand($command)`: Set command\n    * `$command`: The command or full command string to execute, like `gzip` or `gzip -d`.\n       You can still call `addArg()` to add more arguments to the command. If `$escapeCommand` was\n       set to `true`, the command gets escaped through `escapeshellcmd()`.\n * `getCommand()`: The command that was set through `setCommand()` or passed to the constructor.\n * `getExecCommand()`: The full command string to execute.\n * `setArgs($args)`: Set argument as string\n    * `$args`: The command arguments as string. Note, that these will not get escaped. This\n      will overwrite the args added with `addArgs()`.\n * `getArgs()`: The command arguments that where set through `setArgs()` or `addArg()`, as string\n * `addArg($key, $value=null, $escape=null)`: Add argument with correct escaping\n    * `$key`: The argument key to add e.g. `--feature` or `--name=`. If the key does not end with\n       and `=`, the (optional) `$value` will be separated by a space. The key will get\n       escaped if `$escapeArgs` is `true`.\n    * `$value`: The optional argument value which will get escaped if `$escapeArgs` is `true`.\n       An array can be passed to add more than one value for a key, e.g. `addArg('--exclude', ['val1','val2'])`\n       which will create the option \"--exclude 'val1' 'val2'\".\n    * `$escape`: If set, this overrides the `$escapeArgs` setting and enforces escaping/no escaping\n * `setStdIn()`: String or resource to supply to command via standard input.\n   This enables the same functionality as piping on the command line. It can\n   also be a resource like a file handle or a stream in which case its content\n   will be piped into the command like an input redirection.\n * `getOutput()`: The command output as string. Empty if none.\n * `getError()`: The error message, either stderr or internal message. Empty if no error.\n * `getStdErr()`: The stderr output. Empty if none.\n * `getExitCode()`: The exit code or `null` if command was not executed.\n * `getExecuted()`: Whether the command was successfully executed.\n * `getIsWindows()`: Whether we are on a Windows Owe are on a Windows OS\n * `execute()`: Executes the command and returns `true` on success, `false` otherwhise.\n\n\u003e **Note:** `getError()`, `getStdErr()` and `getOutput()` return the trimmed output.\n\u003e You can pass `false` to these methods if you need any possible line breaks at the end.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikehaertl%2Fphp-shellcommand","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikehaertl%2Fphp-shellcommand","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikehaertl%2Fphp-shellcommand/lists"}