Define funções de armazenamento de sessão à nível de usuário

Descrição

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

A partir do PHP 5.4 é possível registrar o seguinte protótipo:

bool session_set_save_handler ( SessionHandlerInterface $sessionhandler [, bool $register_shutdown = true ] )

session_set_save_handler() define, a nível de usuário, as funções de armazenamento de sessão que serão usadas para guardar e buscar dados associados à uma sessão. Ela é mais útil quando um método de armazenamento diferente do método disponibilizado pelas sessões do PHP é preferido. i.e. Armazenar os dados de sessão em um banco de dados.

Parâmetros

Essa função tem dois protótipos.

sessionhandler: Uma instância de uma classe implementando SessionHandlerInterface, como SessionHandler, para registrá-la como manipulador de sessão. Apenas a partir do PHP 5.4.
register_shutdown: Registra session_write_close() como uma função register_shutdown_function().

or

open(string $savePath, string $sessionName)

O callback open funciona igual um construtor em classes e é executado quando a sessão está sendo aberta. É a primeira função de callback executada quando a sessão é iniciada automaticamente ou manualmente com session_start(). O valor de retorno é TRUE para sucesso, FALSE para falha.

close()

O callback close funciona igual um destrutor em classes e é executado depois que o callback write da sessão for chamado. Ele também é invocado quando a função session_write_close() é chamada. O valor de retorno é TRUE para sucesso, FALSE para falha.

read(string $sessionId)

O callback read sempre deve retornar uma sessão codificada (serializada) no formato string ou uma string vazia se não há dados para leitura.

Esse callback é chamado internamente pelo PHP quando a sessão inicia ou quando a função session_start() é chamada. Antes que esse callback seja invocado, o PHP invocará o callback open.

O valor que esse callback retorna deve estar exatamente no mesmo formato de serialização que originalmente foi passado para armazenamento ao callback write. O valor retornado será desserializado automaticamente pelo PHP e usado para preencher a super global $_SESSION. Mesmo que os dados pareçam similares ao de serialize(), note que é um formato diferente, especificado na configuração INI session.serialize_handler.

write(string $sessionId, string $data)

O callback write é chamado quando a sessão precisa ser salva e fechada. Esse callback recebe o ID da sessão atual e uma versão serializada da super global $_SESSION. O método de serialização usado internamente pelo PHP é definido pela configuração INI session.serialize_handler.

Os dados de sessão serializados passado para esse callback devem ser armazenados junto com o ID de sessão passado. Ao buscar esses dados, o callback read deve retornar exatamente o mesmo valor que foi passado originalmente para o callback write.

Esse callback é invocado quando o PHP é encerrado ou explicitamente quando a função session_write_close() é chamada. Note que depois de executar esta função, o PHP executará internamente o callback close.

Nota:
O manipulador "write" não é executado enquanto o fluxo de saída não for encerrado. Portanto, saídas de comandos de debug no manipulador "write" nunca serão vistas pelo browser. Se a saída de debug é necessária, é recomendado que ela seja escrita em arquivo.

destroy($sessionId)

Esse callback é executado quando uma sessão é destruída com session_destroy() ou com session_regenerate_id() com o parâmetro de destruição definido como TRUE. O valor de retorno deve ser TRUE para sucesso, FALSE para falha.

gc($lifetime)

O callback de limpeza (gc) é invocado pelo PHP, internamente e periodicamente, para apagar dados de sessão antiga. A frequência é controlada por session.gc_probability e session.gc_divisor. O valor do parâmetro que é passado para esse callback pode ser definido em session.gc_maxlifetime. O valor de retorno deve ser TRUE para sucesso, FALSE para falha.

create_sid()

Esse callback é executado quando um novo ID de sessão é necessário. Nenhum parâmetro é necessário e o valor de retorno deve ser uma string que seja um ID de sessão válido para seu manipulador.

Valor Retornado

Retorna TRUE em caso de sucesso ou FALSE em caso de falha.

Exemplos

Exemplo #1 Manipulador de sessão personalizado: veja o código completo na sinópse de SessionHandlerInterface.

O código a seguir é para o PHP 5.4.0 ou superior. Aqui é demonstrado apenas a execução, o código completo pode ser visto na sinópse de SessionHandlerInterface no link acima.

