<commit_before># CeSession
Alternative PHP session handler

## Who is this for?
While PHP supports session handling, the implementation is less than stellar.
Cesession provides an alternative with built-in helpers to use either an SQL
database, memcached or a NoSQL database.

Cesession offers a seamless interface with the well-known `$_SESSION`
superglobal, so any existing code should Just Work(tm).

An added advantage of using SQL based databases is that you can set up a
foreign key constraint between the current user and the current session, so
people get automatically logged out.

## Installation

### Composer (recommended)
`$ composer require monomelodies/cesession`

### Manual
1. Clone or download the repository;
2. Add the `Cesession` namespace to your autoloader for
   `/path/to/cesession/src`.
3. Create the relevant table (see scripts in `./info/sql`)

That's it!

## Setting up
To begin, _before_ any call to `session_start` create the `Cesession\Session`
object and register a _handler_. Currently Cesession ships with a `Pdo` handler
that does exactly what its name implies (store the session data in a
PDO-compatible database, e.g. PostgreSQL or MySQL):

```php
<?php

use Cesession\Session;
use Cesession\Handler;

$session = new Session('my-session-name');
$db = new PDO('dsn', 'user', 'pass');
$handler = new Handler\Pdo($db);
$session->registerHandler($handler);
session_start();
```

## Registering a PDO handler
To register a handler, simply call the `registerHandler` method on the
`$session` object and pass in a handler object. Each handler object _must_
implement the `Cesession\Handler` interface. This is done both for type hinting
and to ensure the required methods exist. The `Handler` interface is a subset
of PHP's built-in `SessionHandlerInterface`.

The optional second argument to `registerHandler` is a probability percentage
between 0 and 100. This signifies the probability that for supporting calls, the
action is _also_ delegated to the next handler (if defined).

E.g., say you want to store sessions in Memcached (fast!) but persist to a PDO
backend every ten calls on average:

```php
<?php

$session->registerHandler(new Handler\Memcached($memcached), 10);
$session->registerHandler(new Handler\Pdo($db));
```

> Note: currently only the Pdo handler is supported out of the box.
<commit_msg>update docs<commit_after># CeSession
Alternative PHP session handler

## Who is this for?
While PHP supports session handling, the implementation is less than stellar.
Cesession provides an alternative with built-in helpers to use either an SQL
database, memcached or a NoSQL database.

Cesession offers a seamless interface with the well-known `$_SESSION`
superglobal, so any existing code should Just Work(tm).

An added advantage of using SQL based databases is that you can set up a
foreign key constraint between the current user and the current session, so
people get automatically logged out.

## Installation

### Composer (recommended)
`$ composer require monomelodies/cesession`

### Manual
1. Clone or download the repository;
2. Add the `Cesession` namespace to your autoloader for
   `/path/to/cesession/src`.
3. Create the relevant table (see scripts in `./info/sql`)

That's it!

## Setting up
To begin, _before_ any call to `session_start` create the `Cesession\Session`
object and register a _handler_. Currently Cesession ships with a `Pdo` handler
that does exactly what its name implies (store the session data in a
PDO-compatible database, e.g. PostgreSQL or MySQL):

```php
<?php

use Cesession\Session;
use Cesession\Handler;

$session = new Session('my-session-name');
$db = new PDO('dsn', 'user', 'pass');
$handler = new Handler\Pdo($db);
$session->registerHandler($handler);
session_start();
```

## Registering a PDO handler
To register a handler, simply call the `registerHandler` method on the
`$session` object and pass in a handler object. Each handler object _must_
implement the `Cesession\Handler` interface. This is done both for type hinting
and to ensure the required methods exist. The `Handler` interface is a subset
of PHP's built-in `SessionHandlerInterface`.

The optional second argument to `registerHandler` is a probability percentage
between 0 and 100. This signifies the probability that for supporting calls, the
action is _also_ delegated to the next handler (if defined).

E.g., say you want to store sessions in Memcached (fast!) but persist to a PDO
backend every ten calls on average:

```php
<?php

$session->registerHandler(new Handler\Memcached($memcached), 10);
$session->registerHandler(new Handler\Pdo($db));
```

> Note: currently only the Pdo and Memcached handlers are supported out of the
> box.

## Forcing an operation on all handlers
Sometimes you'll want to ensure an operation gets persisted to all handlers, for
instance when a user's authentication state changes. Use the `force` method for
this. The first argument is the session method you need to call, the second an
array of arguments to pass:

```php
<?php

// Force emptying of the current session on all handlers:
$session->force('write', [session_id(), []]);
```

Internally this calls the method on all defined handlers with a probability of
100%. Note that using `force` only makes sense if you have multiple handlers
defined with varying probabilities.

{'fraction_non_alphanumeric': 0.08109630185845691, 'fraction_numerical': 0.003942181340341655, 'mean_word_length': 4.973094170403588, 'pattern_counts': {'":': 0, '<': 8, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5571593', 'n_tokens_mistral': 1474, 'n_tokens_neox': 1411, 'n_words': 721}