proc-open.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 6667724b8a42ba501172bc874dd1644a6744be0f Maintainer: yuanyuqiang Status: ready -->
<!-- CREDITS: mowangjuanzi -->
<!-- splitted from ./en/functions/exec.xml, last change in rev 1.28 -->
<refentry xml:id="function.proc-open" xmlns="http://docbook.org/ns/docbook">
   <refnamediv>
    <refname>proc_open</refname>
    <refpurpose>
     执行一个命令，并且打开用来输入/输出的文件指针。
    </refpurpose>
   </refnamediv>
   <refsect1 role="description">
    &reftitle.description;
     <methodsynopsis>
   <type class="union"><type>resource</type><type>false</type></type><methodname>proc_open</methodname>
   <methodparam><type class="union"><type>array</type><type>string</type></type><parameter>command</parameter></methodparam>
   <methodparam><type>array</type><parameter>descriptor_spec</parameter></methodparam>
   <methodparam><type>array</type><parameter role="reference">pipes</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>cwd</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>env_vars</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>options</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
    <para>
     类似 <function>popen</function> 函数，
     但是 <function>proc_open</function> 提供了更加强大的控制程序执行的能力。
    </para>

<!-- ptys are currently disabled in the sources
    <para>
     PHP 5 introduces pty support for systems with Unix98 ptys. This allows
     your script to interact with applications that expect to be talking to a
     terminal.  A pty works like a pipe, but is bi-directional, so there is no
     need to specify a read/write mode.  The example below shows how to use a
     pty; note that you don't have to have all descriptors talking to a pty.
     Also note that only one pty is created, even though pty is specified 3
     times.  In a future version of PHP, it might be possible to do more than
     just read and write to the pty.
    </para>
-->

   </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>command</parameter></term>
     <listitem>
      <para>
       以 &string; 形式执行的命令行。特殊字符必须经过转义，并且使用正确的引号。
      </para>
      <note>
       <simpara>
        在 <emphasis>Windows</emphasis> 上, 除非在 <parameter>options</parameter> 中
        把 <literal>bypass_shell</literal> 设置为  &true;
        ，否则 <parameter>command</parameter> 会被传递给 <command>cmd.exe</command> （实际上是 <literal>%ComSpec%</literal>）
        其中的 <literal>/c</literal> 标志是 <emphasis>未加引号的</emphasis> 字符串 （也就是和 <function>proc_open</function> 一样）。
        这可能会导致 <command>cmd.exe</command> 删除 <parameter>command</parameter> 中的引号 （详见 <command>cmd.exe</command> 文档），
        从而导致意外的，甚至是潜在的危险行为，因为
        <command>cmd.exe</command> 错误消息可能包含 （部分） 传递的 <parameter>command</parameter> （见下面的例子）。
       </simpara>
      </note>
      <para>
       从 PHP 7.4.0 开始，<parameter>command</parameter> 参数可以使用 &array; 类型传递。
       在这种情况下，进程将直接打开（不通过 shell ）。
       而 PHP 会处理任何必要的参数转义。
      </para>
      <note>
       <para>
        在 Windows 上， &array; 元素的参数转义假定
        执行命令的命令行解析与 VC 运行时进行的命令行参数解析兼容。
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>descriptor_spec</parameter></term>
     <listitem>
      <para>
        一个索引数组。
        数组的键表示描述符，数组元素值表示 PHP 如何将这些描述符传送至子进程。
        0 表示标准输入（stdin），1 表示标准输出（stdout），2 表示标准错误（stderr）。
      </para>
      <para>
       数组中的元素可以是：
       <simplelist>
        <member>   
         包含了要传送至进程的管道的描述信息的数组。第一个元素为描述符类型，第二个元素是针对该描述符的选项。有效的类型有：<literal>pipe</literal>（第二个元素可以是：<literal>r</literal>
         向进程传送该管道的读取端，<literal>w</literal> 向进程传送该管道的写入端），以及
         <literal>file</literal>（第二个元素为文件名）。注意除了 <literal>w</literal>
         之外的任何内容都视为 <literal>r</literal>。
        </member>
        <member>
          流资源表示真实文件描述符（例如：已打开的文件，套接字，<constant>STDIN</constant>）。
        </member>
       </simplelist>
      </para>
      <para>
        文件描述符的值不限于 0，1 和 2，你可以使用任何有效的文件描述符
        并将其传送至子进程。
        这使得你的脚本可以和其他脚本交互操作。
        例如，可以通过指定文件描述符将密码以更加安全的方式
        传送至诸如 PGP，GPG 和 openssl 程序，
        同时也可以很方便的获取这些程序的状态信息。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>pipes</parameter></term>
     <listitem>
      <para>
        将被置为索引数组，
        其中的元素是被执行程序创建的管道对应到 PHP 这一端的文件指针。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>cwd</parameter></term>
     <listitem>
      <para>
        要执行命令的初始工作目录。
        必须是 <emphasis role="strong">绝对</emphasis> 路径，
        设置此参数为 &null; 
        表示使用默认值（当前 PHP 进程的工作目录）。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>env_vars</parameter></term>
     <listitem>
      <para>
        要执行的命令所使用的环境变量。
        设置此参数为 &null; 表示使用和当前 PHP 进程相同的环境变量。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
        你还可以指定一些附加选项。
        目前支持的选项包括：
       <simplelist>
        <member>
         <literal>suppress_errors</literal> （仅用于 Windows 平台）：
         设置为 &true; 表示抑制本函数产生的错误。
        </member>
        <member>
         <literal>bypass_shell</literal> （仅用于 Windows 平台）：
         设置为 &true; 表示绕过 <literal>cmd.exe</literal> shell。
        </member>
        <member>
         <literal>blocking_pipes</literal> （仅用于 Windows 平台）：
         设置为 &true; 表示强制堵塞管道。
        </member>
        <member>
         <literal>create_process_group</literal> （仅用于 Windows 平台）：
         设置为 &true; 表示允许子进程处理 <literal>CTRL</literal> 事件。
        </member>
        <member>
         <literal>create_new_console</literal> （仅用于 Windows 平台）：
         表示新进程有一个新的控制台，用于代替父进程的控制台。
        </member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
    返回表示进程的资源类型，
    当使用完毕之后，请调用 <function>proc_close</function> 函数来关闭此资源。
    如果失败，返回 &false;。
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   自 PHP 8.3.0 起，如果 <parameter>command</parameter> 是没有元素的空数组，则会抛出 <exceptionname>ValueError</exceptionname>。
  </simpara>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.3.0</entry>
       <entry>
        如果 <parameter>command</parameter> 是没有元素的空数组，将会抛出 <exceptionname>ValueError</exceptionname>。
       </entry>
      </row>
      <row>
       <entry>7.4.4</entry>
       <entry>
        为 <parameter>options</parameter> 参数增加 <literal>create_new_console</literal> 选项。
       </entry>
      </row>
      <row>
       <entry>7.4.0</entry>
       <entry>
        <function>proc_open</function> 的 <parameter>command</parameter> 参数现在也允许数组类型。
       </entry>
      </row>
      <row>
       <entry>7.4.0</entry>
       <entry>
        为 <parameter>options</parameter> 参数增加 <literal>create_process_group</literal> 选项。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>proc_open</function> 示例</title>
    <programlisting role="php">
