proc-open.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 6667724b8a42ba501172bc874dd1644a6744be0f Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.proc-open" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>proc_open</refname>
  <refpurpose>
   Exécute une commande et ouvre les pointeurs de fichiers pour les entrées / sorties
  </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> est similaire à <function>popen</function>
   mais fournit un plus grand degré de contrôle sur l'exécution du programme.
  </para>
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>command</parameter></term>
     <listitem>
      <para>
       La commande à exécuter en tant que &string;. Les caractères spéciaux
       doivent être échappé correctement, et une application correcte des
       guillemets doit être appliqué.
      </para>
      <note>
       <simpara>
        Sur <emphasis>Windows</emphasis>, sauf si <literal>bypass_shell</literal> est définie à &true; dans
        <parameter>options</parameter>, <parameter>command</parameter> est
        passé à <command>cmd.exe</command> (en fait, <literal>%ComSpec%</literal>)
        avec le drapeau <literal>/c</literal> est une &string; <emphasis>sans
        guillemets</emphasis> (c.à.d. exactement comment elle a été fournie à
        <function>proc_open</function>). Ceci peut causer
        <command>cmd.exe</command> à supprimer les guillemets entourant de
        <parameter>command</parameter> (pour plus de détails voir la documentation
        de <command>cmd.exe</command>), résulatant dans du comportement
        innatendu, et potentiellement dangereux, car les messages d'erreurs de
        <command>cmd.exe</command> peuvent contenir (une partir de) la
        <parameter>command</parameter> passé (voir exemple ci-dessous).
       </simpara>
      </note>
      <para>
       À partir de PHP 7.4.0, <parameter>command</parameter> peut être passé comme
       un &array; de paramètres de commandes.
       Dans ce cas le processus sera ouvert directement (sans passer à travers
       un shell) et PHP se chargera d'échapper les arguments nécessaire.
      </para>
      <note>
       <para>
        Sur Windows, l'échappement des arguments des éléments du &array; assume
        que le traitement de la ligne de commande de la commande exécuté est
        compatible avec le traitement d'arguments de ligne de commande fait par
        le runtime VC.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>descriptor_spec</parameter></term>
     <listitem>
      <para>
       Un tableau indexé, dont les clés représentent le numéro de descripteur 
       et la valeur la méthode avec laquelle PHP va passer ce descripteur au 
       processus fils. 0 est stdin, 1 est stdout, et 2 est stderr.
      </para>
      <para>
       Chaque élément peut être :
       <simplelist>
        <member>
         Un tableau décrivant le pipe à passer au processus. Le premier élément
         est le type du descripteur et le second est une option pour le type donné.
         Les types valides sont <literal>pipe</literal> (le second élément est soit
         <literal>r</literal> pour passer la fin de lecture du pipe au processus, ou
         <literal>w</literal> pour passer la fin d'écriture) et
         <literal>file</literal> (le second élément est le nom de fichier).
         À noter que tout autre élément différent de <literal>w</literal> est traité comme <literal>r</literal>.
        </member>
        <member>
         Une ressource de flux représentant un descripteur de fichier (e.g. un fichier
         ouvert, un socket, ou bien <constant>STDIN</constant>).
        </member>
       </simplelist>
      </para>
      <para>
       Les numéros de pointeurs de fichiers ne sont pas limités à 0, 1 et 2 -
       vous pouvez spécifier n'importe quel numéro de descripteur valide, et
       il sera passé au processus fils. Cela permettra à votre script d'inter opérer
       avec d'autres scripts, et d'être exécuté comme "co-processus". En particulier,
       c'est très pratique pour passer des mots de passes à des programmes comme
       PGP, GPG et openssl, avec une méthode très protégée. C'est aussi pratique
       pour lire des informations de statut fournies par ces programmes, sur des
       descripteurs auxiliaires.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>pipes</parameter></term>
     <listitem>
      <para>
       Doit être défini en un tableau indexé de pointeurs de fichiers qui 
       correspondent à la fin de n'importe quel descripteur PHP qui sont
       créés.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>cwd</parameter></term>
     <listitem>
      <para>
       Le dossier initial de travail de la commande. Cela doit être
       un chemin <emphasis role="strong">absolu</emphasis>
       vers le dossier ou &null; si vous voulez utiliser la valeur
       par défaut (le dossier de travail du processus courant PHP)
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>env_vars</parameter></term>
     <listitem>
      <para>
       Un tableau contenant les variables d'environnement pour la commande
       qui doit être exécutée, ou &null; pour utiliser le même environnement
       que le processus PHP courant
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       Vous permet de spécifier des options supplémentaires. Les options
       actuellement supportées sont :
       <simplelist>
        <member>
         <literal>suppress_errors</literal> (windows uniquement): suppression des
         erreurs générées par cette fonction lorsque définit à &true;
        </member>
        <member>
         <literal>bypass_shell</literal> (windows uniquement): bypass du shell
         <literal>cmd.exe</literal> lorsque définit à &true;
        </member>
        <member>
         <literal>blocking_pipes</literal> (windows uniquement): force
         les tubes bloquand lorsque définit à &true;
        </member>
        <member>
         <literal>create_process_group</literal> (windows uniquement) : permet
         au processus enfant de gérer les évènement <literal>CTRL</literal>  
         lorsqu'il est à &true;
        </member>
        <member>
         <literal>create_new_console</literal> (windows uniquement) : le nouvel
         processus à une nouvelle console, au lieu d'hériter la console de son
         parent.
        </member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne une ressource représentant le processus, qui pourra être utilisé par 
   la fonction <function>proc_close</function> lorsque vous n'en aurez plus besoin.
   En cas d'échec, &false; sera retourné.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   À partir de PHP 8.3.0, une exception <exceptionname>ValueError</exceptionname> est levée si 
   <parameter>command</parameter> est un tableau sans au moins un élément non vide.
  </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>
        Une exception <exceptionname>ValueError</exceptionname> sera levée si
        <parameter>command</parameter> est un tableau sans au moins un élément non vide.
       </entry>
      </row>
      <row>
       <entry>7.4.4</entry>
       <entry>
        Ajout de l'option <literal>create_new_console</literal> au paramètre
        <parameter>options</parameter>.
       </entry>
      </row>
      <row>
       <entry>7.4.0</entry>
       <entry>
        <function>proc_open</function> accepte désormais un &array;
        pour <parameter>command</parameter>.
       </entry>
      </row>
      <row>
       <entry>7.4.0</entry>
       <entry>
        Ajout de l'option <literal>create_process_group</literal> au paramètre 
        <parameter>options</parameter>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>proc_open</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$descriptorspec = array(
   0 => array("pipe", "r"),  // // stdin est un pipe où le processus va lire
   1 => array("pipe", "w"),  // stdout est un pipe où le processus va écrire
   2 => array("file", "/tmp/error-output.txt", "a") // stderr est un fichier
);

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

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

if (is_resource($process)) {
    // $pipes ressemble à :
    // 0 => fichier accessible en écriture, connecté à l'entrée standard du processus fils
    // 1 => fichier accessible en lecture, connecté à la sortie standard du processus fils
    // Toute erreur sera ajoutée au fichier /tmp/error-output.txt

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

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

    // Il est important que vous fermiez les pipes avant d'appeler
    // proc_close afin d'éviter un verrouillage.
    $return_value = proc_close($process);

    echo "La commande a retourné $return_value\n";
}
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Array
(
    [some_option] => aeiou
    [PWD] => /tmp
    [SHLVL] => 1
    [_] => /usr/local/bin/php
)
La commande a retourné 0
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Bizarrerie de <function>proc_open</function> sur Windows</title>
    <simpara>
     Bien que l'on puisse s'attendre à ce que le programme suivant recherche
     le fichier <filename>filename.txt</filename> pour le texte
     <literal>search</literal> et d'afficher les résultats,
     il se comporte plutôt différemment.
    </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>
     Pour contourner ce comportement, il est généralement suffisant d'entourer
     <parameter>command</parameter> de guillemets additionnelles :
    </simpara>
    <programlisting role="php">
<![CDATA[
$cmd = '""findstr" "search" "filename.txt""';
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Compatibilité Windows : les descripteurs au-delà de 2 (stderr) sont
    accessibles au processus fils, sous la forme de pointeurs hérités, mais
    comme l'architecture Windows n'associe pas de nombre aux descripteurs
    de bas niveau, le processus fils n'a, actuellement, aucun moyen 
    d'y accéder. D'un autre coté, stdin, stdout et stderr fonctionnent
    comme d'habitude.
   </para>
  </note>
  <note>
   <para>
    Si vous n'avez besoin que d'un processus unidirectionnel,
    <function>popen</function> sera plus pratique, car plus simple à 
    utiliser.
   </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><link linkend="language.operators.execution">Les guillemets obliques</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
-->