You have likely upgraded Drupal to version 10.3.0 and noticed a new message in the reports regarding the State Cache:
The message reads as follows:
The State Cache flag $settings['state_cache'] is not enabled. It is recommended to enable it in settings.php unless too many keys are stored. Starting with Drupal 11, State Cache will be enabled by default.
What is the State API?
Let's begin by understanding what the State API is. The State API in Drupal is a system that allows the storage and retrieval of small data fragments that are necessary for site operation but are not part of the overall configuration. Unlike the Config API, which focuses on data that must be consistent across different environments (like production, development, etc.), the State API is intended for environment-specific data that can change more dynamically and do not need to be synchronized across different environments.
Why does it need to be cached?
Currently, State API entries are stored in the 'key_value' table. If you have never seen this table, it is a generic and flexible key-value store widely used in Drupal for multiple data storage purposes, a large catch-all box. This means that the table is not optimized for access and reading.
The main change is that `\Drupal\Core\State\State` now extends `\Drupal\Core\Cache\CacheCollector`. This means that the most queried State API elements can be retrieved more efficiently from the cache instead of frequently querying the database. This is particularly beneficial for high-traffic sites where efficiency is key to maintaining optimal performance.
What if we move the entire key_value table to the cache?
Depending on the system we use, the size dedicated to the cache may vary and is limited; intensive use may degrade the site's performance, hindering the retrieval of truly necessary information.
Drupal's State API is designed to handle small data fragments that need frequent access and do not change consistently across environments. For example:
- Maintenance flag: Enable site maintenance.
- Last cron execution: Date and time of the lastest cron execution.
- Data to optimize route queries: Information used to improve routing.
However, certain cases are not optimal for the State API. For example, a development `flag` accessed only during a container rebuild should be avoided, such as twig debugging. Instead, the `key_value` service should be used for large or infrequently accessed information with its appropriate collection.
So, would enabling the State cache be enough for my needs?
Drupal provides the option to configure the State API cache to prevent issues in existing sites with many or large entries; this feature must be explicitly enabled using the configuration flag:
$settings['state_cache'] = TRUE;This ensures that the site takes advantage of the new cache functionality. If not explicitly set, Drupal will display the warning message mentioned at the beginning. It is important to note that in Drupal 11+, the state cache is permanently enabled, eliminating the option to configure this flag.
How do I know if I should enable it?
Before activating this option, you need to check the current usage of the State API; this can be done using the following database query:
SELECT COUNT(*), SUM(LENGTH(value)) FROM key_value WHERE collection = 'state';If the environment has more than 100 entries or a total value size over 100,000, you should consider reviewing and optimizing specific entries. Use the following query for more details:
SELECT name, LENGTH(value) FROM key_value WHERE collection = 'state'
ORDER BY LENGTH(value) DESC LIMIT 100;What do I do with entries that are too large or do not fit the State API?
As we have mentioned, the State API entries so far were stored in the 'key_value' table. If you want to keep them, you can change the collection they belong to by replacing the State API service with the 'key_value' one.
Conclusion
This change significantly improves the efficiency and performance of Drupal sites by optimizing the handling of state elements through caching. Although most developers won't need to make changes to their code, it's crucial to review the site configuration to ensure these new capabilities are adequately utilized. Optimizing queries and the cache structure can provide substantial benefits to the end-user's experience and server resource management.
