fopen.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 74b2af242f2131cd43a8830fee3864f1f68ccbed Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fopen">
 <refnamediv>
  <refname>fopen</refname>
  <refpurpose>Ouvre un fichier ou une URL</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>resource</type><type>false</type></type><methodname>fopen</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam><type>string</type><parameter>mode</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter><initializer>&false;</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>fopen</function> crée une ressource nommée, spécifiée par
   le paramètre <parameter>filename</parameter>, sous la forme d'un flux.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       Si <parameter>filename</parameter> est de la forme "protocole://",
       <parameter>filename</parameter> est supposé être une URL, et PHP va
       rechercher un gestionnaire de protocole adapté pour lire ce fichier.
       Si aucun gestionnaire pour ce protocole n'est disponible, PHP va émettre
       une alerte qui vous permettra de savoir que vous avez des problèmes dans
       votre script, et il tentera d'exploiter <parameter>filename</parameter>
       comme un fichier classique.
      </para>
      <para>
       Si PHP décide que le fichier <parameter>filename</parameter> est un fichier
       local, il va essayer d'ouvrir un flux avec ce fichier. Le fichier doit être
       accessible à PHP. Il vous faut donc vous assurer que vous avez les
       droits d'accès à ce fichier. Si vous activez
       la directive <link linkend="ini.open-basedir">open_basedir</link>, d'autres
       conditions peuvent aussi s'appliquer.
      </para>
      <para>
       Si PHP a décidé que <parameter>filename</parameter> spécifie
       un protocole enregistré, et que ce protocole est enregistré comme
       un protocole réseau, PHP s'assurera que la directive
       <link linkend="ini.allow-url-fopen">allow_url_fopen</link> est activée.
       Si elle est inactive, PHP va émettre une alerte et l&apos;appel <function>fopen</function>
       va échouer.
      </para>
      <note>
       <para>
        La liste des protocoles supportés est disponible sur <xref linkend="wrappers"/>.
        Certains protocoles (appelés aussi <literal>wrappers</literal> ou gestionnaires)
        supportent des <literal>context</literal> et/ou des options dans le fichier
        &php.ini;. Référez-vous aux pages du manuel traitant le protocole, pour connaître
        la liste des options qui sont disponibles. ( e.g. l'option de &php.ini;
        <literal>user_agent</literal> est utilisée par le gestionnaire <literal>http</literal>).
       </para>
      </note>
      <para>
       Sous Windows, assurez-vous de bien protéger les antislashs
       utilisés dans le chemin du fichier, ou bien utilisez des slashs.
       <informalexample>
        <programlisting role="php">
