README

PHP session handler built on Symfony components and supporting Silex v1 & v2.

Supports session storage with:

• Doctrine cache
• Symfony Filesystem
• Bolt Filesystem
• Memcache
• Memcached
• PSR-6 Cache
• PSR-16 Simple Cache
• Redis

Service Providers

Silex 1

use Bolt\Session\Bridge\Silex1\SessionServiceProvider;
use Silex\Application;


$app = new Applicaiton();
$app->register(new SessionServiceProvider());

Silex 2

use Bolt\Session\Bridge\Silex2\SessionServiceProvider;
use Silex\Application;

$app = new Applicaiton();
$app->register(new SessionServiceProvider());

Browser cookies

By default, Bolt will inherit the settings cookies_lifetime, cookies_domain, and enforce_ssl (for cookie_secure) should no override options be set, as per the order of precedence explained in the introduction.

However, there are several override settings available, should you need more fine-grained control.

Life time

Time in seconds, that a cookie will be valid for. Setting this value to 0 means "until the browser is closed".

In .php.ini this setting is session.cookie_lifetime.

Base URI path

Specifies URI path to set in the session cookie.

In .php.ini this setting is session.cookie_path.

Override domain name

Specifies the domain to set in the session cookie. Default is null, meaning the host name of the server which generated the cookie.

In .php.ini this setting is session.cookie_domain.

Enforce HTTPS requests

Setting this to true will enforce a HTTPS connection requirement to set, and use, the session cookie.

In .php.ini this setting is session.cookie_secure.

Restricting request to the HTTP protocol

Marks the cookie as accessible only through the HTTP protocol, blocking access to requests by things such as JavaScript.

This setting can effectively help to reduce identity theft through XSS attacks, although browser support may vary.

Setting in your config.yml:

In .php.ini this setting is session.cookie_httponly.

Session ID generation

Session IDs are randomly generated to uniquely identify a user's session. Bolt internally handles this generation in a fashion close to how PHP 7.1+ now does to better ensure the uniqueness of the generated ID.

By default, both PHP & Bolt use an ID length of 32, which should provide only a small chance of collisions, or predictability, of the generated ID.

On hosts with a consistent amount of available CPU resources, and a focus on security, you should consider a number of 48 or greater. However, this will increase the server load, and amount of time taken to generate session IDs.

An example of generating 1,000 session IDs on PHP 7.0 and an Intel i5-5200:

Maximum value supported is 256.

In PHP 7.1+ the .php.ini this setting is session.sid_length.

Session storage handler

Session storage handling, by default, is our filesystem layer. However, we also support Redis & Memcached for more advanced use-cases.

Setting in your config.yml:

In .php.ini this setting is session.save_handler.

Note: Some web hosting providers may implement alternative session handling that is not compatible with Bolt Session.

Should you encounter exceptions from SessionServiceProvider indicating problems with PHP's system save path, set save_handler: filesystem, and the save_path option shown below.

Using the Redis handler

When using Redis as the handler, the following options are also under the connections subkey, of the session options:

If the native \Redis library is available, it will be used as the handler for Redis, if not available, it will instead check for the PHP implementation of the native library, \Predis\Client and use that.

Using the Memcached handler

When using Memcached as the handler, the following options are also under the connections subkey, of the session options:

Saved session file path

Session data is cached in between requests, and is not cleared by the normal cache clearing functionality.

Instead, it uses garbage collection to manage deletion of expired sessions. See the section below on garbage collection for details on configuration.

Note: Manually deleting session data on a live server is never advised. Should this ever be required on a live server, ensure all users are logged off, and place the site into maintenance mode first.

In .php.ini this setting is session.save_path.

Using the Filesystem handler

When using the default filesystem handler, the save_path parameter needs to be in the form of {mount point}://{path}.

See the Overview of Bolt's Filesystem page for details on the mount points available in Bolt.

Warning: If you set this to a world-readable directory, such as /tmp, other users on the server may be able to hijack sessions, or extract potentially sensitive data.

Using the Redis handler

When using Redis as the handler, save_path should be defined in the format tcp://IPADDRESS:PORT, with a default of tcp://127.0.0.1:6379.

Using the Memcached handler

When using Memcached as the handler, save_path should be defined in the format IPADDRESS:PORT, with a default of 127.0.0.1:11211.

Garbage collection

Session garbage collection is the removal of sessions older than the configured maximum life time.

The need to perform garbage collection is determined based on a random probability calculation during the initialisation of each session.

Maximum life time

The maximum life time setting specifies the number of seconds after which session data will be seen as 'garbage' and potentially cleaned up.

In .php.ini this setting is session.gc_maxlifetime.

Probability & divisor

The setting gc_divisor coupled with gc_probability define the probability that the garbage collection (GC) process is performed.

In Bolt's session storage handler, the probability is calculated by generating a random number between 0 and gc_divisor. If the value of gc_probability is greater than the random number, garbage collection will be performed, and session files older than the maximum configured life time are removed.

Note: To disable garbage collection, set gc_probability to -1.

In .php.ini these settings are:

• session.gc_probability
• session.gc_divisor