Make it easier for theme builders to enable Twig debugging and disable render cache

Hi, I came across this issue while promoting the Mix → module, which provides a similar solution to solve this problem. By enabling/disabling twig debugging, twig auto_reload and related caches with a single checkbox. No need to edit the settings*.php and *services.yml files anymore.

Before this issue gets fixed and added to the core, maybe it's worth you guys taking a peek at the Mix module. Perhaps there would be some useful information or ideas that could be used to improve the core.

It would be great if anyone who is interested in the Mix module could try it out, thanks very much.

The following is a screenshot of the settings form.

→

I implemented some changes to the open MR.

A new form named "Developer settings" has been added, with its own route and menu item. It contains a checkbox, "Enable Twig debug mode", which enables the Twig "debug" flag, and two other conditional checkboxes. These are to handle Twig's "autoload" and cache disabling. The one disabling cache disables both Twig cache flag and the Drupal's page, render and dynamic page caches.

The three options can also be overridden from settings file. Please, let me know if this implementation works better!

Coming here to find a way to disable auto_reload, which seems to be automatic while debug is set to 'true'.
I understand that in most case it is useful, but from a theming side it is NOT ALWAYS the case and I would like to have the option to disable it. (If there is already a way, could someone please let me know). In case if we are using Vite.js to compile the theme, auto_reload is unnecessary and time consuming.

@sahaj you can set debug to true and auto_reload to false if you want debug but not auto_reload.

The behaviour is that if auto_reload is not specified, then it inherits the value of debug.

Great work, this will be a nice improvement. Could the same be done for core and module development, so that all caches can eventually be easily disabled, via the GUI or running a single command such as drush cache:disable? ✨ Easy way to bypass all caching with Drush or settings.php Active .

Bumping the version to 10.1.x

Re-rolled the MR and created a patch (since MR is against 10.0.x and Zequi is probably sleeping)

Reworked the patch. Moved settings to Performance from Developer settings. Streamlined the options a little bit. Removed anything involving settings.php overrides to simplify the logic. The settings.php work in the existing patch is already possible via services.yml, this issue should focus on a UI for those values.

I'm going to revise #59. There's no test coverage and I think empty values should be deleted from state and not saved as false.

Great to see this moving forward thanks everyone. The issue summary seems to be getting increasingly left behind.

1)

Moved settings to Performance from Developer settings.

I can see your point, as previously there was "Admin > Config > Development > Developer Settings" - and what's the difference between development settings and developer settings😃.

On the other hand we now seem to have "Admin > Config > Development > Performance" and then a details box titled "Developer settings", which still doesn't seem quite right. How about reorganising the Performance page something like this:

• Rename "Caching" to "Web Caching"
• New section "Internal Caching" or "Cache Bins" (or whatever the right name is). Module caches could later be added here as per #56
• New section "Twig" containing the 3 checkboxes

2) Two of your four settings are "disable XXX" rather than "enable XXX" - potentially this negation is a confusing UI??

3) It would be great to have warnings in the form UI for the two settings that have potential disadvantages:
twig_debug: This modifies the HTML markup and may lead into different behavior from production, even causing bugs.
cache: This is recommended; even in the dev environment, because the auto_reload option ensures that cached templates which have changed get compiled again.

4) The patch seems to save the new values to state rather than config, which seems unusual and potentially confusing. I understand that the values are likely to be different on dev vs production. However that's also true for many of the other development settings. What is the advantage to this approach?

5) The code seems to invalidate the container if any value is enabled. Shouldn't this be if any value has changed?

I'll reply to #61 in full later, but

4) The patch seems to save the new values to state rather than config, which seems unusual and potentially confusing. I understand that the values are likely to be different on dev vs production. However that's also true for many of the other development settings. What is the advantage to this approach?

This shouldn't be a configuration that can be persisted. It should be something specific to that environment, which is what the state key value store is for.

5) The code seems to invalidate the container if any value is enabled. Shouldn't this be if any value has changed?

