The DynamoDB Session Handler is a custom session handler for PHP that allows developers to use Amazon DynamoDB as a session store. Using DynamoDB for session storage alleviates issues that occur with session handling in a distributed web application by moving sessions off of the local file system and into a shared location. DynamoDB is fast, scalable, easy to setup, and handles replication of your data automatically.
The DynamoDB Session Handler uses the session_set_save_handler()
function
to hook DynamoDB operations into PHP's native session functions
to allow for a true drop in replacement. This includes support for features like
session locking and garbage collection which are a part of PHP's default
session handler.
For more information on the Amazon DynamoDB service, please visit the Amazon DynamoDB homepage.
The first step is to instantiate and register the session handler.
use Aws\DynamoDb\SessionHandler;
$sessionHandler = SessionHandler::fromClient($dynamoDb, [
'table_name' => 'sessions'
]);
$sessionHandler->register();
Before you can actually use the session handler, you need to create a table in which to store the sessions. This can be done ahead of time through the AWS Console for Amazon DynamoDB, or using the SDK.
Once the session handler is registered and the table exists, you can write to
and read from the session using the $_SESSION
superglobal, just like you
normally do with PHP's default session handler. The DynamoDB Session Handler
encapsulates and abstracts the interactions with Amazon DynamoDB and enables
you to simply use PHP's native session functions and interface.
// Start the session
session_start();
// Alter the session data
$_SESSION['user.name'] = 'jeremy';
$_SESSION['user.role'] = 'admin';
// Close the session (optional, but recommended)
session_write_close();
You may configure the behavior of the session handler using the following options. All options are optional, but you should make sure to understand what the defaults are.
table_name
'sessions'
.hash_key
'id'
.session_lifetime
ini_get('session.gc_maxlifetime')
.consistent_read
GetItem
operation. This defaults
to true
.locking
false
.batch_config
SessionHandler::garbageCollect()
.max_lock_wait_time
10
and is only used with session locking.min_lock_retry_microtime
10000
and is only used with session locking.max_lock_retry_microtime
50000
and is only used with session locking.To configure the Session Handler, you must specify the configuration options when you instantiate the handler. The following code is an example with all of the configuration options specified.
$sessionHandler = SessionHandler::fromClient($dynamoDb, [
'table_name' => 'sessions',
'hash_key' => 'id',
'session_lifetime' => 3600,
'consistent_read' => true,
'locking' => false,
'batch_config' => [],
'max_lock_wait_time' => 10,
'min_lock_retry_microtime' => 5000,
'max_lock_retry_microtime' => 50000,
]);
Aside from data storage and data transfer fees, the costs associated with using Amazon DynamoDB are calculated based on the provisioned throughput capacity of your table (see the Amazon DynamoDB pricing details). Throughput is measured in units of Write Capacity and Read Capacity. The Amazon DynamoDB homepage says:
A unit of read capacity represents one strongly consistent read per second (or two eventually consistent reads per second) for items as large as 4 KB. A unit of write capacity represents one write per second for items as large as 1 KB.
Ultimately, the throughput and the costs required for your sessions table is going to correlate with your expected traffic and session size. The following table explains the amount of read and write operations that are performed on your DynamoDB table for each of the session functions.
Read via session_start() |
|
Read via session_start()
(Using session locking) |
|
Write via session_write_close() |
|
Delete via session_destroy() |
|
Garbage Collection |
|
The DynamoDB Session Handler supports pessimistic session locking in order to mimic the behavior of PHP's default session handler. By default the DynamoDB Session Handler has this feature turned off since it can become a performance bottleneck and drive up costs, especially when an application accesses the session when using ajax requests or iframes. You should carefully consider whether or not your application requires session locking or not before enabling it.
To enable session locking, set the 'locking'
option to true
when you instantiate the SessionHandler
.
$sessionHandler = SessionHandler::fromClient($dynamoDb, [
'table_name' => 'sessions',
'locking' => true,
]);
The DynamoDB Session Handler supports session garbage collection by using a series of Scan
and BatchWriteItem
operations. Due to the nature of how the Scan
operation works and in order to find all of the expired sessions and
delete them, the garbage collection process can require a lot of provisioned throughput.
For this reason, we do not support automated garbage collection . A better practice is to schedule the garbage collection to occur during an off-peak time where a burst of consumed throughput will not disrupt the rest of the application. For example, you could have a nightly cron job trigger a script to run the garbage collection. This script would need to do something like the following:
$sessionHandler = SessionHandler::fromClient($dynamoDb, [
'table_name' => 'sessions',
'batch_config' => [
'batch_size' => 25,
'before' => function ($command) {
echo "About to delete a batch of expired sessions.\n";
}
]
]);
$sessionHandler->garbageCollect();
You can also use the 'before'
option within 'batch_config'
to introduce delays on the BatchWriteItem
operations that are performed by the garbage collection process. This will increase the amount of time it takes the
garbage collection to complete, but it can help you spread out the requests made by the session handler in order to
help you stay close to or within your provisioned throughput capacity during garbage collection.
$sessionHandler = SessionHandler::fromClient($dynamoDb, [
'table_name' => 'sessions',
'batch_config' => [
'before' => function ($command) {
$command['@http']['delay'] = 5000;
}
]
]);
$sessionHandler->garbageCollect();
'batch_config'
option to your advantage.To use the DynamoDB session handler, your configured credentials must have permission to use the DynamoDB table that you created in a previous step. The following IAM policy contains the minimum permissions that you need. To use this policy, replace the Resource value with the Amazon Resource Name (ARN) of the table that you created previously. For more information about creating and attaching IAM policies, see Managing IAM Policies in the AWS Identity and Access Management User Guide.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"dynamodb:GetItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:Scan",
"dynamodb:BatchWriteItem"
],
"Effect": "Allow",
"Resource": "arn:aws:dynamodb:<region>:<account-id>:table/<table-name>"
}
]
}