Static Public Member Functions
static	background (string $command)
static	exec (string $executable, array $args=[], string &$stderr='')
static	execCombined (string $executable, array $args=[])
static	execToFile (string $executable, array $args, string $stdoutFile, string $stderrFile)
static	shellExec (string $command)
static	stream (string $executable, array $args, callable $lineCallback)

Static Private Member Functions
static	writeLog (string $log)

Detailed Description

Class CommandRunner

Centralizes all PHP shell-execution primitives (proc_open, popen, shell_exec) so that every external command goes through a single, auditable point with consistent argument escaping and logging.

Three execution modes:

exec() capture stdout/stderr, hidden console window (replaces proc_open)
stream() stream output line-by-line via callback (replaces popen)
shellExec() capture output from a fully-formed command (replaces shell_exec)

Rules:

exec() and stream() always escapeshellarg() every argument individually.
shellExec() is reserved for hardcoded commands with no dynamic user input. Pass dynamic arguments through exec() or stream() instead.

Definition at line 27 of file class.commandrunner.php.

Member Function Documentation

◆ background()

background ( string $command )

static

Launch a command in the background without waiting for output.

Uses the Windows "start /B" cmd.exe idiom to detach the process immediately. The caller is responsible for ensuring $command is properly constructed; use escapeshellarg() on any dynamic values before passing them in.

Parameters

string $command Fully-formed command string to run in the background.

Definition at line 220 of file class.commandrunner.php.

                                                      : void
    {
        self::writeLog('CommandRunner::background: ' . $command);
        pclose(popen('start /B ' . $command, 'r'));
    }

References $command, and writeLog().

Referenced by QuickPick\installModule().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ exec()

exec	(	string	$executable,
		array	$args = [],
		string &	$stderr = '' )

static

Execute an executable with arguments, capturing stdout and stderr.

Each argument is individually escaped with escapeshellarg(). The console window is hidden on Windows via bypass_shell + CREATE_NO_WINDOW semantics.

Parameters

