(PHP 4, PHP 5, PHP 7, PHP 8)
session_set_save_handler — Define funções de armazenamento de sessão à nível de usuário
$open,$close,$read,$write,$destroy,$gc,$create_sid = ?,$validate_sid = ?,$update_timestamp = ?É possível registrar o seguinte protótipo:
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.
Essa função tem dois protótipos.
sessionhandlerUma instância de uma classe implementando SessionHandlerInterface, e opcionalmente SessionIdInterface e/ou SessionUpdateTimestampHandlerInterface, como SessionHandler, para registrá-la como manipulador de sessão.
register_shutdownRegistra session_write_close() como uma função register_shutdown_function().
openUm callable com a seguinte assinatura:
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.
closeUm callable com a seguinte assinatura:
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.
readUm callable com a seguinte assinatura:
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.
writeUm callable com a seguinte assinatura:
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.
destroyUm callable com a seguinte assinatura:
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.
gcUm callable com a seguinte assinatura:
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_sidUm callable com a seguinte assinatura:
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_sidUm callable com a seguinte assinatura:
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_timestampUm callable com a seguinte assinatura:
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.
Exemplo #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 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.
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().