doc-fr/reference/http/functions/header.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.23 $ -->
<!-- EN-Revision: 1.24 Maintainer: yannick Status: ready -->
 <refentry id="function.header">
  <refnamediv>
   <refname>header</refname>
   <refpurpose>Envoie un en-tête HTTP</refpurpose>
  </refnamediv>
  <refsect1>
   <title>Description</title>
   <methodsynopsis>
    <type>void</type><methodname>header</methodname>
    <methodparam><type>string</type><parameter>string</parameter></methodparam>
    <methodparam choice="opt"><type>bool</type><parameter>replace</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>http_response_code</parameter></methodparam>
   </methodsynopsis>
   <para>
    <function>header</function> permet de spécifier l'en-tête <acronym>HTTP</acronym>
    <parameter>string</parameter> lors de l'envoi des fichiers HTML.
    Reportez-vous à <ulink url="&url.rfc;2616">HTTP/1.1 Specification</ulink>
    pour plus d'informations sur les en-têtes <acronym>HTTP</acronym>.
   </para>
   <para>
    Le paramètre optionnel <parameter>replace</parameter> indique
    si la fonction <function>header</function> doit remplacer
    un en-tête précédemment émis, ou bien ajouter un autre en-tête
    du même type. Par défaut, un nouvel en-tête va écraser le
    précédent, mais si vous passez &false; dans cet argument, vous pouvez
    forcer les en-têtes multiples pour un même type d'en-tête.
    Par exemple :
   </para>
   <para>
    <example>
     <title>Identification HTTP avec <function>header</function></title>
     <programlisting role="php">
