koded/session

A session library with custom handlers and php.ini support

1.1.0 2019-12-10 22:19 UTC

Requires

• php: ~7.3
• ext-json: *
• koded/cache-simple: ~2
• koded/http: ~1
• psr/http-server-middleware: ~1

Requires (Dev)

• phpunit/phpunit: ~7
• scrutinizer/ocular: ^1.6

Suggests

• ext-memcached: *
• ext-redis: *

BSD-3-Clause

• Mihail Binev

• redis
• memcached
• session
• session-handler

README

The library relies on the php.ini settings. Every session ini directive can be reset with the Koded\Session\SessionConfiguration object.

Refer to php.ini session directives: http://php.net/manual/en/session.security.ini.php

Usage

The session is started automatically by using one of the 2 methods:

app configuration

[
    'session' => [
        // your ini "session." overwrites, without "session." prefix
    ]
]

or using a SessionMiddleware

include this middleware class in your middleware stack

// your middleware stack
$middleware = [
    SessionMiddleware::class
];

Session class and function

session()->get('key');
session()->set('key', 'value');
// etc.

The session class can be instantiated and used, but the function session() is recommended instead an instance of Session class.

Handlers Configuration

The bare minimum is to define the handler you want to use for the session:

// in your configuration file

return [
    'session' => [
        'save_handler' => 'redis | memcache'
    ]
]

If you do not choose one of the Redis or Memcached, it defaults to files handler which is the PHP's default session mechanism.

However, the files handler might not be desirable if your application runs in Docker, Kubernetes, distributed environment, etc.

The best choice for PHP sessions is Redis in almost all situations.

WARNING: Memcached may drop the session data, because it's nature. Use it with caution!

Redis handler

[
    'session' => [
        'save_handler' => 'redis'
        
        // OPTIONAL, these are the defaults
        'host' => 'localhost',
        'port' => 6379,
        'timeout' => 0.0,
        'retry' => 0,
        'db' => 0,
        
        'prefix' => 'sess:',
        'serializer' => 'php', // or "json"
        'binary' => false,     // TRUE for igbinary
    ]
]

A typical Redis settings:

• 1 server
• application + redis on the same machine
• Redis (127.0.0.1:6379)
• no auth (Redis is not available from outside)

[
    'session' => [
        'save_handler' => 'redis',
        'name'         => 'session-name',
        'prefix'       => 'sess:',

        // isolate the session data in other db
        'db'           => 1
    ]
]

To support huge volumes you need a good sysadmin skills and wast knowledge to set the Redis server(s).

Memcached handler

[
    'session' => [
        'save_handler' => 'memcached',
        
        // OPTIONAL: defaults to ['127.0.0.1', 11211]
        // If you have multiple memcached servers
        'servers' => [
            ['127.0.0.1', 11211],
            ['127.0.0.1', 11212],
            ['127.0.0.2']
            ...
        ],
        
        // OPTIONAL: the options are not mandatory
        'options' => [
            ...
        ]
    ]
]

A typical Memcached settings:

• 1 server
• application + memcached on the same machine
• Memcached (127.0.0.1:11211)

[
    'session' => [
        'save_handler' => 'memcached',
        'name'         => 'session-name',
        'prefix'       => 'sess.'
    ]
]

To support huge amount of users you need a decent amounts of RAM on your servers. But Memcached is a master technology for this, so you should be fine.

Files handler

This one is not recommended for any serious business. It's fine only for small projects.

All session directives are copied from php.ini.

[
    'session' => [
        // OPTIONAL: defaults to "session_save_path()"
        // the path where to store the session data
        'save_path' => '/var/www/sessions',
        'serialize_handler' => 'php'
    ]
]

A typical native PHP session settings:

[
    'session' => [
        // really nothing,
        // skip this section in your configuration
    ]
]

You cannot use this handler if you've scaled your application, because the session data will most likely be handled randomly on a different instance for every HTTP request.