Sessions
Contents
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
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.
Using a Remote Database
If you wish to use a remote database for the management of sessions, the tblsessions table will need to be created manually. The first step for this would be to upload the tblsessions.schema.sql file to the remote server, which can be located within WHMCS at resources/sql/install/tblsessions.schema.sql, then import the contents of that file to your database via command line like this:
mysql -u root [database_name] < /path/to/tblsessions.schema.sql
This commands assumes root access to the server.
Troubleshooting
Sessions are not being removed automatically
If you notice that the system is not removing sessions from the location in your session configuration, either the location of the session.save_path PHP setting or the database table when using database sessions is likely using non-standard values for the PHP session.gc_probability and session.gc_divisor settings. Most commonly, this is 0 for one or both of them.
These settings are part of a probability-based calculation and have values of 1 and 1000 respectively, meaning that there is a 1% chance of garbage collection being executed per request. We recommend setting these settings to the default values.