Starting Session

Session starts in the "front controller," which is the /public/index.php. By default, the class SessionManager has been registered (or bound) using the Container class in the /bootstrap/bindings.php. Thus, to use the methods from the SessionManager class, one can make new instance of the class or better call it using Container class.

This is an example of starting the session using both ways:

use Zap\Core\Utils\SessionManager;
$sessionMgr = new SessionManager;
$sessionMgr->start();

//or

use Zap\Core\Utils\Container;
use Zap\Core\Utils\SessionManager;

$sessionMgr = Container::getInstance()->make(SessionManager::class);
$sessionMgr->start();

The difference between both is that the second one does not create a new instance but use the existing one (singleton).

Adding Session

Sessions can be added for different purposes, but typically, a session is added to store the logged user data. For this purpose, SessionManager can be used in the model or controller method (e.g., validating login) and in the middleware (e.g., validating access).

All sessions are stored in an encrypted array, with the top-level key is taken from the SESSION_NAME in the .env. However, you are free to store sessions as many as possible with the name of your choice. Here are some examples for adding or storing sessions:

$sessionMgr = Container::getInstance()->make(SessionManager::class);
$userdata = [
 'name' => 'John Doe',
 'status' => 'active',
 'role' => 'user',
 'contact' => [
 'address' => 'Elm Street number 404',
 'email' => 'johndoe@example.com'
 ]
];
$sessionMgr->regenerate(true); //important when access previlege is concerned
$sessionMgr->set(config('app.session'), $userdata);

$editedPost = [
 'id' => 500,
 'title' => 'A Nightmare on Elm Street',
 'author' => 'Jane Doe'
];
$sessionMgr->set('editedPost', $editedPost);

Keep in mind that the session name is string, while the session data is array.

Checking and Getting Session

To check whether a session exists (by session name), you can use has() method. This method returns boolean (true if exists, otherwise, false). Meanwhile, to get the session data, use get() method.

//assuming that you are using Container
//checking session
$sessionName = config('app.session'); // or any session name you set
$sessionExist = $sessionMgr->has($sessionName); // return true or false

//getting session
$sessionData = $sessionMgr->get($sessionName); // return array or false if the session does not exist

In Zap, sessions stored using SessionManager cannot be read by using $_SESSION, unless they are stored using $_SESSION. Trying $sessionData = $_SESSION[config('app.session')] will return encrypted string.

I have stored a session data with name testSession. This is what it looks like when the session data is retrieved using $_SESSION:

iPvDxWom+Ub9BS58XoTkFDnnMJS1biw/Zc32veioYD/EC49N6c+CNlIBBjnSq1d4GUEcj6aPkI4WgkwCTvThGlbbrEVGgz0n1k+v7FEvxTimY/qlVSF7b0P4UQrvUYpT1

Without the ZAP_KEY, even Tony Stark and Jarvis cannot decrypt this session data!

Meanwhile, with the correct method, the session data looks like this:

Array
(
    [text] => This is a test session data
)
1

Updating Session

SessionManager enables you for updating session data entirely or by keys. For instance, when a logged user changes their email or name, their status (in session data) can be updated without having to log in again.

For updating the entire session data, first prepare the updated data array, then use $sessionMgr->set($sessionName, $updatedData). This will replace the entire session data with the new array. Meanwhile, for updating specific keys within the session data, use $sessionMgr->updateVal($sessionName, $key, $value) for a single key, and $sessionMgr->update($sessionName, $updates) for multiple keys.

//update single key 
$sessionName = config('app.session'); // or any session name you set
$sessionMgr->updateVal($sessionName, 'email', 'newemail@example.com');

//update multiple keys

$updatedData = [
 'email' => 'newemail@example.com',
 'name' => 'New Name'
];
$sessionMgr->updateVal($sessionName, $updatedData);

//replace entire session data
$newSessionData = [
 'name' => 'New Name',
 'status' => 'active',
 'role' => 'user',
 'contact' => [
 'address' => 'New Address',
 'email' => 'newemail@example.com'
 ]
];
$sessionMgr->set($sessionName, $newSessionData);

Unsetting and Destroying Session

To unset a session, use $sessionMgr->unset(). This will remove the session data from the session storage. To destroy the entire session, use $sessionMgr->destroy(). This will remove all session data and end the session.

//unset a session
$sessionName = config('app.session'); // or any session name you set
$sessionMgr->unset($sessionName);

//destroy the entire session
$sessionMgr->destroy();