Installation¶

You can install the component in many different ways:

• Use the official Git repository (https://github.com/symfony/Process);
• Install it via Composer (symfony/process on Packagist).

Usage¶

The Process class allows you to execute a command in a sub-process:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use Symfony\Component\Process\Process;

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

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

print $process->getOutput();

The component takes care of the subtle differences between the different platforms when executing the command.

New in version 2.2: The getIncrementalOutput() and getIncrementalErrorOutput() methods were added in Symfony 2.2.

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

Getting real-time Process Output¶

When executing a long running command (like rsync-ing files 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) {
    if (Process::ERR === $type) {
        echo 'ERR > '.$buffer;
    } else {
        echo 'OUT > '.$buffer;
    }
});

New in version 2.1: The non-blocking feature was added in 2.1.

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
 9
10
11
12

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

// ... do other things

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

Stopping a Process¶

Any asynchronous process can be stopped at any time with the stop() method. This method takes a timeout as its argument. Once the timeout is reached, the process is terminated.

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

// ... do other things

$process->stop(3);

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
    <?php echo 'Hello World'; ?>
EOF
);
$process->run();

New in version 2.1: The ProcessBuilder class was added in Symfony 2.1.

To make your code work better on all platforms, you might want to use the ProcessBuilder class instead:

1
2
3
4

use Symfony\Component\Process\ProcessBuilder;

$builder = new ProcessBuilder(array('ls', '-lsa'));
$builder->getProcess()->run();

Process Timeout¶

You can limit the amount of time a process takes to complete by setting a timeout (in seconds):

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 RuntimeException 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);
}