proc_open
Execute a command and open file pointers for input/output
&reftitle.description;
resourceproc_openmixedcmdarraydescriptorspecarraypipesstringcwd&null;arrayenv&null;arrayother_options&null;proc_open is similar to popen
but provides a much greater degree of control over the program execution.
&reftitle.parameters;
cmd
The commandline to execute as &string;. Special characters have to be properly escaped,
and proper quoting has to be applied.
On Windows, unless bypass_shell is set to &true; in
other_options, the cmd 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
cmd (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
cmd (see example below).
As of PHP 7.4.0, cmd 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.
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.
descriptorspec
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).
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
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
other_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
&reftitle.returnvalues;
Returns a resource representing the process, which should be freed using
proc_close when you are finished with it. On failure
returns &false;.
&reftitle.changelog;
&Version;&Description;7.4.4
Added the create_new_console option to the
other_options parameter.
7.4.0proc_open now also accepts an &array;
for the cmd.
7.4.0
Added the create_process_group option to the
other_options parameter.
&reftitle.examples;
A <function>proc_open</function> example
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], '');
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";
}
?>
]]>
&example.outputs.similar;
aeiou
[PWD] => /tmp
[SHLVL] => 1
[_] => /usr/local/bin/php
)
command returned 0
]]>
<function>proc_open</function> 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.
]]>
&example.outputs;
To work around that behavior, it is usually sufficient to enclose the
cmd in additional quotes:
&reftitle.notes;
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.
If you only need a uni-directional (one-way) process pipe, use
popen instead, as it is much easier to use.
&reftitle.seealso;
popenexecsystempassthrustream_selectThe backtick operator