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. 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 #

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.

Using 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 use database session storage, set the $session_handling value in the configuration.php file:

$session_handling = 'database';

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

Advanced Configuration #

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

For example, advanced configurations might use the following structure and key-and-value pairs:

$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 an internal handler name other than "default"
        'config' => [
            'host' => 'my.host.local', // Provide the hostname or IP of the database server
            'database' => 'db_name', // Provide the name of the database to use
            'username' => 'db_user', // Provide the username for authentication at the server
            'password' => 'db_password', // Provide the password for authentication at the server
        ],
        'table' => 'user_sessions', // Provide the name of the table; see tblsessions in WHMCS for schema
        'logErrors' => false, // Whether session SQL errors should be recorded to the 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 that the named database has the appropriate target table and schema. You can find a copy of the appropriate table schema is in the resources/sql/install/tblsessions.schema.sql file.

Using a Remote Database #

If you wish to use a remote database for the management of sessions, you will need to create the tblsessions table manually. First, upload the tblsessions.schema.sql file to the remote server at resources/sql/install/tblsessions.schema.sql. Then, import the contents of that file to your database by running the following command:

mysql -u root [database_name] < /path/to/tblsessions.schema.sql

This commands requires root access to the server.

Last modified: October 30, 2024