FlightPHP Sesión - Manejador de Sesiones Ligero Basado en Archivos

Esto es un plugin ligero, basado en archivos, para manejar sesiones en el Flight PHP Framework. Proporciona una solución simple pero potente para gestionar sesiones, con características como lecturas de sesiones no bloqueantes, cifrado opcional, funcionalidad de auto-commit y un modo de prueba para desarrollo. Los datos de sesión se almacenan en archivos, lo que lo hace ideal para aplicaciones que no requieren una base de datos.

Si deseas usar una base de datos, consulta el plugin ghostff/session que incluye muchas de estas mismas características pero con un backend de base de datos.

Visita el repositorio de Github para el código fuente completo y detalles.

Instala el plugin a través de Composer:

composer require flightphp/session

Aquí hay un ejemplo simple de cómo usar el plugin flightphp/session en tu aplicación Flight:

require 'vendor/autoload.php';

use flight\Session;

$app = Flight::app();

// Registra el servicio de sesión
$app->register('session', Session::class);

// Ejemplo de ruta con uso de sesión
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'); // Esto imprime: johndoe
    echo $session->get('preferences', 'default_theme'); // Esto imprime: default_theme

    if ($session->get('user_id')) {
        Flight::json(['message' => '¡El usuario está logueado!', 'user_id' => $session->get('user_id')]);
    }
});

Flight::route('/logout', function() {
    $session = Flight::session();
    $session->clear(); // Limpia todos los datos de sesión
    Flight::json(['message' => 'Cerrado de sesión exitoso']);
});

Flight::start();

Puntos Clave

• No Bloqueante: Usa read_and_close para iniciar la sesión por defecto, previniendo problemas de bloqueo de sesiones.
• Auto-Commit: Habilitado por defecto, por lo que los cambios se guardan automáticamente al cerrar a menos que se desactive.
• Almacenamiento en Archivos: Las sesiones se almacenan en el directorio temporal del sistema bajo /flight_sessions por defecto.

Puedes personalizar el manejador de sesiones pasando un arreglo de opciones al registrar:

// Sí, es un arreglo doble :)
$app->register('session', Session::class, [ [
    'save_path' => '/custom/path/to/sessions',         // Directorio para los archivos de sesión
    'prefix' => 'myapp_',                              // Prefijo para los archivos de sesión
    'encryption_key' => 'a-secure-32-byte-key-here',   // Habilita el cifrado (se recomienda 32 bytes para AES-256-CBC)
    'auto_commit' => false,                            // Desactiva el auto-commit para control manual
    'start_session' => true,                           // Inicia la sesión automáticamente (por defecto: true)
    'test_mode' => false,                              // Habilita el modo de prueba para desarrollo
    'serialization' => 'json',                         // Método de serialización: 'json' (por defecto) o 'php' (heredado)
] ]);

Opciones de Configuración

Por defecto, esta biblioteca usa serialización JSON para los datos de sesión, lo que es seguro y evita vulnerabilidades de inyección de objetos PHP. Si necesitas almacenar objetos PHP en la sesión (no recomendado para la mayoría de las aplicaciones), puedes optar por la serialización PHP heredada:

• 'serialization' => 'json' (por defecto):
  • Solo se permiten arreglos y primitivos en los datos de sesión.
  • Más seguro: inmune a la inyección de objetos PHP.
  • Los archivos se prefijan con J (JSON plano) o F (JSON cifrado).
• 'serialization' => 'php':
  • Permite almacenar objetos PHP (usa con precaución).
  • Los archivos se prefijan con P (serialización PHP plana) o E (serialización PHP cifrada).

Nota: Si usas serialización JSON, intentar almacenar un objeto lanzará una excepción.

Commit Manual

Si desactivas el auto-commit, debes confirmar los cambios manualmente:

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

Flight::route('/update', function() {
    $session = Flight::session();
    $session->set('key', 'value');
    $session->commit(); // Guarda explícitamente los cambios
});

Seguridad de Sesión con Cifrado

Habilita el cifrado para datos sensibles:

$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'); // Se cifra automáticamente
    echo $session->get('credit_card'); // Se descifra al recuperar
});

Regeneración de Sesión

Regenera el ID de sesión por seguridad (por ejemplo, después de iniciar sesión):

Flight::route('/post-login', function() {
    $session = Flight::session();
    $session->regenerate(); // Nuevo ID, mantiene los datos
    // O
    $session->regenerate(true); // Nuevo ID, elimina los datos antiguos
});

Ejemplo de Middleware

Protege rutas con autenticación basada en sesiones:

Flight::route('/admin', function() {
    Flight::json(['message' => 'Bienvenido al panel de administración']);
})->addMiddleware(function() {
    $session = Flight::session();
    if (!$session->get('is_admin')) {
        Flight::halt(403, 'Acceso denegado');
    }
    // Esto es solo un ejemplo simple de cómo usarlo en middleware. Para un ejemplo más detallado, consulta la documentación de [middleware](/learn/middleware).
});

La clase Session proporciona estos métodos:

• set(string $key, $value): Almacena un valor en la sesión.
• get(string $key, $default = null): Recupera un valor, con un valor predeterminado opcional si la clave no existe.
• delete(string $key): Elimina una clave específica de la sesión.
• clear(): Elimina todos los datos de sesión, pero mantiene el mismo nombre de archivo para la sesión.
• commit(): Guarda los datos de sesión actuales en el sistema de archivos.
• id(): Devuelve el ID de sesión actual.
• regenerate(bool $deleteOldFile = false): Regenera el ID de sesión, incluyendo la creación de un nuevo archivo de sesión, manteniendo todos los datos antiguos y el archivo antiguo permanece en el sistema. Si $deleteOldFile es true, se elimina el archivo de sesión antiguo.
• destroy(string $id): Destruye una sesión por ID y elimina el archivo de sesión del sistema. Esto forma parte de la SessionHandlerInterface y $id es requerido. El uso típico sería $session->destroy($session->id()).
• getAll(): Devuelve todos los datos de la sesión actual.

Todos los métodos excepto get() y id() devuelven la instancia de Session para encadenamiento.

¡Las contribuciones son bienvenidas! Bifurca el repositorio, realiza tus cambios y envía una solicitud de extracción. Reporta errores o sugiere características a través del rastreador de problemas de Github.

Este plugin está licenciado bajo la Licencia MIT. Consulta el repositorio de Github para detalles.