FlightPHP Session - Manipulador de Sessão Leve Baseado em Arquivos

Isto é um plugin leve e baseado em arquivos para manipular sessões no Flight PHP Framework. Ele oferece uma solução simples e poderosa para gerenciar sessões, com recursos como leituras de sessão não bloqueantes, criptografia opcional, funcionalidade de auto-commit e um modo de teste para desenvolvimento. Os dados da sessão são armazenados em arquivos, tornando-o ideal para aplicações que não requerem um banco de dados.

Se você quiser usar um banco de dados, verifique o plugin ghostff/session que possui muitos desses mesmos recursos, mas com backend de banco de dados.

Visite o repositório no Github para o código-fonte completo e detalhes.

Instale o plugin via Composer:

composer require flightphp/session

Aqui está um exemplo simples de como usar o plugin flightphp/session na sua aplicação Flight:

require 'vendor/autoload.php';

use flight\Session;

$app = Flight::app();

// Registra o serviço de sessão
$app->register('session', Session::class);

// Exemplo de rota com uso de sessão
Flight::route('/login', function() {
    $session = Flight::session();
    $session->set('user_id', 123);
    $session->set('username', 'johndoe');
    $session->set('is_admin', false);

    echo $session->get('username'); // Saída: johndoe
    echo $session->get('preferences', 'default_theme'); // Saída: default_theme

    if ($session->get('user_id')) {
        Flight::json(['message' => 'Usuário está logado!', 'user_id' => $session->get('user_id')]);
    }
});

Flight::route('/logout', function() {
    $session = Flight::session();
    $session->clear(); // Limpa todos os dados da sessão
    Flight::json(['message' => 'Deslogado com sucesso']);
});

Flight::start();

Pontos Chave

• Não Bloqueante: Usa read_and_close para iniciar a sessão por padrão, impedindo problemas de bloqueio de sessão.
• Auto-Commit: Ativado por padrão, então as alterações são salvas automaticamente no desligamento, a menos que desativado.
• Armazenamento em Arquivos: As sessões são armazenadas no diretório temporário do sistema sob /flight_sessions por padrão.

Você pode personalizar o manipulador de sessão passando um array de opções ao registrar:

// Sim, é um array duplo :)
$app->register('session', Session::class, [ [
    'save_path' => '/custom/path/to/sessions',         // Diretório para os arquivos de sessão
    'prefix' => 'myapp_',                              // Prefixo para os arquivos de sessão
    'encryption_key' => 'a-secure-32-byte-key-here',   // Ativa criptografia (32 bytes recomendados para AES-256-CBC)
    'auto_commit' => false,                            // Desativa auto-commit para controle manual
    'start_session' => true,                           // Inicia a sessão automaticamente (padrão: true)
    'test_mode' => false,                              // Ativa modo de teste para desenvolvimento
    'serialization' => 'json',                         // Método de serialização: 'json' (padrão) ou 'php' (legado)
] ]);

Opções de Configuração

Por padrão, esta biblioteca usa serialização JSON para os dados da sessão, o que é seguro e previne vulnerabilidades de injeção de objetos PHP. Se você precisar armazenar objetos PHP na sessão (não recomendado para a maioria dos apps), você pode optar pela serialização PHP legada:

• 'serialization' => 'json' (padrão):
  • Apenas arrays e primitivos são permitidos nos dados da sessão.
  • Mais seguro: imune a injeção de objetos PHP.
  • Arquivos são prefixados com J (JSON simples) ou F (JSON criptografado).
• 'serialization' => 'php':
  • Permite armazenar objetos PHP (use com cautela).
  • Arquivos são prefixados com P (serialização PHP simples) ou E (serialização PHP criptografada).

Nota: Se você usar serialização JSON, tentar armazenar um objeto lançará uma exceção.

Commit Manual

Se você desativar o auto-commit, você deve commitar as alterações manualmente:

$app->register('session', Session::class, ['auto_commit' => false]);

Flight::route('/update', function() {
    $session = Flight::session();
    $session->set('key', 'value');
    $session->commit(); // Salva explicitamente as alterações
});

Segurança de Sessão com Criptografia

Ative a criptografia para dados sensíveis:

$app->register('session', Session::class, [
    'encryption_key' => 'your-32-byte-secret-key-here'
]);

Flight::route('/secure', function() {
    $session = Flight::session();
    $session->set('credit_card', '4111-1111-1111-1111'); // Criptografado automaticamente
    echo $session->get('credit_card'); // Descriptografado na recuperação
});

Regeneração de Sessão

Regenere o ID da sessão por segurança (ex.: após o login):

Flight::route('/post-login', function() {
    $session = Flight::session();
    $session->regenerate(); // Novo ID, mantém os dados
    // OU
    $session->regenerate(true); // Novo ID, deleta os dados antigos
});

Exemplo de Middleware

Proteja rotas com autenticação baseada em sessão:

Flight::route('/admin', function() {
    Flight::json(['message' => 'Bem-vindo ao painel de administração']);
})->addMiddleware(function() {
    $session = Flight::session();
    if (!$session->get('is_admin')) {
        Flight::halt(403, 'Acesso negado');
    }
});

Isto é apenas um exemplo simples de como usar isso em middleware. Para um exemplo mais detalhado, veja a documentação de middleware.

A classe Session fornece esses métodos:

• set(string $key, $value): Armazena um valor na sessão.
• get(string $key, $default = null): Recupera um valor, com um padrão opcional se a chave não existir.
• delete(string $key): Remove uma chave específica da sessão.
• clear(): Deleta todos os dados da sessão, mas mantém o mesmo nome de arquivo para a sessão.
• commit(): Salva os dados atuais da sessão no sistema de arquivos.
• id(): Retorna o ID da sessão atual.
• regenerate(bool $deleteOldFile = false): Regenera o ID da sessão, incluindo a criação de um novo arquivo de sessão, mantendo todos os dados antigos e o arquivo antigo permanece no sistema. Se $deleteOldFile for true, o arquivo de sessão antigo é deletado.
• destroy(string $id): Destrói uma sessão pelo ID e deleta o arquivo de sessão do sistema. Isso faz parte da SessionHandlerInterface e $id é obrigatório. Uso típico seria $session->destroy($session->id()).
• getAll() : Retorna todos os dados da sessão atual.

Todos os métodos, exceto get() e id(), retornam a instância Session para encadeamento.

Contribuições são bem-vindas! Faça fork no repositório, faça suas alterações e envie um pull request. Relate bugs ou sugira recursos via o rastreador de issues do Github.

Este plugin é licenciado sob a Licença MIT. Veja o repositório no Github para detalhes.