README

This library implements a type-hinted container for session model objects.

This approach gives you type-hinted closures whenever you're working with session state of any sort, which is great for IDE support and code comprehension in general.

Usage

Note that SessionService does not attempt to control the PHP session lifecycle - it only provides a type-safe means of storing serialized objects in session variables; you are still in charge of e.g. starting the session with session_start(), etc.

Setting up

Let's assume you have a session model like this one:

class Cart
{
    /** @var int */
    public $user_id;

    /** @var int[] */
    public $product_ids = array();
}

In a real project, you probably want to use a dependency injection container or some other means of centrally managing your SessionContainer instance.

At the end of your request cycle (centrally, e.g. after dispatching a controller, but before sending the response), you must call commit() to store the session data:

// commit session container contents to session variables:

$session->commit();

This ensures you don't have partial changes made to session variables in case of errors. If you don't care about transactional sessions and want changes committed automatically, you can register a shutdown function, for example:

register_shutdown_function(function () use ($session) {
    $session->commit();
});

Working with the session model container

In the following examples, for simplicty, we'll assume your session container is a global variable:

use mindplay\session\SessionContainer;

$session = new SessionContainer();

Note that, in a real project, you would probably want to type-hint e.g. controllers against the abstract SessionContainer interface, since calling e.g. commit() isn't relevant there.

To access/update a session model object, pass a type-hinted closure to the update() method:

// add some products to the Cart:

$session->update(
    function (Cart $cart) {
        $cart->product_ids[] = 777;
        $cart->product_ids[] = 555;
    }
);

The update() method will construct Cart for you - it's therefore important to note that session model classes must always have an empty constructor.

You can take values out of a container as well:

$cart = $session->update(function (Cart $cart) {
    return $cart;
});

But do note that it's generally not very good practice to take session model objects out of the container, as this blurs the fact that you're making changes to session state - the call to update() clarifies what you're doing.

To remove a session model object:

// empty the cart:

$session->remove(Cart::class);

If you have a reference to the session model object, remove() will also accept that.

Optional session models

If you don't know if a session model has been constructed yet, and you want to avoid creating an empty session model, you can use a default null parameter in the closure:

$session->update(
    function (Cart $cart = null) {
        if ($cart) {
            // ...
        }
    }
);

Multiple models in one call

If you need two (or more) session model objects at the same time, just ask for them:

$session->update(function (User $user, Cart $cart) {
    // ...
});

Remove all session models

To remove all session models, call the clear() method.

Note that the session models are not removed from underlying storage until commit() is called.

Custom storage and testing

A MockSessionStorage implementation is included, useful for integration tests - you can provide this (or any SessionStorage implementation) at construction time, e.g.:

use mindplay\session\MockSessionStorage;
use mindplay\session\SessionContainer;

$storage = new MockSessionStorage('foo');

$container = new SessionContainer($storage);

During integration tests, you can make assertions about the contents of the public MockSessionStorage::$data property, which contains the raw session model objects, indexed by class-name.

mindplay / session

Maintainers

Details