The Process Component
The Process Component¶
The Process component executes commands in sub-processes.
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 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.
New in version 2.2: The getIncrementalOutput()
and getIncrementalErrorOutput()
methods
were introduced in Symfony 2.2.
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 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:
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 introduced 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:
$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 wait()
method is blocking,
which means that your code will halt at this line until the external
process is completed.
Stopping a Process¶
New in version 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
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:
$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();
New in version 2.3: The ProcessBuilder::setPrefix
method was introduced in Symfony 2.3.
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:
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\Component\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 Signals¶
New in version 2.3: The signal
method was introduced in Symfony 2.3.
When running a program asynchronously, you can send it POSIX signals with the
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¶
New in version 2.3: The getPid
method was introduced in Symfony 2.3.
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();
|
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.
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.