WordPress Native PHP Sessions

About WordPress Native PHP Sessions

This plugin allows you to use PHP sessions in WordPress, which can be useful for certain plugins or themes. It implements PHP's native session handlers and stores the sessions in the WordPress database. You can configure the session lifetime and there are also CLI commands available for managing the sessions. If you encounter any issues, there are troubleshooting steps provided as well.

Frequently asked questions

What does the WordPress Native PHP Sessions plugin do?

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.

How can I override the session lifetime in the WordPress Native PHP Sessions plugin?

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 plugin is loaded. For example, you can create a small Must-use plugin with the following code: function my_session_expiration_override() { return 60*60*4; // 4 hours } add_filter( 'pantheon_session_expiration', 'my_session_expiration_override' );

What CLI commands are available in the WordPress Native PHP Sessions plugin?

The following CLI commands are available in the plugin: wp pantheon session add-index - This command should be run if your installation of the plugin occurred before the addition of the primary ID key to the session table. wp pantheon session primary-key-finalize - 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 - 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.

Is the WordPress Native PHP Sessions plugin compatible with WordPress Multisite?

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

How can I troubleshoot errors related to the WordPress Native PHP Sessions plugin?

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 the WP Native PHP Sessions plugin is loading. To fix this, create a new file at wp-content/mu-plugins/000-loader.php and include the following code: 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 still allowing you to use the WordPress plugin updater to keep the plugin up-to-date.

Changelog

1.4.3 (November 13, 2023)

Fixed a PHP warning when running the pantheon session add-index command on a single site installation. [#285]

1.4.2 (November 8, 2023)

Fixed an issue with the pantheon session add-index PHP warning. [#276]
Fixed a syntax issue with the suggested WP CLI commands [#278]
Made wp pantheon session add-index, wp pantheon session primary-key-finalize, and wp pantheon session primary-key-revert fully multisite compatible. [#275]

1.4.1 (October 23, 2023)

Fixed an issue with the pantheon session add-index command not working properly on WP multisite [#270]
Made the notice added in 1.4.0 dismissable (stores in user meta) & hides for multisite (an update is coming to iterate through all sites on a network) [#271]

1.4.0 (October 17, 2023)

Adds new CLI command to add a Primary Column (id) to the pantheon_sessions table for users who do not have one. [#265]
Adds alert to dashboard for users who need to run the command.
8.3 compatibility and code quality updates
Updates Pantheon WP Coding Standards to 2.0 [#264]

1.3.6 (June 1, 2023)

Fixes PHP 8.2 deprecated dynamic property error [#251] (props @miguelaxcar)
Update CONTRIBUTING.md [#252].
Update informational Error message for the case of headers already sent [#249].
Add pantheon-wp-coding-standards [#247].

1.3.5 (April 7, 2023)

Bump yoast/phpunit-polyfills from 1.0.4 to 1.0.5 [#245].
Bump tested up to version

1.3.4 (February 7, 2023)

Add fallback for $session->get_data() [[#237(https://github.com/pantheon-systems/wp-native-php-sessions/pull/237)]] (reported on WordPress.org)
Update CODEOWNERS file [#239]
Fix GPL license in composer.json file [#236]
Bump grunt from 1.5.3 to 1.6.1 [#235]

1.3.3 (January 25, 2023)

Bump version in pantheon-sessions.php [#234].

1.3.2 (January 25, 2023)

PHP 8.2 compatibility [#232].
Bump dealerdirect/phpcodesniffer-composer-installer from 0.7.2 to 1.0.0 [#229].
Update images for lint and test-behat jobs [#228].

1.3.1 (December 5, 2022)

Document session lifetime handling [#224].
Make dependabot target develop branch [#226].
Ignore .wordpress-org directory [#223].

1.3.0 (November 28th, 2022)

Added CONTRIBUTING.MD and GitHub action to automate deployments to wp.org. [#219]

1.2.5 (October 28, 2022)

Added #[ReturnTypeWillChange] where required to silence deprecation warnings in PHP 8.1. [#216]

1.2.4 (September 14th, 2021)

Increases data blob size from 64k to 16M for new session tables; existing tables will need to manually modify the column if they want to apply this change [#193].

1.2.3 (April 9th, 2021)

Assigns the table name to a variable before using in query [#188].

1.2.2 (March 29th, 2021)

Includes an auto-incrementing id column for replication support [#187].

1.2.1 (September 17th, 2020)

Plugin textdomain needs to be the same as the WordPress.org slug [#169].

1.2.0 (May 18th, 2020)

Avoids using cookies for sessions when WP-CLI is executing [#154].

1.1.0 (April 23rd, 2020)

Avoids initializing PHP sessions when doing cron [#149].

1.0.0 (March 2nd, 2020)

Plugin is stable.

0.9.0 (October 14th, 2019)

Refactors session callback logic into Session_Handler abstraction, fixing PHP notice in PHP 7.3 [#135].

0.8.1 (August 19th, 2019)

Fixes handling of ‘X-Forwarded-For’ header in get_client_ip_server() [#126].

0.8.0 (August 13th, 2019)

Respects various HTTP_* sources for client IP address [#122].

0.7.0 (April 3rd, 2019)

Adds a safety check that restores $wpdb when it’s missing.

0.6.9 (May 15th, 2018)

Ensures _pantheon_session_destroy() uses a return value.

0.6.8 (May 4th, 2018)

Switches to E_USER_WARNING instead of E_WARNING when triggering errors.

0.6.7 (April 26th, 2018)

Disables plugin load when WP_INSTALLING, because session table creation breaks installation process.

0.6.6 (March 8th, 2018)

Restores session instantiation when WP-CLI is executing, because not doing so causes other problems.

0.6.5 (February 6th, 2018)

Disables session instantiation when defined( 'WP_CLI' ) && WP_CLI because sessions don’t work on CLI.

0.6.4 (October 10th, 2017)

Triggers PHP error when plugin fails to write session to database.

0.6.3 (September 29th, 2017)

Returns false when we entirely fail to generate a session.

0.6.2 (June 6th, 2017)

Syncs session user id when a user logs in and logs out.

0.6.1 (May 25th, 2017)

Bug fix: Prevents warning session_write_close() expects exactly 0 parameters, 1 given.

0.6.0 (November 23rd, 2016)

Bug fix: Prevents PHP fatal error in session_write_close() by running on WordPress’ shutdown action, before $wpdb destructs itself.
Bug fix: Stores the actual user id in the sessions table, instead of (bool) $user_id.

0.5

Compatibility with PHP 7.
Adds pantheon_session_expiration filter to modify session expiration value.

0.4

Adjustment to session_id() behavior for wider compatibility
Using superglobal for REQUEST_TIME as opposed to time()

0.3

Fixes issue related to WordPress plugin load order

0.1

Initial release