This is why it needs test. It should be invalidating if it's ever changed but there may be edge cases.

Also: wording. I avoided trying to make it perfect because the issue comments will provide the bikeshedding for best words.

New patch
- fixed twig_autoreload to twig_auto_reload for cspell
- improved UX (auto-check sub-checkboxes if nothing is enabled) and values bug
- container invalidation anytime twig dev mode values change

3) It would be great to have warnings in the form UI for the two settings that have potential disadvantages:

I think it should link to official docs, because they'll stay up to date. @mherchel informed me about twig debug adding HTML comments which breaks RSS feeds. So there are edge cases and this is best handled in guides.

All wording and variable names are up for discussion, just getting work up so we can review.

Forgot the patch 🙈

Thanks for the responses @mglaman

I think it should link to official docs, because they'll stay up to date

Great - the wording was from the docs anyway

@mherchel informed me about twig debug adding HTML comments which breaks RSS feeds. So there are edge cases and this is best handled in guides.

It's funny how many people who haven't hit this themselves say that it's an edge case😃. It's not only RSS, please see 🌱 [META] twig debug can break parts of site Active (which when counting together all the child issues has more followers than this one😃).

@lauriii commented in #51

It could even be helpful to provide an explanation in the UI that the Twig Debug mode modifies the HTML markup and may lead into different behavior from production.

It can save people some trouble so I wonder is there any significant disadvantage???

New patch: fixes phpcs, and container invalidation when root twig development mode toggle used

The last submitted patch, 66: 3278493-66.patch, failed testing. View results →

mherchel → credited callinmullaney → .

mherchel → credited hbrokmeier → .

mherchel → credited mndonx → .

Did some hallway testing at MidCamp with front-end devs @hbrokmeier, @callinmullaney, @mndonx (crediting).

We worked on verbiage and expectations:

• Rename the “Performance” page title (and menu entry) to “Performance and caching”
• Change the new details label to “Theme development settings”
• Directly within the new details element add this text:
  • These settings should only be enabled on development environments and never on production.
• For caching description text:
  • Change label: Do not cache markup
  • Change description: Disables render cache, dynamic page cache, and page cache.
• Use case. If we rebuild the environment, we don’t want to have to re-check this form. Can we override these settings in settings.php or have a drush command?

I looked at this issue with M&M at MC (@mherchel and @mglaman at MidCamp 2023). What is the best way to present the options under "Twig development mode"?

The options "Enable Twig auto reload" and "Disable Twig cache" are not independent, so it does not make sense to have a checkbox for each. If I have it straight, the first option invalidates the cache if it is older than the source, and the second option completely bypasses caching. Instead of two checkboxes, I think there should be three radio buttons:

• Normal caching
• Cache, but recompile changed templates
• No caching

I also reviewed the current labels and descriptions:

- [ ] Enable Twig debug mode
Enables Twig debug mode, which provides Twig's dump() function, outputs template suggestions to HTML comments, and allows to set Twig auto reload and to disable caches.
- [ ] Enable Twig auto reload
When enabled, Twig templates are recompiled when the source code changes.
- [ ] Disable Twig cache
Disables Twig template cache.

It is confusing to use "Enable" and "Disable" for checkboxes. We should avoid repeating the label in the description. We do not need a description at all if it just repeats the label. I came up with some alternative text:

- [ ] Show debug information in HTML comments
Show template suggestions in HTML comments and provide Twig's dump() function.
- [ ] Recompile changed templates
- [ ] Bypass template cache

Maybe remove "in HTML comments" from the first comment.

The last option on the page is

- [ ] Disable cache bins for rendered output
Disables render cache, dynamic page cache, and page cache to bypass caching during rendering.

I suggest changing that to

- [ ] Do not cache markup
Disables render cache, dynamic page cache, and page cache.

New work-in-progress patch since I'm leaving MidCamp soon. Captures some ideas from @benjifisher where there we unify auto_reload and disable caches as a radio option. Enabling auto_reload is useless if caches are disabled because there are no compiled templates to checksum and reload.