<![CDATA[
<?php
$handle = fopen("c:\\folder\\resource.txt", "r");
?>
]]>
        </programlisting>
       </informalexample>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       Le paramètre <parameter>mode</parameter> spécifie le type d'accès désiré
       au flux. Il peut prendre les valeurs suivantes :
       <table>
        <title>
         Liste des modes possibles pour la fonction <function>fopen</function> en utilisant
         le paramètre <parameter>mode</parameter>
        </title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry><parameter>mode</parameter></entry>
           <entry>Description</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><literal>'r'</literal></entry>
           <entry>
            Ouvre en lecture seule et place le pointeur de fichier au
            début du fichier.
           </entry>
          </row>
          <row>
           <entry><literal>'r+'</literal></entry>
           <entry>
            Ouvre en lecture et écriture et place le pointeur de
            fichier au début du fichier.
           </entry>
          </row>
          <row>
           <entry><literal>'w'</literal></entry>
           <entry>
            Ouvre en écriture seule ; place le pointeur de fichier au
            début du fichier et réduit la taille du fichier à 0.
            Si le fichier n'existe pas, on tente de le créer.
           </entry>
          </row>
          <row>
           <entry><literal>'w+'</literal></entry>
           <entry>
            Ouvre en lecture et écriture ; le comportement est
            le même que pour <literal>'w'</literal>.
           </entry>
          </row>
          <row>
           <entry><literal>'a'</literal></entry>
           <entry>
            Ouvre en écriture seule ; place le pointeur de fichier à
            la fin du fichier. Si le fichier n'existe pas, on tente
            de le créer. Dans ce mode, la fonction <function>fseek</function>
            n'a aucun effet, les écritures surviennent toujours.
           </entry>
          </row>
          <row>
           <entry><literal>'a+'</literal></entry>
           <entry>
            Ouvre en lecture et écriture ; place le pointeur de fichier
            à la fin du fichier. Si le fichier n'existe pas, on tente
            de le créer. Dans ce mode, la fonction <function>fseek</function>
            n'affecte que la position de lecture, les écritures sont toujours 
            ajoutées à la fin.
           </entry>
          </row>
          <row>
           <entry><literal>'x'</literal></entry>
           <entry>
            Crée et ouvre le fichier en écriture seulement ; place le pointeur de
            fichier au début du fichier. Si le fichier existe déjà,
            <function>fopen</function> va échouer, en retournant &false; et
            en générant une erreur de niveau <constant>E_WARNING</constant>.
            Si le fichier n'existe pas, <function>fopen</function> tente de le
            créer. Ce mode est l'équivalent des options <literal>O_EXCL|O_CREAT</literal>
            pour l'appel système <literal>open(2)</literal> sous-jacent.
           </entry>
          </row>
          <row>
           <entry><literal>'x+'</literal></entry>
           <entry>
            Crée et ouvre le fichier pour lecture et écriture ; le comportement est
            le même que pour <literal>'x'</literal>.
           </entry>
          </row>
          <row>
           <entry><literal>'c'</literal></entry>
           <entry>
            Ouvre le fichier pour écriture seulement. Si le fichier n'existe pas, il
            sera créé, s'il existe, il n'est pas tronqué (contrairement à
            <literal>'w'</literal>) et l'appel à la fonction n'échoue pas (comme dans
            le cas de <literal>'x'</literal>). Le pointeur du fichier est positionné
            au début. Ce mode peut être utile pour obtenir un verrou (voyez
            <function>flock</function>) avant de tenter de modifier le fichier, utiliser
            <literal>'w'</literal> pourrait tronquer le fichier avant d'obtenir le verrou
            (vous pouvez toujours tronquer grâce à <function>ftruncate</function>).
           </entry>
          </row>
          <row>
           <entry><literal>'c+'</literal></entry>
           <entry>
            Ouvre le fichier pour lecture et écriture, le comportement est le même
            que pour le mode <literal>'c'</literal>.
           </entry>
          </row>
          <row>
           <entry><literal>'e'</literal></entry>
           <entry>
            Défini l'indicateur close-on-exec sur le descripteur de fichier 
            ouvert. Disponible uniquement en PHP compilé sur les systèmes 
            conforme POSIX.1-2008.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <note>
       <para>
        Les systèmes d'exploitation utilisent différents caractères
        pour les nouvelles lignes. Lorsque vous écrivez un fichier
        texte et insérez une nouvelle ligne, vous devez utiliser le bon
        caractère pour votre système d'exploitation. Les systèmes Unix
        utilisent <literal>\n</literal> comme nouvelle ligne, les systèmes
        Windows utilisent <literal>\r\n</literal>, et les systèmes
        Macintosh (Mac OS Classic) utilisent <literal>\r</literal>.
       </para>
       <para>
        Si vous n'utilisez pas le bon caractère de nouvelle ligne lors de
        l'écriture de vos fichiers, vous risquez d'ouvrir vos fichiers avec
        des applications qui donneront un aspect 'bizarre' au texte.
       </para>
       <para>
        Windows propose un mode de traduction (<literal>'t'</literal>),
        qui va traduire automatiquement les caractères <literal>\n</literal> en
        <literal>\r\n</literal> lorsque vous travaillez sur le fichier.
        À l'inverse, vous pouvez utiliser l'option <literal>'b'</literal> pour forcer
        le fichier à être écrit en mode binaire, sans traduction des données.
        Pour utiliser ces options, ajoutez <literal>'b'</literal> ou <literal>'t'</literal>
        comme dernier caractère du paramètre <parameter>mode</parameter>.
       </para>
       <para>
        Le mode de traduction par défaut est <literal>'b'</literal>.
        Vous pouvez utiliser <literal>'t'</literal> lorsque vous écrivez des
        fichiers de texte et le caractère <literal>\n</literal> pour définir
        vos fin de ligne, dans les scripts, mais que vous vous attendez à ce
        que le fichier soit relu par une application comme les anciennes versions
        de Notepad. Vous devriez toujours utiliser l'option <literal>'b'</literal>
        dans les autres cas.
       </para>
       <para>
        Si vous spécifiez <literal>'t'</literal> lorsque vous travaillez
        avec des fichiers binaires, vous pourriez rencontrer des problèmes
        avec vos données, comme des images corrompues ou des caractères
        <literal>\r\n</literal> inopinés.
       </para>
      </note>
      <note>
       <para>
        Pour des raisons de portabilité, il est fortement
        recommandé de réécrire les scripts qui utilisent l'option
        <literal>'t'</literal>, pour qu'ils utilisent le bon caractère
        de nouvelle ligne et le mode <literal>'b'</literal>.
       </para>
      </note>
      <note>
       <simpara>
        Le <parameter>mode</parameter> est ignoré pour les enveloppes de flux
        <filename>php://output</filename>, <filename>php://input</filename>,
        <filename>php://stdin</filename>, <filename>php://stdout</filename>,
        <filename>php://stderr</filename> et <filename>php://fd</filename>.
       </simpara>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>use_include_path</parameter></term>
     <listitem>
      <para>
       Le troisième paramètre optionnel <parameter>use_include_path</parameter> 
       peut être défini à &true; pour chercher le fichier dans 
       l'<link linkend="ini.include-path">include_path</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>context</parameter></term>
     <listitem>
      &note.context-support;
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne une ressource représentant le pointeur de fichier,
   &return.falseforfailure;
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  &fs.emits.warning.on.failure;
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.0.16, 7.1.2</entry>
       <entry>
        L'option <literal>'e'</literal> a été ajoutée.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>fopen</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$handle = fopen("/home/rasmus/file.txt", "r");
