Skip to content

Latest commit

 

History

History
292 lines (205 loc) · 8.87 KB

process.rst

File metadata and controls

292 lines (205 loc) · 8.87 KB
Raw

single: Process single: Components; Process

The Process Component

The Process component executes commands in sub-processes.

Installation

You can install the component in 2 different ways:

Usage

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

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.

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 Symfony\\Component\\Process\\Process::getIncrementalOutput and Symfony\\Component\\Process\\Process::getIncrementalErrorOutput methods returns the new outputs since the last call.

2.4 The clearOutput() and clearErrorOutput() methods were introduced in Symfony 2.4.

The Symfony\\Component\\Process\\Process::clearOutput method clears the contents of the output and Symfony\\Component\\Process\\Process::clearErrorOutput clears the contents of the error output.

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 Symfony\\Component\\Process\\Process::run method:

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 Symfony\\Component\\Process\\Process::start method to start an asynchronous process, the Symfony\\Component\\Process\\Process::isRunning method to check if the process is done and the Symfony\\Component\\Process\\Process::getOutput method to get the output:

$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:

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

Note

The Symfony\\Component\\Process\\Process::wait method is blocking, which means that your code will halt at this line until the external process is completed.

Stopping a Process

2.3 The signal parameter of the stop method was introduced in Symfony 2.3.

Any asynchronous process can be stopped at any time with the Symfony\\Component\\Process\\Process::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<reference-process-signal> to find out more about signal handling in the Process component:

$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:

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 Symfony\\Component\\Process\\ProcessBuilder class instead:

use Symfony\Component\Process\ProcessBuilder;

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

2.3 The ProcessBuilder::setPrefix<Symfony\\Component\\Process\\ProcessBuilder::setPrefix> method was introduced in Symfony 2.3.

In case you are building a binary driver, you can use the Symfony\\Component\\Process\\Process::setPrefix method to prefix all the generated process commands.

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

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):

use Symfony\Component\Process\Process;

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

If the timeout is reached, a Symfony\\Process\\Exception\\RuntimeException is thrown.

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

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

while ($condition) {
    // ...

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

    usleep(200000);
}

Process Idle Timeout

2.4 The Symfony\\Component\\Process\\Process::setIdleTimeout method was added in Symfony 2.4.

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:

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

2.3 The signal method was introduced in Symfony 2.3.

When running a program asynchronously, you can send it posix signals with the Symfony\\Component\\Process\\Process::signal method:

use Symfony\Component\Process\Process;

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

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

Caution

Due to some limitations in PHP, if you're using signals with the Process component, you may have to prefix your commands with exec. Please read Symfony Issue#5759 and PHP Bug#39992 to understand why this is happening.

POSIX signals are not available on Windows platforms, please refer to the PHP documentation for available signals.

Process Pid

2.3 The getPid method was introduced in Symfony 2.3.

You can access the pid of a running process with the Symfony\\Component\\Process\\Process::getPid method.

use Symfony\Component\Process\Process;

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

$pid = $process->getPid();

Caution

Due to some limitations in PHP, if you want to get the pid of a symfony Process, you may have to prefix your commands with exec. Please read Symfony Issue#5759 to understand why this is happening.