I talked about this issue at MidCamp with @akalata and Jen Stein (not sure of the d.o username). We agreed that the UI should have three radio buttons, and we recommend this:

• Cache Twig templates normally
• Autoload Twig templates
  • Cache, but recompile changed templates
• Do not cache templates

(That is, the middle option is the only one that needs description/help text.) Probably the middle option should be selected by default when "Twig development mode" is enabled.

Removing myself from assignee. Not actively working on it right now, so someone else can try a reroll with with feedback included

I talked about this issue at MidCamp with @akalata and Jen Stein (not sure of the d.o username). We agreed that the UI should have three radio buttons, and we recommend this:

The issue with this option is that it doesn't give the granularity of enabling and disabling the 3 options, as pointed out in #37 by @adamPS and +1'd by @lauriii in #51

mherchel → credited akalata → .

Adding credit for @akalata's discussion with @benjifisher.

Pretty sure Jen Stein isn't on Drupal.org. I found her on MidCamp's site, but not here.

Verbiage changes

I am afraid I was not clear in #74.

There are currently three checkboxes:

• Twig debug mode
• Twig auto reload
• Disable Twig cache

I meant to suggest that we keep the first one and replace the other two with three radio buttons.

That reduces 4 options to 3. The one we leave out is disabling the second option and enabling the third. That combination does not make much sense: see #72. Anna, Jen, and I think this is a better UI than the suggestion at the end of #51:

We could potentially visualize some of this as well by hiding the auto reload checkbox when the full "Twig debug" mode is turned on.

Adding a missing comma

Let me see if I can help a little here.

If I read it correctly, PHPStan is complaining that you are telling it to ignore some lines that do not have any problems. So this patch removes the @phpstan-ignore-next-line annotations.

I am a little unsure, since core/scripts/dev/commit-code-check.sh passes locally with or without those annotations.

Worked with @ckrina (UX Maintainer) and @mglaman on a Zoom call to nail down the user interface. For any additional improvements, please open up a followup issue.

On admin/config, this item will go directly under “Performance”

This form will go under admin/config/development/settings. The title of the page and menu item is “Development settings”

When “Twig development mode” checkbox is checked, both checkboxes within the child fieldset are checked by default.

Note that we removed the Twig auto-reload setting, as when Twig debug mode is enabled, this will automatically get enabled. This is the most common development setting for new developers. For more advanced configuration, changes can still be made in development.services.yml

Note we will open up a followup issue to provide a indication in the UI if settings are overridden.

This is a huge improvement for front-end DX, thanks for working on this!

The form doesn't tell the user that the changes have been saved.

