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>mixed</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><initializer>&null;</initializer></methodparam>
19
-
<methodparam choice="opt"><type>array</type><parameter>env</parameter><initializer>&null;</initializer></methodparam>
20
-
<methodparam choice="opt"><type>array</type><parameter>other_options</parameter><initializer>&null;</initializer></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,7 +44,7 @@
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
50
The commandline to execute as &string;. Special characters have to be properly escaped,
...
...
@@ -53,19 +53,19 @@
53
53
<note>
54
54
<simpara>
55
55
On <emphasis>Windows</emphasis>, unless <literal>bypass_shell</literal> is set to &true; in
56
-
<parameter>other_options</parameter>, the <parameter>cmd</parameter> is
56
+
<parameter>options</parameter>, the <parameter>command</parameter> is
57
57
passed to <command>cmd.exe</command> (actually, <literal>%ComSpec%</literal>)
58
58
with the <literal>/c</literal> flag as <emphasis>unquoted</emphasis> string
59
59
(i.e. exactly as has been given to <function>proc_open</function>).
60
60
This can cause <command>cmd.exe</command> to remove enclosing quotes from
61
-
<parameter>cmd</parameter> (for details see the <command>cmd.exe</command> documentation),
61
+
<parameter>command</parameter> (for details see the <command>cmd.exe</command> documentation),
62
62
resulting in unexpected, and potentially even dangerous behavior, because
63
63
<command>cmd.exe</command> error messages may contain (parts of) the passed
64
-
<parameter>cmd</parameter> (see example below).
64
+
<parameter>command</parameter> (see example below).
65
65
</simpara>
66
66
</note>
67
67
<para>
68
-
As of PHP 7.4.0, <parameter>cmd</parameter> may be passed as &array; of command parameters.
68
+
As of PHP 7.4.0, <parameter>command</parameter> may be passed as &array; of command parameters.
69
69
In this case the process will be opened directly (without going through a shell)
70
70
and PHP will take care of any necessary argument escaping.
71
71
</para>
...
...
@@ -79,7 +79,7 @@
79
79
</listitem>
80
80
</varlistentry>
81
81
<varlistentry>
82
-
<term><parameter>descriptorspec</parameter></term>
82
+
<term><parameter>descriptor_spec</parameter></term>
83
83
<listitem>
84
84
<para>
85
85
An indexed array where the key represents the descriptor number and the
...
...
@@ -95,6 +95,7 @@
95
95
element is either <literal>r</literal> to pass the read end of the pipe
96
96
to the process, or <literal>w</literal> to pass the write end) and
97
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>.
98
99
</member>
99
100
<member>
100
101
A stream resource representing a real file descriptor (e.g. opened file,
...
...
@@ -134,7 +135,7 @@
134
135
</listitem>
135
136
</varlistentry>
136
137
<varlistentry>
137
-
<term><parameter>env</parameter></term>
138
+
<term><parameter>env_vars</parameter></term>
138
139
<listitem>
139
140
<para>
140
141
An array with the environment variables for the command that will be
...
...
@@ -143,7 +144,7 @@
143
144
</listitem>
144
145
</varlistentry>
145
146
<varlistentry>
146
-
<term><parameter>other_options</parameter></term>
147
+
<term><parameter>options</parameter></term>
147
148
<listitem>
148
149
<para>
149
150
Allows you to specify additional options. Currently supported options
...
...
@@ -186,6 +187,15 @@
186
187
</para>
187
188
</refsect1>
188
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
+

189
199
<refsect1 role="changelog">
190
200
&reftitle.changelog;
191
201
<para>
...
...
@@ -198,25 +208,33 @@
198
208
</row>
199
209
</thead>
200
210
<tbody>
211
+
<row>
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>
201
219
<row>
202
220
<entry>7.4.4</entry>
203
221
<entry>
204
222
Added the <literal>create_new_console</literal> option to the
205
-
<parameter>other_options</parameter> parameter.
223
+
<parameter>options</parameter> parameter.
206
224
</entry>
207
225
</row>
208
226
<row>
209
227
<entry>7.4.0</entry>
210
228
<entry>
211
229
<function>proc_open</function> now also accepts an &array;
212
-
for the <parameter>cmd</parameter>.
230
+
for the <parameter>command</parameter>.
213
231
</entry>
214
232
</row>
215
233
<row>
216
234
<entry>7.4.0</entry>
217
235
<entry>
218
236
Added the <literal>create_process_group</literal> option to the
219
-
<parameter>other_options</parameter> parameter.
237
+
<parameter>options</parameter> parameter.
220
238
</entry>
221
239
</row>
222
240
</tbody>
...
...
@@ -308,7 +326,7 @@ operable program or batch file.
308
326
</screen>
309
327
<simpara>
310
328
To work around that behavior, it is usually sufficient to enclose the
311
-
<parameter>cmd</parameter> in additional quotes:
329
+
<parameter>command</parameter> in additional quotes:
312
330
</simpara>
313
331
<programlisting role="php">
314
332
<![CDATA[
...
...
@@ -377,7 +395,6 @@ if (is_resource($process)) {
377
395
</para>
378
396
</refsect1>
379
397
</refentry>
380
-

381
398
<!-- Keep this comment at the end of the file
382
399
Local variables:
383
400
mode: sgml
384
401



Translation status