reference/network/functions/header.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: cefe817294283d42d0555951c02b9223a5a5ca4a Maintainer: takagi Status: ready -->
<!-- Credits: mumumu -->
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.header">
 <refnamediv>
  <refname>header</refname>
  <refpurpose>生の HTTP ヘッダを送信する</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> は、生の
   <acronym>HTTP</acronym> ヘッダを送信するために使用されます。
   <acronym>HTTP</acronym> ヘッダについての詳細な情報は
   <link xlink:href="&url.rfc;2616">HTTP/1.1 仕様</link>
   を参照ください。
  </para>
  <para>
   覚えておいて頂きたいのは、<function>header</function> 関数は、
   通常の HTML タグまたは PHP からの出力にかかわらず、すべての実際の
   出力の前にコールする必要があることです。
   頻出するエラーとして、<function>include</function>
   または <function>require</function> 関数、他のファイルをアクセスする関数に
   空白または空行があり、<function>header</function> の前に出力が
   行われてしまうというものがあります。同じ問題は、単一の PHP/HTML
   ファイルを使用している場合でも存在します。
   <informalexample>
    <programlisting role="php">
<![CDATA[
<html>
<?php
/* これはエラーとなります。この上に出力があることに注目してください。
 * それは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>
       ヘッダ文字列。
      </para>
      <para>
       特殊な header コールが 2 種類あります。最初のものは、
       文字列 "<literal>HTTP/</literal>"
       から始まる全てのヘッダ (大文字・小文字は区別されません) です。
       このヘッダは、送信する HTTP ステータスコードを示すために使用されます。
       例えば、存在しないファイルへのリクエストを処理するためにある PHP
       スクリプトを使用するよう (<literal>ErrorDocument</literal>
       ディレクティブにより) Apache を設定する場合、
       そのスクリプトが正しいステータスコードを返すようにする必要があります。
      </para>
      <para>
       <informalexample>
        <programlisting role="php">
<![CDATA[
<?php
// この例は、"HTTP/" から始まる特別な場合を示しています。
// これより良い、典型的な使い方として、以下があげられます:
// 1. header($_SERVER["SERVER_PROTOCOL"] . " 404 Not Found");
//    (HTTP/1.0 を使いながら、httpステータスメッセージを上書きする)
// 2. http_response_code(404); (デフォルトのメッセージを使う)
header("HTTP/1.1 404 Not Found");
?>
]]>
        </programlisting>
       </informalexample>
      </para>
      <para>
       2 番目の特別なヘッダは、"Location:"
       ヘッダです。このヘッダがブラウザに返されるだけではなく、
       ブラウザに <literal>REDIRECT</literal> (302) ステータスコードを返します
       (<literal>201</literal> や <literal>3xx</literal>
       ステータスコードが既に送信されていない場合にのみ)。
      </para>
      <para>
       <informalexample>
        <programlisting role="php">
<![CDATA[
<?php
header("Location: http://www.example.com/"); /* ブラウザをリダイレクトします */

/* リダイレクトする際に、これ以降のコードが実行されないことを確認してください */
exit;
?>
]]>
        </programlisting>
       </informalexample>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>replace</parameter></term>
     <listitem>
      <para>
       オプションのパラメータ <parameter>replace</parameter> は、ヘッダが
       前に送信された類似のヘッダを置換するか、または、同じ形式の二番目の
       ヘッダを追加するかどうかを指定します。デフォルトでは、この関数は
       置換を行ないますが、二番目の引数に &false; を指定すると、同じ型の
       複数のヘッダを強制的に生成します。例えば、
      </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>
       HTTP レスポンスコードを強制的に指定の値にします。このパラメータが意味をなすのは
       <parameter>header</parameter> が空文字列でないときだけであることに注意しましょう。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

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

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   ヘッダを予定通りに送信できなかった場合、
   <function>header</function> 関数は
   <constant>E_WARNING</constant> レベルの警告を発生させます。
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>ダウンロードダイアログ</title>
    <para>
     PDF ファイルを生成した場合など、
     それをダウンロードするかの確認ダイアログを表示させたいことがあるでしょう。
     そんな場合は、<link xlink:href="&url.rfc;2183">Content-Disposition</link>
     ヘッダを使用してファイル名を指定すると、ブラウザ側でダイアログを表示させることができます。
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// PDFを出力します
header('Content-Type: application/pdf');

