Use native PHP sessions and stay horizontally scalable. Better living through superior technology.
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 $_SESSION
s 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
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 WordPress 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.
As of 1.4.2 the add-index
, primary-key-add
and primary-key-revert
commands are fully multisite compatible.
See CONTRIBUTING.md for information on contributing.
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 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.
/wp-content/plugins/
directoryThat’s it!
This implements the built-in PHP session handling functions, rather than introducing anything custom. That way you can use built-in language functions like the $_SESSION
superglobal and session_start()
in your code. Everything else will “just work”.
PHP’s fallback default functionality is to allow sessions to be stored in a temporary file. This is what most code that invokes sessions uses by default, and in simple use-cases it works, which is why so many plugins do it.
However, if you intend to scale your application, local tempfiles are a dangerous choice. They are not shared between different instances of the application, producing erratic behavior that can be impossible to debug. By storing them in the database the state of the sessions is shared across all application instances.
Please report security bugs found in the source code of the WP Native PHP Sessions plugin through the Patchstack Vulnerability Disclosure Program. The Patchstack team will assist you with verification, CVE assignment, and notify the developers of this plugin.
pantheon session add-index
command on a single site installation. [#285]pantheon session add-index
PHP warning. [#276]wp pantheon session add-index
, wp pantheon session primary-key-finalize
, and wp pantheon session primary-key-revert
fully multisite compatible. [#275]pantheon session add-index
command not working properly on WP multisite [#270]pantheon_sessions
table for users who do not have one. [#265]composer.json
file [#236].wordpress-org
directory [#223].#[ReturnTypeWillChange]
where required to silence deprecation warnings in PHP 8.1. [#216]id
column for replication support [#187].Session_Handler
abstraction, fixing PHP notice in PHP 7.3 [#135].get_client_ip_server()
[#126].HTTP_*
sources for client IP address [#122].$wpdb
when it’s missing._pantheon_session_destroy()
uses a return value.E_USER_WARNING
instead of E_WARNING
when triggering errors.WP_INSTALLING
, because session table creation breaks installation process.defined( 'WP_CLI' ) && WP_CLI
because sessions don’t work on CLI.session_write_close()
by running on WordPress’ shutdown
action, before $wpdb
destructs itself.(bool) $user_id
.pantheon_session_expiration
filter to modify session expiration value.session_id()
behavior for wider compatibilitytime()