<![CDATA[
<?php
$descriptorspec = array(
   0 => array("pipe", "r"),  // 标准输入，子进程从此管道中读取数据
   1 => array("pipe", "w"),  // 标准输出，子进程向此管道中写入数据
   2 => array("file", "/tmp/error-output.txt", "a") // 标准错误，写入到一个文件
);

$cwd = '/tmp';
$env = array('some_option' => 'aeiou');

$process = proc_open('php', $descriptorspec, $pipes, $cwd, $env);

if (is_resource($process)) {
    // $pipes 现在看起来是这样的：
    // 0 => 可以向子进程标准输入写入的句柄
    // 1 => 可以从子进程标准输出读取的句柄
    // 错误输出将被追加到文件 /tmp/error-output.txt

    fwrite($pipes[0], '<?php print_r($_ENV); ?>');
    fclose($pipes[0]);

    echo stream_get_contents($pipes[1]);
    fclose($pipes[1]);
    

    // 切记：在调用 proc_close 之前关闭所有的管道以避免死锁。
    $return_value = proc_close($process);

    echo "command returned $return_value\n";
}
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Array
(
    [some_option] => aeiou
    [PWD] => /tmp
    [SHLVL] => 1
    [_] => /usr/local/bin/php
)
command returned 0
]]>
    </screen>
   </example>
  </para>

  <para>
   <example>
    <title><function>proc_open</function> 在 Windows 上的怪异行为</title>
    <simpara>
     虽然人们可能期望下面的程序能够搜索文件
     <filename>filename.txt</filename> 进行文本搜索，
     并打印结果，但它的行为相当不同。
    </simpara>
    <programlisting role="php">
     <![CDATA[
<?php
$descriptorspec = [STDIN, STDOUT, STDOUT];
$cmd = '"findstr" "search" "filename.txt"';
$proc = proc_open($cmd, $descriptorspec, $pipes);
proc_close($proc);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
     <![CDATA[
'findstr" "search" "filename.txt' is not recognized as an internal or external command,
operable program or batch file.
]]>
    </screen>
    <simpara>
     要解决该行为，通常只需将 <parameter>command</parameter> 加上引号：
    </simpara>
    <programlisting role="php">
     <![CDATA[
$cmd = '""findstr" "search" "filename.txt""';
]]>
    </programlisting>
   </example>
  </para>

<!-- ptys are currently disabled
  <para>
   <example>
    <title>ptys usage</title>
    <programlisting role="php">
<![CDATA[
<?php
// Create a pseudo terminal for the child process
$descriptorspec = array(
   0 => array("pty"),
   1 => array("pty"),
   2 => array("pty")
);
$process = proc_open("cvs -d:pserver:cvsread@cvs.php.net:/repository login", $descriptorspec, $pipes);
if (is_resource($process)) {
   // work with it here
}
?>
]]>
    </programlisting>
   </example>
  </para>
-->

 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Windows 兼容性：超过 2 的描述符也可以作为可继承的句柄传送到子进程。
    但是，由于 Windows 的架构并不将文件描述符和底层句柄进行关联，
    所以，子进程无法访问这样的句柄。
    标准输入，标准输出和标注错误会按照预期工作。
   </para>
  </note>
  <note>
   <para>
    如果你只需要单向的进程管道，
    使用 <function>popen</function> 函数会更加简单。
   </para>
  </note>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>popen</function></member>
    <member><function>exec</function></member>
    <member><function>system</function></member>
    <member><function>passthru</function></member>
    <member><function>stream_select</function></member>
    <member>The <link linkend="language.operators.execution">执行运算符</link></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->