Класс 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 для шифровки/дешифровки данных сессии и передачи результата родительскому классу и от него. Или, к примеру, вы можете полностью переопределить такой метод как callback-функция сборщика мусора (gc).

Так как SessionHandler является обёрткой над стандартным внутренним обработчиком сессии, то пример, приведённый выше про шифровку данных может быть применён к любому внутреннему обработчику сессии даже без понимания внутреннего устройства процесса работы сессии.

Для использования этого класса, во-первых, установите обработчик, который вы хотите дополнить используя session.save_handler. Далее передайте экземпляр класса SessionHandler или одного из классов, расширяющих его функции session_set_save_handler().

Обратите внимание, что методы этого класса предназначены для внутреннего вызова из 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|false

public write(string $id, string $data): bool

}

Внимание

Этот класс предназначен для расширения текущего внутреннего обработчика сессии PHP. При этом, если вам нужно написать собственный обработчик, то необходимо написать собственную реализацию интерфейса SessionHandlerInterface вместо расширения класса SessionHandler.

Пример #1 Использование SessionHandler для того, чтобы добавить шифровку данных ко внутреннему обработчику сессий PHP.


<?php

 /**
  * расшифровать данные, используя алгоритм AES 256
  *
  * @param data $edata
  * @param string $password
  * @return расшифрованные данные
  */
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);
  }

/**
 * зашифровать данные алгоритмом AES 256
 *
 * @param data $data
 * @param string $password
 * @return base64 зашифрованные данные
 */
function encrypt($data, $password) {
    // Установить случайную соль
    $salt = openssl_random_pseudo_bytes(16);

    $salted = '';
    $dx = '';
    // Ключ соли (32) и вектор инициализации (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', но можно использовать любой другой
// обработчик, например 'sqlite', 'memcache' или 'memcached',
// которые предоставлены расширениями PHP.
ini_set('session.save_handler', 'files');

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

// устанавливаем и получаем значения из $_SESSION

Замечание:
Так как методы этого класса предназначены для внутренних вызовов из PHP, как часть нормального процесса работы сессий, вызовы родительских методов из дочернего класса (иными словами "родных" обработчиков) будет возвращать false до тех пор, пока сессия не будет запущена (автоматически или прямым вызовом session_start()). Это важный момент для понимания, особенно при тестировании, где методы класса могут быть вызваны вручную.

Содержание

SessionHandler::close — Закрывает сессию
SessionHandler::create_sid — Возвращает новый идентификатор сессии
SessionHandler::destroy — Уничтожает сессию
SessionHandler::gc — Очищает старые сессии
SessionHandler::open — Инициализирует сессию
SessionHandler::read — Считывает данные сессии
SessionHandler::write — Записывает данные сессии

add a note

User Contributed Notes 5 notes

down

rasmus at mindplay dot dk ¶

8 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:

https://gist.github.com/mindplay-dk/623bdd50c1b4c0553cd3

I hope this makes it considerably easier to implement a custom SessionHandler and get it right the first time :-)

down

-1

saccani dot francesco dot NOSPAM at gmail dot com ¶

4 years 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.

https://gist.github.com/franksacco/d6e943c41189f8ee306c182bf8f07654

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.

down

tony at marston-home dot demon dot co dot uk ¶

5 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.

down

-1

wei dot kavin at gmail dot com ¶

4 years 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);
session_start();
$a = $handler->write("aaa","bbbb");var_dump($a);exit;

============================================================

output：bool(false)

down

-3

jeremie dot legrand at komori-chambon dot fr ¶

8 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() {
        $this->log('close');
        return parent::close();
    }

    public function create_sid() {
        $this->log('create_sid');
        return parent::create_sid();
    }

    public function destroy($session_id) {
        $this->log('destroy('.$session_id.')');
        return parent::destroy($session_id);
    }

    public function gc($maxlifetime) {
        $this->log('close('.$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) {
        $this->log('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");
        fclose($hdl);
    }
}
ini_set('session.save_handler', 'files');
$handler = new DumpSessionHandler('/path/to/dump_sessions.log');
session_set_save_handler($handler, true);

add a note