説明

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): bool

session_set_save_handler() は、セッションに関連するデータを保存および取得するために使用されるユーザー定義のセッション保存関数を設定します。この関数は、PHP セッションにより提供されるもの以外の保存方法を使用したい場合に有用です。例えば、セッションデータをローカルデータベースに保存します。

パラメータ

この関数には二種類のプロトタイプがあります。

sessionhandler: SessionHandlerInterface、 SessionIdInterface(オプション) または SessionUpdateTimestampHandlerInterface を実装したクラス、たとえば SessionHandler のインスタンスで、これをセッションハンドラとして登録する。
register_shutdown: session_write_close() を register_shutdown_function() 関数として登録するかどうか。

あるいは

open

以下のシグネチャを持つ callable:

open(string $savePath, string $sessionName): bool

open コールバックはクラスのコンストラクタのようなもので、セッションを開くときに実行されます。セッションが自動で開始したり、あるいは手動で session_start() で開始させたりするときに、最初に実行されるコールバック関数がこれです。成功した場合は true、失敗した場合は false を返します。

close

以下のシグネチャを持つ callable:

close(): bool

close コールバックはクラスのデストラクタのようなもので、write コールバックがコールされた後で実行されます。また、session_write_close() がコールされたときにも実行されます。成功した場合は true、失敗した場合は false を返します。

read

以下のシグネチャを持つ callable:

read(string $sessionId): string

read コールバックは、常にセッションエンコード (シリアライズ) された文字列を返さなければなりません。何もデータを読み込まなかった場合は空文字列を返します。

このコールバックは、セッションが開始したときや session_start() がコールされたときに PHP が内部的に実行します。このコールバックを実行する前に、PHP は open コールバックを実行します。

このコールバックが返す値は、 write コールバックがストレージに渡した形式とまったく同じシリアライズ形式でなければなりません。返された値を PHP が自動的にアンシリアライズして、スーパーグローバル $_SESSION に格納します。データの形式は serialize() したものと似ていますが、実際は違う形式であることに注意しましょう。シリアライズの方法は ini 設定 session.serialize_handler で指定します。

write

以下のシグネチャを持つ callable:

write(string $sessionId, string $data): bool

write コールバックは、セッションの保存や終了が必要となったときにコールされます。このコールバックが受け取るのは、現在のセッション ID とシリアライズ後のスーパーグローバル $_SESSION です。 PHP が内部で利用するシリアライズ方法は、ini 設定 session.serialize_handler で指定します。

このコールバックに渡されたシリアライズ後のセッションデータを、渡されたセッション ID に対応させて格納しなければなりません。このデータを取得した read コールバックは、 write コールバックに最初に渡されたのとまったく同じ値を返さなければなりません。

このコールバックが実行されるのは、PHP のスクリプトが終了するときか、あるいは明示的に session_write_close() がコールされたときです。この関数の実行後には、PHP が内部的に close コールバックを実行することに注意しましょう。

注意:
"write" ハンドラは、出力ストリームが閉じてから実行されます。したがって、"write" ハンドラ内でデバッグ出力を行っても、それはブラウザに表示されません。デバッグ出力が必要なら、それをファイルに書き出すようにしましょう。

destroy

以下のシグネチャを持つ callable:

destroy(string $sessionId): bool

このコールバックが実行されるのは、 session_destroy() あるいは session_regenerate_id() (destroy パラメータを true にした場合) を実行し、セッションを破棄した場合です。成功した場合は true、失敗した場合は false を返します。

gc

以下のシグネチャを持つ callable:

gc(int $lifetime): bool

ガベージコレクタコールバックは PHP が内部で定期的に実行し、古いセッションデータを破棄します。実行頻度は session.gc_probability および session.gc_divisor で設定します。この関数に渡される有効期限の値は session.gc_maxlifetime で設定できます。成功した場合は true、失敗した場合は false を返します。

create_sid

以下のシグネチャを持つ callable:

create_sid(): string

このコールバックは、新しいセッション ID が必要になったときに実行されます。パラメータは不要です。戻り値は、使っているハンドラで有効なセッション ID を表す文字列となります。

validate_sid

以下のシグネチャを持つ callable:

validate_sid(string $key): bool

このコールバックは、セッションが開始された場合に実行されます。但し、セッションID が渡され、 session.use_strict_mode が有効な場合に限ります。 key は検証するセッションID を指定します。渡されたID のセッションが既に存在する場合、セッションID は有効です。成功した場合は true、失敗した場合は false を返します。

update_timestamp

以下のシグネチャを持つ callable:

update_timestamp(string $key, string $val): bool

このコールバックは、セッションが更新された時に実行されます。 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() でセッションを閉じます。

参考

設定ディレクティブ session.save_handler
設定ディレクティブ session.serialize_handler
register_shutdown_function() - シャットダウン時に実行する関数を登録する
session_register_shutdown() - セッションのシャットダウン関数
手続き型の完全なリファレンス実装は » save_handler.inc を参照ください。