Edit Report a Bug

    A classe SessionHandler

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

    Introdução

    SessionHandler é uma classe especial que pode ser usada para expor o manipulador interno atual do PHP de gravação de sessão por herança. Existem sete métodos que envolvem (wrap) as sete funções internas de callbacks do manipulador de gravação de sessão (open, close, read, write, destroy, gc e create_sid). Por padrão, esta classe vai envolver qualquer manipulador de gravação interno definido pela diretiva de configuração session.save_handler, que normalmente é files por padrão. Outros manipuladores internos de gravação de sessão podem ser fornecidos por extensões do PHP, como por exemplo SQLite (como sqlite), Memcache (como memcache), e Memcached (como memcached).

    Quando uma instância de SessionHandler é definida como manipulador de gravação usando session_set_save_handler(), ela envolverá o manipulador de gravação atual. Uma classe que estende SessionHandler permite sobrescrever os métodos, interceptá-los ou filtrá-los chamando os métodos da classe pai que envolvem os manipuladores de sessão internos do PHP.

    Isto permite, por exemplo, interceptar os métodos read e write para criptografar/descriptografar os dados de sessão e então passar o resultado de e para a classe pai. Alternativamente, pode-se sobrescrever completamente um método como o callback de limpeza gc.

    Como o SessionHandler envolve os manipuladores de gravação atuais, o exemplo acima de criptografia pode ser aplicado em qualquer manipulador de gravação interno sem precisar saber o funcionamento interno dos manipuladores.

    Para usar esta classe, primeiro configure o manipulador de gravação que você quer expor usando session.save_handler e então passe uma instância de SessionHandler ou uma classe que a estenda para session_set_save_handler().

    Note que os métodos de callbacks desta classe são projetados para serem chamados internamente pelo PHP e não para serem chamados pelo código do usuário. Os valores de retorno são igualmente processados internamente pelo PHP. Para mais informações do fluxo de trabalho da sessão, consulte session_set_save_handler().

    Resumo da classe

    class SessionHandler implements SessionHandlerInterface, SessionIdInterface {
    /* Métodos */
    public close(): bool
    public create_sid(): string
    public destroy(string $id): bool
    public gc(int $max_lifetime): int|false
    public open(string $path, string $name): bool
    public read(string $id): string|false
    public write(string $id, string $data): bool
    }
    Aviso

    Esta classe é projetada para expor o manipulador interno do PHP de gravação de sessão; se você quiser escrever manipuladores de gravação personalizados, implemente a interface SessionHandlerInterface ao invés de estender a classe SessionHandler.

    Exemplo #1 Usando SessionHandler para adicionar criptografia aos manipuladores internos do PHP de gravação.

    <?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; // depende do comprimento da chave
    $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) {
    // Gera um salt aleatório criptograficamente seguro usando random_bytes()
    $salt = random_bytes(16);

    $salted = '';
    $dx = '';
    // Salt em key(32) e 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);
    }
    }

    // iremos interceptar o manipulador nativo de arquivos, mas trabalharemos igualmente
    // com outros manipuladores internos como 'sqlite', 'memcache' ou 'memcached'
    // que são disponibilizados por extensões do PHP
    ini_set('session.save_handler', 'files');

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

    // proceder para definir e recuperar os valores pela chave de $_SESSION

    Nota:

    Como os métodos dessa classe são projetados para serem chamados internamente pelo PHP como parte do fluxo normal da sessão, chamadas à esses métodos (ou seja, os manipuladores internos nativos reais) por classes filhas irão retornar false, a não ser que a sessão tenha sido iniciada (independente se foi de forma automática ou pela chamada de session_start()). É importante levar isto em consideração quando escrever testes unitários onde os métodos da classe podem ser invocados manualmente.

    Índice

    add a note add a note

    User Contributed Notes 7 notes

    up
    42
    rasmus at mindplay dot dk
    9 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 :-)
    up
    5
    tuncdan dot ozdemir dot peng at gmail dot com
    1 year ago
    Those who are planning to implement your own SessionHandler, let's say using a Database system, please make sure your 'create_sid' method creates a new record in your database with empty string '' as your 'data' using the new session ID created, otherwise when 'read' method is called (which is always called no matter if it is a brand new session or not), you will get an error because there is no record with that session ID yet.  The funny part is that the error you get will sound like PHP is trying open the session on your local drive (coming from your .ini file).
    up
    3
    tuncdan dot ozdemir dot peng at gmail dot com
    1 year ago
    The best way to set up your own session handler is to extend the native SessionHandler (override the 7 methods + constructor as per your need, keeping the same signatures).  Optionally, you can also implement SessionUpdateTimestampHandlerInterface if you plan to use 'lazy_write':

    Option 1:

    class MyOwnSessionHandler extends \SessionHandler { ..... }

    Option 2:

    class MyOwnSessionHandler extends \SessionHandler implements \SessionUpdateTimestampHandlerInterface { ..... }

    I would NOT recommend to do this:

    class MyOwnSessionHandler implements \SessionHandlerInterface, \SessionIdInterface, \SessionUpdateTimestampHandlerInterface { ... }

    If you are curious, here are the methods called in the order (using PHP 8.2 with XAMPP v3.3.0 on Windows 11 64-bit):

    - open (always called)

    - validateId and/or create_sid:

        validateId is called if you implement SessionUpdateTimestampHandlerInterface.  If validation fails, create_sid is called.    

        create_sid is called if a new session ID is needed: new session, etc.

    - read (always called)

    - write OR updateTimestamp OR destroy:

        if you call 'destroy', neither 'write' or 'updateTimestamp' is called,

        if you have the 'lazy_write' on AND implemented SessionUpdateTimestampHandlerInterface,
        then 'updateTimestamp' is called instead of 'write' if nothing changes.

    - close (always called)
    up
    5
    tony at marston-home dot demon dot co dot uk
    6 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.
    up
    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.
    up
    -4
    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);
    up
    -3
    wei dot kavin at gmail dot com
    5 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)
    add a note add a note
    To Top