proc-open.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- 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>
     Execute a command and open file pointers for input/output
    </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>proc_open</function> is similar to <function>popen</function>
     but provides a much greater degree of control over the program execution.
    </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>
       The commandline to execute as &string;. Special characters have to be properly escaped,
       and proper quoting has to be applied.
      </para>
      <note>
       <simpara>
        On <emphasis>Windows</emphasis>, unless <literal>bypass_shell</literal> is set to &true; in
        <parameter>options</parameter>, the <parameter>command</parameter> is
        passed to <command>cmd.exe</command> (actually, <literal>%ComSpec%</literal>)
        with the <literal>/c</literal> flag as <emphasis>unquoted</emphasis> string
        (i.e. exactly as has been given to <function>proc_open</function>).
        This can cause <command>cmd.exe</command> to remove enclosing quotes from
        <parameter>command</parameter> (for details see the <command>cmd.exe</command> documentation),
        resulting in unexpected, and potentially even dangerous behavior, because
        <command>cmd.exe</command> error messages may contain (parts of) the passed
        <parameter>command</parameter> (see example below).
       </simpara>
      </note>
      <para>
       As of PHP 7.4.0, <parameter>command</parameter> 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.
      </para>
      <note>
       <para>
        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.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>descriptor_spec</parameter></term>
     <listitem>
      <para>
       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.
      </para>
      <para>
       Each element can be:
       <simplelist>
        <member>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 <literal>pipe</literal> (the second
         element is either <literal>r</literal> to pass the read end of the pipe
         to the process, or <literal>w</literal> to pass the write end) and
         <literal>file</literal> (the second element is a filename).
         Note that anything else than <literal>w</literal> is treated like <literal>r</literal>.
        </member>
        <member>
         A stream resource representing a real file descriptor (e.g. opened file,
         a socket, <constant>STDIN</constant>).
        </member>
       </simplelist>
      </para>
      <para>
       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.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>pipes</parameter></term>
     <listitem>
      <para>
       Will be set to an indexed array of file pointers that correspond to
       PHP's end of any pipes that are created.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>cwd</parameter></term>
     <listitem>
      <para>
       The initial working dir for the command. This must be an
       <emphasis role="strong">absolute</emphasis> directory path, or &null;
       if you want to use the default value (the working dir of the current
       PHP process)
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>env_vars</parameter></term>
     <listitem>
      <para>
       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
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       Allows you to specify additional options. Currently supported options
       include:
       <simplelist>
        <member>
         <literal>suppress_errors</literal> (windows only): suppresses errors
         generated by this function when it's set to &true;
        </member>
        <member>
         <literal>bypass_shell</literal> (windows only): bypass
         <literal>cmd.exe</literal> shell when set to &true;
        </member>
        <member>
         <literal>blocking_pipes</literal> (windows only): force
         blocking pipes when set to &true;
        </member>
        <member>
         <literal>create_process_group</literal> (windows only): allow the
         child process to handle <literal>CTRL</literal> events when set to &true;
        </member>
        <member>
         <literal>create_new_console</literal> (windows only): the new process
         has a new console, instead of inheriting its parent's console
        </member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a resource representing the process, which should be freed using
   <function>proc_close</function> when you are finished with it. On failure
   returns &false;.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   As of PHP 8.3.0, throws a <exceptionname>ValueError</exceptionname> if
   <parameter>command</parameter> is an array without at least one
   non-empty element.
  </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>
        A <exceptionname>ValueError</exceptionname> will be thrown if
        <parameter>command</parameter> is an array without at least one
        non-empty element.
       </entry>
      </row>
      <row>
       <entry>7.4.4</entry>
       <entry>
        Added the <literal>create_new_console</literal> option to the
        <parameter>options</parameter> parameter.
       </entry>
      </row>
      <row>
       <entry>7.4.0</entry>
       <entry>
        <function>proc_open</function> now also accepts an &array;
        for the <parameter>command</parameter>.
       </entry>
      </row>
      <row>
       <entry>7.4.0</entry>
       <entry>
        Added the <literal>create_process_group</literal> option to the
        <parameter>options</parameter> parameter.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>A <function>proc_open</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$descriptorspec = array(
   0 => 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], '<?php print_r($_ENV); ?>');
    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";
}
?>
]]>
    </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> quirk on Windows</title>
    <simpara>
     While one may expect the following program to search the file
     <filename>filename.txt</filename> for the text <literal>search</literal> and
     to print the results, it behaves rather differently.
    </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>
     To work around that behavior, it is usually sufficient to enclose the
     <parameter>command</parameter> in additional quotes:
    </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 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.
   </para>
  </note>
  <note>
   <para>
   If you only need a uni-directional (one-way) process pipe, use
   <function>popen</function> instead, as it is much easier to use.
   </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">backtick operator</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
-->