PHP マニュアル
前のページ |  | 次のページ

# setcookie

(PHP 3, PHP 4 , PHP 5)

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()+60*60*24*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()と クッキーのセクション も参照してください。

前のページ | ホーム | 次のページ
headers_sent | 上に戻る | setrawcookie