tundra / session
Intuitive library for managing complex session handling.
Requires
- php: ^5.4|^7.0|^8.0
This package is auto-updated.
Last update: 2025-05-21 22:09:25 UTC
README
The Tundra Session is a robust, high-performance PHP library for managing sessions. Requires PHP >= 7.0
It integrates with PHP's session_set_save_handler()
and remains fully compatible with PHP’s built-in session system.
Standard functions like session_destroy()
and session_write_close()
will still work but will only affect
the default driver.
You can use your web server to set the "Parted" cookie attribute where necessary, also my repository https://github.com/jacopovalanzano/php-http can be used to set custom cookie attributes like "Parted" via PHP.
Using the session handler
Start a new session using Tundra\Session\SessionHandler::start()
When the session starts, PHP will use the selected driver to retrieve session data.
The data retrieved is used to populate the $_SESSION
array.
When the session is closed using SessionHandler::close()
, each driver will persist the session data to storage.
If the session is closed using session_write_close()
instead, only the default driver will persist the session data.
If you use multiple drivers, set the fastest driver as the default driver.
This is useful if, for example, you want a fast APC session and a persistent copy of the session data in a database.
$apcDriver = new \Tundra\Session\Drivers\ApcSession(); // Memory driver $fileDriver = new \Tundra\Session\Drivers\FileSession(); // File driver $session = new \Tundra\Session\SessionHandler(); $session->addDriver("apc_driver", $apcDriver); $session->addDriver("file_driver", $fileDriver); $session->setDefaultDriver("apc_driver"); // A default driver must alway be set $session->driver("file_driver")->open("/tmp/php", $session->getName()); // Open the session driver $session->start(); // Start a new session: opens then reads the data from the default driver and puts it in $_SESSION (`null` if no data) $session->set("key", "value"); // Set the session data; the equivalent of $_SESSION["key"] = "value" $session->get("key"); // Get the session data from $_SESSION; the equivalent of $_SESSION["key"] $session->close(); // Save the session data on each driver
The session data is not stored immediately when set; instead, it is saved when the session is closed:
$session->close(); // Each driver will store the session data // or \session_write_close(); // Only the default driver will store the session data
You cannot set or get data while the session is closed.
$session->set("key", "value"); // Fills the $_SESSION array $session->start(); // Start the session: the $_SESSION array is now empty $session->get("key"); // Throws an error or returns null $session->close(); // No data to save $session->get("key"); // Throws an error or returns null
Opening and closing sessions
Opening and closing the session involves reading the data from one driver and writing data to every driver available.
$session->start(); // Reads the data from the default driver and puts it in $_SESSION $session->close(); // Saves the session data on each driver & runs each driver "close" method
You must use the SessionHandler::start()
to open a new session and the SessionHandler::close()
method
to instruct each driver to store the session data, and finally close the session.
The session should be operated exclusively by the SessionHandler
, but the PHP session, $_SESSION
and the
driver wrapper \Tundra\Session\SessionDriverWrapper
can do that too.
Opening and closing multiple sessions
The start()
method will only open the default driver storage. If you want to use multiple drivers, you must
open each driver individually using the open()
method:
$fileDriver = new \Tundra\Session\Drivers\FileSession(); $apcDriver = new \Tundra\Session\Drivers\ApcSession(); $sqlDriver = new YourSQLSession(); $session = new \Tundra\Session\SessionHandler(); $session->addDriver("apc_driver", $apcDriver); $session->addDriver("file_driver", $fileDriver); $session->addDriver("sql_driver", $sqlDriver); $session->setDefaultDriver("apc_driver"); $session->driver("file_driver")->open("/tmp/file"); // Open the file driver $session->driver("sql_driver")->open(""); // Open the SQL driver (path is empty; argument required but not actually needed by the SQL driver) $session->start(); // Let the default driver open the session $session->close(); // Save the session data on each driver
You can also use the openAll()
method. Use openAll()
before starting the session:
$session->openAll("/tmp/php", $session->getName()); $session->start(); $session->close(); // Save the session data on each driver
⚠️ The default driver will always be opened on session start by PHP's session_set_save_handler
, when the start()
method is called. This behavior could lead to unexpected results if the driver is not designed to be opened more than once without being closed first. The openAll
method causes the default driver to be opened a second time when the session starts.
Close the session
Depending on the driver, session data may not be readable or writable while the session is closed, often due to file locks or database transactions.
Examples
Create a file session:
<?php /** * Start a new file session: */ $session = new \Tundra\Session\SessionHandler(); $fileDriver = new \Tundra\Session\Drivers\FileSession(); // Driver $session->setDefaultDriver("apc_driver"); // Always set a default driver $session->addDriver($fileDriver); $session->start(); // Start the session
You should always check if the session was started:
if(! $session->isStarted()) { $session->start(); }
Or even better, you can use the safeStart
method
try { $session->safeStart(); } catch(\RuntimeException $e) { // ... }
Create an "APC" session in-memory. The session data will be lost on restart:
<?php /** * Start a new APC session (sessions will be lost on restart): */ $session = new \Tundra\Session\SessionHandler(); $apcDriver = new \Tundra\Session\Drivers\ApcSession(); $session->addDriver($apcDriver); // Start the session if(! $session->isStarted()) { $session->start(); }
Use multiple drivers:
<?php /** * Set multiple drivers */ $session = new \Tundra\Session\SessionHandler(); $apcDriver = new \Tundra\Session\Drivers\ApcSession(); $fileDriver = new \Tundra\Session\Drivers\FileSession(); $session->addDriver("apc_driver", $apcDriver); $session->addDriver("file_driver", $fileDriver); $session->setDefaultDriver("apc_driver"); // Always set a default driver // Start the session if(! $session->isStarted()) { // Open all the drivers $session->openAll($path, $sessionName); // Start the session $session->start(); }
Create your own driver
class SQLSession implements \SessionHandlerInterface { public function open($path, $sessionName) { // ... } public function close() { // ... } public function read($sessionId) { // ... } public function write($sessionId, $data) { // ... } public function destroy($sessionId) { // ... } public function gc($maxlifetime) { // ... } }
Implement the mock SQLSession
driver:
$session = new \Tundra\Session\SessionHandler(); $sqlDriver = new SQLSession(); $session->addDriver($sqlDriver); $session->start(); $session->set("foo", "bar"); $session->get("foo"); $session->close();
You can call custom driver methods using driver()
:
class SQLSession implements \SessionHandlerInterface { // ... public function getData($key) { // ... if(! $connection->isOpen()) { $connection->open(); } $data = $connection->select($key)->from("table")->get(); $connection->close(); return $data; } }
Call the getData() method:
$session->driver()->getData("foo");
Handling session data
Session destroy
When you destroy the session, the session stops running, but the global $_SESSION
variable remains untouched.
However, the session storage is cleared—if using file-based storage, for example, the session file is deleted;
if using an SQL database driver, the session record is removed.
The session data remains available within PHP until the script execution ends.
Session invalidate
When you invalidate the session, the session remains active, but the global $_SESSION
variable is cleared,
and a new session ID is generated. PHP will no longer have access to the previous session data, but the
storage remains untouched. This can lead to excessive session files or database records, potentially increasing
storage size. Ensure you genuinely need a new session without removing the old one from storage.
⚠️ Using invalidate
can lead to huge database size or a lot of session files. Make sure you intend to
generate a new session, without deleting the previous session from storage.
Session clear
When you clear the session, it remains active, but the global $_SESSION
variable is emptied while keeping the
same session ID. PHP will no longer have access to the session data. This results in an empty session file or
database record, causing all data to be lost when the session is closed, though the record or file
itself will persist.
Session erase
If you want to create a fresh new session and destroy the storage data, use erase()
.
This will stop the session, clear the session data from both the storage and the PHP system, and
generate a new session ID.