reference/exec/functions/proc-open.xml
6667724b8a42ba501172bc874dd1644a6744be0f
...
...
@@ -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>
...
...
@@ -147,6 +187,15 @@
147
187
</para>
148
188
</refsect1>
149
189

190
+
<refsect1 role="errors">
191
+
&reftitle.errors;
192
+
<simpara>
193
+
As of PHP 8.3.0, throws a <exceptionname>ValueError</exceptionname> if
194
+
<parameter>command</parameter> is an array without at least one
195
+
non-empty element.
196
+
</simpara>
197
+
</refsect1>
198
+

150
199
<refsect1 role="changelog">
151
200
&reftitle.changelog;
152
201
<para>
...
...
@@ -160,10 +209,32 @@
160
209
</thead>
161
210
<tbody>
162
211
<row>
163
-
<entry>5.2.1</entry>
212
+
<entry>8.3.0</entry>
213
+
<entry>
214
+
A <exceptionname>ValueError</exceptionname> will be thrown if
215
+
<parameter>command</parameter> is an array without at least one
216
+
non-empty element.
217
+
</entry>
218
+
</row>
219
+
<row>
220
+
<entry>7.4.4</entry>
221
+
<entry>
222
+
Added the <literal>create_new_console</literal> option to the
223
+
<parameter>options</parameter> parameter.
224
+
</entry>
225
+
</row>
226
+
<row>
227
+
<entry>7.4.0</entry>
228
+
<entry>
229
+
<function>proc_open</function> now also accepts an &array;
230
+
for the <parameter>command</parameter>.
231
+
</entry>
232
+
</row>
233
+
<row>
234
+
<entry>7.4.0</entry>
164
235
<entry>
165
-
Added the <literal>bypass_shell</literal> option to the
166
-
<parameter>other_options</parameter> parameter.
236
+
Added the <literal>create_process_group</literal> option to the
237
+
<parameter>options</parameter> parameter.
167
238
</entry>
168
239
</row>
169
240
</tbody>
...
...
@@ -228,6 +299,43 @@ command returned 0
228
299
</example>
229
300
</para>
230
301

302
+
<para>
303
+
<example>
304
+
<title><function>proc_open</function> quirk on Windows</title>
305
+
<simpara>
306
+
While one may expect the following program to search the file
307
+
<filename>filename.txt</filename> for the text <literal>search</literal> and
308
+
to print the results, it behaves rather differently.
309
+
</simpara>
310
+
<programlisting role="php">
311
+
<![CDATA[
312
+
<?php
313
+
$descriptorspec = [STDIN, STDOUT, STDOUT];
314
+
$cmd = '"findstr" "search" "filename.txt"';
315
+
$proc = proc_open($cmd, $descriptorspec, $pipes);
316
+
proc_close($proc);
317
+
?>
318
+
]]>
319
+
</programlisting>
320
+
&example.outputs;
321
+
<screen>
322
+
<![CDATA[
323
+
'findstr" "search" "filename.txt' is not recognized as an internal or external command,
324
+
operable program or batch file.
325
+
]]>
326
+
</screen>
327
+
<simpara>
328
+
To work around that behavior, it is usually sufficient to enclose the
329
+
<parameter>command</parameter> in additional quotes:
330
+
</simpara>
331
+
<programlisting role="php">
332
+
<![CDATA[
333
+
$cmd = '""findstr" "search" "filename.txt""';
334
+
]]>
335
+
</programlisting>
336
+
</example>
337
+
</para>
338
+

231
339
<!-- ptys are currently disabled
232
340
<para>
233
341
<example>
...
...
@@ -287,7 +395,6 @@ if (is_resource($process)) {
287
395
</para>
288
396
</refsect1>
289
397
</refentry>
290
-

291
398
<!-- Keep this comment at the end of the file
292
399
Local variables:
293
400
mode: sgml
294
401



Translation status