# 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 の内部セッションハンドラのメソッドをラップして オーバーライドしたり処理を割り込ませたりフィルタをかけたりできるようになります。

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

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

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

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

## クラス概要

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

## 注意

警告

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

## 例

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

    <?php

     /**
      * decrypt AES 256
      *
      * @param data $edata
      * @param string $password
      * @return decrypted data
      */
    function decrypt($edata, $password) {
        $data = base64_decode($edata);
        $salt = substr($data, 0, 16);
        $ct = substr($data, 16);

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

        return openssl_decrypt($ct, 'AES-256-CBC', $key, true, $iv);
      }

    /**
     * crypt AES 256
     *
     * @param data $data
     * @param string $password
     * @return base64 encrypted data
     */
    function encrypt($data, $password) {
        // 暗号学的にセキュアな、ランダムなソルト値を、random_bytes() を使って生成します。
        $salt = random_bytes(16);

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

        $key = substr($salted, 0, 32);
        $iv  = substr($salted, 32,16);

        $encrypted_data = openssl_encrypt($data, 'AES-256-CBC', $key, true, $iv);
        return base64_encode($salt . $encrypted_data);
    }

    class EncryptedSessionHandler extends SessionHandler
    {
        private $key;

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

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

            if (!$data) {
                return "";
            } else {
                return decrypt($data, $this->key);
            }
        }

        public function write($id, $data)
        {
            $data = encrypt($data, $this->key);

            return parent::write($id, $data);
        }
    }

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

    $key = 'secret_string';
    $handler = new EncryptedSessionHandler($key);
    session_set_save_handler($handler, true);
    session_start();

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

> 注意:

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

## 目次

- SessionHandler::close — セッションを閉じる
- SessionHandler::create_sid — 新規セッション ID を返す
- SessionHandler::destroy — セッションを破棄する
- SessionHandler::gc — 古いセッションを削除する
- SessionHandler::open — セッションを開始する
- SessionHandler::read — セッションのデータを読み込む
- SessionHandler::write — セッションのデータを書き込む

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open