archived-doc-ja/reference/network/functions/setcookie.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 6122a8317ca0068fc71f6a5167e0a2d99166ec7c Maintainer: mumumu Status: ready -->
<refentry xml:id="function.setcookie" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>setcookie</refname>
  <refpurpose>クッキーを送信する</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>setcookie</methodname>
   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>expires_or_options</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>path</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>domain</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>secure</parameter><initializer>&false;</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>&false;</initializer></methodparam>
  </methodsynopsis>
  <simpara>PHP 7.3.0 以降で使える代替のシグネチャ(名前付き引数をサポートしていません):</simpara>
  <methodsynopsis>
   <type>bool</type><methodname>setcookie</methodname>
   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
  </methodsynopsis>
  <simpara>
   <function>setcookie</function> は、その他のヘッダ情報と共に
   送信するクッキーを定義します。 ほかのヘッダ情報と同様に、
   クッキーは、スクリプトによる他のあらゆる出力よりも<emphasis>前に</emphasis>
   送信される必要があります（これはHTTPプロトコルの制約です）。
   <literal>&lt;html&gt;</literal> や <literal>&lt;head&gt;</literal> タグはもちろん
   空白も含め、あらゆる出力よりも前にこの関数をコールするようにしなければなりません。
  </simpara>
  <simpara>
   一度クッキーが送信されると、次のページのロードからは
   <varname>$_COOKIE</varname> 配列によってクッキーにアクセスできます。
   クッキーの値は <varname>$_REQUEST</varname>
   配列からもアクセスできるかもしれません。
  </simpara>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <function>setcookie</function>
   の各パラメータがどのように解釈されるのかについては、
   <link xlink:href="&url.rfc;6265">RFC 6265</link>
   が標準的なリファレンスを提供しています。
   <variablelist>
    <varlistentry>
     <term><parameter>name</parameter></term>
     <listitem>
      <simpara>
       クッキーの名前。
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>value</parameter></term>
     <listitem>
      <simpara>
       クッキーの値。この値はクライアントのコンピュータに保存されますので、
       重要な情報は格納しないでください。
       <parameter>name</parameter> が <literal>'cookiename'</literal> だとすると、
       その値は <varname>$_COOKIE['cookiename']</varname> で取得することができます。
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>expires_or_options</parameter></term>
     <listitem>
      <simpara>
       クッキーが期限切れになる時間。
       これは Unix タイムスタンプなので
       Epoch（1970 年 1 月 1 日）からの経過秒数となります。
       この値を設定するひとつの方法として、
       <function>time</function> が返した値に、
       期限としたい必要な秒数を加算することが考えられます。
       たとえば、<literal>time()+60*60*24*30</literal>
       はクッキーの有効期限を 30 日後にセットします。
       別のやり方として、<function>mktime</function> を使うことも考えられます。
       この値に <literal>0</literal> を設定したり省略したりした場合は、
       クッキーはセッションの最後(つまりブラウザを閉じるとき) が有効期限となります。
      </simpara>
      <note>
       <simpara>
        <parameter>expires_or_options</parameter> パラメータには、
        <literal>Wdy, DD-Mon-YYYY HH:MM:SS GMT</literal>
        といった形式ではなく、Unix タイムスタンプを渡します。
        これは、PHP の内部で自動的に変換を行っているからです。
       </simpara>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>path</parameter></term>
     <listitem>
      <simpara>
       サーバー上での、クッキーを有効としたいパス
       <literal>'/'</literal> をセットすると、クッキーは
       <parameter>domain</parameter> 配下の全てで有効となります。
       <literal>'/foo/'</literal> をセットすると、クッキーは
       <literal>/foo/</literal> ディレクトリとそのサブディレクトリ配下
       (例えば <literal>/foo/bar/</literal>) で有効となります。
       デフォルト値は、クッキーがセットされたときのカレントディレクトリです。
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>domain</parameter></term>
     <listitem>
      <simpara>
       クッキーが有効な (サブ) ドメイン。これを
       <literal>'www.example.com'</literal> などのサブドメインに設定すると、
       <literal>www</literal>
       サブドメインおよびそれ自身のすべてのサブドメイン
       (w2.www.example.com など) でクッキーが使えるようになります。
       サブドメインを含むドメイン全体でクッキーを有効にしたければ、
       そのドメイン自体
       (この場合は <literal>'example.com'</literal>) を設定します。
      </simpara>
      <simpara>
       古いブラウザの中には、非推奨になった
       <link xlink:href="&url.rfc;2109">RFC 2109</link>
       を実装しているものが未だに残っているかもしれません。
       そのようなブラウザでは、すべてのサブドメインにマッチさせるためには先頭に
       <literal>.</literal> が必要となります。
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>secure</parameter></term>
     <listitem>
      <simpara>
       クライアントからのセキュアな HTTPS 接続の場合にのみクッキーが送信されるようにします。
       &true; を設定すると、セキュアな接続が存在する場合にのみクッキーを設定します。
       サーバー側では、このようにセキュアな接続の場合にのみクッキーを送信するという処理は
       プログラマの責任で行うことになります
       (たとえば <varname>$_SERVER["HTTPS"]</varname> の内容を使用します)。
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>httponly</parameter></term>
     <listitem>
      <simpara>
       &true; を設定すると、HTTP を通してのみクッキーにアクセスできるようになります。
       つまり、JavaScript のようなスクリプト言語からはアクセスできなくなるということです。
       この設定を使用すると、XSS 攻撃によって ID を盗まれる危険性を減らせる
       (が、すべてのブラウザがこの設定をサポートしているというわけではありません)
       と言われていますが、これはしばしば議論の対象となります。
       &true; あるいは &false; で指定します。
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <simpara>
       <literal>expires</literal>, <literal>path</literal>, <literal>domain</literal>,
       <literal>secure</literal>, <literal>httponly</literal> および <literal>samesite</literal>
       のうちから、任意のキーを設定可能な連想配列(<type>array</type>)です。
      </simpara>
      <simpara>
       値については、キーと同じ名前のパラメーターで説明した意味と同じです。
       <literal>samesite</literal> 要素の値は、
       <literal>None</literal>, <literal>Lax</literal> または <literal>Strict</literal> です。
       上記で許されているオプションのうち、与えられなかったものについては、
       デフォルト値は明示的にパラメータを与えた場合のデフォルト値と同じです。
       <literal>samesite</literal> 要素が省略された場合は、SameSite クッキー属性は設定されません。
      </simpara>

      <note>
       <simpara>
        上のリストにないキーをクッキーの属性に設定する場合、
        <function>header</function> を使います。
       </simpara>
      </note>
      <note>
       <simpara>
        <literal>samesite</literal> を <literal>"None"</literal>
        に設定する場合、<literal>secure</literal>
        も有効にしなければなりません。
        さもないと、クッキーがクライアントにブロックされてしまいます。
       </simpara>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <simpara>
   もしもこの関数をコールする前に何らかの出力がある場合には、
   <function>setcookie</function> は失敗し &false; を返します。
   <function>setcookie</function> が正常に実行されると、&true; を返します。
   この関数では、ユーザーがクッキーを受け入れたかどうかを判断することはできません。
  </simpara>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   <parameter>options</parameter> 配列にサポートされていないキーが含まれている場合:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     PHP 8.0.0 より前のバージョンでは、<constant>E_WARNING</constant> が発生していました。
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     PHP 8.0.0 以降では、<exceptionname>ValueError</exceptionname> がスローされます。
    </simpara>
   </listitem>
  </itemizedlist>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.2.0</entry>
      <entry>
       Cookie の日付フォーマットが <literal>'D, d M Y H:i:s \G\M\T'</literal> になりました。
       これより前のバージョンでは <literal>'D, d-M-Y H:i:s T'</literal> でした。
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       サポートされていないキーを渡すと、<constant>E_WARNING</constant>
       を発生させる代わりに <exceptionname>ValueError</exceptionname> をスローするようになりました。
      </entry>
     </row>
     <row>
      <entry>7.3.0</entry>
      <entry>
       <parameter>options</parameter> 配列をサポートする追加のシグネチャが追加されました。
       このシグネチャは、SameSite クッキー属性の設定もサポートしています。
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <simpara>
   The effects of the following examples can be observed using the browser
   developer tools cookie list (usually in the Storage or Application tab).
  </simpara>
  <example>
   <title><function>setcookie</function> でクッキーを送信する例</title>
   <programlisting role="php">