$handle = fopen("/home/rasmus/file.gif", "wb");
$handle = fopen("http://www.example.com/", "r");
$handle = fopen("ftp://user:password@example.com/somefile.txt", "w");
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &warn.ssl-non-standard;
  <note>
   <para>
   Si vous rencontrez des problèmes en lecture ou écriture
   de fichier et que vous utilisez PHP en version module de serveur,
   n'oubliez pas que les fichiers auxquels vous accédez ne sont
   pas nécessairement accessibles au processus serveur.
   </para>
  </note>
  <note>
   <para>
    Cette fonction peut également réussir lorsque <parameter>filename</parameter>
    est un dossier. Si vous avez un doute sur le fait que
    <parameter>filename</parameter> soit un fichier ou un dossier, vous pouvez
    utiliser la fonction <function>is_dir</function> avant d'utiliser la fonction
    <function>fopen</function>.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><xref linkend="wrappers"/></member>
    <member><function>fclose</function></member>
    <member><function>fgets</function></member>
    <member><function>fread</function></member>
    <member><function>fwrite</function></member>
    <member><function>fsockopen</function></member>
    <member><function>file</function></member>
    <member><function>file_exists</function></member>
    <member><function>is_readable</function></member>
    <member><function>stream_set_timeout</function></member>
    <member><function>popen</function></member>
    <member><function>stream_context_create</function></member>
    <member><function>umask</function></member>
    <member><classname>SplFileObject</classname></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
-->