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

# session_set_save_handler

(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

### Descrição

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

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

ou

`open`

  Um callable com a seguinte assinatura:

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

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

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

  function 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`.

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

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

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

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

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

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

### Registro de Alterações

Versão | Descrição
--- | ---
8.4.0 | Chamar session_set_save_handler() com mais de dois argumentos agora foi descontinuado. Use a assinatura com dois argumentos.

### Exemplos

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

### Notas

Aviso

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.

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

### 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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open