rancoud/session

Session package

Session Package

, _(*1)

Session., _(*2)

Installation

composer require rancoud/session

Informations

By default session is in read only (option read_and_close = 1).
You can specify it using Session::setReadWrite() or Session::setReadOnly(), _(*3)

Session::start() is not needed, but: * Session will automatically start in read only when using get, has, hasKeyAndValue, getAll * Session will automatically start in write mode when using set, remove, getAndRemove, keepFlash, gc, regenerate, _(*4)

How to use it?

Set and get value from $_SESSION, _(*5)

Session::set('key', 'value');
$value = Session::get('key');

Use custom options, _(*6)

// first way
Session::setOption('name', 'custom_session_name');

// second way
Session::start(['cookie_lifetime' => 1440]);

Session::set('key', 'value');
$value = Session::get('key');

With encryption on default php session, _(*7)

Session::useDefaultEncryptionDriver('keyForEncryption');
Session::set('key', 'value');
$value = Session::get('key');

With File driver, _(*8)

Session::useFileDriver();
Session::set('key', 'value');
$value = Session::get('key');

With Database driver (you have to install rancoud/database), _(*9)

$conf = new \Rancoud\Database\Configurator([
    'engine'   => 'mysql',
    'host'     => '127.0.0.1',
    'user'     => 'root',
    'password' => '',
    'database' => 'test_database'
]);
$db = new \Rancoud\Database\Database($conf);

// for using a current connection
Session::useCurrentDatabaseDriver($db);

// for creating a new connection
//Session::useNewDatabaseDriver($conf);

Session::set('key', 'value');
$value = Session::get('key');

With Redis driver (you have to install predis/predis), _(*10)

$params = [
    'scheme' => 'tcp',
    'host'   => '127.0.0.1',
    'port'   => 6379,
];
$redis = new Predis\Client($params);

// for using a current connection
Session::useCurrentRedisDriver($redis);

// for creating a new connection
//Session::useNewRedisDriver($params);

Session::set('key', 'value');
$value = Session::get('key');

With your own driver implementing SessionHandlerInterface and/or SessionUpdateTimestampHandlerInterface, _(*11)

$driver = new MyCustomDriver();
Session::useCustomDriver($driver);
Session::set('key', 'value');
$value = Session::get('key');

Session

Static General Commands

• start([options: array = []]): void
• regenerate(): bool
• destroy(): bool
• commit(): void
• rollback(): bool
• unsaved(): bool
• hasStarted(): bool
• getId(): string
• setId(id: string): string
• gc(): void
• setReadOnly(): void
• setReadWrite(): void
• isReadOnly(): bool

Static Variables $_SESSION access

• set(key: string, value: mixed): void
• get(key: string): mixed
• getAll(): array
• getAndRemove(key: string): mixed
• has(key: string): bool
• hasKeyAndValue(key: string, value: mixed): bool
• remove(key: string): void

Static Variables flash access

Flash data are store in a separate variable.
They will dissapear at the end of the script execution or after commit() unsaved().
You can use keepFlash for saving it in $_SESSION.
When flash data is restore, it will be delete in $_SESSION., _(*12)

• setFlash(key: string, value: mixed): void
• getFlash(key: string): mixed
• getAllFlash(): array
• hasFlash(key: string): bool
• hasFlashKeyAndValue(key: string, value: mixed): bool
• keepFlash([keys: array = []]): void

Static Options

• setOption(key: string, value): void
• setOptions(options: array): void
• getOption(key: string): mixed

Static Driver

• getDriver(): \SessionHandlerInterface

Static PHP Session Default Driver

• useDefaultDriver(): void
• useDefaultEncryptionDriver(key: string, [method: string|null = null]): void
• setLengthSessionID(length: int): void
• getLengthSessionID(): int

Static File Driver

• useFileDriver(): void
• useFileEncryptionDriver(key: string, [method: string|null = null]): void
• setPrefixForFile(prefix: string): void
• setLengthSessionID(length: int): void
• getLengthSessionID(): int

Static Database Driver

• useNewDatabaseDriver(configuration: \Rancoud\Database\Configurator|array): void
• useCurrentDatabaseDriver(databaseInstance: \Rancoud\Database\Database): void
• useNewDatabaseEncryptionDriver(configuration: \Rancoud\Database\Configurator|array, key: string, [method: string = null]): void
• useCurrentDatabaseEncryptionDriver(databaseInstance: \Rancoud\Database\Database, key: string, [method: string = null]): void
• setUserIdForDatabase(userId: int): void
• setLengthSessionID(length: int): void
• getLengthSessionID(): int

Static Redis Driver

• useNewRedisDriver(configuration: array|string): void
• useCurrentRedisDriver(redisInstance: \Predis\Client): void
• useNewRedisEncryptionDriver(configuration: array|string, key: string, [method: string = null]): void
• useCurrentRedisEncryptionDriver(redisInstance: \Predis\Client, key: string, [method: string = null]): void
• setLengthSessionID(length: int): void
• getLengthSessionID(): int

Static Custom Driver

• useCustomDriver(customDriver: \SessionHandlerInterface): void

Session options

List of session options you can change:
* save_path * name * save_handler * auto_start * gc_probability * gc_divisor * gc_maxlifetime * serialize_handler * cookie_lifetime * cookie_path * cookie_domain * cookie_secure * cookie_httponly * cookie_samesite * use_strict_mode * use_cookies * use_only_cookies * referer_check * cache_limiter * cache_expire * use_trans_sid * trans_sid_tags * trans_sid_hosts * sid_length * sid_bits_per_character * upload_progress.enabled * upload_progress.cleanup * upload_progress.prefix * upload_progress.name * upload_progress.freq * upload_progress.min_freq * lazy_write * read_and_close, _(*13)

Driver Informations

Default

Use SessionHandler, _(*14)

File

Extends SessionHandler, _(*15)

Database

You need to install, _(*16)

composer require rancoud/database

CREATE TABLE IF NOT EXISTS `sessions` (
  `id` varchar(128) NOT NULL,
  `id_user` int(10) unsigned DEFAULT NULL,
  `last_access` datetime NOT NULL,
  `content` text NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Redis

You need to install, _(*17)

composer require predis/predis

How to Dev

docker compose build && docker compose run lib composer ci for launching tests, _(*18)