Installation¶

You can install the component in 2 different ways:

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

Then, require the vendor/autoload.php file to enable the autoloading mechanism provided by Composer. Otherwise, your application won't be able to find the classes of this Symfony component.

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
12

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

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

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

echo $process->getOutput();

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

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 foreach 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 $e) {
    echo $e->getMessage();
}

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

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) {
    if (Process::ERR === $type) {
        echo 'ERR > '.$buffer;
    } else {
        echo 'OUT > '.$buffer;
    }
});

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:

$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 argument. 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.

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

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

use Symfony\Component\Process\ProcessBuilder;

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

In case you are building a binary driver, you can use the setPrefix() method to prefix all the generated process commands.

The following example will generate two process commands for a tar binary adapter:

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

use Symfony\Component\Process\ProcessBuilder;

$builder = new ProcessBuilder();
$builder->setPrefix('/usr/bin/tar');

// '/usr/bin/tar' '--list' '--file=archive.tar.gz'
echo $builder
    ->setArguments(array('--list', '--file=archive.tar.gz'))
    ->getProcess()
    ->getCommandLine();

// '/usr/bin/tar' '-xzf' 'archive.tar.gz'
echo $builder
    ->setArguments(array('-xzf', 'archive.tar.gz'))
    ->getProcess()
    ->getCommandLine();

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

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();