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.

The Process class executes a command in a
sub-process, taking care of the differences between operating system and
escaping arguments to prevent security issues. It replaces PHP functions like
exec, passthru, shell_exec and
system:

1
2
3
4
5
6
7
8
9
10
11
12

useSymfony\Component\Process\Exception\ProcessFailedException;useSymfony\Component\Process\Process;$process=newProcess(['ls','-lsa']);$process->run();// executes after the command finishesif(!$process->isSuccessful()){thrownewProcessFailedException($process);}echo$process->getOutput();

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.

If you need to use stream redirections, conditional execution, or any other
feature provided by the shell of your operating system, you can also define
commands as strings using the
fromShellCommandline() static
factory.

Each operating system provides a different syntax for their command-lines,
so it becomes your responsibility to deal with escaping and portability.

When using strings to define commands, variable arguments are passed as
environment variables using the second argument of the run(),
mustRun() or start() methods. Referencing them is also OS-dependent:

1
2
3
4
5
6
7
8

// On Unix-like OSes (Linux, macOS)$process=Process::fromShellCommandline('echo "$MESSAGE"');// On Windows$process=Process::fromShellCommandline('echo "!MESSAGE!"');// On both Unix-like and Windows$process->run(null,['MESSAGE'=>'Something to output']);

If you prefer to create portable commands that are independent from the
operating system, you can write the above command as follows:

// works the same on Windows , Linux and macOS$process=Process::fromShellCommandline('echo "${:MESSAGE}"');

Portable commands require using a syntax that is specific to the component: when
enclosing a variable name into "${: and }" exactly, the process object
will replace it with its escaped value, or will fail if the variable is not
found in the list of environment variables attached to the command.

The constructor of the Process class and
all of its methods related to executing processes (run(), mustRun(),
start(), etc.) allow passing an array of environment variables to set while
running the process:

This feature won't work as expected in servers using PHP output buffering.
In those cases, either disable the output_buffering PHP option or use the
ob_flush PHP function to force sending the output buffer.

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=newProcess(['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=newProcess(['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:

Instead of waiting until the process has finished, you can use the
waitUntil() method to keep or stop
waiting based on some PHP logic. The following example starts a long running
process and checks its output to wait until its fully initialized:

1
2
3
4
5
6
7
8
9
10
11

$process=newProcess(['/usr/bin/php','slow-starting-server.php']);$process->start();// ... do other things// waits until the given anonymous function returns true$process->waitUntil(function($type,$output){return$output==='Ready. Waiting for commands...';});// ... do things after the process is ready

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:

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=newInputStream();$input->write('foo');$process=newProcess(['cat']);$process->setInput($input);$process->start();// ... read process output or do other things$input->write('bar');$input->close();$process->wait();// will echo: foobarecho$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.

$stream=fopen('php://temporary','w+');$process=newProcess(['cat']);$process->setInput($stream);$process->start();fwrite($stream,'foo');// ... read process output or do other thingsfwrite($stream,'bar');fclose($stream);$process->wait();// will echo: 'foobar'echo$process->getOutput();

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=newProcess(['ls','-lsa']);$process->start();// ... do other things$process->stop(3,SIGINT);

You can run the process by using a a prepared command line using the
double bracket notation. You can use a placeholder in order to have a
process that can only be changed with the values and without changing
the PHP code:

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:

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

useSymfony\Component\Process\PhpExecutableFinder;$phpBinaryFinder=newPhpExecutableFinder();$phpBinaryPath=$phpBinaryFinder->find();// $phpBinaryPath = '/usr/local/bin/php' (the result will be different on your computer)