The Process Component

Installation

1

$ composer require symfony/process

Usage

The Process class executes a command in a sub-process, taking care of the differences between operating system and escaping arguments to prevent security issues. It replaces PHP functions like exec, passthru, shell_exec and system:

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\Component\Process\Exception\ProcessFailedException;
use Symfony\Component\Process\Process;

$process = new Process(['ls', '-lsa']);
$process->run();

// executes after the command finishes
if (!$process->isSuccessful()) {
    throw new ProcessFailedException($process);
}

echo $process->getOutput();

The getOutput() method always returns the whole content of the standard output of the command and getErrorOutput() the content of the error output. Alternatively, the getIncrementalOutput() and getIncrementalErrorOutput() methods return the new output since the last call.

The clearOutput() method clears the contents of the output and clearErrorOutput() clears the contents of the error output.

You can also use the Process class with the for each construct to get the output while it is generated. By default, the loop waits for new output before going to the next iteration:

1
2
3
4
5
6
7
8
9
10

$process = new Process(['ls', '-lsa']);
$process->start();

foreach ($process as $type => $data) {
    if ($process::OUT === $type) {
        echo "\nRead from stdout: ".$data;
    } else { // $process::ERR === $type
        echo "\nRead from stderr: ".$data;
    }
}

1
2
3
4
5
6

$process = new Process(['ls', '-lsa']);
$process->start();
$iterator = $process->getIterator($process::ITER_SKIP_ERR | $process::ITER_KEEP_OUTPUT);
foreach ($iterator as $data) {
    echo $data."\n";
}

The mustRun() method is identical to run(), except that it will throw a ProcessFailedException if the process couldn't be executed successfully (i.e. the process exited with a non-zero code):

1
2
3
4
5
6
7
8
9
10
11
12

use Symfony\Component\Process\Exception\ProcessFailedException;
use Symfony\Component\Process\Process;

$process = new Process(['ls', '-lsa']);

try {
    $process->mustRun();

    echo $process->getOutput();
} catch (ProcessFailedException $exception) {
    echo $exception->getMessage();
}

Configuring Process Options

Symfony uses the PHP proc_open function to run the processes. You can configure the options passed to the other_options argument of proc_open() using the setOptions() method:

1
2
3

$process = new Process(['...', '...', '...']);
// this option allows a subprocess to continue running after the main script exited
$process->setOptions(['create_new_console' => true]);

Using Features From the OS Shell

Using an array of arguments is the recommended way to define commands. This saves you from any escaping and allows sending signals seamlessly (e.g. to stop processes while they run):

1
2

$process = new Process(['/path/command', '--option', 'argument', 'etc.']);
$process = new Process(['/path/to/php', '--define', 'memory_limit=1024M', '/path/to/script.php']);

If you need to use stream redirections, conditional execution, or any other feature provided by the shell of your operating system, you can also define commands as strings using the fromShellCommandline() static factory.

Each operating system provides a different syntax for their command-lines, so it becomes your responsibility to deal with escaping and portability.

When using strings to define commands, variable arguments are passed as environment variables using the second argument of the run(), mustRun() or start() methods. Referencing them is also OS-dependent:

1
2
3
4
5
6
7
8

// On Unix-like OSes (Linux, macOS)
$process = Process::fromShellCommandline('echo "$MESSAGE"');

// On Windows
$process = Process::fromShellCommandline('echo "!MESSAGE!"');

// On both Unix-like and Windows
$process->run(null, ['MESSAGE' => 'Something to output']);

If you prefer to create portable commands that are independent from the operating system, you can write the above command as follows:

1
2

// works the same on Windows , Linux and macOS
$process = Process::fromShellCommandline('echo "${:MESSAGE}"');

Portable commands require using a syntax that is specific to the component: when enclosing a variable name into "${: and }" exactly, the process object will replace it with its escaped value, or will fail if the variable is not found in the list of environment variables attached to the command.

Setting Environment Variables for Processes

The constructor of the Process class and all of its methods related to executing processes (run(), mustRun(), start(), etc.) allow passing an array of environment variables to set while running the process:

1
2
3

$process = new Process(['...'], null, ['ENV_VAR_NAME' => 'value']);
$process = Process::fromShellCommandline('...', null, ['ENV_VAR_NAME' => 'value']);
$process->run(null, ['ENV_VAR_NAME' => 'value']);

