setcookie

説明

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

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

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

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

表 1. setcookie() 引数の説明

引数	説明	例
`name`	クッキーの名前	'cookiename' is called as `$_COOKIE['cookiename']`
`value`	クッキーの値。この値はクライアントのコンピュータに保存されますので、重要な情報は格納しないでください。	`name` が 'cookiename' だとすると、その値は`$_COOKIE['cookiename']`で取得することができます。
`expire`	クッキーの有効期限。これはUNIX標準時、つまりepoch（1970年1月1日）からの秒数です。 time() または mktime() 関数により返された現在のUNIX標準時に、期限としたい必要な秒数を加算したものを利用することができるでしょう。	`time()+606024*30`はクッキーの有効期限を30日後にセットします。もしも設定しない場合、クッキーはセッションの最後（つまりブラウザを閉じるとき）が有効期限となります。
`path`	サーバー上での、クッキーを有効としたいパス	`'/'` をセットすると、クッキーは `domain`配下の全てで有効となります。 `'/foo/'`をセットすると、クッキーは `/foo/`ディレクトリとそのサブディレクトリ配下（例えば`/foo/bar/`）で有効となります。デフォルト値はクッキーがセットされたときのカレントディレクトリです。
`domain`	クッキーが有効なドメイン	exapmle.comの全てのサブドメインでクッキーを有効とするには `'.example.com'`をセットします。 `.`は必須ではありませんが多くのブラウザにおいて互換性があります。 `www.example.com`にセットすると、クッキーは`www`サブドメインにおいてのみ有効となります。末尾のマッチングについての詳細はspec をご覧ください。
`secure`	`1`をセットするとセキュアなHTTPS接続の場合にのみクッキーが送信されるようになります。デフォルトは`0`です。	`0` or `1`

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

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

陥りやすい失敗:

クッキーはクッキーを有効にするために次にページをロードするまでアクセスすることができません。クッキーが正常にセットされたかテストするために、クッキーの有効期限が切れる前に次のページをロードしてクッキーをチェックしてください。有効期限はexpire引数でセットされます。クッキーの利用についてデバッグするのに良い方法は print_r($_COOKIE);をコールすることです。
クッキーは設定されたものと同じパラメータで削除する必要があります。値が空文字列("")で、その他の全ての引数が前にsetcookieをコールした時と同じである場合に、指定された名前のクッキーはリモートクライアント上から削除されます。
クッキー名で配列を記述することにより、クッキーの配列を設定することも可能ですが、複数のクッキーがユーザーのシステム上に保存されることになります。 explode() や serialize()を使用することで、ひとつのクッキー上に複数の名前と値をセットすることも考慮してください。

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エンコードされ、またクッキーを受信した際は、自動的にデコードされてクッキー名と同じ名前の変数に格納されることに注意して下さい。すなわち、スクリプト内部でTestCookieの内容を見たい場合は、以下の例のうちの一つを使用して下さい。


<?php
// Print an individual cookie
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 // set the cookies setcookie ("cookie[three]", "cookiethree"); setcookie ("cookie[two]", "cookietwo"); setcookie ("cookie[one]", "cookieone"); // ページをリロードした後にprintする if (isset($_COOKIE['cookie'])) { foreach ($_COOKIE['cookie'] as $name => $value) { echo "$name : $value <br />\n"; } } /* 結果 three : cookiethree two : cookietwo one : cookieone */ ?>

注意: クッキーに関する詳細は、http://www.netscape.com/newsref/std/cookie_spec.html にあるNetscapeのクッキーに関する仕様と RFC 2965 をご覧ください。
expire引数は Wdy, DD-Mon-YYYY HH:MM:SS GMTといった日付フォーマットではなく、UNIXタイムスタンプを与えることに注意してください。なぜなら、PHPはこの変換を内部で行うからです。

注意: サービスパック1を適用したMicrosoftインターネットエクスプローラ4 は、パスに関するパラメータを設定したクッキーを正確に処理することができません。
Netscape Communicator 4.05およびMicrosoft Internet Explorer 3.x は、pathとtime が設定されていない場合、クッキーを正確に処理することができないようです。

header()とクッキーのセクションも参照してください。