WordPress and PHP Sessions
Learn more about the behaviors of WordPress and PHP sessions.Discuss in our Forum Discuss in Slack
This section provides information on WordPress and PHP sessions.
WordPress Core does not use sessions. All "user state" is managed via cookies. This is a Core design decision.
However, some plugins or themes will use
session_start() or PHP's
$_SESSION superglobal. You must use the Pantheon-maintained WordPress Native PHP Sessions plugin to use PHP Sessions on Pantheon.
This plugin will not solve all
$_SESSION based issues and errors due to implementation differences. If you use this plugin and still have issues, modify the code within your theme or plugin that calls
$_SESSION to remove this functionality or use an alternative.
Troubleshooting Session Errors
Before installing WordPress Native PHP Sessions, you might see the following error:
Warning: session_start(): user session functions not defined
Plugins with session-using code are relying on PHP's default session manager, which is temporary files on local disk. Pantheon does not support this because it will not work properly in our distributed environment.
Varnish or Caching Is Not Working When a Plugin or Theme That Uses
$_SESSIONS Is Enabled
Due to how caching and sessions work, sessions must be uncached to work correctly, and it is impossible to use cached content when there are sessions in place. It is best to use a cookie-based solution to avoid a performance hit from uncached session pages.
Evidence of this issue can be detected by inspecting the header. The session cookie is always set on every page load:
Set-Cookie: SESS1234XXXXXXXXXXXXXX path=/; domain=.example.pantheonsite.io; HttpOnly
The best way to determine which plugin or theme is preventing caching is to search your site's plugin and theme code for the
session_start() PHP function:
cd wp-content grep -rnw . -e 'session_start'
Alternatively, you can inspect the headers using
curl -sI example.com after each of the following steps, until you determine which component is breaking the cache:
Use your default theme (twentynineteen for example) and check for the cookie.
Disable the plugins one by one to see if a plugin is breaking the cache. Do not forget to clear the cache from the Pantheon dashboard every time that you disable a plugin. The first plugin disabled which makes the cache work again is most likely the culprit.
Note: If you have a local copy of your site, you can search it for plugins that uses
$_SESSIONS, and start turning them off first.
Remove (temporarily) the third-party must-use plugins and leave only the
WP Native PHP Sessionsto check if a third-party must-use plugin or drop-in plugin is breaking the cache. There should be no drop-ins in place.
Install WordPress Native PHP Sessions Plugin
Install the WordPress Native PHP Sessions plugin if
$_SESSIONs are necessary for your application:
Set the connection mode to SFTP for the Dev or Multidev environment via the Pantheon Dashboard or with Terminus:
terminus connection:set <site>.<env> sftp
Install and activate WordPress Native PHP Sessions from within the Dev or Multidev environment's WordPress Dashboard (
/wp-admin/plugin-install.php?tab=search&s=wp+native-php-sessions) or with Terminus:
terminus wp <site>.<env> -- plugin install wp-native-php-sessions --activate
Commit your changes via the Site Dashboard or with Terminus:
terminus env:commit --message "Adding php native sessions plugin" -- <site>.<env>
Merge your changes into Dev if you are working on a Multidev:
terminus multidev:merge-to-dev -- <site>.<multidev>
Deploy the plugin to the Test environment within the Site Dashboard or with Terminus:
terminus env:deploy <site>.test --sync-content --updatedb --note="Install WordPress Native PHP Sessions plugin"
Activate the plugin within the WordPress Dashboard on the Test environment (
/wp-admin/plugins.php) or with Terminus:
terminus wp <site>.test -- plugin activate wp-native-php-sessions
Deploy the plugin to the Live environment within the Site Dashboard or with Terminus:
terminus env:deploy <site>.live --note="Install WordPress Native PHP Sessions plugin"
Activate the plugin within the WordPress Dashboard on the Live environment (
/wp-admin/plugins.php) or with Terminus:
terminus wp <site>.live -- plugin activate wp-native-php-sessions
Refer to Fix WordPress PHP Session Problems on Pantheon with a Script for more information.
Sessions and Scalability
Starting a session for every user is an application anti-pattern. Serving pages to users with sessions cannot be done out of a cache, so creating a session for every visitor inherently makes your application unscalable.
Our plugin provides an admin screen to see how many sessions have been started. You can also examine the headers being sent by your website. If you start a new incognito window and see a
PHPSESS cookie being sent in response to a request for your site, you have some over-eager sessions code.
Command line users can use this quick snippet to test:
curl -Is https://www.getpantheon.com | grep PHPSESS|wc -l
You should substitute your site URL in the example, and the desired output is "0" (zero).
If your site is overaggressively starting sessions, you should search through the codebase for references to
$_SESSION to see where it is happening and develop a workaround. If the code is in a community plugin, open an issue on WordPress.org to alert the author to the problem and share your solution.