Docs for upcoming cookies and sessions changes

gistfile1.md

Docs for Session and Cookie.

Updates related to the Session and Cookie classes.

Container

Container is a very simple one which can be used as is or extended by a developers class in an extension for example.

Access Methods

The methods follow three patterns to allow a developers choice of coding style.

Setting a value is super simple.

$container->set('my-key', $value);
$container['my-key'] = $value;
$container->{'my-key'} = $value;

As is getting a value

$value = $container->get('my-key');
$value = $container['my-key'];
$value = $container->{'my-key'};

Other methods allow checking whether a value is set, and unset the value too.

$exists = $container->exists('my-key');
$exists = isset($container['my-key']);
$exists = isset($container->{'my-key'});

Unsetting too.

$container->remove('my-key');
unset($container['my-key']);
unset($container->{'my-key'});

Subsetting the container.

To make container use easier for a system like Symphony, a subset of keys cab be collected together to make a smaller container to pass through to a class for usage.

// Container contains 'my-key', 'my-other-key', 'yet-another-key'
$subset = $container->subSet(['my-key', 'my-other-key']);
// Subset is a new instance with 'my-key', 'my-other-key'

Calling values

As Symphony uses a lot of static variables in it's classes that are accessible via methods, it made sense to allow this pattern from an instantiable container, therefore, any key => value can be accessed by a call.

Using this call method allows either setting or getting, and is super handy for callables, services and even values.

$container->set('myKey', 'some value');
$value = $container->myKey(); // 'some value';

$container->set('myKey', function ($con, $args) {
    // The container is available, as is any args passed in at call time
    $obj = new StdClass;
    foreach ($args as $key => $value) {
        $obj->{$key} = $value;
    }
    return $obj;
});
$container->myKey(['my', 'args', 'list']); // stdclass with properties

Other Methods

A couple of other methods are available

$keys = $container->keys(); // Gathers an array of container keys
$all = $container->all();   // Gets the whole container as an array

Sessions

Sessions have been re-imagined for Symphony. Gone are the days of accessing the Cookie class to handle sessions. This was a backwards practice that has caused problems in many builds, as it took complete control of both session and cookie handling.

Session now only deals with sessions. The Session class is instantiated on run, and is stored in Symphony::Session() for developer access. The Session class has all the accessors of Container, and will persist anything set into the session handler for the duration of the session details in the Configuration.

The main difference is that sessions are handled separately for the admin and frontend; A serious problem for current builds who need to handle user logins differently from admin logins.

Configuration

        ###### SESSION ######
        'session' => array(
            'admin_session_name' => 'symphony_admin',
            'public_session_name' => 'symphony_public',
            'admin_session_expires' => '2 weeks',
            'public_session_expires' => '2 weeks',
            'session_gc_probability' => '1',
            'session_gc_divisor' => '10',
        ),
        ########

Session Handling

Sessions can be handled in a variety of ways now, although the default is to use the symphony database. If a developer wants to, this could be replaced with a redis based handler for example.

Cookies

Cookies need no configuration, and are available for developers to use in extensions.

Cookies now only deals with cookies. The Cookies class is instantiated on run, and is stored in Symphony::Cookies() for developer access. The Cookies class has all the accessors of Container, and will persist anything set into a cookie for the max-age or expires timeframe.

All existing cookies are loaded for reference, so they could be overridded, or removed if required. Any new cookies are added to a container for modification through the lifecycle of Symphony.

Added Bouns: Session Flash

Session Flash messaging allows a developer to persist anything string-like over the course of a page load. This means that if an extension needs some data from a previous page, instead of having to store it in the session and then remember to remove it after, just flash it, and it will be removed automatically, unless you tell flash to keep it for another page.

It's pretty simple to use, with few methods.

$flash->now('my-key', 'my message string'); // Makes the string available in this request only, like temporary session storage
$flash->next('my-key', 'my message string'); // makes the message available for the next page load

To retrieve the messages just do the following

$message = $flash->current()['my-key']; // 'my message string'

If you want to keep the message for another request, then call $flash->keep() to keep all the current flash messages.