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. On Pantheon, support for sessions requires the WordPress Native PHP Sessions plugin which we maintain. Sites that need to utilize PHP Sessions should install this plugin.
Given the variety of implementations, this plugin will not solve all
$_SESSION based issues and errors. 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
Prior to 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 need to be uncached to work properly, and it is impossible use cached content when there are sessions in place. It would be best to use a cookie based solution to avoid a performance hit from uncached session pages.
Symptoms of this issue shows when the header is inspected, you will see that 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 not allowing caching is to use our Varnish check tool, or by inspecting the headers using
curl -sI example.com with each of the following steps, until you determine which component is breaking the cache:
To check your theme, use your default theme (twentynineteen for example), and check for the cookie.
To see if a plugin is breaking the cache, disable the plugins one by one. 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.
To check if a 3rd party must-use plugin or drop-in plugin is breaking the cache, temporarily remove the 3rd party must-use plugins and leave only the
WP Native PHP Sessions. There should be no drop-ins in place.
Install WordPress Native PHP Sessions Plugin
$_SESSIONs are necessary for your application, install the WordPress Native PHP Sessions plugin:
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
Deploy the plugin to the Test environment within the Site Dashboard or with Terminus:
terminus env:deploy <site>.test --sync-content --cc --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 --cc --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
Once enabled, your functionality will "just work". For more information, see Fix WordPress PHP Session Problems on Pantheon with a Script.
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 there, but the desired output is "0" (zero).
If your site is overly aggressively 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.