Native PHP Sessions

Description

WordPress core does not use PHP sessions, but sometimes they are required by your use-case, a plugin or theme.

This plugin implements PHP’s native session handlers, backed by the WordPress database. This allows plugins, themes, and custom code to safely use PHP $_SESSIONs in a distributed environment where PHP’s default tempfile storage just won’t work.

Note that primary development is on GitHub if you would like to contribute:

https://github.com/pantheon-systems/wp-native-php-sessions

Configuration

By default the session lifetime is set to 0, which is until the browser is closed.

To override this use the pantheon_session_expiration filter before the Native PHP Sessions plugin is loaded. For example a small Must-use plugin (a.k.a. mu-plugin) could contain:

<?php
function my_session_expiration_override() {
    return 60*60*4; // 4 hours
}
add_filter( 'pantheon_session_expiration', 'my_session_expiration_override' );<h3>CLI Commands</h3>

wp pantheon session add-index

Added in 1.4.0. This command should be run if your installation of the plugin occurred before the addition of the primary ID key to the session table in version 1.2.2. You will be automatically notified when you visit any admin page if this is the case. If there’s no message, your version is good to go. Note that this command is non-destructive, a new table will be created and the existing one preserved in a backup state until you have verified that the upgrade is functioning as expected.

wp pantheon session primary-key-finalize

Added in 1.4.0. If you have run the add-index command and have verified that the new table is functioning correctly, running the primary-key-finalize command will perform a database cleanup and remove the backup table.

wp pantheon session primary-key-revert

Added in 1.4.0. If you have run the add-index command and something unexpected has occurred, just run the primary-key-revert command and the backup table will immediately be returned to being the active table.

WordPress Multisite

As of 1.4.2 the add-index, primary-key-add and primary-key-revert commands are fully multisite compatible.

Contributing

See CONTRIBUTING.md for information on contributing.

Troubleshooting

If you see an error like “Fatal error: session_start(): Failed to initialize storage module:” or “Warning: ini_set(): A session is active.”, then you likely have a plugin that is starting a session before WP Native PHP Sessions is loading.

To fix, create a new file at wp-content/mu-plugins/000-loader.php and include the following:

<?php
if (file_exists(WP_PLUGIN_DIR . '/wp-native-php-sessions/pantheon-sessions.php')) {
    require_once WP_PLUGIN_DIR . '/wp-native-php-sessions/pantheon-sessions.php';
}

This mu-plugin will load WP Native PHP Sessions before all other plugins, while letting you still use the WordPress plugin updater to keep the plugin up-to-date.

Technical details