Process Helper

Warning: You are browsing the documentation for Symfony 6.3, which is no longer maintained.

Read the updated version of this page for Symfony 7.2 (the current stable version).

The Process Helper shows processes as they're running and reports useful information about process status.

To display process details, use the ProcessHelper and run your command with verbosity. For example, running the following code with a very verbose verbosity (e.g. -vv):

        1
2
3
4
5
6
        use Symfony\Component\Process\Process;

$helper = $this->getHelper('process');
$process = new Process(['figlet', 'Symfony']);

$helper->run($output, $process);
    

will result in this output:

Console output showing two lines: "RUN 'figlet' 'Symfony'" and "RES Command ran successfully".

It will result in more detailed output with debug verbosity (e.g. -vvv):

In between the command line and the result line, the command's output is now shown prefixed by "OUT".

In case the process fails, debugging is easier:

The last line shows "RES 127 Command dit not run successfully", and the output lines show more the error information from the command.

Note

By default, the process helper uses the error output (stderr) as its default output. This behavior can be changed by passing an instance of StreamOutput to the run() method.

Arguments

There are three ways to use the process helper:

Using a command line string:

        1
2
        // ...
$helper->run($output, 'figlet Symfony');
    

An array of arguments:
```
1
2
```
```
// ...
$helper->run($output, ['figlet', 'Symfony']);
```
Note
When running the helper against an array of arguments, be aware that these will be automatically escaped.

Passing a Process instance:

        1
2
3
4
5
6
        use Symfony\Component\Process\Process;

// ...
$process = new Process(['figlet', 'Symfony']);

$helper->run($output, $process);
    

Customized Display

You can display a customized error message using the third argument of the run() method:

        1
        $helper->run($output, $process, 'The process failed :(');
    

A custom process callback can be passed as the fourth argument. Refer to the Process Component for callback documentation:

        1
2
3
4
5
6
7
8
9
        use Symfony\Component\Process\Process;

$helper->run($output, $process, 'The process failed :(', function (string $type, string $data): void {
    if (Process::ERR === $type) {
        // ... do something with the stderr output
    } else {
        // ... do something with the stdout
    }
});
    

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.

TOC

Version