+++ b/core/modules/system/system.install
@@ -1531,6 +1531,23 @@ function (callable $hook, string $module) use (&$module_list, $update_registry,
+  if ($phase === 'runtime') {
+    $twig_development = \Drupal::state()->getMultiple(['twig_debug', 'twig_cache_disable']);
+    if (array_reduce($twig_development, static fn (bool $toggled, ?bool $value) => $toggled ?: $value, FALSE)) {
+      $requirements['twig_debug_enabled'] = [
+        'title' => t('Twig development mode'),
+        'value' => t('Twig development mode settings are turned on. Go to @link to disable them.', [
+          '@link' => Link::createFromRoute(
+            'performance and caching settings page',
+            'system.performance_settings',
+          )->toString(),
+        ]),
+        'severity' => REQUIREMENT_WARNING,
+      ];

Wrong page! And could use individual boolean checks versus array_reduce now that it is only two options.

Matt's going for a run. Updating the patch to fix 👆

No clue if this is correct. Let's find out! 🤞

The last submitted patch, 90: 3278493-90.patch, failed testing. View results →

Debugging test failures. Also replacing usage "recompiles" to just "recompile"

So it is due to fetching the state service during the altering of the service container.

    /** @var \Drupal\Core\State\StateInterface $state */
    $state = $container->get('state');

I should have expected that I suppose. I know this approach works with config because JSON:API Extras does it, but that's because we have BootstrapConfigStorageFactory.

Something about fetching the key-value store here breaks things. I don't know why yet.

AH! So our test fails are caused by persist and 📌 Remove the persist service tag Needs work would fix it by handling the persisted key value memory factory.

Okay, here is an updated patch that s/recompiles/recompile and moves logic to a compiler pass outside of the service provider.

I'm going to work on a new issue that fixes the testing bug in KernelTestBase based on 📌 Remove the persist service tag Needs work without trying to deprecated the persist tag.

One more comment spam for the day. Linking to 🐛 Do not use persist tag for keyvalue.memory in KernelTestBase Fixed . Hopefully, that can be merged as a bug fix to unblock this issue.

As a sort of test-only patch for #3358048 and to see how much closer we are, here's #95 and the MR from #3358048 applied together. Interdiff is https://git.drupalcode.org/project/drupal/-/merge_requests/3920.diff ;)

core/scripts/dev/commit-code-check.sh --cached now passing. 😅 Sorry for the noise.

I wanted to compare #95 with #98 to prove that we should commit 🐛 Do not use persist tag for keyvalue.memory in KernelTestBase Fixed , so I queued the test run. Sadly, that failed for the unused use. So here's just #95 after running phpcbf to make core/scripts/dev/commit-code-check.sh happy. This will definitely still fail. Hopefully more like #90 than #98. 🤞

Here is #95 rebased off of 10.1.x, which should be the same as #99.

+++ b/core/modules/system/system.links.menu.yml
@@ -64,24 +64,30 @@ system.admin_config_development:
-system.site_maintenance_mode:
-  title: 'Maintenance mode'
-  parent: system.admin_config_development
-  description: 'Take the site offline for updates and other maintenance tasks.'
-  route_name: system.site_maintenance_mode
-  weight: -10
...
+system.development_settings:
+  title: Development settings
+  parent: system.admin_config_development
+  description: 'Configure theme development settings'
+  route_name: system.development_settings
+  weight: -19
...
+  weight: -10
+system.site_maintenance_mode:
+  title: 'Maintenance mode'
+  parent: system.admin_config_development
+  description: 'Take the site offline for updates and other maintenance tasks.'
+  route_name: system.site_maintenance_mode
+  weight: -5

+++ b/core/modules/system/system.routing.yml
@@ -178,7 +178,15 @@ system.performance_settings:
-    _title: 'Performance'
+    _title: 'Performance and caching'
+  requirements:
+    _permission: 'administer site configuration'
+
+system.development_settings:
+  path: '/admin/config/development/settings'
+  defaults:
+    _form: '\Drupal\system\Form\DevelopmentSettingsForm'
+    _title: 'Development settings'

Okay, I did a horrible merge here and didn't catch it.

Updating issue summary.

New patch
- fixes menu link and routing changes
- renames compiler pass from DeveloperSettingsPass to DevelopmentSettingsPass to match form name
- moves DevelopmentSettingsPass earlier before BackendCompilerPass so setting default_backend is respected

The last submitted patch, 100: 3278493-100.patch, failed testing. View results →

+++ b/core/lib/Drupal/Core/DependencyInjection/Compiler/DevelopmentSettingsPass.php
@@ -0,0 +1,41 @@
+    /** @var \Drupal\Core\State\StateInterface $state */
+    $state = $container->get('state');

This is the reason that we needed to do 🐛 Do not use persist tag for keyvalue.memory in KernelTestBase Fixed . I think this is wrong. We can't use service in compiler passes. That's really really fraught. I think we should have left 🐛 Do not use persist tag for keyvalue.memory in KernelTestBase Fixed alone. This change will result in all KernelTests now using the database for state because it results in the instantiation of the state service prior to \Drupal\KernelTests\KernelTestBase::register() running.

We need to do something different here.

+++ b/core/modules/system/system.install
@@ -1532,6 +1532,24 @@ function (callable $hook, string $module) use (&$module_list, $update_registry,
+    $twig_debug = \Drupal::state()->get('twig_debug', FALSE);
+    $twig_cache_disable = \Drupal::state()->get('twig_cache_disable', FALSE);
+    if ($twig_debug || $twig_cache_disable) {
+      $requirements['twig_debug_enabled'] = [
+        'title' => t('Twig development mode'),
+        'value' => t('Twig development mode settings are turned on. Go to @link to disable them.', [

Since enabling the "Twig development mode" checkbox adds a Warning message to status report page, and "Do not cache markup" is also being introduced as a separate, top-level checkbox alongside Twig development mode, and both of these can be detrimental to website performance on production/live sites, it seems it would follow that we should also have a separate Warning message when "Do not cache markup" checkbox is enabled, right?

This change will result in all KernelTests now using the database for state because it results in the instantiation of the state service prior to \Drupal\KernelTests\KernelTestBase::register() running.

It doesn't, this compiler pass runs after all other service providers register definitions.

What's the alternative? BootstrapConfigStorageFactory causes database calls during container compilation. I don't think Drupal core has this, but contrib does.

We need to do something different here.

It'd be a horrible idea to use config, because it could get exported and persist. Drupal core provides no alternatives or ways to prevent individual configuration objects from being exported.

Per #107: yes, you're right. It needs its own status check.

Just to clarify the container compilation flow:

\Drupal\Core\DrupalKernel::compileContainer invokes all service providers:

    // Register application services.
    $yaml_loader = new YamlFileLoader($container);
    foreach ($this->serviceYamls['app'] as $filename) {
      $yaml_loader->load($filename);
    }
    foreach ($this->serviceProviders['app'] as $provider) {
      if ($provider instanceof ServiceProviderInterface) {
        $provider->register($container);
      }
    }
    // Register site-specific service overrides.
    foreach ($this->serviceYamls['site'] as $filename) {
      $yaml_loader->load($filename);
    }
    foreach ($this->serviceProviders['site'] as $provider) {
      if ($provider instanceof ServiceProviderInterface) {
        $provider->register($container);
      }
    }

Kernel tests register in $GLOBALS['conf']['container_service_providers'] which discoverServiceProviders adds to $this->serviceProviderClasses['site']. Kernel test registers its alias here.

The DeveloperSettingsPass runs after ModifyServiceDefinitionsPass. This compiler pass runs all service providers which implement ServiceModifierInterface.

I agree it's not the best to initialize a service during compilation. However, it is being done after all registration and alters, resulting in final processing by any remaining compiler passes.

This is something I've wanted for years. The fact that it wasn't in core made me think there was some huge obstacle but this is a really solid way of doing it.

Outside of what has been reported, here's the one whole thing I noticed in my review:

+++ b/core/modules/system/system.install
@@ -1532,6 +1532,24 @@ function (callable $hook, string $module) use (&$module_list, $update_registry,
+  // Add warning when twig debug option is enabled.

Could this get test coverage? TBH not concerned about it working right in this scope, but more to ensure some later addition doesn't break it.

Adds status warning for disabled markup output caching. Adds tests for status report.

@mglaman so why was the change in 🐛 Do not use persist tag for keyvalue.memory in KernelTestBase Fixed necessary - what is the root cause? My guess is that persistence is done at a different time. Ah yep \Drupal\Core\DrupalKernel::attachSynthetic() is called after everything is compiled. Should have read #93 - thanks @mglaman

I wish we'd added a bigger comment in 🐛 Do not use persist tag for keyvalue.memory in KernelTestBase Fixed :) but I can open an issue for that. I agree with @mglaman that accessing the db here through state is probably okay. We also probably should use the PassConfig::TYPE_AFTER_REMOVING etc... more in CoreServiceProvider::register() - nearly all of our stuff is being added as an optimisation pass when everything should run after the removing pass. I consider #106 resolved.

Thanks, @alexpott! Yeah I'd love to dive into CoreServiceProvider and our CompilerPass after this, first time I really explored that area.

Re: #112: Here you go. 😉 📌 Improve how KernelTestBase manages its persistent key value storage Fixed

Using a fresh install on D10.1 without a settings.local.php file and with a default development.services.yml file.

1.
Unchecked Twig development mode
Checked Do not cache markup

Went to /admin/reports/status
Verified I see "Markup caching disabled
Render cache, dynamic page cache, and page cache are bypassed. Go to development settings page to enable them."

Unchecked Do not cache markup
Verified warning in status page goes away.

2.
Before checking Twig development mode verified that debug info is not appear in markup
Checked Twig development mode
But didn't check any sub items.
Clicking save doesn't save Twig development mode
Seems expected but slightly odd. But don't think a show stopper

3.
Checked Twig development mode
Checked Twig debug mode
Did not check Disable Twig cache
Clicked save
Twig development mode is unchecked BUG
Inspect the markup and debug info is appearing.
Go to status page verify I see "Twig development mode
Twig development mode settings are turned on. Go to development settings page to disable them."

4.
Checked Twig development mode
Checked Twig debug mode
Checked Disable Twig cache
Clicked save
Twig development mode is checked
Inspect the markup and debug info is appearing

Test coverage seems good.
Other then that one small point think this is good to go.

And as posted in slack a change record should be made.

+++ b/core/modules/system/src/Form/DevelopmentSettingsForm.php
@@ -0,0 +1,144 @@
+      '#default_value' => $twig_debug && $twig_cache_disable,

whomp whomp.

should be ||

Good catch. Fixed in this patch.

Change record created at https://www.drupal.org/node/3359728 →

Issue I found in #115 has been addressed.

Tested this using the standard profile, with olivero:
- Visit homepage with caching fully enabled (ie: nothing checked) - warms cache
- Visit /admin/config/development/settings Check the do not cache markup checkbox / save
- Update a twig template used on the homepage (I updated `html.html.twig`)
- View homepage, confirm new change appears with no cache clear
- Visit /admin/config/development/settings Uncheck the do not cache markup checkbox / save
- View homepage, note old cached version before the change appears

I would expect the new version, is that an issue?

I gave the patch a thorough review and it looks solid. Also the UX is pretty good. I made super minor nitpick changes to the patch. Posting just to make sure custom commands pass.

I think the UI texts in the patch are fine but I'm still planning on creating a follow-up to bikeshed some of the texts.

Committed da2eaec and pushed to 10.1.x. Thanks!

Adding release note.

@crasx / #120 - that's a smart comment. I agree with @lauriii that we can address that in a follow-up.

Here’s the follow-up I filed: 📌 Improve UI texts for Twig development settings Active

I observed this:

+++ b/core/modules/system/src/Form/DevelopmentSettingsForm.php
@@ -0,0 +1,152 @@
+      '#description' => $this->t('Disables render cache, dynamic page cache, and page cache.'),

Über nit… 🙈

s/dynamic page cache/Dynamic Page Cache/

s/page cache/Page Cache/

… because they're module names? That's also how they're capitalized in example.settings.local.php.

OTOH I like this better … because then it's consistent with "render cache". Maybe we should just lowercase them everywhere instead?

Moved to that follow-up. 👍

Yay for getting this in! I just added 🐛 Latest/real markup should be used when caches are enabled Postponed as a followup per #120.

@mherchel,
Tracked down Jen Stein's username: jen.stein

mherchel → credited jen.stein → .

Crediting. Thanks!

Thanks everyone, this is an awesome improvement. I just used it to try the New clean_unique_id Twig filter → in Drupal 11, and it worked flawlessly.

@mherchel suggested at one point, which I agree with:

Use case. If we rebuild the environment, we don’t want to have to re-check this form. Can we override these settings in settings.php or have a drush command?

So I created ✨ Enable Twig debugging and disable render cache via Drush and settings.php Fixed .

Automatically closed - issue fixed for 2 weeks with no activity.

I'm late to the party, but don't you think that having a dedicated checkbox to expose another two checkboxes looks a bit weird from the UX perspective? That also made the logic in the form much more complex.