Sessions

Overview

Sessions are a way to preserve data across subsequent page loads. They are a fundamental element in a web application design. Sessions are a building block for functionality like logins and shopping carts.

Sessions must have a dedicated storage location and be available to the web application. WHMCS supports session storage for either file-backed and database-backed sessions. The most common choice is file sessions, but database sessions can be advantageous for some environments.

File Sessions

File sessions are the most common choice since it is the default for PHP environments. They require little to no configuration, either by a system administrator or a web application, in order for session utility to function immediately. File-backed sessions have historically been the first and best choice for single-instance web applications.

When you use file-backed sessions, web applications write a file to a configured directory for each unique visitor. If the server that hosts your WHMCS installation is shared with other applications or individuals, it is possible that those applications or individuals can read and write to that directory as well. Sharing this directory introduces a security risk since sessions may contain sensitive information. As well, it is very common for applications to implicitly trust the information within these files as if only it would have access to them. Consult with your system administrator, web server documentation, or server's control panel documentation for more guidance on the evaluation and mitigation of any risks for your environment.

Configuration

In WHMCS, using the default PHP file session storage doesn't require configuration.

Database Sessions

This section describes a feature available in version 7.7 and above.

Database sessions are also a common choice for PHP environments. A web application must provide integration code in order to store session data in a database.

Utilizing a system service, such as a database server, has the benefit of supporting multiple application instances, which may be an important part of a high-availability or scalable infrastructure design. Using database stored sessions mitigates the inherent risks of file-backed session permissions. Some web applications allow the configuration of a dedicated database just for session data. This may help reduce the impact in the event of a SQL injection attack.

Configuration

To utilize database session storage, place a simple configuration value in configuration.php.

$session_handling = 'database';

The same database that other configuration value itemize will store the session data.

Advanced Configuration

If you need, advanced configuration options are possible by specifying a more elaborate value for $session_handling.

Below is an example of the structure and key-and-value pairs for advanced configuration:

$session_handling = [
    'serviceProvider' => '\\WHMCS\\Session\\Database\\ServiceProvider',  //do not alter this line
        'database' => [
            'lifetime' => 24 * 60, //provide a session lifetime in minutes, default is 1440 (1 day)
            'connectionAlias' => 'sessionsDbConnection',  //provide internal handler name other than "default"
             'config' => [
                 'host' => 'my.host.local',   //provide hostname or IP of database server
                 'database' => 'db_name',     //provide name of database to use
                 'username' => 'db_user',     //provide username for authenticate at server
                 'password' => 'db_password', //provide password for authentication at server
            ],
            'table' => 'user_sessions', //provide name of table; see tblsessions in WHMCS for schema
            'logErrors' => false, //whether session SQL errors should be recorded to activity log when possible
    ],
];

WHMCS does not manage tables or schema outside the core database. If you provide an advanced configuration, you will need to ensure the named database has the appropriate target table and schema. A copy of the appropriate table schema is in WHMCS at resources/sql/install/tblsessions.schema.sql.