Session

The session contains all data related to a challenge and visitor in order to serve a puzzle and validate it.

Session Data

The following data is stored in a session:

• Widget identifier
• Challenge identifier
• Visitor's IP address
• List of icon identifiers used in the challenge
• Identifier of the correct icon
• Theme of the icon set used in the challenge
• Flag indicating whether the challenge was served to the visitor
• Flag indicating whether the challenge was successfully completed
• Unix timestamp indicating when the challenge will expire

Purging Sessions

When a challenge has been successfully validated or its session has expired, the data is automatically purged during the next server request. If needed, you can disable this auto-purging feature by setting the session.options.purging option to false. Keep in mind that deactivating this feature may lead to the accumulation of expired challenge data in your database table or server session, potentially affecting performance.

Storage

All session data will be stored in the configured storage device. By default, this storage device can either be a database or the server session, depending on your configuration. The driver compatible with your configured storage will be used automatically. You should only consider changing the value of the session.driver option if you intend to implement a custom driver, as described below.

Server Session

When using the provided session storage driver, the challenges are remembered only for the duration of the server session. The key at which the challenge sessions will be stored in the server session is named challenges.

When using the server session to store challenges, it is recommended to set the purging option (session.options.purging) to true to prevent the session from becoming cluttered with expired data.

Note

Please note that to use server session storage, you need to start a session using session_start();.

The server session driver uses the \IconCaptcha\Session\Drivers\KeyValueSession class to handle all related actions.

Database

When using any of the provided database drivers, the challenge sessions are stored in the iconcaptcha_challenges table by default (view schema). You can customize the name of this table by changing the session.options.table option. The data of a challenge is stored in the puzzle column as JSON data.

The database drivers use the \IconCaptcha\Session\Drivers\Database\PDOSession class to handle all related actions.

Custom Driver

If you wish to create your own driver to handle challenge sessions, ensure that your custom class extend the \IconCaptcha\Session\Session class and implements all required functions. The included drivers compatible with session and PDO storage can be viewed here.

Important

Depending on the storage driver you've configured, the implementation of this custom class will differ.

• If you are using database/PDO storage, your constructor should accept \IconCaptcha\Storage\Database\PDOStorageInterface as the first parameter.
• If you are using server session storage, your constructor should accept \IconCaptcha\Storage\KeyValueStorageInterface as the first parameter.
• In case you've created your own storage driver, ensure the first parameter receives the correct type according to your implementation.

Note that database/PDO storage drivers are not compatible with KeyValue storage drivers (like sessions), and vice versa. If your class does not accept the correct storage device, your implementation will throw exceptions during initialization.

Your custom class constructor should resemble the snippet below. It needs to accept the correct storage driver, an options array, the visitor's IP address, and the widget and challenge identifiers.

public function __construct(PDOStorageInterface|KeyValueStorageInterface|mixed $storage, array $options, string $ipAddress, string $widgetId, string $challengeId = null)

To enable your custom driver, update the session.driver configuration option to use your class.

'session' => [
    'driver' => \Path\To\YourSession::class,
    // ...
],