string	$executable	Path to the executable (will be escapeshellarg'd).
array	$args	Arguments, each will be escapeshellarg'd.
string	$stderr	Populated with any stderr output on return.

Returns: string|false stdout output on success, false if the process could not start.

Definition at line 52 of file class.commandrunner.php.

                                                                                       : string|false
    {
        $cmd = escapeshellarg($executable);
        foreach ($args as $arg) {
            $cmd .= ' ' . escapeshellarg((string)$arg);
        }
 
        self::writeLog('CommandRunner::exec: ' . $cmd);
 
        $descriptorspec = [
            0 => ['pipe', 'r'],
            1 => ['pipe', 'w'],
            2 => ['pipe', 'w'],
        ];
 
        $process = @proc_open($cmd, $descriptorspec, $pipes, null, null, ['bypass_shell' => true]);
 
        if (!is_resource($process)) {
            self::writeLog('CommandRunner::exec: failed to start process: ' . $cmd);
 
            return false;
        }
 
        fclose($pipes[0]);
        $output = stream_get_contents($pipes[1]);
        $stderr = stream_get_contents($pipes[2]);
        fclose($pipes[1]);
        fclose($pipes[2]);
        proc_close($process);
 
        if (!empty($stderr)) {
            self::writeLog('CommandRunner::exec stderr: ' . $stderr);
        }
 
        return $output;
    }

References writeLog().

Referenced by execCombined().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ execCombined()

execCombined	(	string	$executable,
		array	$args = [] )

static

Execute an executable with arguments, combining stdout and stderr.

Convenience wrapper around exec() for callers that need both streams merged (e.g. sc.exe which may send status messages to either stream).

Parameters

string	$executable	Path to the executable (will be escapeshellarg'd).
array	$args	Arguments, each will be escapeshellarg'd.

Returns: string|false Combined output, or false if the process could not start.

Definition at line 147 of file class.commandrunner.php.

                                                                           : string|false
    {
        $stderr = '';
        $output = self::exec($executable, $args, $stderr);
 
        if ($output === false) {
            return false;
        }
 
        if (!empty($stderr)) {
            $output .= "\n" . $stderr;
        }
 
        return $output;
    }

References exec().

Referenced by Win32Service\fastServiceCheck().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ execToFile()

execToFile	(	string	$executable,
		array	$args,
		string	$stdoutFile,
		string	$stderrFile )

static

Execute an executable with arguments, redirecting stdout and stderr to files.

Capturing large output through a pipe with stream_get_contents() can be extremely slow on Windows, so this variant lets the child process write its output directly to the given files. The caller reads and cleans up the files.

Parameters

string	$executable	Path to the executable (will be escapeshellarg'd).
array	$args	Arguments, each will be escapeshellarg'd.
string	$stdoutFile	File path the child's stdout is redirected to.
string	$stderrFile	File path the child's stderr is redirected to.

Returns: int|false Process exit code on success, false if the process could not start.

Definition at line 103 of file class.commandrunner.php.

                                                                                                              : int|false
    {
        $cmd = escapeshellarg($executable);
        foreach ($args as $arg) {
            $cmd .= ' ' . escapeshellarg((string)$arg);
        }
 
        self::writeLog('CommandRunner::execToFile: ' . $cmd);
 
        $process = @proc_open(
            $cmd,
            [
                0 => ['pipe', 'r'],
                1 => ['file', $stdoutFile, 'w'],
                2 => ['file', $stderrFile, 'w'],
            ],
            $pipes,
            null,
            null,
            ['bypass_shell' => true]
        );
 
        if (!is_resource($process)) {
            self::writeLog('CommandRunner::execToFile: failed to start process: ' . $cmd);
 
            return false;
        }
 
        fclose($pipes[0]);
 
        return proc_close($process);
    }

References writeLog().

Referenced by Core\isSafeDestinationFileList().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ shellExec()

shellExec ( string $command )

static

Execute a fully-formed shell command and return its output.

Only use this for commands that contain no dynamic user input (e.g. hardcoded system queries such as "net session" or "whoami /groups"). For commands with dynamic arguments, use exec() or stream() instead so that escaping is enforced at the boundary.

Parameters

string $command Fully-formed command string. Must not contain unescaped user input.

Returns: string|null Command output, or null if the command could not be run.

Definition at line 238 of file class.commandrunner.php.

                                                     : ?string
    {
        self::writeLog('CommandRunner::shellExec: ' . $command);
 
        return shell_exec($command);
    }

References $command, and writeLog().

Referenced by Util\isAdmin().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ stream()

stream	(	string	$executable,
		array	$args,
		callable	$lineCallback )

static

Execute an executable with arguments, streaming output line-by-line.

Useful for long-running processes that emit progress information. Each argument is individually escaped with escapeshellarg(). Lines are split on carriage-return (\r) to match Windows progress-reporting conventions. Any data remaining in the buffer after EOF is flushed as a final line.

Parameters

string	$executable	Path to the executable (will be escapeshellarg'd).
array	$args	Arguments, each will be escapeshellarg'd.
callable	$lineCallback	Invoked with each trimmed output line as a string.

Returns: int|false Process exit code on success, false if the process could not start.

Definition at line 177 of file class.commandrunner.php.

                                                                                          : int|false
    {
        $cmd = escapeshellarg($executable);
        foreach ($args as $arg) {
            $cmd .= ' ' . escapeshellarg((string)$arg);
        }
 
        self::writeLog('CommandRunner::stream: ' . $cmd);
 
        $process = popen($cmd, 'rb');
        if (!$process) {
            self::writeLog('CommandRunner::stream: failed to start process: ' . $cmd);
 
            return false;
        }
 
        $buffer = '';
        while (!feof($process)) {
            $buffer .= fread($process, 8192);
            while (($pos = strpos($buffer, "\r")) !== false) {
                $line   = trim(substr($buffer, 0, $pos));
                $buffer = substr($buffer, $pos + 1);
                $lineCallback($line);
            }
        }
 
        // Flush any remaining data not terminated by \r
        if (!empty($buffer)) {
            $lineCallback(trim($buffer));
        }
 
        return pclose($process);
    }

References writeLog().

Referenced by Core\unzipFile().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ writeLog()

writeLog ( string $log )

staticprivate

Writes a log entry to the batch log file.

Parameters

string $log The message to log.

Definition at line 34 of file class.commandrunner.php.

                                                 : void
    {
        global $bearsamppRoot;
        Log::debug($log, Path::getBatchLogFilePath());
    }