<![CDATA[
<?php
header('WWW-Authenticate: Negotiate');
header('WWW-Authenticate: NTLM', false);
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Le second paramètre optionnel force
    le code de réponse HTTP à la valeur de <parameter>http_response_code</parameter>.
    Ce paramètre est disponible en &php; 4.3.0 et plus récent.
   </para>
   <para>
    Il y a deux en-têtes spéciaux. Le premier commence par la chaîne
    "<literal>HTTP/</literal>" (insensible à la casse), qui est utilisée
    pour signifier le statut HTTP à envoyer. Par exemple, si vous avez configuré
    Apache pour utiliser les scripts &php; pour gérer les requêtes vers des fichiers
    inexistants (en utilisant la directive <literal>ErrorDocument</literal>),
    vous voulez-vous assurer que le script génère un code statut correct.
   </para>
   <para>
    <example>
     <title>Générer une erreur 404 avec <function>header</function></title>
     <programlisting role="php">
<![CDATA[
<?php
header("HTTP/1.0 404 Not Found");
?>
]]>
     </programlisting>
    </example>
   </para>
   <note>
    <para>
     Le code statut HTTP doit toujours être le premier à être envoyé au client, au regard de
     l'actuel <function>header</function> qui peut être le premier ou non.
     Le statut peut être écrasé en appelant <function>header</function> avec
     un nouveau statut à n'importe quel moment même si l'en-tête HTTP a déjà été envoyé.
    </para>
   </note>
   <note>
    <para>
     En &php; 3, celà ne fonctionne que si &php; est compilé en tant que module d'Apache.
     Vous arriverez au même effet en utilisant l'en-tête <literal>Status</literal>.
     <example>
      <title><function>header</function> en &php; 3</title>
      <programlisting role="php">
<![CDATA[
<?php
header("Status: 404 Not Found");
?>
]]>
      </programlisting>
     </example>
    </para>
   </note>
   <para>
    Le deuxième type d'appel spécial est <literal>"Location:"</literal>. Non seulement
    il renvoie un en-tête au  client, mais, en plus, il envoie un statut
    <literal>REDIRECT</literal> (302) à
    Apache. Du point de vue de l'auteur de script, cela importe peu,
    mais pour ceux qui connaissent les rouages internes d'Apache, c'est
    primordial.
   </para>
   <para>
    <example>
     <title>Redirection HTTP avec <function>header</function></title>
     <programlisting role="php">
<![CDATA[
<?php
/* Redirige le client vers le site PHP */
header("Location: http://www.php.net/");

/* Garantie que le code ci-dessous n'est jamais exécuté. */
exit();
?>
]]>
     </programlisting>
    </example>
   </para>
   <note>
    <para>
     HTTP/1.1 demande une <acronym>URI</acronym> absolue comme argument
     de <ulink url="&spec.http1.1;-sec14.html#sec14.30"><literal>Location:</literal></ulink>,
     y compris le protocole, hôte et chemin absolu. Mais certains
     navigateurs acceptent les URI relatives. Vous pouvez généralement
     utiliser les variables globales <varname>$_SERVER['HTTP_HOST']</varname>,
     <varname>$_SERVER['PHP_SELF']</varname> et <function>dirname</function> pour
     construire vous-même une URI absolue :
     <example>
      <title>Redirection à l'aide de <function>header</function></title>
      <programlisting role="php">
<![CDATA[
<?php
header("Location: http://" . $_SERVER['HTTP_HOST']
                     . dirname($_SERVER['PHP_SELF'])
                     . "/" . $relative_url);
?>
]]>
      </programlisting>
     </example>
    </para>
   </note>
   <para>
    Les scripts &php; génèrent souvent du HTML dynamiquement,
    qui ne doit pas être mis en cache, ni par le client, ni par les
    proxy intermédiaires. On peut forcer la désactivation du
    cache de nombreux clients et proxy avec :
    <example>
     <title>Interdire la mise en cache avec <function>header</function></title>
     <programlisting role="php">
<![CDATA[
<?php
// Date du passé
header("Expires: Mon, 26 Jul 1997 05:00:00 GMT");

// toujours modifié
header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT");

// HTTP/1.1
header("Cache-Control: no-store, no-cache, must-revalidate");
header("Cache-Control: post-check=0, pre-check=0", false);

// HTTP/1.0
header("Pragma: no-cache");
?>
]]>
     </programlisting>
    </example>
   </para>
   <note>
    <para>
     Vous pouvez vous rendre compte que vos pages ne sont jamais mises
     en cache même si vous utilisez tous les en-têtes ci-dessus.
     Il existe toute une collection de paramètres que les utilisateurs
     peuvent modifier sur leur navigateur pour modifier le
     comportement par défaut du cache. En envoyant les en-têtes
     ci-dessus, vous pouvez imposer vos propres valeurs.
    </para>
    <para>
     De plus, les paramètres <function>session_cache_limiter</function> et
     <literal>session.cache_limiter</literal> peuvent être utilisés pour
     générer les en-têtes de caches corrects, lorsque les sessions sont
     utilisées.
    </para>
   </note>
   <para>
    N'oubliez jamais que <function>header</function> doit être appelée
    avant que le moindre contenu ne soit envoyé, soit par des
    lignes HTML habituelles dans le fichier, soit par des affichges
    &php;. Une erreur très classique est de lire un fichier avec
    <function>include</function> ou <function>require</function>,
    et de laisser des espaces ou des lignes vides, qui génèreront
    un affichage avant que la fonction <function>header</function>
    ne soit appelée. Le même problème existe avec les fichiers
    &php;/HTML standards.
    <example>
     <title><function>header</function> doit toujours être appelé en premier</title>
     <programlisting role="php">
<![CDATA[
<?php

  require("user_logging.inc")
?>
<?php
  header("Content-Type: audio/x-pn-realaudio");
?>
&nbsp;
// Erreur :  Notez la ligne blanche ci-dessus
?>
]]>
     </programlisting>
    </example>
   </para>
   <note>
    <para>
     Depuis &php; 4, vous pouvez utiliser le système de cache (output buffering)
     pour contourner ce problème. Tous vos textes générés seront
     mis en buffer sur le serveur jusqu'à ce que vous les envoyiez. Vous pouvez
     utiliser les fonctions <function>ob_start</function> et
     <function>ob_end_flush</function> dans vos scripts, ou en
     modifiant la directive de configuration <literal>output_buffering</literal>
     dans votre fichier &php.ini; ou vos fichiers
     de configuration du serveur.
    </para>
   </note>
   <para>
    Si vous voulez que vos utilisateur recoivent une alerte pour sauver
    les fichiers générés, comme si vous génériez un
    fichier PDF, vous pouvez utiliser l'en-tête
    <ulink url="&url.rfc;2183">Content-Disposition</ulink> pour
    fournir un nom de fichier par défaut, à afficher dans le
    dialogue de sauvegarde.
    <example>
     <title>
      Utilisation de <function>header</function> pour générer
      un fichier de type PDF ou d'un autre type
     </title>
     <programlisting role="php">
<![CDATA[
<?php
// Vous voulez afficher un pdf
header('Content-type: application/pdf');

// Il sera nommé downloaded.pdf
header('Content-Disposition: attachment; filename="downloaded.pdf"');

// Le source du PDF original.pdf
readfile('original.pdf');
?>
]]>
     </programlisting>
    </example>
    <note>
     <para>
      Il y a un bogue sous Microsoft Internet Explorer 4.01 qui empêche
      cet en-tête de fonctionner. Il n'y a pas d'autre solution.
      Il y a aussi un bogue dans Microsoft Internet Explorer 5.5 qui
      interfère avec ceci, mais qui peut être résolu en utilisant
      le Service Pack 2 ou plus récent.
     </para>
    </note>
   </para>
   <note>
    <simpara>
     Si &safemode; est activé, l'UID du script est ajouté
     à la partie <literal>realm</literal> des en-têtes
     <literal>WWW-Authenticate</literal> que vous envoyez avec
     cet en-tête.
    </simpara>
   </note>
   <para>
    Voir aussi
    <function>headers_sent</function>,
    <function>setcookie</function> et la section sur
    <link linkend="features.http-auth">l'authentification HTTP </link>.
    </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:"../../../../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
-->