DOC Document new session save handlers #783

GuySartorelli · 2025-07-21T04:47:18Z

Issue

New session handlers silverstripe-framework#11719

GuySartorelli · 2025-07-22T23:02:59Z

Linting failure isn't related to this PR

emteknetnz · 2025-07-23T01:32:45Z

en/02_Developer_Guides/18_Cookies_And_Sessions/02_Sessions.md


+#### `CacheSessionHandler`
+
+If you want a more performant session save handler, you can use the [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler). This session save handler can use any cache adapter that implements `Psr\SimpleCache\CacheInterface`, though we recommend specifically using an in-memory cache adapter that gets instantiated from a factory implementing [`InMemoryCacheFactory`](api:SilverStripe\Core\Cache\InMemoryCacheFactory).


Suggested change

If you want a more performant session save handler, you can use the [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler). This session save handler can use any cache adapter that implements `Psr\SimpleCache\CacheInterface`, though we recommend specifically using an in-memory cache adapter that gets instantiated from a factory implementing [`InMemoryCacheFactory`](api:SilverStripe\Core\Cache\InMemoryCacheFactory).

If you want a more performant session save handler, you can use the [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler). This session save handler can use any cache that implements the PSR-16 [`Psr\SimpleCache\CacheInterface`](https://www.php-fig.org/psr/psr-16/#21-cacheinterface), though we recommend specifically using an in-memory cache that gets instantiated from a factory implementing [`InMemoryCacheFactory`](api:SilverStripe\Core\Cache\InMemoryCacheFactory), such as [`MemcachedCacheFactory`](api:SilverStripe\Core\Cache\MemcachedCacheFactory) or [`RedisCacheFactory`](api:SilverStripe\Core\Cache\RedisCacheFactory).

I'll keep "in-memory cache adapter" because in this case it's referring specifically to adapters as documented in https://docs.silverstripe.org/en/6/developer_guides/performance/cache_adapters/#adding-an-in-memory-cache-adapter

Done but removed the bit further down which served the same purpose of pointing out redis and memcached. It was

For example, if you have Redis you can use [`RedisCacheFactory`](api:SilverStripe\Core\Cache\RedisCacheFactory), and if you have Memcached you can use [`MemcachedCacheFactory`](SilverStripe\Core\Cache\MemcachedCacheFactory).

emteknetnz · 2025-07-23T01:35:03Z

en/02_Developer_Guides/18_Cookies_And_Sessions/02_Sessions.md

+> [!NOTE]
+> Although this is using a cache adapter, sessions won't be cleared when flushing the site.


Suggested change

> [!NOTE]

> Although this is using a cache adapter, sessions won't be cleared when flushing the site.

> [!NOTE]

> When using a PSR-16 compatible cache, sessions won't be cleared when flushing the site.

It doesn't matter whether they're PSR-16 or not. I'll remove the word "adapter" which is what I assume you're really after.

emteknetnz · 2025-07-23T01:38:23Z

en/02_Developer_Guides/18_Cookies_And_Sessions/02_Sessions.md

+> [!NOTE]
+> Although this is using a cache adapter, sessions won't be cleared when flushing the site.
+
+You can define the factory which is used to instantiate the cache handler by setting the `SS_SESSION_CACHE_FACTORY` environment variable, or by setting the following YAML configuration:


Suggested change

You can define the factory which is used to instantiate the cache handler by setting the `SS_SESSION_CACHE_FACTORY` environment variable, or by setting the following YAML configuration:

You can define the factory which is used to instantiate the cache by setting the `SS_SESSION_CACHE_FACTORY` environment variable, or by setting the following YAML configuration:

emteknetnz · 2025-07-23T01:41:13Z

en/02_Developer_Guides/18_Cookies_And_Sessions/02_Sessions.md

+
+This provides a low barrier to sharing your sessions across multiple servers, e.g. in a horizontally-scaled hosting scenario.
+
+You can change the name of the table used by setting [`DatabaseSessionHandler.table_name`](api:SilverStripe\Control\SessionHandler\DatabaseSessionHandler->table_name) to the new table name. Note that changing the table name after sessions have already been stored in the old table will result in those sessions being invalidated, unless you manually migrate them to the new table.


Suggested change

You can change the name of the table used by setting [`DatabaseSessionHandler.table_name`](api:SilverStripe\Control\SessionHandler\DatabaseSessionHandler->table_name) to the new table name. Note that changing the table name after sessions have already been stored in the old table will result in those sessions being invalidated, unless you manually migrate them to the new table.

You can change the name of the table used by setting [`DatabaseSessionHandler.table_name`](api:SilverStripe\Control\SessionHandler\DatabaseSessionHandler->table_name) from the default of `_sessions` to a new table name.

> [!IMPORTANT]

> Changing the table name after sessions have already been stored in the old table will result in those sessions being invalidated, unless you manually migrate them to the new table

We don't tend so say "from the default of <default value>" in docs elsewhere from what I can recall so I'll not mention _sessions explicitly. But will make the other changes.

Will use WARNING instead of IMPORTANT as per https://docs.silverstripe.org/en/6/contributing/documentation/#callout-blocks

emteknetnz · 2025-07-23T01:42:31Z

en/08_Changelogs/6.1.0.md

+| Class name | Description |
+| --- | --- |
+| [`FileSessionHandler`](api:SilverStripe\Control\SessionHandler\FileSessionHandler) | Stores sessions in files like the default PHP session handler, except it doesn't lock the file. This is the new default. |
+| [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler) | Stores sessions in a cache adapter that implements `Psr\SimpleCache\CacheInterface`. More performance than the file session handler in most scenarios, but requires additional setup. |


Suggested change

| [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler) | Stores sessions in a cache adapter that implements `Psr\SimpleCache\CacheInterface`. More performance than the file session handler in most scenarios, but requires additional setup. |

| [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler) | Stores sessions in a cache that implements the PSR-16 [`Psr\SimpleCache\CacheInterface`](https://www.php-fig.org/psr/psr-16/#21-cacheinterface). More performant than the `FileSessionsHandler` in most scenarios, though requires additional setup. |

Done. Keeping "but" as that's my preferred word - it does the same thing as "though" in this sentence.

emteknetnz · 2025-07-23T01:44:35Z

en/08_Changelogs/6.1.0.md

+| --- | --- |
+| [`FileSessionHandler`](api:SilverStripe\Control\SessionHandler\FileSessionHandler) | Stores sessions in files like the default PHP session handler, except it doesn't lock the file. This is the new default. |
+| [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler) | Stores sessions in a cache adapter that implements `Psr\SimpleCache\CacheInterface`. More performance than the file session handler in most scenarios, but requires additional setup. |
+| [`DatabaseSessionHandler`](api:SilverStripe\Control\SessionHandler\DatabaseSessionHandler) | Stores sessions in the database. Provides a low barrier to sharing your sessions across multiple servers, e.g. in a horizontally-scaled hosting scenario |


Suggested change

| [`DatabaseSessionHandler`](api:SilverStripe\Control\SessionHandler\DatabaseSessionHandler) | Stores sessions in the database. Provides a low barrier to sharing your sessions across multiple servers, e.g. in a horizontally-scaled hosting scenario |

| [`DatabaseSessionHandler`](api:SilverStripe\Control\SessionHandler\DatabaseSessionHandler) | Stores sessions in the database. Provides a low barrier to sharing sessions across multiple servers, e.g. in a horizontally-scaled hosting scenario |

emteknetnz · 2025-07-23T01:45:17Z

en/00_Getting_Started/03_Environment_Management.md

 | `SS_IN_MEMORY_CACHE_FACTORY` | The [`InMemoryCacheFactory`](api:SilverStripe\Core\Cache\InMemoryCacheFactory) class to use for instantiating in-memory cache adapters. See [caching adapters](/developer_guides/performance/object_caching/#adapters) for more details. |
 | `SS_MANIFESTCACHE` | The manifest cache to use (defaults to file based caching). Must be a `Psr\Cache\CacheItemPoolInterface`, `Psr\SimpleCache\CacheInterface`, or `SilverStripe\Core\Cache\CacheFactory` class implementation. |
+| `SS_SESSION_SAVE_HANDLER_CLASS` | Sets the classname for the session save handler to use for sessions. Alternatively set [`Session.save_handler`](api:SilverStripe\Control\Session->save_handler) via YAML configuration. See [session save handler](/developer_guides/cookies_and_sessions/sessions/#save-handler) for more details. |
+| `SS_SESSION_CACHE_FACTORY` | Sets the factory to use for instantiating a cache adapter if the session save handler has been set to [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler). See [`CacheSessionHandler` docs](/developer_guides/cookies_and_sessions/sessions/#cachesessionhandler) for more details. |


Suggested change

| `SS_SESSION_CACHE_FACTORY` | Sets the factory to use for instantiating a cache adapter if the session save handler has been set to [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler). See [`CacheSessionHandler` docs](/developer_guides/cookies_and_sessions/sessions/#cachesessionhandler) for more details. |

| `SS_SESSION_CACHE_FACTORY` | Sets the factory to use for instantiating a cache if the session save handler has been set to [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler). See [`CacheSessionHandler` docs](/developer_guides/cookies_and_sessions/sessions/#cachesessionhandler) for more details. |

emteknetnz · 2025-07-23T01:45:44Z

en/02_Developer_Guides/18_Cookies_And_Sessions/02_Sessions.md

+You can also set it to the FQCN or injector service name of any session handler that implements [`SessionHandlerInterface`](https://www.php.net/manual/en/class.sessionhandlerinterface.php). `silverstripe/framework` comes with several non-blocking session save handlers you can use.
+
+> [!WARNING]
+> Note that in edge case scenarios, for example if your application wants to modify a session value *based on the value that is already set* and must do so for each request, non-blocking sessions may cause unexpected results.


Suggested change

> Note that in edge case scenarios, for example if your application wants to modify a session value *based on the value that is already set* and must do so for each request, non-blocking sessions may cause unexpected results.

> In edge case scenarios, for example if your application wants to modify a session value *based on the value that is already set* and must do so for each request, non-blocking sessions may cause unexpected results.

emteknetnz · 2025-07-23T01:46:55Z

en/02_Developer_Guides/18_Cookies_And_Sessions/02_Sessions.md

+    factory: 'App\Session\MyCacheFactory'
+```
+
+For example, if you have Redis you can use [`RedisCacheFactory`](api:SilverStripe\Core\Cache\RedisCacheFactory), and if you have Memcached you can use [`MemcachedCacheFactory`](SilverStripe\Core\Cache\MemcachedCacheFactory).


Suggested change

For example, if you have Redis you can use [`RedisCacheFactory`](api:SilverStripe\Core\Cache\RedisCacheFactory), and if you have Memcached you can use [`MemcachedCacheFactory`](SilverStripe\Core\Cache\MemcachedCacheFactory).

For example, if you have Redis you can use `RedisCacheFactory`, and if you have Memcached you can use `MemcachedCacheFactory`.

API docs are linked above in my recommended changes

Removed as redundant to #783 (comment)

emteknetnz · 2025-07-23T01:49:12Z

en/08_Changelogs/6.1.0.md

 The default file-based session handler for PHP holds a lock on the session file while the session is open. This means that multiple concurrent requests from the same user have to wait for one another to finish processing after a session has been started. This includes AJAX requests.

-To resolve this problem, a new [`Session.save_handler`](api:SilverStripe\Control\Session->save_handler) configuration property has been added. By default this is set to [`FileSessionHandler`](api:SilverStripe\Control\SessionHandler\FileSessionHandler) which is *non-blocking* which means that multiple concurrent requests from the same user don't have to wait for one another to finish.
+To resolve this problem, we have provided three new session save handlers. Each of these are *non-blocking* which means that multiple concurrent requests from the same user don't have to wait for one another to finish.


Do we need a link / instructions for how to keep sessions blocking in the changelog in case the non-blocking sessions break something?

That's already in the changelog

If you want to use the default blocking PHP file session handler instead, you can set the Session.save_handler configuration to null

GuySartorelli mentioned this pull request Jul 21, 2025

New session handlers silverstripe/silverstripe-framework#11719

Closed

5 tasks

GuySartorelli force-pushed the pulls/6/session-handlers branch 3 times, most recently from 69e050e to 0c113df Compare July 22, 2025 22:59

emteknetnz requested changes Jul 23, 2025

View reviewed changes

GuySartorelli force-pushed the pulls/6/session-handlers branch from 0c113df to 44fd488 Compare July 23, 2025 03:49

DOC Document new session save handlers

eba7030

GuySartorelli force-pushed the pulls/6/session-handlers branch from 44fd488 to eba7030 Compare July 23, 2025 03:51

emteknetnz approved these changes Jul 30, 2025

View reviewed changes

emteknetnz merged commit ece1cf1 into silverstripe:6 Jul 30, 2025
3 checks passed

emteknetnz deleted the pulls/6/session-handlers branch July 30, 2025 02:59

lozcalver pushed a commit to lozcalver/developer-docs that referenced this pull request Nov 14, 2025

DOC Document new session save handlers (silverstripe#783)

9312b64


		#### `CacheSessionHandler`

		If you want a more performant session save handler, you can use the [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler). This session save handler can use any cache adapter that implements `Psr\SimpleCache\CacheInterface`, though we recommend specifically using an in-memory cache adapter that gets instantiated from a factory implementing [`InMemoryCacheFactory`](api:SilverStripe\Core\Cache\InMemoryCacheFactory).

		> [!NOTE]
		> Although this is using a cache adapter, sessions won't be cleared when flushing the site.

	You can define the factory which is used to instantiate the cache handler by setting the `SS_SESSION_CACHE_FACTORY` environment variable, or by setting the following YAML configuration:
	You can define the factory which is used to instantiate the cache by setting the `SS_SESSION_CACHE_FACTORY` environment variable, or by setting the following YAML configuration:


		This provides a low barrier to sharing your sessions across multiple servers, e.g. in a horizontally-scaled hosting scenario.

		You can change the name of the table used by setting [`DatabaseSessionHandler.table_name`](api:SilverStripe\Control\SessionHandler\DatabaseSessionHandler->table_name) to the new table name. Note that changing the table name after sessions have already been stored in the old table will result in those sessions being invalidated, unless you manually migrate them to the new table.

-You can change the name of the table used by setting [`DatabaseSessionHandler.table_name`](api:SilverStripe\Control\SessionHandler\DatabaseSessionHandler->table_name) to the new table name. Note that changing the table name after sessions have already been stored in the old table will result in those sessions being invalidated, unless you manually migrate them to the new table.
+You can change the name of the table used by setting [`DatabaseSessionHandler.table_name`](api:SilverStripe\Control\SessionHandler\DatabaseSessionHandler->table_name) from the default of `_sessions` to a new table name.
+> [!IMPORTANT]
+> Changing the table name after sessions have already been stored in the old table will result in those sessions being invalidated, unless you manually migrate them to the new table

	\| [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler) \| Stores sessions in a cache adapter that implements `Psr\SimpleCache\CacheInterface`. More performance than the file session handler in most scenarios, but requires additional setup. \|
	\| [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler) \| Stores sessions in a cache that implements the PSR-16 [`Psr\SimpleCache\CacheInterface`](https://www.php-fig.org/psr/psr-16/#21-cacheinterface). More performant than the `FileSessionsHandler` in most scenarios, though requires additional setup. \|

	\| [`DatabaseSessionHandler`](api:SilverStripe\Control\SessionHandler\DatabaseSessionHandler) \| Stores sessions in the database. Provides a low barrier to sharing your sessions across multiple servers, e.g. in a horizontally-scaled hosting scenario \|
	\| [`DatabaseSessionHandler`](api:SilverStripe\Control\SessionHandler\DatabaseSessionHandler) \| Stores sessions in the database. Provides a low barrier to sharing sessions across multiple servers, e.g. in a horizontally-scaled hosting scenario \|

	\| `SS_SESSION_CACHE_FACTORY` \| Sets the factory to use for instantiating a cache adapter if the session save handler has been set to [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler). See [`CacheSessionHandler` docs](/developer_guides/cookies_and_sessions/sessions/#cachesessionhandler) for more details. \|
	\| `SS_SESSION_CACHE_FACTORY` \| Sets the factory to use for instantiating a cache if the session save handler has been set to [`CacheSessionHandler`](api:SilverStripe\Control\SessionHandler\CacheSessionHandler). See [`CacheSessionHandler` docs](/developer_guides/cookies_and_sessions/sessions/#cachesessionhandler) for more details. \|

	> Note that in edge case scenarios, for example if your application wants to modify a session value based on the value that is already set and must do so for each request, non-blocking sessions may cause unexpected results.
	> In edge case scenarios, for example if your application wants to modify a session value based on the value that is already set and must do so for each request, non-blocking sessions may cause unexpected results.

	For example, if you have Redis you can use [`RedisCacheFactory`](api:SilverStripe\Core\Cache\RedisCacheFactory), and if you have Memcached you can use [`MemcachedCacheFactory`](SilverStripe\Core\Cache\MemcachedCacheFactory).
	For example, if you have Redis you can use `RedisCacheFactory`, and if you have Memcached you can use `MemcachedCacheFactory`.

DOC Document new session save handlers #783

DOC Document new session save handlers #783

Uh oh!

Conversation

GuySartorelli commented Jul 21, 2025

Issue

Uh oh!

GuySartorelli commented Jul 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GuySartorelli Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GuySartorelli Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

GuySartorelli Jul 23, 2025 •

edited

Loading

GuySartorelli Jul 23, 2025 •

edited

Loading