NOTE: For Version 3 of the AWS SDK for PHP, please see the V3 User Guide and V3 API Reference.

# Class SessionHandler

Provides an interface for using Amazon DynamoDB as a session store by hooking into PHP's session handler hooks. Once registered, You may use the native `$_SESSION` superglobal and session functions, and the sessions will be stored automatically in DynamoDB. DynamoDB is a great session storage solution due to its speed, scalability, and fault tolerance.

For maximum performance, we recommend that you keep the size of your sessions small. Items greater than 1KB require more throughput in DynamoDB. Also, in this version of the session handler, session locking is turned off by default since it can drive up latencies and costs under high traffic and poor session management, especially when using ajax. Only turn it on if you need it.

By far, the most expensive operation is garbage collection. Therefore, we encourage you to carefully consider your session garbage collection strategy. We recommend that you change the `session.gc_probability` ini setting to 0 so that garbage collection is not triggered randomly. You should consider using a cron job or similar scheduling technique for triggering garbage collection at appropriate times.

  Aws\DynamoDb\Session\SessionHandler implements Aws\DynamoDb\Session\SessionHandlerInterface

Namespace: Aws\DynamoDb\Session
Located at Aws/DynamoDb/Session/SessionHandler.php

## Methods summary

- `public static` `factory ( array $config = array() )`

  Factory method to create a new DynamoDB Session Handler

- `public` `__construct ( Aws\DynamoDb\DynamoDbClient $client, Aws\DynamoDb\Session\LockingStrategy\LockingStrategyInterface $strategy, Aws\DynamoDb\Session\SessionHandlerConfig $config )`

  Constructs a new DynamoDB Session Handler

- `public` `__destruct ( )`

  Destruct the session handler and make sure the session gets written

- `public` `register ( )`

  Register the DynamoDB session handler.

- `public` `isSessionOpen ( )`

  Checks if the session is open and writable

- `public` `isSessionWritten ( )`

  Checks if the session has been written

- `public` `createSessionsTable ( int $readCapacityUnits, int $writeCapacityUnits )`

  Creates a table in DynamoDB for session storage according to provided configuration options.

- `public` `open ( string $savePath, string $sessionName )`

  Open a session for writing. Triggered by session_start()

- `public` `close ( )`

  Close a session from writing

- `public` `read ( string $id )`

  Read a session stored in DynamoDB

- `public` `write ( string $id, string $data )`

  Write a session to DynamoDB

- `public` `destroy ( string $id )`

  Delete a session stored in DynamoDB

- `public` `gc ( int $maxLifetime )`

  Triggers garbage collection on expired sessions

- `public` `garbageCollect ( )`

  Performs garbage collection on the sessions stored in the DynamoDB table

- `protected` `formatId ( string $id )`

  Prepend the session ID with the session name

## Methods detail

# `public static `Aws\DynamoDb\Session\SessionHandler``
`factory( array $config = array() )`

Factory method to create a new DynamoDB Session Handler

The configuration array accepts the following array keys and values:

- locking_strategy: Locking strategy fused for doing session locking. Default: null
- dynamodb_client: DynamoDbClient object used for performing DynamoDB operations
- table_name: Name of the DynamoDB table in which to store the sessions. Default: "sessions"
- hash_key: Name of the hash key in the DynamoDB sessions table. Default: "id"
- session_lifetime: Lifetime of an inactive session before it should be garbage collected.
- consistent_read: Whether or not to use DynamoDB consistent reads for `GetItem`. Default: true
- automatic_gc: Whether or not to use PHP's session auto garbage collection triggers.
- gc_batch_size: Batch size used for removing expired sessions during garbage collection. Default: 25
- gc_operation_delay: Delay between service operations during garbage collection
- max_lock_wait_time: Maximum time (in seconds) to wait to acquire a lock before giving up
- min_lock_retry_microtime: Minimum time (in microseconds) to wait between attempts to acquire a lock
- max_lock_retry_microtime: Maximum time (in microseconds) to wait between attempts to acquire a lock

#### Parameters

$config
  `array`
  $config Configuration options

#### Returns

``Aws\DynamoDb\Session\SessionHandler``
# `public`
`__construct( `Aws\DynamoDb\DynamoDbClient` $client, `Aws\DynamoDb\Session\LockingStrategy\LockingStrategyInterface` $strategy, `Aws\DynamoDb\Session\SessionHandlerConfig` $config )`

