doc-fr/reference/stream/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.19 $ -->
<!-- EN-Revision: 1.23 Maintainer: yannick Status: ready -->
 <reference id="ref.stream">
  <title>Flux</title>
  <titleabbrev>Flux</titleabbrev>

  <partintro>

   <section id="stream.intro">
    &reftitle.intro;
    <simpara>
     Les flux ("<literal>streams</literal>" en anglais) ont été introduits en &php; 4.3.0
     comme méthode de généralisation des fichiers, sockets, connexions
     réseau, données compressées et autres opérations du même type, 
     qui partagent des opérations communes. Dans sa définition la plus simple,
     un <literal>flux</literal> est une <literal>ressource</literal> qui 
     présente des capacités de flux : 
     c'est à dire que ces objets peuvent être lus ou recevoir des
     écritures de manière linéaire, et dispose aussi de moyen d'accéder
     à des positions arbitraires dans le flux.
    </simpara>
    <simpara>
     Un <literal>gestionnaire</literal> (dit <literal>wrapper</literal> en anglais), est une
     fonction qui indique comment le flux se comporte spécifiquement. C'est le
     cas du gestionnaire <literal>http</literal>, qui sait comment traduire
     une URL en une requête <literal>HTTP/1.0</literal> sur un serveur distant. 
     Il existe de nombreux gestionnaires intégrés à &php; 
     par défaut (voir <xref linkend="wrappers"/>),
     et de plus, des gestionnaires spécifiques peuvent être ajoutés dans
     les scripts &php; avec la fonction <function>stream_register_wrapper</function>,
     ou bien directement par une autre extension, en utilisant l'API C de <xref linkend="streams"/>.
     Grâce à la souplesse des gestionnaires qui peuvent être ajoutés à &php;,
     il n'y a pas de limites aux possibilités offertes. Pour connaître la liste
     des gestionnaires actuellement enregistrés, utilisez la fonction
     <function>stream_get_wrappers</function>.
    </simpara>
    <para>
     Une flux est référencé comme :
     <parameter>scheme</parameter>://<parameter>target</parameter>
     <itemizedlist>
      <listitem>
       <simpara>
        <parameter>scheme</parameter>(&string;) -
        Le nom du gestionnaire a utilisé. Par exemple, <literal>file</literal>, <literal>http</literal>, <literal>https</literal>,
        <literal>ftp</literal>, <literal>ftps</literal>, <literal>compress.zlib</literal>, <literal>compress.bz</literal>. et <literal>php.</literal>.
        Voir <xref linkend="wrappers"/>
        pour une liste complète des gestionnaires enregistrés de &php;.
        Si aucun gestionnaire n'est spécifié, la fonction par défaut est utilisée (typiquement,
        <literal>file</literal>://).
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <parameter>target</parameter> -
        Dépend du gestionnaire utilisé. Pour les flux relatifs aux systèmes de fichiers, c'est 
        typiquement un chemin et un nom de fichier du fichier désiré.
        Pour les flux relatifs aux réseaux, c'est typiquement le nom d'hôte, 
        souvent avec un chemin apposé. Voir aussi <xref linkend="wrappers"/> 
        pour une description des cibles des flux intégrés.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
   </section>

   <section id="stream.filters">
    <title>Filtres de flux</title>
    <simpara>
     Un <literal>filtre</literal> est une fonction finale qui effectue des opérations
     sur les données qui sont lues ou écrites dans un flux. Un nombre arbitraire de
     filtre peuvent être ajoutés sur un flux. Des filtres personnalisés peuvent aussi
     être ajoutés avec la fonction <function>stream_register_filter</function>, ou bien
     dans une extension avec l'API C de <xref linkend="streams"/>. Pour connaître la liste
     des gestionnaires actuellement enregistrés, utilisez la fonction
     <function>stream_get_filters</function>.
    </simpara>
   </section>
   
   <section id="stream.contexts">
    <title>Contextes de flux</title>
    <simpara>
     Un <literal>contexte</literal> est un jeu de paramètres et d'options
     spécifiques à un gestionnaire qui modifie ou améliore le comportement
     d'un flux. Les <literal>contextes</literal> sont créés en utilisant la fonction
     <function>stream_context_create</function> et peuvent être donnés aux
     fonctions de créations de flux sur le système de fichier 
     (i.e. <function>fopen</function>, <function>file</function>, 
     <function>file_get_contents</function>, etc.).
    </simpara>
    <simpara>
     Les options peuvent être spécifiées en appelant 
     <function>stream_context_create</function>, ou plus tard, avec
     <function>stream_context_set_option</function>.
     Une liste des options spécifiques à des gestionnaires est disponible
     dans la liste des gestionnaires intégrés (voyez <xref linkend="wrappers"/>).
    </simpara>
    <simpara>
     De plus, les <literal>paramètres</literal> peuvent être envoyés à un contexte en utilisant
     la fonction <function>stream_context_set_params</function>. Actuellement, le
     seul paramètre de contexte supporté par &php; est <literal>notification</literal>. 
     La valeur de ce paramètre doit être le nom d'une fonction qui sera appelée
     lorsqu'un événement survient pour un flux. La fonction d'alerte
     est appelé durant la réception de l'événement, et doit accepter 6 paramètres : 
     </simpara>
    <methodsynopsis>
     <type>void</type><methodname>my_notifier</methodname>
     <methodparam><type>int</type><parameter>notification_code</parameter></methodparam>
     <methodparam><type>int</type><parameter>severity</parameter></methodparam>
     <methodparam><type>string</type><parameter>message</parameter></methodparam>
     <methodparam><type>int</type><parameter>message_code</parameter></methodparam>
     <methodparam><type>int</type><parameter>bytes_transferred</parameter></methodparam>
     <methodparam><type>int</type><parameter>bytes_max</parameter></methodparam>
    </methodsynopsis>
    <simpara>
     <parameter>notification_code</parameter> et <parameter>severity</parameter>
     sont des valeurs numériques qui correspondent aux constantes 
     <constant>STREAM_NOTIFY_*</constant> listées ci-dessous. 
     Si un message descriptif est disponible dans un flux, les
     paramètres <parameter>message</parameter> et <parameter>message_code</parameter>
     en seront équipés. La signification de ces valeurs est dépendante du gestionnaire.

     <parameter>bytes_transferred</parameter> et <parameter>bytes_max</parameter> seront
     fournies si possible.
    </simpara>
   </section>
   
   <section id="stream.installation">
    &reftitle.install; 
    <para>
     Les flux font parti de &php; depuis la version 4.3.0. Aucune étape supplémentaire
     n'est requise pour les activer.
    </para>
   </section>

   <section id="stream.resources">
    <title>Classes Stream</title>
    <simpara>
     Des gestionnaires personnalisés peuvent être enregistrés via la fonction 
     <function>stream_register_wrapper</function>, en utilisant la définition de
     classe décrite dans ce manuel.
    </simpara>
    <simpara>
     La classe <classname>php_user_filter</classname> est prédéfinie. C'est une classe abstraite
     à utiliser avec les filtres personnalisés. Voyez le manuel de la fonction
     <function>stream_register_filter</function> pour plus de détails sur les
     implémentation de filtres utilisateurs.
    </simpara>
   </section>

   &reference.stream.constants;

   <section id="stream.errors">
    <title>Erreurs de flux</title>
    <para>
     Comme avec n'importe quel fichier ou socket, les opérations sur un flux
     peuvent échouer pour une grande variété de raisons (par exemple : impossible
     de se connecter au serveur distant, fichier introuvable, etc.). Un flux peut aussi
     échouer parce que le gestionnaire n'est pas configuré sur le système en
     cours. Voyez le tableau retourné par la fonction 
     <function>stream_get_wrappers</function> pour connaître la liste des gestionnaires
     configurés sur votre installation de &php;. Comme avec la plupart des fonctions
     internes de &php;, si une erreur survient, un message de type 
     <constant>E_WARNING</constant> sera généré pour indiquer la nature
     de l'erreur.
    </para>
   </section>
   
   <section id="stream.examples">
    &reftitle.examples;
    <para>
     <example>
      <title>Exemples avec <function>file_get_contents</function></title>
      <programlisting role="php">
