mirror of
https://github.com/macintoshplus/doc-fr.git
synced 2026-03-24 17:02:18 +01:00
353 lines
11 KiB
XML
353 lines
11 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- EN-Revision: 5c1ccc6e24e5d470e75ef0a5887c2ff583266375 Maintainer: yannick Status: ready -->
|
|
<!-- Reviewed: no -->
|
|
|
|
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.header">
|
|
<refnamediv>
|
|
<refname>header</refname>
|
|
<refpurpose>Envoie un en-tête HTTP brut</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>header</methodname>
|
|
<methodparam><type>string</type><parameter>header</parameter></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter>replace</parameter><initializer>&true;</initializer></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>response_code</parameter><initializer>0</initializer></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 à <link xlink:href="&url.rfc;2616"><literal>HTTP/1.1
|
|
Specification</literal></link> pour plus d'informations sur les en-têtes
|
|
<acronym>HTTP</acronym>.
|
|
</para>
|
|
<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 affichages
|
|
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 produiront
|
|
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.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<html>
|
|
<?php
|
|
/* Ceci produira une erreur. Notez la sortie ci-dessus,
|
|
* qui se trouve avant l'appel à la fonction header() */
|
|
header('Location: http://www.example.com/');
|
|
exit;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>header</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
L'en-tête.
|
|
</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>),
|
|
assurez-vous que le script génère un code statut correct.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// This example illustrates the "HTTP/" special case
|
|
// Better alternatives in typical use cases include:
|
|
// 1. header($_SERVER["SERVER_PROTOCOL"] . " 404 Not Found");
|
|
// (to override http status messages for clients that are still using HTTP/1.0)
|
|
// 2. http_response_code(404); (to use the default message)
|
|
header("HTTP/1.1 404 Not Found");
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<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) au navigateur
|
|
tant qu'un code statut <literal>201</literal> ou <literal>3xx</literal>
|
|
n'a pas été envoyé.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header("Location: http://www.example.com/"); /* Redirection du navigateur */
|
|
|
|
/* Assurez-vous que la suite du code ne soit pas exécutée une fois la redirection effectuée. */
|
|
exit;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>replace</parameter></term>
|
|
<listitem>
|
|
<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>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header('WWW-Authenticate: Negotiate');
|
|
header('WWW-Authenticate: NTLM', false);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>response_code</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Force le code réponse HTTP à la valeur spécifiée. À noter que ce
|
|
paramètre a un effet uniquement si <parameter>header</parameter>
|
|
n'est pas vide.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
&return.void;
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="errors">
|
|
&reftitle.errors;
|
|
<para>
|
|
Lors de l'échec de la planification de l'envoi d'un en-tête,
|
|
<function>header</function> lève une erreur de niveau
|
|
<constant>E_WARNING</constant>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title>Boîte de téléchargement</title>
|
|
<para>
|
|
Si vous voulez que vos utilisateurs 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
|
|
<link xlink:href="&url.rfc;2183">Content-Disposition</link> pour
|
|
fournir un nom de fichier par défaut, à afficher dans le
|
|
dialogue de sauvegarde.
|
|
</para>
|
|
<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>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Directives concernant la mise en cache</title>
|
|
<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 :
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1
|
|
header("Expires: Sat, 26 Jul 1997 05:00:00 GMT"); // Date dans le passé
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<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>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Paramétrer un cookie</title>
|
|
<para>
|
|
<function>setcookie</function> offre un moyen pratique de paramétrer des cookies.
|
|
Pour définir un cookie avec des attributs non pris en charge par <function>setcookie</function>,
|
|
<function>header</function> peut être utilisé.
|
|
</para>
|
|
<para>
|
|
Par exemple, le code suivant définit un cookie qui inclut un attribut
|
|
<literal>Partitioned</literal>.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header('Set-Cookie: name=value; Secure; Path=/; SameSite=None; Partitioned;');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
¬e.network.header.sapi;
|
|
<note>
|
|
<para>
|
|
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>
|
|
<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>
|
|
La plupart des clients moderne accepte des <acronym>URI</acronym>s relative comme argument de
|
|
<link xlink:href="&spec.http1.1;#section-7.1.2">Location:</link>,
|
|
mais certains client plus ancien exigent une URI absolue
|
|
y compris le protocole, l'hôte et le chemin absolu. 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 :
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/* Redirection vers une page différente du même dossier */
|
|
$host = $_SERVER['HTTP_HOST'];
|
|
$uri = rtrim(dirname($_SERVER['PHP_SELF']), '/\\');
|
|
$extra = 'mypage.php';
|
|
header("Location: http://$host$uri/$extra");
|
|
exit;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
L'ID de session n'est pas passé avec l'en-tête Location même si
|
|
<link linkend="ini.session.use-trans-sid">session.use_trans_sid</link>
|
|
est activé. Il doit être passé manuellement en utilisant la constante
|
|
<constant>SID</constant>.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>headers_sent</function></member>
|
|
<member><function>setcookie</function></member>
|
|
<member><function>http_response_code</function></member>
|
|
<member><function>header_remove</function></member>
|
|
<member><function>headers_list</function></member>
|
|
<member>
|
|
La section sur l'<link linkend="features.http-auth">identification
|
|
HTTP</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
|
|
-->
|