Dutch PHP Conference 2021 - Call for Papers

SessionHandler クラス

(PHP 5 >= 5.4.0, PHP 7, PHP 8)


SessionHandler は特殊なクラスで、 これを継承したクラスを作れば PHP が内部的に使っているセッション保存ハンドラを拡張できます。 このクラスには七つのメソッドがあり、それぞれが七つのセッション保存ハンドラコールバック (open, close, read, write, destroy, gc および create_sid) に対応しています。デフォルトでは、このクラスは session.save_handler で定義された内部セッションハンドラをラップします。 通常は files がデフォルトになっています。 それ以外には、PHP の拡張モジュールとして提供されている SQLite (sqlite) や Memcache (memcache) そして Memcached (memcached) が使えます。

SessionHandler のインスタンスを session_set_save_handler() でハンドラとして指定すると、 そのインスタンスが現在の保存ハンドラをラップします。 SessionHandler を継承したクラスを作ると、 親クラスのメソッド、つまり PHP の内部セッションハンドラのメソッドをラップして オーバーライドしたり処理を割り込ませたりフィルタをかけたりできるようになります。

これを利用すると、たとえば readwrite メソッドに処理を割り込ませ、セッションデータの暗号化/復号の処理を追加することができます。 あるいは、ガベージコレクションコールバック gc を完全に自前の処理で置き換えてしまうこともできます。

SessionHandler は現在の内部保存ハンドラのメソッドをラップしているので、 先述の暗号化の例は任意の保存ハンドラに適用することができます。その際に、ハンドラの内部的な動きを知っておく必要はありません。

このクラスを使うには、まず最初に公開したいハンドラを session.save_handler で設定してから、 SessionHandler あるいはそれを継承したクラスのインスタンスを session_set_save_handler() に渡します。

このクラスのコールバックメソッドは PHP が内部的にコールするものであり、 ユーザーのコードから呼ばれることは想定していないことに注意しましょう。 コールバックの返り値も、PHP が内部的に利用するだけです。 セッションの処理の流れについての詳しい情報は session_set_save_handler() を参照ください。