In addition to the env vars passed explicitly, processes inherit all the env vars defined in your system. You can prevent this by setting to false the env vars you want to remove:

1
2
3
4

$process = new Process(['...'], null, [
    'APP_ENV' => false,
    'SYMFONY_DOTENV_VARS' => false,
]);

Getting real-time Process Output

When executing a long running command (like rsync to a remote server), you can give feedback to the end user in real-time by passing an anonymous function to the run() method:

1
2
3
4
5
6
7
8
9
10

use Symfony\Component\Process\Process;

$process = new Process(['ls', '-lsa']);
$process->run(function ($type, $buffer): void {
    if (Process::ERR === $type) {
        echo 'ERR > '.$buffer;
    } else {
        echo 'OUT > '.$buffer;
    }
});

Running Processes Asynchronously

You can also start the subprocess and then let it run asynchronously, retrieving output and the status in your main process whenever you need it. Use the start() method to start an asynchronous process, the isRunning() method to check if the process is done and the getOutput() method to get the output:

1
2
3
4
5
6
7
8

$process = new Process(['ls', '-lsa']);
$process->start();

while ($process->isRunning()) {
    // waiting for process to finish
}

echo $process->getOutput();

You can also wait for a process to end if you started it asynchronously and are done doing other stuff:

1
2
3
4
5
6
7
8

$process = new Process(['ls', '-lsa']);
$process->start();

// ... do other things

$process->wait();

// ... do things after the process has finished

wait() takes one optional argument: a callback that is called repeatedly whilst the process is still running, passing in the output and its type:

1
2
3
4
5
6
7
8
9
10

$process = new Process(['ls', '-lsa']);
$process->start();

$process->wait(function ($type, $buffer): void {
    if (Process::ERR === $type) {
        echo 'ERR > '.$buffer;
    } else {
        echo 'OUT > '.$buffer;
    }
});

Instead of waiting until the process has finished, you can use the waitUntil() method to keep or stop waiting based on some PHP logic. The following example starts a long running process and checks its output to wait until its fully initialized:

1
2
3
4
5
6
7
8
9
10
11

$process = new Process(['/usr/bin/php', 'slow-starting-server.php']);
$process->start();

// ... do other things

// waits until the given anonymous function returns true
$process->waitUntil(function ($type, $output): bool {
    return $output === 'Ready. Waiting for commands...';
});

// ... do things after the process is ready

Streaming to the Standard Input of a Process

Before a process is started, you can specify its standard input using either the setInput() method or the 4th argument of the constructor. The provided input can be a string, a stream resource or a Traversable object:

1
2
3

$process = new Process(['cat']);
$process->setInput('foobar');
$process->run();

When this input is fully written to the subprocess standard input, the corresponding pipe is closed.

In order to write to a subprocess standard input while it is running, the component provides the InputStream class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

$input = new InputStream();
$input->write('foo');

$process = new Process(['cat']);
$process->setInput($input);
$process->start();

// ... read process output or do other things

$input->write('bar');
$input->close();

$process->wait();

// will echo: foobar
echo $process->getOutput();

The write() method accepts scalars, stream resources or Traversable objects as arguments. As shown in the above example, you need to explicitly call the close() method when you are done writing to the standard input of the subprocess.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

$stream = fopen('php://temporary', 'w+');

$process = new Process(['cat']);
$process->setInput($stream);
$process->start();

fwrite($stream, 'foo');

// ... read process output or do other things

fwrite($stream, 'bar');
fclose($stream);

$process->wait();

// will echo: 'foobar'
echo $process->getOutput();

Using TTY and PTY Modes

All examples above show that your program has control over the input of a process (using setInput()) and the output from that process (using getOutput()). The Process component has two special modes that tweak the relationship between your program and the process: teletype (tty) and pseudo-teletype (pty).

In TTY mode, you connect the input and output of the process to the input and output of your program. This allows for instance to open an editor like Vim or Nano as a process. You enable TTY mode by calling setTty():

1
2
3
4
5
6
7

$process = new Process(['vim']);
$process->setTty(true);
$process->run();

// As the output is connected to the terminal, it is no longer possible
// to read or modify the output from the process!
dump($process->getOutput()); // null

