setcookie

(PHP 3, PHP 4, PHP 5)

setcookie -- クッキーを送信する

説明

bool setcookie ( string name [, string value [, int expire [, string path [, string domain [, bool secure [, bool httponly]]]]]] )

setcookie() は、その他のヘッダ情報と共に 送信するクッキーを定義します。 ほかのヘッダ情報と同様に、 クッキーは、スクリプトによる他のあらゆる出力よりも前に 送信される必要があります(これはHTTPプロトコルの制約です)。 <html><head> タグはもちろん 空白も含め、あらゆる出力よりも前にこの関数をコールするようにしなければなりません。 もしもこの関数をコールする前に何らかの出力がある場合には、 setcookie() は失敗し FALSE を返します。 setcookie() が正常に実行されると、TRUE を返します。 この関数はユーザーがクッキーを受け入れたかどうかを示すことはしません。

注意: PHP 4 では、この関数をコールする前でも出力できるように、 スクリプトの全ての出力をサーバ内にバッファリングさせることができます。 そのためには、ob_start()ob_end_flush() を使用するか、あるいは php.inioutput_buffering 設定を使用します。

name 以外の全ての引数はオプションです。 全ての引数に関して引数の指定をスキップするために空文字列 ("") とすることが可能です。 expire および secure は数値なので、空文字列でスキップすることはできません。代わりにゼロ (0) を使用してください。 以下の表は setcookie() の引数の説明です。 setcookie() 関数の各引数が どのように作用するかを知るには Netscape cookie specification を、そして HTTP クッキーの動作についての詳細な情報は とRFC 2965 を参照ください。

表 1. setcookie() 引数の説明

引数説明
name クッキーの名前 'cookiename' が $_COOKIE['cookiename'] としてコールされます。
value クッキーの値。この値はクライアントのコンピュータに保存されますので、 重要な情報は格納しないでください。 name が 'cookiename' だとすると、 その値は $_COOKIE['cookiename'] で取得することができます。
expire クッキーの有効期限。これは Unix タイムスタンプなので Epoch(1970 年 1 月 1 日)からの経過秒数となります。 time() または mktime() 関数により 返された現在のUNIX標準時に、期限としたい必要な秒数を加算したものを 利用することができるでしょう。 time()+60*60*24*30 はクッキーの有効期限を 30 日後にセットします。 もしも設定しない場合、クッキーはセッションの最後 (つまりブラウザを閉じるとき) が有効期限となります。
path サーバー上での、クッキーを有効としたいパス '/' をセットすると、クッキーは domain 配下の全てで有効となります。 '/foo/' をセットすると、クッキーは /foo/ ディレクトリとそのサブディレクトリ配下 (例えば /foo/bar/) で有効となります。 デフォルト値は、クッキーがセットされたときのカレントディレクトリです。
domain クッキーが有効なドメイン exapmle.com の全てのサブドメインでクッキーを有効とするには '.example.com' をセットします。 . は必須ではありませんが、 多くのブラウザにおいて互換性があります。 www.example.com にセットすると、 クッキーはwww サブドメインにおいてのみ有効となります。 末尾のマッチングについての詳細は 仕様 をご覧ください。
secure セキュアな HTTPS 接続の場合にのみクッキーが送信されるようにします。 TRUE を設定すると、セキュアな接続が存在する場合にのみクッキーを 設定します。デフォルトは FALSE です。 TRUE または FALSE
httponly TRUE を設定すると、HTTP を通してのみクッキーにアクセスできるようになります。 つまり、JavaScript のようなスクリプト言語からはアクセスできなくなるということです。 この設定を使用すると、XSS 攻撃によって ID を盗まれる危険性を減らせます (が、すべてのブラウザがこの設定をサポートしているというわけではありません)。 PHP 5.2.0 で追加されました。 TRUE または FALSE

一度クッキーが送信されると、次のページのロードからは $_COOKIE$HTTP_COOKIE_VARS 配列によってクッキーにアクセスできます。 $_COOKIE のような autoglobals4.1.0 以降で有効となることに注意してください。 $HTTP_COOKIE_VARS は PHP 3 以降で使用できます。 クッキーの値は $_REQUEST 配列からもアクセスできます。

注意: PHPの register_globals ディレクティブが on になっている場合、 クッキーは変数にも登録されています。 以下の例では、$TestCookie 変数が存在します。 $_COOKIE の使用が推奨されます。

陥りやすい失敗

PHP 3 において同じスクリプトで setcookie() を複数回コールした場合、逆の順番で実行されます。 他のクッキーを挿入する前にあるクッキーを削除しようとする場合、 削除する前に挿入を行う必要があります。PHP 4 では、 setcookie() を複数回コールした場合でもコールした順番で実行されます。

以下はクッキーを送信する例です。

例 1. setcookie() による送信のサンプル

<?php
$value
= 'something from somewhere';

setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600);  /* 有効期限は一時間です */
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", ".example.com", 1);
?>

クッキーの value の部分は、クッキーの送信を行う際に自動的に URL エンコードされ、またクッキーを受信した際は、自動的にデコード されてクッキー名と同じ名前の変数に格納されることに注意してください。 この挙動が気に入らない場合、もし PHP 5 を使用しているなら 代わりに setrawcookie() を使ってください。 スクリプト内部で TestCookie の内容を見たい場合は、 以下のいずれかの例を使用します。

<?php
// 個々のクッキーを表示します
echo $_COOKIE["TestCookie"];
echo
$HTTP_COOKIE_VARS["TestCookie"];

// デバッグ/テスト用には、全てのクッキーを見る方法があります。
print_r($_COOKIE);
?>

クッキーを削除する場合には、ブラウザの削除機構を起動するために 必ず有効期限を過去に設定する必要があります。 次に、先ほど例で送信したクッキーを削除する例を示します。

例 2. setcookie() による削除の例

<?php
// 有効期限を一時間前に設定します
setcookie ("TestCookie", "", time() - 3600);
setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", ".example.com", 1);
?>

クッキー名で配列を記述することにより、クッキーの配列を設定することも可能です。 これにより配列要素と同数のクッキーを設定されますが、 クッキーがスクリプトに受信された際に、 値はクッキー名を有する配列に置きかえられます。

例 3. setcookie() と配列

<?php
// クッキーを設定します
setcookie("cookie[three]", "cookiethree");
setcookie("cookie[two]", "cookietwo");
setcookie("cookie[one]", "cookieone");

// ページを再読み込みした後に、表示します
if (isset($_COOKIE['cookie'])) {
    foreach (
$_COOKIE['cookie'] as $name => $value) {
        echo
"$name : $value <br />\n";
    }
}
?>

この結果は、次のようになります。

three : cookiethree
two : cookietwo
one : cookieone

注意: RFC 2109 および RFC 2695 も参考になるでしょう。

expire パラメータには、Wdy, DD-Mon-YYYY HH:MM:SS GMT といった形式ではなく Unix タイムスタンプを渡していることにお気づきでしょうか。 これは、PHP の内部で自動的に変換を行っているからです。

expire は、クライアントの時刻と比較されます。 サーバの時刻との比較ではありません。

注意: サービスパック 1 を適用した Microsoft Internet Explorer 4 は、 パスに関するパラメータを設定したクッキーを正確に処理することができません。

Netscape Communicator 4.05 および Microsoft Internet Explorer 3.x は、path と time が設定されていない場合、 クッキーを正確に処理することができないようです。

header()setrawcookie() およびクッキーのセクション も参照ください。