<![CDATA[
<?php

$value = 'something from somewhere';

// Set a "session cookie" that expires when the browser is closed
setcookie("TestCookie", $value);
// Set a cookie that expires in 1 hour
setcookie("TestCookie", $value, time()+3600);
// Set a cookie that applies only to a specific path on a specific domain
// Note that the domain used should match the site domain
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", true);

?>
]]>
   </programlisting>
  </example>
  <simpara>
   クッキーの value の部分は、クッキーの送信を行う際に自動的に
   URL エンコードされ、またクッキーを受信した際は、自動的にデコード
   されることに注意してください。
   この挙動は
   <function>setrawcookie</function> を代わりに使うことでで回避できます。
  </simpara>
  <simpara>
   上の例でセットしたクッキーの内容を、
   後続のリクエストで参照するには、以下のようにします:
  </simpara>
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
// Print an individual cookie
echo $_COOKIE["TestCookie"];

// Another way to debug/test is to view all cookies
print_r($_COOKIE);
?>
]]>
   </programlisting>
  </informalexample>
  <example>
   <title><function>setcookie</function> でクッキーを削除する例</title>
   <simpara>
    クッキーを削除する場合には、ブラウザの削除機構を起動するために
    必ず有効期限を過去(但し、0 ではありません。
    0はセッションクッキーのために予約されています)
    に設定する必要があります。
   </simpara>
   <simpara>
    先ほどの例で送信したクッキーを削除する例を以下に示します:
   </simpara>
   <programlisting role="php">