In PTY mode, your program behaves as a terminal for the process instead of a plain input and output. Some programs behave differently when interacting with a real terminal instead of another program. For instance, some programs prompt for a password when talking with a terminal. Use setPty() to enable this mode.

Stopping a Process

Any asynchronous process can be stopped at any time with the stop() method. This method takes two arguments: a timeout and a signal. Once the timeout is reached, the signal is sent to the running process. The default signal sent to a process is SIGKILL. Please read the signal documentation below to find out more about signal handling in the Process component:

1
2
3
4
5
6

$process = new Process(['ls', '-lsa']);
$process->start();

// ... do other things

$process->stop(3, SIGINT);

Executing PHP Code in Isolation

If you want to execute some PHP code in isolation, use the PhpProcess instead:

1
2
3
4
5
6
7

use Symfony\Component\Process\PhpProcess;

$process = new PhpProcess(<<<EOF
    <?= 'Hello World' ?>
EOF
);
$process->run();

Process Timeout

By default processes have a timeout of 60 seconds, but you can change it passing a different timeout (in seconds) to the setTimeout() method:

1
2
3
4
5

use Symfony\Component\Process\Process;

$process = new Process(['ls', '-lsa']);
$process->setTimeout(3600);
$process->run();

If the timeout is reached, a ProcessTimedOutException is thrown.

For long running commands, it is your responsibility to perform the timeout check regularly:

1
2
3
4
5
6
7
8
9
10
11

$process->setTimeout(3600);
$process->start();

while ($condition) {
    // ...

    // check if the timeout is reached
    $process->checkTimeout();

    usleep(200000);
}

Process Idle Timeout

In contrast to the timeout of the previous paragraph, the idle timeout only considers the time since the last output was produced by the process:

1
2
3
4
5
6

use Symfony\Component\Process\Process;

$process = new Process(['something-with-variable-runtime']);
$process->setTimeout(3600);
$process->setIdleTimeout(60);
$process->run();

In the case above, a process is considered timed out, when either the total runtime exceeds 3600 seconds, or the process does not produce any output for 60 seconds.

Process Signals

When running a program asynchronously, you can send it POSIX signals with the signal() method:

1
2
3
4
5
6
7

use Symfony\Component\Process\Process;

$process = new Process(['find', '/', '-name', 'rabbit']);
$process->start();

// will send a SIGKILL to the process
$process->signal(SIGKILL);

Process Pid

You can access the pid of a running process with the getPid() method:

1
2
3
4
5
6

use Symfony\Component\Process\Process;

$process = new Process(['/usr/bin/php', 'worker.php']);
$process->start();

$pid = $process->getPid();

Disabling Output

As standard output and error output are always fetched from the underlying process, it might be convenient to disable output in some cases to save memory. Use disableOutput() and enableOutput() to toggle this feature:

1
2
3
4
5

use Symfony\Component\Process\Process;

$process = new Process(['/usr/bin/php', 'worker.php']);
$process->disableOutput();
$process->run();

Finding an Executable

The Process component provides a utility class called ExecutableFinder which finds and returns the absolute path of an executable:

1
2
3
4
5

use Symfony\Component\Process\ExecutableFinder;

$executableFinder = new ExecutableFinder();
$chromedriverPath = $executableFinder->find('chromedriver');
// $chromedriverPath = '/usr/local/bin/chromedriver' (the result will be different on your computer)

The find() method also takes extra parameters to specify a default value to return and extra directories where to look for the executable:

1
2
3
4

use Symfony\Component\Process\ExecutableFinder;

$executableFinder = new ExecutableFinder();
$chromedriverPath = $executableFinder->find('chromedriver', '/path/to/chromedriver', ['local-bin/']);

Finding the Executable PHP Binary

This component also provides a special utility class called PhpExecutableFinder which returns the absolute path of the executable PHP binary available on your server:

1
2
3
4
5

use Symfony\Component\Process\PhpExecutableFinder;

$phpBinaryFinder = new PhpExecutableFinder();
$phpBinaryPath = $phpBinaryFinder->find();
// $phpBinaryPath = '/usr/local/bin/php' (the result will be different on your computer)

Checking for TTY Support

Another utility provided by this component is a method called isTtySupported() which returns whether TTY is supported on the current operating system:

1
2
3

use Symfony\Component\Process\Process;

$process = (new Process())->setTty(Process::isTtySupported());