session_set_save_handler
ユーザー定義のセッション保存関数を設定する
説明
bool session_set_save_handler(
callable $open,
callable $close,
callable $read,
callable $write,
callable $destroy,
callable $gc,
callable $create_sid = ?,
callable $validate_sid = ?,
callable $update_timestamp = ?
)
bool session_set_save_handler(object $sessionhandler, bool $register_shutdown = true)
パラメータ
この関数には二種類のプロトタイプがあります。
-
sessionhandler
-
SessionHandlerInterface、
SessionIdInterface(オプション)
または
SessionUpdateTimestampHandlerInterface
を実装したクラス、たとえば
SessionHandler のインスタンスで、
これをセッションハンドラとして登録する。
-
register_shutdown
-
session_write_close を
register_shutdown_function 関数として登録するかどうか。
あるいは
-
open
-
以下のシグネチャを持つ callable:
bool open(string $savePath, string $sessionName)
open コールバックはクラスのコンストラクタのようなもので、セッションを開くときに実行されます。
セッションが自動で開始したり、あるいは手動で session_start
で開始させたりするときに、最初に実行されるコールバック関数がこれです。
成功した場合は true、失敗した場合は false を返します。
-
close
-
以下のシグネチャを持つ callable:
bool close()
close コールバックはクラスのデストラクタのようなもので、write コールバックがコールされた後で実行されます。
また、session_write_close がコールされたときにも実行されます。
成功した場合は true、失敗した場合は false を返します。
-
read
-
以下のシグネチャを持つ callable:
string read(string $sessionId)
read コールバックは、常にセッションエンコード (シリアライズ)
された文字列を返さなければなりません。何もデータを読み込まなかった場合は空文字列を返します。
このコールバックは、セッションが開始したときや
session_start がコールされたときに PHP が内部的に実行します。
このコールバックを実行する前に、PHP は
open コールバックを実行します。
このコールバックが返す値は、
write コールバックがストレージに渡した形式とまったく同じシリアライズ形式でなければなりません。
返された値を PHP が自動的にアンシリアライズして、スーパーグローバル $_SESSION
に格納します。データの形式は serialize したものと似ていますが、実際は違う形式であることに注意しましょう。
シリアライズの方法は ini 設定 session.serialize_handler で指定します。
-
write
-
以下のシグネチャを持つ callable:
bool write(string $sessionId, string $data)
write コールバックは、セッションの保存や終了が必要となったときにコールされます。
このコールバックが受け取るのは、現在のセッション ID とシリアライズ後のスーパーグローバル $_SESSION です。
PHP が内部で利用するシリアライズ方法は、ini 設定
session.serialize_handler で指定します。
このコールバックに渡されたシリアライズ後のセッションデータを、
渡されたセッション ID に対応させて格納しなければなりません。
このデータを取得した read コールバックは、
write コールバックに最初に渡されたのとまったく同じ値を返さなければなりません。
このコールバックが実行されるのは、PHP のスクリプトが終了するときか、あるいは明示的に session_write_close
がコールされたときです。この関数の実行後には、PHP が内部的に close
コールバックを実行することに注意しましょう。
注意:
"write" ハンドラは、出力ストリームが閉じてから実行されます。
したがって、"write" ハンドラ内でデバッグ出力を行っても、
それはブラウザに表示されません。
デバッグ出力が必要なら、それをファイルに書き出すようにしましょう。
-
destroy
-
以下のシグネチャを持つ callable:
bool destroy(string $sessionId)
このコールバックが実行されるのは、
session_destroy あるいは
session_regenerate_id (destroy パラメータを true にした場合)
を実行し、セッションを破棄した場合です。
成功した場合は true、失敗した場合は false を返します。
-
gc
-
以下のシグネチャを持つ callable:
bool gc(int $lifetime)
ガベージコレクタコールバックは PHP が内部で定期的に実行し、古いセッションデータを破棄します。
実行頻度は session.gc_probability
および session.gc_divisor で設定します。
この関数に渡される有効期限の値は session.gc_maxlifetime
で設定できます。
成功した場合は true、失敗した場合は false を返します。
-
create_sid
-
以下のシグネチャを持つ callable:
string create_sid()
このコールバックは、新しいセッション ID が必要になったときに実行されます。
パラメータは不要です。戻り値は、使っているハンドラで有効なセッション ID を表す文字列となります。
-
validate_sid
-
以下のシグネチャを持つ callable:
bool validate_sid(string $key)
このコールバックは、セッションが開始された場合に実行されます。
但し、セッションID が渡され、
session.use_strict_mode
が有効な場合に限ります。
key は検証する セッションID を指定します。
渡されたID のセッションが既に存在する場合、セッションID は有効です。
成功した場合は true、失敗した場合は false を返します。
-
update_timestamp
-
以下のシグネチャを持つ callable:
bool update_timestamp(string $key, string $val)
このコールバックは、セッションが更新された時に実行されます。
key はセッションID、
val はセッションデータを指定します。
成功した場合は true、失敗した場合は false を返します。
戻り値
成功した場合に true を、失敗した場合に false を返します。
例
例1
自作のセッションハンドラ: 完全なコードは SessionHandlerInterface を参照
ここでは実行するところだけを示します。完全な例は、上でリンクしている
SessionHandlerInterface のページを参照ください。
session_set_save_handler でオブジェクト指向型のプロトタイプを使っていることと、
シャットダウン関数をその parameter フラグで登録していることに注目しましょう。
オブジェクトをセッション保存ハンドラとして使うときには、この方法をおすすめします。
<?php
class MySessionHandler implements SessionHandlerInterface
{
// ここでインターフェイスを実装します
}
$handler = new MySessionHandler();
session_set_save_handler($handler, true);
session_start();
// $_SESSION への値の設定や格納されている値の取得を進めます
注意
警告
write ハンドラおよび
close ハンドラはオブジェクトが破棄されたあとにコールされます。
そのため、これらのハンドラでオブジェクトを使ったり例外をスローしたりすることはできません。
例外をキャッチできないのでその情報をトレースすることもできず、
例外は単純に無視されてしまいます。
しかし、オブジェクトのデストラクタではセッションを使えます。
この「ニワトリが先かタマゴが先か」の問題を解決するために、
デストラクタから session_write_close
をコールできますが、より確実なのは先述のとおりシャットダウン関数を登録することです。
警告
SAPI の種類によっては、スクリプトの終了時にセッションを閉じると
現在の作業ディレクトリが変わってしまうことがあります。これを防ぐには、
事前に session_write_close でセッションを閉じます。