<![CDATA[
<?php
// set the expiration date to one hour ago
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>
]]>
   </programlisting>
  </example>
  <example>
   <title><function>setcookie</function> と配列</title>
   <simpara>
    クッキー名に配列記法を使うことで、
    "クッキーの配列"を設定することも可能です。
    これにより配列要素と同数のクッキーを設定されますが、
    クッキーがスクリプトに受信された際に、
    値はクッキー名を有する配列に置きかえられます。
   </simpara>
   <programlisting role="php">
<![CDATA[
<?php
// set the cookies
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");

// after the page reloads, print them out
if (isset($_COOKIE['cookie'])) {
    foreach ($_COOKIE['cookie'] as $name => $value) {
        $name = htmlspecialchars($name);
        $value = htmlspecialchars($value);
        echo "$name : $value <br />\n";
    }
}
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
three : cookiethree
two : cookietwo
one : cookieone
]]>
   </screen>
  </example>
  <note>
   <simpara>
    <literal>[</literal> や <literal>]</literal> のような区切り文字を
    Cookie の名前の一部として使ってしまうと、RFC 6265 section 4 違反になります。
    しかし、RFC 6265, section 5 によると、
    ユーザーエージェントがこうした区切り文字をサポートしていることが想定されています。
   </simpara>
  </note>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <simpara>
    この関数をコールする前でも出力できるようにするには、
    出力バッファリングを使います。
    すべての出力は、
    フラッシュ(明示的にフラッシュするか、
    スクリプトの実行が終了する際に)されるまでバッファリングされます。
    そのためには、<function>ob_start</function>
    や <function>ob_end_flush</function>
    を使用するか、
    あるいは &php.ini; やサーバー設定ファイルの
    <literal>output_buffering</literal>
    を使用します。
   </simpara>
  </note>
  <para>
   陥りやすい失敗:
   <itemizedlist>
    <listitem>
     <simpara>
      クッキーは、クッキーを有効にするために次にページをロードするまで
      アクセスすることができません。クッキーが正常にセットされたか
      テストするために、クッキーの有効期限が切れる前に次のページを
      ロードしてクッキーをチェックしてください。
      有効期限は <parameter>expires_or_options</parameter> 引数でセットされます。
      クッキーの利用についてデバッグするのに良い方法は
      <literal>print_r($_COOKIE);</literal> をコールすることです。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      クッキーは設定されたものと同じパラメータで削除する必要があります。
      <parameter>value</parameter> が空文字列で、その他の全ての引数が前に <function>setcookie</function>
      をコールした時と同じである場合に、指定された名前のクッキーが
      リモートクライアント上から削除されます。
      内部的な動作として、これは値を 'deleted' に変更した上で有効期限を
      過去に設定しています。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      クッキーの値として &false; を設定すると、クッキーを削除しようとします。
      そのため、boolean 値は使用できません。その代わりとして、
      &false; ではなく <emphasis>0</emphasis>、そして &true;
      ではなく <emphasis>1</emphasis> を使用します。
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      クッキー名で配列を記述することにより、
      クッキーの配列を設定することも可能ですが、複数のクッキー
      がユーザーのシステム上に保存されることになります。
      <function>json_encode</function> を使用して
      ひとつのクッキー上に複数の名前と値をセットすることも
      考慮してください。<function>serialize</function>
      の使用はセキュリティホールになり得るため、
      この目的のために使用することはお勧めしません。
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <simpara>
   <function>setcookie</function> を複数回コールした場合は、コールした順番で実行されます。
  </simpara>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>header</function></member>
   <member><function>setrawcookie</function></member>
   <member><link linkend="features.cookies">クッキー</link></member>
   <member><link xlink:href="&url.rfc;6265">RFC 6265</link></member>
   <member><link xlink:href="&url.rfc;2109">RFC 2109</link></member>
  </simplelist>
 </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
-->