<![CDATA[
<?php
/* Lit un fichier local dans le dossier /home/bar */
$localfile = file_get_contents("/home/bar/foo.txt");                         

/* Identique au précédent, mais utilise explicitement le gestionnaire FILE */
$localfile = file_get_contents("file:///home/bar/foo.txt");                  

/* Lit un fichier distant sur le serveur www.example.com avec le protocole HTTP */
$httpfile  = file_get_contents("http://www.example.com/foo.txt");
  
/* Lit le même fichier sur le serveur www.example.com avec le protocole HTTPS */
$httpsfile = file_get_contents("https://www.example.com/foo.txt");           

/* Lit un fichier distant sur le serveur ftp.example.com en utilisant le protocole FTP */
$ftpfile   = file_get_contents("ftp://user:pass@ftp.example.com/foo.txt");   

/* Lit un fichier distant sur le serveur ftp.example.com en utilisant le protocole FTPS */
$ftpsfile  = file_get_contents("ftps://user:pass@ftp.example.com/foo.txt");  
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     <example>
      <title>Envoie d'une requête de type POST sur un serveur sécurisé</title>
      <programlisting role="php">
<![CDATA[
<?php
/* Envoi d'une requête POST sur le serveur https://secure.example.com/form_action.php
 * Inclusion des variables "foo" et "bar"
 */

$sock = fsockopen("ssl://secure.example.com", 443, $errno, $errstr, 30);
if (!$sock) die("$errstr ($errno)\n");

$data = "foo=" . urlencode("Valeur de Foo") . "&bar=" . urlencode("Valeur de Bar");

fputs($sock, "POST /form_action.php HTTP/1.0\r\n");
fputs($sock, "Host: secure.example.com\r\n");
fputs($sock, "Content-type: application/x-www-form-urlencoded\r\n");
fputs($sock, "Content-length: " . strlen($data) . "\r\n");
fputs($sock, "Accept: */*\r\n");
fputs($sock, "\r\n");
fputs($sock, "$data\r\n");
fputs($sock, "\r\n");

$headers = "";
while ($str = trim(fgets($sock, 4096))) {
  $headers .= "$str\n";
}

echo "\n";

$body = "";
while (!feof($sock)) {
  $body .= fgets($sock, 4096);
}

fclose($sock);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     <example>
      <title>Ecrire des données dans un fichier compressé</title>
      <programlisting role="php">
<![CDATA[
<?php
/* Création d'un fichier compressé contenant une chaîne arbitraire
 * Le fichier peut etre lu en utilisant le gestionnaire compress.zlib
 * ou simplement decompresse; en ligne de commande avec 'gzip -d foo-bar.txt.gz'
 */
$fp = fopen("compress.zlib://foo-bar.txt.gz","w");
if (!$fp) die("Impossible de créer le fichier.");

fwrite($fp, "Ceci est un test.\n");

fclose($fp);
?>
]]>
      </programlisting>
     </example>
    </para>
   </section>
  </partintro>

&reference.stream.functions;

 </reference>
<!-- 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:"../../../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
-->