proc_open()

proc_open() — Execute a command and open file pointers for input/output.

Built-in function of PHP 8.5. The manual lists it as available in PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8. This page is the reference card: signature, parameters and return value, plus the changelog and the example the manual provides.

What it does

proc_open() is similar to popen() but provides a much greater degree of control over the program execution.

Signature

proc_open(array|string $command, array $descriptor_spec, array &$pipes, ?string $cwd = null, ?array $env_vars = null, ?array $options = null): resource|false

Parameters

Parameter	Type	What it takes
$command	array\|string	The commandline to execute as string. Special characters have to be properly escaped, and proper quoting has to be applied.
$descriptor_spec	array	An indexed array where the key represents the descriptor number and the value represents how PHP will pass that descriptor to the child process. 0 is stdin, 1 is stdout, while 2 is stderr.
&$pipes	array	Will be set to an indexed array of file pointers that correspond to PHP's end of any pipes that are created.
$cwd	?string	The initial working dir for the command. This must be an absolute directory path, or null if you want to use the default value (the working dir of the current PHP process)
$env_vars	?array	An array with the environment variables for the command that will be run, or null to use the same environment as the current PHP process
$options	?array	Allows you to specify additional options. Currently supported options include: suppress_errors (windows only): suppresses errors generated by this function when it's set to true bypass_shell (windows only): bypass cmd.exe shell when set to true blocking_pipes (windows only): force blocking pipes when set to true create_process_group (windows only): allow the child process to handle CTRL events when set to true ...

Return value

Returns a resource representing the process, which should be freed using proc_close() when you are finished with it. On failure returns false.

Example

A runnable snippet:

$descriptorspec = array( 0 => array("pipe", "r"), // stdin is a pipe that the child will read from 1 => array("pipe", "w"), // stdout is a pipe that the child will write to 2 => array("file", "/tmp/error-output.txt", "a") // stderr is a file to write to ); $cwd = '/tmp'; $env = array('some_option' => 'aeiou'); $process = proc_open('php', $descriptorspec, $pipes, $cwd, $env); if (is_resource($process)) { // $pipes now looks like this: // 0 => writeable handle connected to child stdin // 1 => readable handle connected to child stdout // Any error output will be appended to /tmp/error-output.txt fwrite($pipes[0], '<?php print_r($_ENV); ?>'); fclose($pipes[0]); echo stream_get_contents($pipes[1]); fclose($pipes[1]); // It is important that you close any pipes before calling // proc_close in order to avoid a deadlock $return_value = proc_close($process); echo "command returned $return_value\n"; }

Output:

Array ( [some_option] => aeiou [PWD] => /tmp [SHLVL] => 1 [_] => /usr/local/bin/php ) command returned 0

Changelog

Version	Change
8.3.0	A ValueError will be thrown if command is an array without at least one non-empty element.
7.4.4	Added the create_new_console option to the options parameter.
7.4.0	proc_open() now also accepts an array for the command.
7.4.0	Added the create_process_group option to the options parameter.