doc-fr/reference/outcontrol/functions/ob-start.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 9e0a39029d6e66cd5f7c7e8cfecf76fdb8ad7f49 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="function.ob-start" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>ob_start</refname>
  <refpurpose>Enclenche la temporisation de sortie</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>ob_start</methodname>
   <methodparam choice="opt"><type>callable</type><parameter>callback</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>chunk_size</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>PHP_OUTPUT_HANDLER_STDFLAGS</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>ob_start</function> démarre la temporisation de sortie. 
   Tant qu'elle est enclenchée, aucune donnée, hormis les en-têtes, 
   n'est envoyée au navigateur, mais temporairement mise en tampon.
  </para>
  <para>
   Le contenu de ce tampon peut être copié dans une chaîne
   avec la fonction <function>ob_get_contents</function>. Pour afficher le
   contenu de ce tampon, utilisez <function>ob_end_flush</function>. Au
   contraire, <function>ob_end_clean</function> effacera le contenu de ce
   tampon.
  </para>
  <warning>
   <para>
    Quelques serveurs web (par exemple Apache) modifient le dossier de
    travail d'un script lorsqu'il appelle une fonction de rappel.
    Vous pouvez revenir à un comportement normal en ajoutant
    <literal>chdir(dirname($_SERVER['SCRIPT_FILENAME']))</literal>
    dans votre fonction de rappel.
   </para>
  </warning>
  <para>
   Les tampons de sortie sont gérés par pile, c'est-à-dire que vous pouvez
   appeler plusieurs fois <function>ob_start</function> simultanément.
   Assurez-vous que vous appelez <function>ob_end_flush</function>
   suffisamment souvent. Si plusieurs fonctions de rappel sont actives,
   les contenus seront filtrés séquentiellement, dans l'ordre d'emboîtement.
  </para>
  <para>
   Si les tampons de sortie sont encore actif quand le script se termine,
   PHP affiche le contenu automatiquement.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
       Une fonction optionnelle de rappel peut être spécifiée.
       Cette fonction prend une chaîne comme paramètre, et
       retourne une chaîne. Elle sera appelée lorsque le tampon sera envoyé
       ou supprimé (avec les fonctions <function>ob_flush</function>,
       <function>ob_clean</function> ou des fonctions similaires)
       ou lorsque le tampon sera envoyé
       au navigateur à la fin du script et recevra le contenu du tampon de
       sortie. Lorsque la fonction <parameter>callback</parameter> est
       appelée, elle doit retourner un nouveau contenu pour le tampon de sortie :
       celui-ci sera envoyé au navigateur. Si <parameter>callback</parameter>
       n'est pas une fonction accessible, la fonction retournera &false;.
       Voici la signature de la fonction de rappel :
      </para>
      <para>
       <methodsynopsis>
        <type>string</type><methodname><replaceable>handler</replaceable></methodname>
        <methodparam><type>string</type><parameter>buffer</parameter></methodparam>
        <methodparam choice="opt"><type>int</type><parameter>phase</parameter></methodparam>
       </methodsynopsis>
       <variablelist>
        <varlistentry>
         <term><parameter>buffer</parameter></term>
         <listitem>
          <simpara>
           Contenu du buffer de sortie.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>phase</parameter></term>
         <listitem>
          <simpara>
           Masque de bits de <link linkend="outcontrol.constants">constantes
           <constant>PHP_OUTPUT_HANDLER_*</constant></link>.
          </simpara>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
      <para>
       Si <parameter>callback</parameter> retourne &false;,
       l'entrée originale est envoyée au navigateur.
      </para>
      <para>
       Le paramètre <parameter>callback</parameter> peut être annulé
       en y passant la valeur &null;.
      </para>
      <para>
       <function>ob_end_clean</function>, <function>ob_end_flush</function>,
       <function>ob_clean</function>, <function>ob_flush</function> et
       <function>ob_start</function> ne doivent pas être appelés depuis une
       fonction de rappel. Si vous les appelez depuis une fonction de
       rappel, le comportement ne sera pas défini. Si vous voulez effacer
       le contenu du tampon, retournez "" (une chaîne vide) depuis la fonction
       de rappel. Vous ne pourrez jamais appeler les fonctions utilisant
       la fonction de temporisation de sortie comme
       <literal>print_r($expression, true)</literal> ou
       <literal>highlight_file($filename, true)</literal> depuis une fonction de
       rappel.
      </para>
      <note>
       <para>
        La fonction <function>ob_gzhandler</function> a été
        introduite pour faciliter l'envoi de fichiers compressés
        avec gzip aux navigateurs web qui supportent les pages
        compressées. <function>ob_gzhandler</function>
        détermine le type d'encodage accepté par un navigateur,
        et retourne le contenu le plus adéquat.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>chunk_size</parameter></term>
     <listitem>
      <para>
       Si le paramètre optionnel <parameter>chunk_size</parameter> est passé,
       la fonction de rappel est appelée à chaque nouvelle ligne après 
       <parameter>chunk_size</parameter> octets d'affichage. La valeur
       par défaut <literal>0</literal> (zéro) signifie que l'affichage
       de la fonction ne sera appelé que lorsque le buffer de sortie est clos.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       Le paramètre <parameter>flags</parameter> est un masque qui contrôle
       les opérations qui peuvent être effectuées sur le tampon de sortie.
       Par défaut, il autorise le tampon de sortie à être nettoyé, envoyé
       et supprimé, ce qui peut être défini explicitement avec les constantes
       <constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant> |
       <constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant> |
       <constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant>, ou
       <constant>PHP_OUTPUT_HANDLER_STDFLAGS</constant> comme alias.
      </para>
      <para>
       Chaque drapeau contrôle l'accès à un jeu de fonctions, tel décrit
       ci-dessous :
       <informaltable>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Constante</entry>
           <entry>Fonctions</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant></entry>
           <entry>
            <function>ob_clean</function>,
            <function>ob_end_clean</function> et
            <function>ob_get_clean</function>.
           </entry>
          </row>
          <row>
           <entry><constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant></entry>
           <entry>
            <function>ob_end_flush</function>,
            <function>ob_flush</function> et
            <function>ob_get_flush</function>.
           </entry>
          </row>
          <row>
           <entry><constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant></entry>
           <entry>
            <function>ob_end_clean</function>,
            <function>ob_end_flush</function> et
            <function>ob_get_flush</function>.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </informaltable>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple de gestion de sortie avec fonction de rappel</title>
    <programlisting role="php">
<![CDATA[
<?php

function rappel($buffer)
{
  // remplace toutes les pommes par des carottes
  return (str_replace("pommes de terre", "carottes", $buffer));
}

ob_start("rappel");

?>
<html>
<body>
<p>C'est comme comparer des carottes et des pommes de terre.</p>
</body>
</html>
<?php

ob_end_flush();

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
<html>
<body>
<p>C'est comme comparer des carottes et des carottes.</p>
</body>
</html>
]]>
    </screen>
   </example>
  </para>

  <para>
   <example xml:id="function.ob-start.flags-bc">
    <title>Crée un tampon de sortie in-effaçable</title>
    <programlisting role="php">
<![CDATA[
<?php

ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>ob_get_contents</function></member>
    <member><function>ob_end_clean</function></member>
    <member><function>ob_end_flush</function></member>
    <member><function>ob_implicit_flush</function></member>
    <member><function>ob_gzhandler</function></member>
    <member><function>ob_iconv_handler</function></member>
    <member><function>mb_output_handler</function></member>
    <member><function>ob_tidyhandler</function></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
-->