Download the PHP package snicco/session without Composer

Snicco Session: A custom session implementation for environments where $_SESSION can't be used

Table of contents

1. Motivation
2. Installation
3. Usage
   1. Configuration
   2. Creating a serializer
   3. Drivers
   4. Creating the session manager
   5. Starting a session
   6. The immutable session
   7. The mutable session
   8. Accessing nested data
   9. Flash messages / Old input
   10. Encrypting session data
   11. Saving a session
   12. Setting the session cookie
   13. Managing sessions based on user id
   14. Garbage collection
4. Contributing
5. Issues and PR's
6. Security

Motivation

While PHP's native $_SESSION is fine for most use cases there are certain environments where it's not ideal. Two of them being distributed WordPress code or PSR7/PSR15 applications.

The Session component of the Snicco project is a completely standalone library with zero dependencies on any framework.

Features:

• Automatically handles invalidation, rotation and idle-timeouts.
• Non-blocking.
• Tracks if sessions are dirty and only updates if needed (without affected timeouts).
• Only accepts server-side generated session IDs.
• Supports many storage backends, all in their separate composer packages.

• Uses paragonie's split token approach to protect against timing based side-channel attacks.

• Secure by design, it's not possible to hijack session ids by compromising the storage backend (assuming read-only access)
• PSR-7/15 compatible. No hidden dependencies on PHP super globals.
• Differentiation between mutable and immutable session objects.
• Choose between json_encoding your session data or serializing it. Or provide your own normalizer.
• Supports encrypting and decrypting session data (through an interface, don't panic).
• Advanced session management based on user ids.
• Support for flash messages and old input.
• 100% test coverage and 100% psalm type-coverage.

Installation

Usage

Creating a session configuration

Creating a serializer

This package comes with two inbuilt serializers:

1. The JsonSerializer, which assumes that all your session content is JsonSerializableor equivalent.
2. The PHPSerializer, which will use serialize and unserialize.

If these don't work you, simply implement the Serializer interface.

Creating a session driver

The SessionDriver is an interface that abstracts away the concrete storage backend for the session data.

Currently, the following drivers are available:

• InMemoryDriver, for usage during testing.
• EncryptedDriver, takes another SessionDriver as an argument and encrypts/decrypts its data.

• Psr16Driver, allows you to use any PSR-16 cache. You can use this driver by using the snicco/session-psr16-bridge.

• WPDBDriver, you can use snicco/session-wp-bridge to store sessions using the WordPress database.
• WP_Object_Cache you can use snicco/session-wp-bridge to store sessions using the WordPress object cache.

• Custom, if none of these drivers work for you (and there is no PSR-16 adapter) you can use snicco/session-testing to test a custom implementation of yours against the interface.

Creating a session manager

The SessionManager is responsible for creating and persisting Session objects.

Starting a session

The SessionManager uses an instance of CookiePool to start a session.

You can instantiate this object either from the $_COOKIE superglobal or any plain array.

Calling SessionManger::start() will handle:

1. Rejecting the session id and generating a new, empty session, if the provided id can't be found in the driver (or is absent).
2. Rotating the session id based on your configuration.
3. Rotating and clearing the session if the session is idle based on your configuration.

Calling SessionManager::start() will return an instance of Session. MutableSession interface and the ImmutableSession interface.

This allows you to clearly separate the different concerns of reading and writing to the session.

In your code you should either depend on MutableSession or ImmutableSession.

The Session interface is only needed to persist the session with the session manager.

The immutable session

The ImmutableSession only has methods that return data. There is no way to modify the session.

The mutable session

The Mutable only has methods that modify data. There is no way to read the session data.

Accessing nested data

Nested data can be accessed using "dots".

Flash messages / Old input

Flashing data to the session means storing it only until the session is saved twice.

The most common use case for this is to display toast notifications after a POST request.

Old input works very similar. The most common use case is to display submitted form data on failure to validate the form.

Encrypting session data

If you are storing sensitive data in your session you can use the EncryptedDriver.

This driver will wrap another (inner) session driver and encrypt/decrypt your data before passing it to your application code.

To function, the EncryptedDriver needs an instance of SessionEncryptor, which is a dead-simple interface with no implementation.

Here is how you would use defuse/php-encryption to encrypt your sessions.

Saving a session

Session is a value object. Changes in the session are only persisted when the session manager saves it.

Once a Session is saved it is locked. Calling any state changing methods on a locked session will throw a SessionIsLocked exception.

Calling save on an unmodified session will only update the last activity of the session using SessionDriver::touch() .

This eliminates a lot a race-conditions that might happen with overlapping GET/POST requests that read and write a session.

Setting the session cookie

Setting cookies is out of scope for this library (because we don't know how you handle HTTP concerns in your application).

Instead, the session manager provides a method to retrieve a SessionCookie value object from a session.

An example on how to use the SessionCookie class to set the session cookie using setcookie. You can do something similar if you are using PSR-7 requests.

Managing session based on user id

It's not a requirement to store user ids in your session.

However, if you choose so, this package provides some nice tools to manage sessions based on user ids.

The SessionDriver interface.

Not all drivers support this interface tho.

Garbage collection

You should call SessionManager::gc() on every request where you use sessions.

Contributing

This repository is a read-only split of the development repo of the Snicco project.

This is how you can contribute.

Reporting issues and sending pull requests

Please report issues in the Snicco monorepo.

Security

If you discover a security vulnerability, please follow our disclosure procedure.