Php Shellcommand Laravel Package

Getting Started

Start by requiring the package via Composer: composer require mikehaertl/php-shellcommand. Then, instantiate a ShellCommand object with the base command and execute it:

use mikehaertl\ShellCommand\ShellCommand;

$command = new ShellCommand(['ls', '-la', '/tmp']);
if ($command->execute()) {
    echo $command->getOutput();     // stdout
    echo $command->getErrorOutput(); // stderr
    echo $command->getExitCode();   // 0 on success
} else {
    throw new \RuntimeException($command->getError());
}

First use case: integrating with system CLI tools (e.g., ffmpeg, convert, git, node) from web tasks like media processing, file generation, or CI orchestration—without messy string concatenation or manual escapeshellarg() calls.

Implementation Patterns

• Safe argument building: Pass command + args as array to avoid injection risks:
  new ShellCommand(['git', 'clone', $url, $dir]) automatically escapes args.
• Environment isolation: Use setEnv() to define process-specific env vars without polluting the global environment:
  $command->setEnv(['PATH' => '/usr/local/bin', 'CUSTOM_VAR' => 'value'])
• Working directory control: setCwd('/app/tmp') ensures commands run in the right context—especially useful for tools like npm or composer.
• Timeout enforcement: Prevent stuck processes with setTimeout(30) (seconds) or setTimeout(0) for no limit.
• Async-friendly handling: Use executeAsync() to spawn background processes (e.g., sending notifications, report generation), then poll isRunning() or wait().
• Stdin piping: Feed data programmatically via setStdin('content'), useful for tools expecting pipe input (e.g., gzip, sha256sum).
• Log & debug: Leverage getFullCommand() for logging the exact shell invocation used (helps reproducibility).

Gotchas and Tips

• Windows compatibility: Escape behavior and shell syntax differ on Windows. Prefer ['binary', '--flag', 'value'] over string commands—avoid cmd.exe pitfalls by using full paths where possible.
• Exit code ≠ success: Some tools (e.g., grep, rsync) return non-zero exit codes for non-error conditions. Always cross-check with getErrorOutput() and tool documentation.
• Large output handling: getOutput() loads entire output into memory. For large outputs (e.g., tail -f or find . | xargs), consider streaming: implement outputCallback via setOutputCallback(fn($line) => fwrite(STDOUT, $line)).
• Resource cleanup: If using executeAsync(), explicitly wait() or end() to avoid zombie processes—especially in CLI scripts.
• Debugging failures: Enable setShowError(true) on the ShellCommand instance to see the raw proc_open() error message when execution fails unexpectedly.
• Permissions & safe_mode: open_basedir or safe_mode (deprecated but still present) may block command execution—always test in production-like environments.