Constructs a new DynamoDB Session Handler

#### Parameters

$client
  ``Aws\DynamoDb\DynamoDbClient``
  $client Client for doing DynamoDB operations
$strategy
  ``Aws\DynamoDb\Session\LockingStrategy\LockingStrategyInterface``
  $strategy Locking strategy for performing session locking logic
$config
  ``Aws\DynamoDb\Session\SessionHandlerConfig``
  $config Configuration options for the session handler

# `public`
`__destruct( )`

Destruct the session handler and make sure the session gets written

NOTE: It is usually better practice to call `session_write_close()` manually in your application as soon as session modifications are complete. This is especially true if session locking is enabled.

#### Link

http://php.net/manual/en/function.session-set-save-handler.php#refsect1-function.session-set-save-handler-notes
# `public boolean`
`register( )`

Register the DynamoDB session handler.

Uses the PHP-provided method to register this class as a session handler.

#### Returns

`boolean`
Whether or not the handler was registered
# `public boolean`
`isSessionOpen( )`

Checks if the session is open and writable

#### Returns

`boolean`
Whether or not the session is open for writing
# `public boolean`
`isSessionWritten( )`

Checks if the session has been written

#### Returns

`boolean`
Whether or not the session has been written
# `public array`
`createSessionsTable( integer $readCapacityUnits, integer $writeCapacityUnits )`

Creates a table in DynamoDB for session storage according to provided configuration options.

Note: This is a one-time operation. It may be better to do this via the AWS management console ahead of time.

#### Parameters

$readCapacityUnits
  `integer`
  $readCapacityUnits RCUs for table read throughput
$writeCapacityUnits
  `integer`
  $writeCapacityUnits WCUs table write throughput

#### Returns

`array`
The command result
# `public boolean`
`open( string $savePath, string $sessionName )`

Open a session for writing. Triggered by session_start()

Part of the standard PHP session handler interface

#### Parameters

$savePath
  `string`
  $savePath The session save path
$sessionName
  `string`
  $sessionName The session name

#### Returns

`boolean`
Whether or not the operation succeeded
# `public boolean`
`close( )`

Close a session from writing

Part of the standard PHP session handler interface

#### Returns

`boolean`
Success
# `public string`
`read( string $id )`

Read a session stored in DynamoDB

Part of the standard PHP session handler interface

#### Parameters

$id
  `string`
  $id The session ID

#### Returns

`string`
The session data
# `public boolean`
`write( string $id, string $data )`

Write a session to DynamoDB

Part of the standard PHP session handler interface

#### Parameters

$id
  `string`
  $id The session ID
$data
  `string`
  $data The serialized session data to write

#### Returns

`boolean`
Whether or not the operation succeeded
# `public boolean`
`destroy( string $id )`

Delete a session stored in DynamoDB

Part of the standard PHP session handler interface

#### Parameters

$id
  `string`
  $id The session ID

#### Returns

`boolean`
Whether or not the operation succeeded
# `public boolean`
`gc( integer $maxLifetime )`

Triggers garbage collection on expired sessions

Part of the standard PHP session handler interface

#### Parameters

$maxLifetime
  `integer`
  $maxLifetime The value of `session.gc_maxlifetime`. Ignored

#### Returns

`boolean`
# `public`
`garbageCollect( )`

Performs garbage collection on the sessions stored in the DynamoDB table

If triggering garbage collection manually, use this method. If your garbage collection is triggered automatically by php (not recommended), then use the `gc` method.

# `protected string`
`formatId( string $id )`

Prepend the session ID with the session name

#### Parameters

$id
  `string`
  $id The session ID

#### Returns

`string`
Prepared session ID

### Magic methods summary

## Properties summary

`protected `Aws\DynamoDb\DynamoDbClient`` | $client | # The DynamoDB client
`protected `Aws\DynamoDb\Session\LockingStrategy\LockingStrategyInterface`` | $lockingStrategy | # The locking strategy
`protected `Aws\DynamoDb\Session\SessionHandlerConfig`` | $config | # The config for the handler and locking strategy
`protected string` | $savePath | # The session save path
`protected string` | $sessionName | # The session name
`protected string` | $dataRead | # Stores the serialized data that was read for tracking changes
`protected string` | $openSessionId | # Keeps track of the open session's ID
`protected boolean` | $sessionWritten | # Keeps track of whether the session has been written