Vecode Caldera

Overview

Description

Caldera Validation is a session abstraction layer, to ease interacting with sessions.

As with the other Caldera components it has been built to be swappable and modular.

Installation

The easisest way to install it is to use Composer:

composer require vecode/caldera-session

Requires

php: >=8.1
ext-mbstring: *

Basic usage

Getting started

By default, PHP provides a file-based session mechanism, however, depending on the type and size of your project you may need a beefier solution.

Caldera Session allows you to change the way session data is stored and accesed, for example, by offloading it to the database; it works through the use of adapters so that you can make your own ones to leverage more advanced storage solutions, such as Redis or Memcached.

So, first you will need to create a Session instance:

use Caldera\Session\Adapter\NativeAdapter;
use Caldera\Session\Session;

$adapter = new NativeAdapter();
$session = new Session($adapter);

The default adapter is the NativeAdapter that uses the base PHP session mechanism; the main advantage of using Caldera Session even with the NativeAdapter is that you gain access to properly encapsulated session management functionality (ready for use with a container implementation) and some helper methods for storage and value flashing.

Session management

To begin, you must start the session, with the start method:

$session->start();

You can also regenerate the session by using the regenerate method

$session->regenerate()

And destroy it with all its related data using the destroy method

$session->destroy()

Storing data

To store values simply use the set method:

$uid = sha256( random_bytes(64) );
$session->set('uid', $uid);

First you specify the name of the entry (an string), then you pass the value of that entry, it can be an scalar value or an array:

$input = $request->getParsedBody();
$session->set('input', $input);

Retrieveing data

To retrieve data stored on the session use the get method:

$uid = $session->get('uid');

A second parameter can be passed as a default value:

$uid = $session->get('uid', '');

You can also check if a certain element is set by using the has method:

if ( $session->has('uid') ) {
    # TBD: Do something if UID is set in the session
}

Clearing data

To delete a single item, use the delete method:

$session->delete('uid');

But if you want to delete all the session contents without regenerating the session ID, use the clear method:

$session->clear();

Pushing and pulling

You can easily build data blocks by pushing values with the push method:

$session->push('errors', 'Name is required');
$session->push('errors', 'Email is required');

Then you can use the pull method to get the entire array and delete it from the session data:

$errors = $session->pull('errors');

Again, you can specify a default value should you want to:

$errors = $session->pull('errors', []);

Flashing data

Other handy tool is the flashing functionality: set data that will get deleted after the next request.

This is particularly useful for messages, validation results, form-input, and so-on.

To flash data, use the flash method:

$session->flash('message', 'Now you are logged off');

Then simply recover with the get method:

$message = $session->get('message');

If you'd like to keep the data for an extra request, use the keep method:

$session->keep('message');

Also if you'd like to keep the entire flash data for an extra session, use the reflash method:

$session->reflash();

Custom adapters

Two adapters are included:

NativeAdapter - Uses the default session mechanism from PHP
DatabaseAdapter - Uses Caldera Database to store and retrieve data to/from the database

To use DatabaseAdapter you just need to pass the current $database instance (see the Caldera Database documentation for more details):

use Caldera\Session\Adapter\DatabaseAdapter;
use Caldera\Session\Session;

$adapter = new DatabaseAdapter($database);
$session = new Session($adapter);
$session->start();

You may also write your own adapters to leverage Redis, Memcached or any other storage backend; just implement both AdapterInterface and SessionHandlerInterface.

For more details on SessionHandlerInterface, check the official PHP documentation.

Also, you can check the source code for DatabaseAdapter for the implementation details.