array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'pt_BR', ), 'this' => array ( 0 => 'function.session-set-save-handler.php', 1 => 'session_set_save_handler', ), 'up' => array ( 0 => 'ref.session.php', 1 => 'Funções para Sessão', ), 'prev' => array ( 0 => 'function.session-set-cookie-params.php', 1 => 'session_set_cookie_params', ), 'next' => array ( 0 => 'function.session-start.php', 1 => 'session_start', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'pt_BR', 'path' => 'reference/session/functions/session-set-save-handler.xml', ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); ?>
(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.
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().
open
Um 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.
close
Um 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.
read
Um 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.
write
Um 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.
destroy
Um 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.
gc
Um 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_sid
Um 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_sid
Um 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_timestamp
Um 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().