proc_open

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

proc_open Execute a command and open file pointers for input/output

Description

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

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

Parameters

command

The commandline to execute as string. Special characters have to be properly escaped, and proper quoting has to be applied.

Note: On Windows, unless bypass_shell is set to true in options, the command is passed to cmd.exe (actually, %ComSpec%) with the /c flag as unquoted string (i.e. exactly as has been given to proc_open()). This can cause cmd.exe to remove enclosing quotes from command (for details see the cmd.exe documentation), resulting in unexpected, and potentially even dangerous behavior, because cmd.exe error messages may contain (parts of) the passed command (see example below).

As of PHP 7.4.0, command may be passed as array of command parameters. In this case the process will be opened directly (without going through a shell) and PHP will take care of any necessary argument escaping.

Note:

On Windows, the argument escaping of the array elements assumes that the command line parsing of the executed command is compatible with the parsing of command line arguments done by the VC runtime.

descriptor_spec

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.

Each element can be:

  • An array describing the pipe to pass to the process. The first element is the descriptor type and the second element is an option for the given type. Valid types are pipe (the second element is either r to pass the read end of the pipe to the process, or w to pass the write end) and file (the second element is a filename). Note that anything else than w is treated like r.
  • A stream resource representing a real file descriptor (e.g. opened file, a socket, STDIN).

The file descriptor numbers are not limited to 0, 1 and 2 - you may specify any valid file descriptor number and it will be passed to the child process. This allows your script to interoperate with other scripts that run as "co-processes". In particular, this is useful for passing passphrases to programs like PGP, GPG and openssl in a more secure manner. It is also useful for reading status information provided by those programs on auxiliary file descriptors.

pipes

Will be set to an indexed array of file pointers that correspond to PHP's end of any pipes that are created.

cwd

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

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

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
  • create_new_console (windows only): the new process has a new console, instead of inheriting its parent's console

Return Values

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

Changelog

Version Description
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.

Examples

Example #1 A proc_open() example

<?php
$descriptorspec 
= array(
   
=> array("pipe""r"),  // stdin is a pipe that the child will read from
   
=> array("pipe""w"),  // stdout is a pipe that the child will write to
   
=> 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";
}
?>

The above example will output something similar to:

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

Example #2 proc_open() quirk on Windows

While one may expect the following program to search the file filename.txt for the text search and to print the results, it behaves rather differently.

<?php
$descriptorspec 
= [STDINSTDOUTSTDOUT];
$cmd '"findstr" "search" "filename.txt"';
$proc proc_open($cmd$descriptorspec$pipes);
proc_close($proc);
?>

The above example will output:

'findstr" "search" "filename.txt' is not recognized as an internal or external command,
operable program or batch file.

To work around that behavior, it is usually sufficient to enclose the command in additional quotes:

$cmd = '""findstr" "search" "filename.txt""';

Notes

Note:

Windows compatibility: Descriptors beyond 2 (stderr) are made available to the child process as inheritable handles, but since the Windows architecture does not associate file descriptor numbers with low-level handles, the child process does not (yet) have a means of accessing those handles. Stdin, stdout and stderr work as expected.

Note:

If you only need a uni-directional (one-way) process pipe, use popen() instead, as it is much easier to use.

See Also

  • popen() - Opens process file pointer
  • exec() - Execute an external program
  • system() - Execute an external program and display the output
  • passthru() - Execute an external program and display raw output
  • stream_select() - Runs the equivalent of the select() system call on the given arrays of streams with a timeout specified by seconds and microseconds
  • The backtick operator