reference/exec/functions/proc-open.xml
769812c12f00c1978bf7dd711dca38dbf05462da
...
...
@@ -1,7 +1,7 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
3
<!-- splitted from ./en/functions/exec.xml, last change in rev 1.28 -->
4
-
<refentry xml:id='function.proc-open' xmlns="http://docbook.org/ns/docbook">
4
+
<refentry xml:id="function.proc-open" xmlns="http://docbook.org/ns/docbook">
5
5
<refnamediv>
6
6
<refname>proc_open</refname>
7
7
<refpurpose>
...
...
@@ -11,14 +11,14 @@
11
11
<refsect1 role="description">
12
12
&reftitle.description;
13
13
<methodsynopsis>
14
-
<type>resource</type><methodname>proc_open</methodname>
15
-
<methodparam><type>string</type><parameter>cmd</parameter></methodparam>
16
-
<methodparam><type>array</type><parameter>descriptorspec</parameter></methodparam>
17
-
<methodparam><type>array</type><parameter role="reference">pipes</parameter></methodparam>
18
-
<methodparam choice="opt"><type>string</type><parameter>cwd</parameter></methodparam>
19
-
<methodparam choice="opt"><type>array</type><parameter>env</parameter></methodparam>
20
-
<methodparam choice="opt"><type>array</type><parameter>other_options</parameter></methodparam>
21
-
</methodsynopsis>
14
+
<type class="union"><type>resource</type><type>false</type></type><methodname>proc_open</methodname>
15
+
<methodparam><type class="union"><type>array</type><type>string</type></type><parameter>command</parameter></methodparam>
16
+
<methodparam><type>array</type><parameter>descriptor_spec</parameter></methodparam>
17
+
<methodparam><type>array</type><parameter role="reference">pipes</parameter></methodparam>
18
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>cwd</parameter><initializer>&null;</initializer></methodparam>
19
+
<methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>env_vars</parameter><initializer>&null;</initializer></methodparam>
20
+
<methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
21
+
</methodsynopsis>
22
22
<para>
23
23
<function>proc_open</function> is similar to <function>popen</function>
24
24
but provides a much greater degree of control over the program execution.
...
...
@@ -44,15 +44,42 @@
44
44
<para>
45
45
<variablelist>
46
46
<varlistentry>
47
-
<term><parameter>cmd</parameter></term>
47
+
<term><parameter>command</parameter></term>
48
48
<listitem>
49
49
<para>
50
-
The command to execute
50
+
The commandline to execute as &string;. Special characters have to be properly escaped,
51
+
and proper quoting has to be applied.
51
52
</para>
53
+
<note>
54
+
<simpara>
55
+
On <emphasis>Windows</emphasis>, unless <literal>bypass_shell</literal> is set to &true; in
56
+
<parameter>options</parameter>, the <parameter>command</parameter> is
57
+
passed to <command>cmd.exe</command> (actually, <literal>%ComSpec%</literal>)
58
+
with the <literal>/c</literal> flag as <emphasis>unquoted</emphasis> string
59
+
(i.e. exactly as has been given to <function>proc_open</function>).
60
+
This can cause <command>cmd.exe</command> to remove enclosing quotes from
61
+
<parameter>command</parameter> (for details see the <command>cmd.exe</command> documentation),
62
+
resulting in unexpected, and potentially even dangerous behavior, because
63
+
<command>cmd.exe</command> error messages may contain (parts of) the passed
64
+
<parameter>command</parameter> (see example below).
65
+
</simpara>
66
+
</note>
67
+
<para>
68
+
As of PHP 7.4.0, <parameter>command</parameter> may be passed as &array; of command parameters.
69
+
In this case the process will be opened directly (without going through a shell)
70
+
and PHP will take care of any necessary argument escaping.
71
+
</para>
72
+
<note>
73
+
<para>
74
+
On Windows, the argument escaping of the &array; elements assumes that the
75
+
command line parsing of the executed command is compatible with the parsing
76
+
of command line arguments done by the VC runtime.
77
+
</para>
78
+
</note>
52
79
</listitem>
53
80
</varlistentry>
54
81
<varlistentry>
55
-
<term><parameter>descriptorspec</parameter></term>
82
+
<term><parameter>descriptor_spec</parameter></term>
56
83
<listitem>
57
84
<para>
58
85
An indexed array where the key represents the descriptor number and the
...
...
@@ -68,6 +95,7 @@
68
95
element is either <literal>r</literal> to pass the read end of the pipe
69
96
to the process, or <literal>w</literal> to pass the write end) and
70
97
<literal>file</literal> (the second element is a filename).
98
+
Note that anything else than <literal>w</literal> is treated like <literal>r</literal>.
71
99
</member>
72
100
<member>
73
101
A stream resource representing a real file descriptor (e.g. opened file,
...
...
@@ -107,7 +135,7 @@
107
135
</listitem>
108
136
</varlistentry>
109
137
<varlistentry>
110
-
<term><parameter>env</parameter></term>
138
+
<term><parameter>env_vars</parameter></term>
111
139
<listitem>
112
140
<para>
113
141
An array with the environment variables for the command that will be
...
...
@@ -116,7 +144,7 @@
116
144
</listitem>
117
145
</varlistentry>
118
146
<varlistentry>
119
-
<term><parameter>other_options</parameter></term>
147
+
<term><parameter>options</parameter></term>
120
148
<listitem>
121
149
<para>
122
150
Allows you to specify additional options. Currently supported options
...
...
@@ -130,6 +158,18 @@
130
158
<literal>bypass_shell</literal> (windows only): bypass
131
159
<literal>cmd.exe</literal> shell when set to &true;
132
160
</member>
161
+
<member>
162
+
<literal>blocking_pipes</literal> (windows only): force
163
+
blocking pipes when set to &true;
164
+
</member>
165
+
<member>
166
+
<literal>create_process_group</literal> (windows only): allow the
167
+
child process to handle <literal>CTRL</literal> events when set to &true;
168
+
</member>
169
+
<member>
170
+
<literal>create_new_console</literal> (windows only): the new process
171
+
has a new console, instead of inheriting its parent's console
172
+
</member>
133
173
</simplelist>
134
174
</para>
135
175
</listitem>
...
...
@@ -160,10 +200,24 @@
160
200
</thead>
161
201
<tbody>
162
202
<row>
163
-
<entry>5.2.1</entry>
203
+
<entry>7.4.4</entry>
204
+
<entry>
205
+
Added the <literal>create_new_console</literal> option to the
206
+
<parameter>options</parameter> parameter.
207
+
</entry>
208
+
</row>
209
+
<row>
210
+
<entry>7.4.0</entry>
164
211
<entry>
165
-
Added the <literal>bypass_shell</literal> option to the
166
-
<parameter>other_options</parameter> parameter.
212
+
<function>proc_open</function> now also accepts an &array;
213
+
for the <parameter>command</parameter>.
214
+
</entry>
215
+
</row>
216
+
<row>
217
+
<entry>7.4.0</entry>
218
+
<entry>
219
+
Added the <literal>create_process_group</literal> option to the
220
+
<parameter>options</parameter> parameter.
167
221
</entry>
168
222
</row>
169
223
</tbody>
...
...
@@ -228,6 +282,43 @@ command returned 0
228
282
</example>
229
283
</para>
230
284

285
+
<para>
286
+
<example>
287
+
<title><function>proc_open</function> quirk on Windows</title>
288
+
<simpara>
289
+
While one may expect the following program to search the file
290
+
<filename>filename.txt</filename> for the text <literal>search</literal> and
291
+
to print the results, it behaves rather differently.
292
+
</simpara>
293
+
<programlisting role="php">
294
+
<![CDATA[
295
+
<?php
296
+
$descriptorspec = [STDIN, STDOUT, STDOUT];
297
+
$cmd = '"findstr" "search" "filename.txt"';
298
+
$proc = proc_open($cmd, $descriptorspec, $pipes);
299
+
proc_close($proc);
300
+
?>
301
+
]]>
302
+
</programlisting>
303
+
&example.outputs;
304
+
<screen>
305
+
<![CDATA[
306
+
'findstr" "search" "filename.txt' is not recognized as an internal or external command,
307
+
operable program or batch file.
308
+
]]>
309
+
</screen>
310
+
<simpara>
311
+
To work around that behavior, it is usually sufficient to enclose the
312
+
<parameter>command</parameter> in additional quotes:
313
+
</simpara>
314
+
<programlisting role="php">
315
+
<![CDATA[
316
+
$cmd = '""findstr" "search" "filename.txt""';
317
+
]]>
318
+
</programlisting>
319
+
</example>
320
+
</para>
321
+

231
322
<!-- ptys are currently disabled
232
323
<para>
233
324
<example>
...
...
@@ -287,7 +378,6 @@ if (is_resource($process)) {
287
378
</para>
288
379
</refsect1>
289
380
</refentry>
290
-

291
381
<!-- Keep this comment at the end of the file
292
382
Local variables:
293
383
mode: sgml
294
384