The Process Component
Warning: You are browsing the documentation for Symfony 2.x, which is no longer maintained.
Read the updated version of this page for Symfony 7.1 (the current stable version).
The Process component executes commands in sub-processes.
Installation
1
$ composer require symfony/process
Alternatively, you can clone the https://github.com/symfony/process repository.
Note
If you install this component outside of a Symfony application, you must
require the vendor/autoload.php
file in your code to enable the class
autoloading mechanism provided by Composer. Read
this article for more details.
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.
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();
}
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
Note
The wait() method is blocking, which means that your code will halt at this line until the external process is completed.
Note
If a Response
is sent before a child process had a chance to complete,
the server process will be killed (depending on your OS). It means that
your task will be stopped right away. Running an asynchronous process
is not the same as running a process that survives its parent process.
If you want your process to survive the request/response cycle, you can
take advantage of the kernel.terminate
event, and run your command
synchronously inside this event. Be aware that kernel.terminate
is called only if you use PHP-FPM.
Caution
Beware also that if you do that, the said PHP-FPM process will not be available to serve any new request until the subprocess is finished. This means you can quickly block your FPM pool if you're not careful enough. That is why it's generally way better not to do any fancy things even after the request is sent, but to use a job queue instead.
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;
}
});
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
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:
1 2 3 4
use Symfony\Component\Process\ProcessBuilder;
$processBuilder = new ProcessBuilder(array('ls', '-lsa'));
$processBuilder->getProcess()->run();
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
use Symfony\Component\Process\ProcessBuilder;
$processBuilder = new ProcessBuilder();
$processBuilder->setPrefix('/usr/bin/tar');
// '/usr/bin/tar' '--list' '--file=archive.tar.gz'
echo $processBuilder
->setArguments(array('--list', '--file=archive.tar.gz'))
->getProcess()
->getCommandLine();
// '/usr/bin/tar' '-xzf' 'archive.tar.gz'
echo $processBuilder
->setArguments(array('-xzf', 'archive.tar.gz'))
->getProcess()
->getCommandLine();
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 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
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:
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);
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 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.
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();
Caution
You cannot enable or disable the output while the process is running.
If you disable the output, you cannot access getOutput()
,
getIncrementalOutput()
, getErrorOutput()
or getIncrementalErrorOutput()
.
Moreover, you could not pass a callback to the start()
, run()
or mustRun()
methods or use setIdleTimeout()
.
Finding the Executable PHP Binary
This component also provides a 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)