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

# 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.ini` の `output_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 日後にセットします。 0 を設定したり省略したりした場合は、クッキーはセッションの最後 (つまりブラウザを閉じるとき) が有効期限となります。
`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` のような autoglobals は 4.1.0 以降で有効となることに注意してください。 `$HTTP_COOKIE_VARS` は PHP 3 以降で使用できます。 クッキーの値は $_REQUEST 配列からもアクセスできます。

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

陥りやすい失敗

- クッキーは、クッキーを有効にするために次にページをロードするまで アクセスすることができません。クッキーが正常にセットされたか テストするために、クッキーの有効期限が切れる前に次のページを ロードしてクッキーをチェックしてください。 有効期限は `expire` 引数でセットされます。 クッキーの利用についてデバッグするのに良い方法は `print_r($_COOKIE);` をコールすることです。

- クッキーは設定されたものと同じパラメータで削除する必要があります。 値が空文字列 ("") で、その他の全ての引数が前に setcookie をコールした時と同じである場合に、指定された名前のクッキーが リモートクライアント上から削除されます。

- クッキーの値として `FALSE` を設定すると、クッキーを削除しようとします。 そのため、boolean 値は使用できません。その代わりとして、 `FALSE` ではなく 0、そして `TRUE` ではなく 1 を使用します。

- クッキー名で配列を記述することにより、 クッキーの配列を設定することも可能ですが、複数のクッキー がユーザーのシステム上に保存されることになります。 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 エンコードされ、またクッキーを受信した際は、自動的にデコード されてクッキー名と同じ名前の変数に格納されることに注意してください。 この挙動が気に入らない場合、もし 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() およびクッキーのセクション も参照ください。

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