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

Descrição

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 = ?
): bool

É possível registrar o seguinte protótipo:

session_set_save_handler(object $sessionhandler, bool $register_shutdown = true): bool

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, por exemplo 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, e opcionalmente SessionIdInterface e/ou SessionUpdateTimestampHandlerInterface, como SessionHandler, para registrá-la como manipulador de sessão.
register_shutdown: Registra session_write_close() como uma função register_shutdown_function().

or

open

Um callable com a seguinte assinatura:

open(string $savePath, string $sessionName): bool

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

Um callable com a seguinte assinatura:

close(): bool

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

Um callable com a seguinte assinatura:

read(string $sessionId): string

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

Um callable com a seguinte assinatura:

write(string $sessionId, string $data): bool

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.

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

Um callable com a seguinte assinatura:

destroy(string $sessionId): bool

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

Um callable com a seguinte assinatura:

gc(int $lifetime): bool

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

Um callable com a seguinte assinatura:

create_sid(): string

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.

validate_sid

Um callable com a seguinte assinatura:

validate_sid(string $key): bool

Este callback é executado quando uma sessão é iniciada, um ID de sessão é fornecido e session.use_strict_mode é habilitado. A key é o ID da sessão para validar. Um ID de sessão é válido se já existir uma sessão com esse ID. O valor retornado deve ser true em caso de sucesso, false em caso de falha.

update_timestamp

Um callable com a seguinte assinatura:

update_timestamp(string $key, string $val): bool

Este callback é executado quando uma sessão é atualizada. key é o ID da sessão, val são os dados da sessão. O valor retornado deve ser true em caso de sucesso, false em caso de falha.

Valor Retornado

Retorna true em caso de sucesso ou false em caso de falha.

Exemplos

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

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

Notas

Warning

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

Warning

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().

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 no final da execução do script
The session_register_shutdown() - Função de finalização da sessão
Visite » save_handler.inc para ver uma implementação completamente procedural