(PHP 4, PHP 5)
setcookie — クッキーを送信する
setcookie() は、その他のヘッダ情報と共に 送信するクッキーを定義します。 ほかのヘッダ情報と同様に、 クッキーは、スクリプトによる他のあらゆる出力よりも前に 送信される必要があります（これはHTTPプロトコルの制約です）。 <html> や <head> タグはもちろん 空白も含め、あらゆる出力よりも前にこの関数をコールするようにしなければなりません。
一度クッキーが送信されると、次のページのロードからは $_COOKIE や $HTTP_COOKIE_VARS 配列によってクッキーにアクセスできます。 $_COOKIE のような スーパーグローバル は PHP 4.1.0 以降で有効となることに注意してください。 クッキーの値は $_REQUEST 配列からもアクセスできます。
name 以外の全ての引数はオプションです。 全ての引数に関して引数の指定をスキップするために空文字列 ("") とすることが可能です。 expire および secure は数値なので、空文字列でスキップすることはできません。代わりにゼロ (0) を使用してください。
setcookie() の各パラメータがどのように作用するのかを知るには » RFC 2109 を参照ください。
クッキーの名前。
クッキーの値。この値はクライアントのコンピュータに保存されますので、 重要な情報は格納しないでください。 name が 'cookiename' だとすると、 その値は $_COOKIE['cookiename'] で取得することができます。
クッキーの有効期限。これは Unix タイムスタンプなので Epoch（1970 年 1 月 1 日）からの経過秒数となります。 time() または mktime() 関数により 返された現在のUNIX標準時に、期限としたい必要な秒数を加算したものを 利用することができるでしょう。 time()+60*60*24*30 はクッキーの有効期限を 30 日後にセットします。 0 を設定したり省略したりした場合は、クッキーはセッションの最後 (つまりブラウザを閉じるとき) が有効期限となります。
注意:
expire パラメータには、Wdy, DD-Mon-YYYY HH:MM:SS GMT といった形式ではなく Unix タイムスタンプを渡していることにお気づきでしょうか。 これは、PHP の内部で自動的に変換を行っているからです。
サーバ上での、クッキーを有効としたいパス '/' をセットすると、クッキーは domain 配下の全てで有効となります。 '/foo/' をセットすると、クッキーは /foo/ ディレクトリとそのサブディレクトリ配下 (例えば /foo/bar/) で有効となります。 デフォルト値は、クッキーがセットされたときのカレントディレクトリです。
クッキーが有効なドメイン。 exapmle.com の全てのサブドメイン (example.com 自身も含む) でクッキーを有効とするには '.example.com' をセットします。 最初の . がなくてもクッキーを受け付けるブラウザもありますが、 » RFC 2109 では必ずつけなければならないことになっています。 'www.example.com' あるいは '.www.example.com' クッキーは www サブドメインにおいてのみ有効となります。
クライアントからのセキュアな HTTPS 接続の場合にのみクッキーが送信されるようにします。 TRUE を設定すると、セキュアな接続が存在する場合にのみクッキーを設定します。 サーバ側では、このようにセキュアな接続の場合にのみクッキーを送信するという処理は プログラマの責任で行うことになります (たとえば $_SERVER["HTTPS"] の内容を使用します)。
TRUE を設定すると、HTTP を通してのみクッキーにアクセスできるようになります。 つまり、JavaScript のようなスクリプト言語からはアクセスできなくなるということです。 この設定を使用すると、XSS 攻撃によって ID を盗まれる危険性を減らせます (が、すべてのブラウザがこの設定をサポートしているというわけではありません)。 PHP 5.2.0 で追加されました。 TRUE あるいは FALSE で指定します。
もしもこの関数をコールする前に何らかの出力がある場合には、 setcookie() は失敗し FALSE を返します。 setcookie() が正常に実行されると、TRUE を返します。 この関数では、ユーザがクッキーを受け入れたかどうかを判断することはできません。
以下はクッキーを送信する例です。
例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) {
$name = htmlspecialchars($name);
$value = htmlspecialchars($value);
echo "$name : $value <br />\n";
}
}
?>
上の例の出力は以下となります。
three : cookiethree two : cookietwo one : cookieone
| バージョン | 説明 |
|---|---|
| 5.2.0 | httponly パラメータが追加されました。 |
注意:
この関数をコールする前でも出力できるように、 スクリプトの全ての出力をサーバ内にバッファリングさせることができます。 そのためには、ob_start() や ob_end_flush() を使用するか、あるいは php.ini やサーバ設定ファイルの output_buffering を使用します。
注意:
PHPの register_globals ディレクティブが on になっている場合、 クッキーは変数にも登録されています。 以下の例では、$TestCookie 変数が存在します。 $_COOKIE の使用することを推奨します。
陥りやすい失敗
setcookie() を複数回コールした場合は、コールした順番で実行されます。