SessionHandler implements SessionHandlerInterface , SessionIdInterface {
/* メソッド */
public close ( ) : bool
public create_sid ( ) : string
public destroy ( string $id ) : bool
public gc ( int $max_lifetime ) : int|bool
public open ( string $path , string $name ) : bool
public read ( string $id ) : string
public write ( string $id , string $data ) : bool

このクラスは現在の PHP 内部セッション保存ハンドラを公開するように作られています。 自作の保存ハンドラを用意したい場合は、SessionHandler を継承するのではなく SessionHandlerInterface を実装したクラスを作るようにしましょう。


バージョン 説明
5.5.1 SessionHandler::create_sid() が追加されました。

例1 SessionHandler を使って PHP の保存ハンドラに暗号化機能を追加する例


  * decrypt AES 256
  * @param data $edata
  * @param string $password
  * @return decrypted data
function decrypt($edata$password) {
$data base64_decode($edata);
$salt substr($data016);
$ct substr($data16);

$rounds 3// キーの長さに依存します
$data00 $password.$salt;
$hash = array();
$hash[0] = hash('sha256'$data00true);
$result $hash[0];
    for (
$i 1$i $rounds$i++) {
$hash[$i] = hash('sha256'$hash[$i 1].$data00true);
$result .= $hash[$i];
$key substr($result032);
$iv  substr($result32,16);


 * crypt AES 256
 * @param data $data
 * @param string $password
 * @return base64 encrypted data
function encrypt($data$password) {
// ランダムな salt を設定します
$salt openssl_random_pseudo_bytes(16);

$salted '';
$dx '';
// Salt the key(32) and iv(16) = 48
while (strlen($salted) < 48) {
$dx hash('sha256'$dx.$password.$salttrue);
$salted .= $dx;

$key substr($salted032);
$iv  substr($salted32,16);

$encrypted_data openssl_encrypt($data'AES-256-CBC'$keytrue$iv);
base64_encode($salt $encrypted_data);

EncryptedSessionHandler extends SessionHandler

    public function 
$this->key $key;

    public function 
$data parent::read($id);

        if (!
$data) {
        } else {

    public function 
$data encrypt($data$this->key);


// この例では標準の 'files' ハンドラを横取りしていますが、他のネイティブハンドラである
// PHP 拡張モジュール 'sqlite'、'memcache'、'memcached'
// の場合でもまったく同じように使えます。

$key 'secret_string';
$handler = new EncryptedSessionHandler($key);

// $_SESSION への値の設定や格納されている値の取得を進めます


このクラスのメソッドは、セッション処理の一環として PHP が内部的にコールするためのものとして作られています。 そのため、子クラスから親のメソッド (実際のネイティブハンドラ) をコールすると、 (自動で開始するか、あるいは session_start() を実行するなどして) セッションを実際に開始していない限りはその返り値が false となります。 この点は、ユニットテストを書く際に注意が必要です。というのも、 ユニットテストではクラスのメソッドを手動でコールする可能性があるからです。


add a note add a note

User Contributed Notes 5 notes

rasmus at mindplay dot dk
5 years ago
As the life-cycle of a session handler is fairly complex, I found it difficult to understand when explained using just words - so I traced the function calls made to a custom SessionHandler, and created this overview of precisely what happens when you call various session methods:


I hope this makes it considerably easier to implement a custom SessionHandler and get it right the first time :-)
wei dot kavin at gmail dot com
1 year ago
php -S localhost:8000 -t foo/

touch index.php

vi index.php
class NativeSessionHandler extends \SessionHandler
    public function __construct($savePath = null)
        if (null === $savePath) {
            $savePath = ini_get('session.save_path');

        $baseDir = $savePath;

        if ($count = substr_count($savePath, ';')) {
            if ($count > 2) {
                throw new \InvalidArgumentException(sprintf('Invalid argument $savePath \'%s\'', $savePath));

            // characters after last ';' are the path
            $baseDir = ltrim(strrchr($savePath, ';'), ';');

        if ($baseDir && !is_dir($baseDir) && !@mkdir($baseDir, 0777, true) && !is_dir($baseDir)) {
            throw new \RuntimeException(sprintf('Session Storage was not able to create directory "%s"', $baseDir));

        ini_set('session.save_path', $savePath);
        ini_set('session.save_handler', 'files');

$handler = new NativeSessionHandler("/var/www/foo");
session_set_save_handler($handler, true);
$a = $handler->write("aaa","bbbb");var_dump($a);exit;


saccani dot francesco dot NOSPAM at gmail dot com
10 months ago
I made this gist to provide a complete overview of the PHP session handler life cycle updated to version 7.0 or above. In particular, I wanted to emphasize what methods and in what order are called when the native PHP functions are used for session management.


I hope this analysis will help all the developers interested in understanding in detail the native session management performed by PHP and what a custom session handler should do.
Any comment or suggestion is appreciated.
tony at marston-home dot demon dot co dot uk
2 years ago
Your custom session handler should not contain calls to any of the session functions, such as session_name() or session_id(), as the relevant values are passed as arguments on various handler methods. Attempting to obtain values from alternative sources may not work as expected.
jeremie dot legrand at komori-chambon dot fr
4 years ago
Here is a wrapper to log in a file each session's operations. Useful to investigate sessions locks (which prevent PHP to serve simultaneous requests for a same client).
Just change the file name at the end to dump logs where you want.

class DumpSessionHandler extends SessionHandler {
    private $fich;

    public function __construct($fich) {
        $this->fich = $fich;

    public function close() {
        return parent::close();

    public function create_sid() {
        return parent::create_sid();

    public function destroy($session_id) {
        return parent::destroy($session_id);

    public function gc($maxlifetime) {
        return parent::gc($maxlifetime);

    public function open($save_path, $session_name) {
        $this->log('open('.$save_path.', '.$session_name.')');
        return parent::open($save_path, $session_name);

    public function read($session_id) {
        return parent::read($session_id);

    public function write($session_id, $session_data) {
        $this->log('write('.$session_id.', '.$session_data.')');
        return parent::write($session_id, $session_data);

    private function log($action) {
        $base_uri = explode('?', $_SERVER['REQUEST_URI'], 2)[0];
        $hdl = fopen($this->fich, 'a');
        fwrite($hdl, date('Y-m-d h:i:s').' '.$base_uri.' : '.$action."\n");
ini_set('session.save_handler', 'files');
$handler = new DumpSessionHandler('/path/to/dump_sessions.log');
session_set_save_handler($handler, true);
To Top