// downloaded.pdf という名前で保存させます
header('Content-Disposition: attachment; filename="downloaded.pdf"');

// もとの PDF ソースは original.pdf です
readfile('original.pdf');
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>キャッシュディレクティブ</title>
    <para>
     PHP スクリプトはしばしば動的に HTML を生成するため、クライアント
     ブラウザやサーバーおよびクライアントブラウザの間でプロキシがキャッシュを
     行ったりするべきではありません。多くのプロキシとクライアントでは、
     以下のコードにより強制的にキャッシュを無効にできます。
    </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"); // 過去の日付
?>
]]>
    </programlisting>
    <para>
     <note>
      <para>
       上記のヘッダを全て出力しなかったとしてもページのキャッシュが
       行われない場合があることに気付くかもしれません。デフォルトの
       ブラウザのキャッシュの動作をユーザーが変更できる手段はいくつもあります。
       上記のヘッダを送信することにより、スクリプトの出力がキャッシュされる
       可能性がある設定を上書きするべきです。
      </para>
      <para>
       さらに、<function>session_cache_limiter</function> および
       設定 <literal>session.cache_limiter</literal> を用いると、
       セッションが使用された際にキャッシュ関係の正しいヘッダを
       自動的に生成させることもできます。
      </para>
     </note>
    </para>
   </example>
  </para>
  <para>
   <example>
    <title>クッキーを設定する</title>
    <para>
     <function>setcookie</function> は、クッキーを設定する便利な方法を提供します。
     <function>setcookie</function> がサポートしていない属性をクッキーに設定する方法として、
     <function>header</function> が使えます。
    </para>
    <para>
     たとえば、以下のコードは
     <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;
  &note.network.header.sapi;
  <note>
   <para>
    出力のバッファリングを使用してこの問題を回避することができます。
    この場合、ブラウザへの出力が送信するまでサーバーに
    全てバッファリングされるオーバーヘッドがあります。出力バッファリングは、
    <function>ob_start</function> と
    <function>ob_end_flush</function> をスクリプトでコールするか
    &php.ini; またはサーバー設定ファイルの設定ディレクティブ
    <literal>output_buffering</literal> を設定することにより
    行うことが可能です。
   </para>
  </note>
  <note>
   <para>
    実際に <function>header</function> が最初にコールされたか
    どうかにかかわらず、HTTP ステータスヘッダ行は
    クライアントに対し常に最初に送信されます。
    HTTP ヘッダが既に送信されていない限り、
    <function>header</function> をコールすることでステータスは
    常に上書きされます。
   </para>
  </note>
  <note>
   <para>
    最近のクライアントの大半は
    <link xlink:href="&spec.http1.1;#section-7.1.2">Location:</link>
    への引数として相対 <acronym>URI</acronym> も受け付けますが、
    古いクライアントの中にはスキームとホスト名そして絶対パスを含む絶対 URL しか受け付けないものもあります。
    通常は、相対 URI から絶対 URI を作成するためには
    <varname>$_SERVER['HTTP_HOST']</varname>、
    <varname>$_SERVER['PHP_SELF']</varname> および
    <function>dirname</function> を使用できます。
    <informalexample>
     <programlisting role="php">
<![CDATA[
<?php
/* カレントディレクトリの別のページにリダイレクトします */
$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>
    <link linkend="ini.session.use-trans-sid">session.use_trans_sid</link>
    が有効であったとしても、セッション ID が Location ヘッダとともに
    渡されることはありません。<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>
     <link linkend="features.http-auth">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
-->