Skip to content

rancoud/Session

Repository files navigation

Session Package

Packagist PHP Version Support Packagist Version Packagist Downloads Composer dependencies Test workflow Codecov

Session.

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()

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

How to use it?

Set and get value from $_SESSION

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

Use custom options

// 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

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

With File driver

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

With Database driver (you have to install rancoud/database)

$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)

$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

$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.

  • 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

Driver Informations

Default

Use SessionHandler

File

Extends SessionHandler

Database

You need to install

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

composer require predis/predis

How to Dev

docker compose build && docker compose run lib composer ci for launching tests