Note que é usado orientação à objetos com session_set_save_handler() e a função de encerramento (register_shutdown) é registrada usando sua respectiva flag. Isto geralmente é aconselhável ao registrar objetos como manipuladores de gravação de sessão.


<?php
class MySessionHandler implements SessionHandlerInterface
{
    // implementa a interface aqui
}

$handler = new MySessionHandler();
session_set_save_handler($handler, true);
session_start();

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

Exemplo #2 Manipuladores personalizados de gravação de sessão usando objetos

O código a seguir é para versões do PHP anteriores à 5.4.0.

O exemplo a seguir apresenta um armazenamento de sessão baseada em arquivos semelhante aos manipuladores de gravação de sessão padrões do PHP files. Este exemplo poderia ser facilmente estendido para cobrir o armazenamento em banco de dados usando sua engine de banco de dados favorita e que seja suportada pelo PHP.

Note que foi registrada a função session_write_close() usando register_shutdown_function() em versões do PHP anteriores à 5.4.0. Isso geralmente é aconselhável ao registrar objetos como manipuladores de gravação de sessão em versões anteriores à 5.4.0.


<?php
class FileSessionHandler
{
    private $savePath;

    function open($savePath, $sessionName)
    {
        $this->savePath = $savePath;
        if (!is_dir($this->savePath)) {
            mkdir($this->savePath, 0777);
        }

        return true;
    }

    function close()
    {
        return true;
    }

    function read($id)
    {
        return (string)@file_get_contents("$this->savePath/sess_$id");
    }

    function write($id, $data)
    {
        return file_put_contents("$this->savePath/sess_$id", $data) === false ? false : true;
    }

    function destroy($id)
    {
        $file = "$this->savePath/sess_$id";
        if (file_exists($file)) {
            unlink($file);
        }

        return true;
    }

    function gc($maxlifetime)
    {
        foreach (glob("$this->savePath/sess_*") as $file) {
            if (filemtime($file) + $maxlifetime < time() && file_exists($file)) {
                unlink($file);
            }
        }

        return true;
    }
}

$handler = new FileSessionHandler();
session_set_save_handler(
    array($handler, 'open'),
    array($handler, 'close'),
    array($handler, 'read'),
    array($handler, 'write'),
    array($handler, 'destroy'),
    array($handler, 'gc')
    );

// a linha a seguir evita comportamentos não esperados ao usar objetos como manipuladores de gravação
register_shutdown_function('session_write_close');

session_start();
// proceder para definir e recuperar valores pela chave de $_SESSION

Notas

Aviso

Ao utilizar objetos como manipuladores de gravação de sessão, é importante registrar a função de finalização no PHP para evitar efeitos colaterais não esperados devido à forma como o PHP destrói objetos internamente em seu encerramento e que pode impedir que as funções write e close sejam executadas. Normalmente, 'session_write_close' deve ser registrada usando a função register_shutdown_function().

A partir do PHP 5.4.0 pode ser usado session_register_shutdown() ou simplesmente a flag 'register shutdown' ao invocar session_set_save_handler() usando o método orientado à objetos e passando uma instância que implemente SessionHandlerInterface.

Aviso

A partir do PHP 5.0.5 os manipuladores write e close são executados depois da destruição de objetos e portanto não podem usar objetos ou lançar exceções. Não é possível capturar nem exibir o rastro (trace) de exceções e a execução simplesmente será interrompida de forma inesperada. Contudo, os destrutores do objeto podem usar sessões.

É possível chamar session_write_close() do destrutor para resolver esse problema de 'o ovo e a galinha' mas a forma mais confiável é registrar a função de finalização como descrito acima.

Aviso

O diretório de trabalho atual é alterado com algumas SAPIs (Server API) se a sessão for fechada na finalização do script. É possível fechar a sessão antecipadamente com session_write_close().

Changelog

Versão	Descrição
5.5.1	Adicionado o parâmetro opcional `create_sid`.
5.4.0	Adicionado SessionHandlerInterface para a implementação de manipuladores de sessão e SessionHandler para expor manipuladores de sessão internos do PHP.

Veja Também

session.save_handler (diretiva de configuração)
session.serialize_handler (diretiva de configuração)
A register_shutdown_function() - Registra uma função para ser executada ao final da execução
A session_register_shutdown() - Função de finalização da sessão para PHP 5.4.0+
Visite » save_handler.inc para ver uma implementação completamente procedural