Problem/Motivation

This was discovered over at #3301173: Allow starterkit theme generator tool to clone Olivero.

If a theme is enabled in the UI, any SDC components inside that new theme are not available unless you additionally do a Drupal cache clear. This causes Drupal to throw a 500 error to the admin user who enabled the theme! This isn't an issue for components in modules, since ModuleInstaller does clear those caches, while ThemeInstaller does not.

Steps to reproduce

Proposed resolution

I grabbed this from ModuleInstaller and it solves the issue. But I have no idea yet if it's the correct fix.

diff --git a/core/lib/Drupal/Core/Extension/ThemeInstaller.php b/core/lib/Drupal/Core/Extension/ThemeInstaller.php
index 364d672c12f..9565fcf37b4 100644
--- a/core/lib/Drupal/Core/Extension/ThemeInstaller.php
+++ b/core/lib/Drupal/Core/Extension/ThemeInstaller.php
@@ -248,6 +248,7 @@ public function install(array $theme_list, $install_dependencies = TRUE) {
     }
 
     $this->cssCollectionOptimizer->deleteAll();
+    \Drupal::getContainer()->get('plugin.cache_clearer')->clearCachedDefinitions();
     $this->resetSystem();
 
     // Invoke hook_themes_installed() after the themes have been installed.
@@ -301,6 +302,7 @@ public function uninstall(array $theme_list) {
     $extension_config->save(TRUE);
 
     // Refresh theme info.
+    \Drupal::getContainer()->get('plugin.cache_clearer')->clearCachedDefinitions();
     $this->resetSystem();
     $this->themeHandler->reset();
 

Remaining tasks

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet

CommentFileSizeAuthor
#14 part-2-working.mp44.94 MBmherchel
#14 part-1-broken.mp42.57 MBmherchel

Issue fork drupal-3522505

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

deviantintegral created an issue. See original summary.

quietone’s picture

Version: 11.1.x-dev » 11.x-dev
mherchel’s picture

Issue summary: View changes
Priority: Normal » Major

Bumping this to Major (note it may need to be critical). Most new themes will have SDCs, and this will affect anyone who install new themes via the UI.

nicxvan made their first commit to this issue’s fork.

mherchel’s picture

Slack discussion at https://drupal.slack.com/archives/C079NQPQUEN/p1746998199858839

In it, backend framework manager @larowlan states (in regards to @deviantintegral approach in the issue summary)

that approach looks fine to me, ideally with the cache clearer injected

mherchel’s picture

Issue summary: View changes

Updating the steps to reproduce

mherchel’s picture

Issue summary: View changes

evidently the test case isn't as simple as I initially thought. I've run into this a lot, but need to see what the differentiator is that causes it.

godotislate’s picture

Here's a failing kernel test that shows a couple issues going on.

<?php

declare(strict_types=1);

namespace Drupal\KernelTests\Components;

use Drupal\Core\Theme\Component\ComponentValidator;
use Drupal\Core\Theme\Component\SchemaCompatibilityChecker;
use Drupal\Core\Theme\ComponentNegotiator;
use Drupal\Core\Theme\ComponentPluginManager;

/**
 * Tests discovery of components in a theme being installed.
 */
class ComponentPluginManagerDiscoveryTest extends ComponentKernelTestBase {

  /**
   * {@inheritdoc}
   */
  protected static $themes = ['stark'];

  public function testComponentDiscoveryOnThemeInstall(): void {
    $definitions = \Drupal::service('plugin.manager.sdc')->getDefinitions();
    $this->assertArrayNotHasKey('sdc_theme_test:bar', $definitions);
    \Drupal::service('theme_installer')->install(['sdc_theme_test']);
    $definitions = \Drupal::service('plugin.manager.sdc')->getDefinitions();
    $this->assertArrayHasKey('sdc_theme_test:bar', $definitions);
  }

}

First thing is that because there is no container rebuild or component plugin cache clear on theme install, $definitions get cached in the first line before the theme is installed, and the cache is not invalidated after theme install, so the last line's assert fails.

However, even if we just add a plugin cache clear after the theme install like this:

  public function testComponentDiscoveryOnThemeInstall(): void {
    $definitions = \Drupal::service('plugin.manager.sdc')->clearCachedDefinitions();
    $this->assertArrayNotHasKey('sdc_theme_test:bar', $definitions);
    \Drupal::service('theme_installer')->install(['sdc_theme_test']);
    $definitions = \Drupal::service('plugin.manager.sdc')->getDefinitions();
    $this->assertArrayHasKey('sdc_theme_test:bar', $definitions);
  }

The last line still fails, because there is no container rebuild on theme install, so the component plugin manager has not changed, and the DirectoryWithMetadataPluginDiscovery $discovery object property in the component plugin manager does not get its $directories property updated to include the new theme's component directory. So as long as the component plugin definitions aren't cached again before the next request, the component plugins should be updated correctly, which can be seen if with the test rewritten to pass like this:

<?php

declare(strict_types=1);

namespace Drupal\KernelTests\Components;

use Drupal\Core\Theme\Component\ComponentValidator;
use Drupal\Core\Theme\Component\SchemaCompatibilityChecker;
use Drupal\Core\Theme\ComponentNegotiator;
use Drupal\Core\Theme\ComponentPluginManager;

/**
 * Tests discovery of components in a theme being installed.
 */
class ComponentPluginManagerDiscoveryTest extends ComponentKernelTestBase {

  /**
   * {@inheritdoc}
   */
  protected static $themes = ['stark'];

  public function testComponentDiscoveryOnThemeInstall(): void {
    $definitions = \Drupal::service('plugin.manager.sdc')->getDefinitions();
    $this->assertArrayNotHasKey('sdc_theme_test:bar', $definitions);
    \Drupal::service('theme_installer')->install(['sdc_theme_test']);
    \Drupal::service('plugin.manager.sdc')->clearCachedDefinitions();

    // Create a new component plugin manager object to simulate a new plugin
    // manager object instantiated on the next request.
    $manager = new ComponentPluginManager(
      \Drupal::service('module_handler'),
      \Drupal::service('theme_handler'),
      \Drupal::service('cache.discovery'),
      \Drupal::service('config.factory'),
      \Drupal::service('theme.manager'),
      \Drupal::service(ComponentNegotiator::class),
      \Drupal::service('file_system'),
      \Drupal::service(SchemaCompatibilityChecker::class),
      \Drupal::service(ComponentValidator::class),
      \Drupal::getContainer()->getParameter('app.root'),
    );
    $definitions = $manager->getDefinitions();
    $this->assertArrayHasKey('sdc_theme_test:bar', $definitions);
  }

}

So I think there are two things going on:

  1. If the component plugins have been cached before a new theme install, installing a new theme does not clear the cache, and the theme's plugins don't get found
  2. Even if the plugin cache is cleared during theme install, rebuilding the component plugin cache within the same request will not pick up the new plugins because the manager's discovery directories are not rebuilt
nicxvan’s picture

I think @godot is on to something. I pushed up a test case based on the original report and could not reproduce it manually or in the test.

godotislate’s picture

Status: Active » Needs review

MR with fix and test is up. I injected the component plugin manager instead of the plugin cache clearer into the theme installer, since it seemed to be overkill to clear all the plugin caches, but should be easy enough to change if needed.

godotislate changed the visibility of the branch 3522505-new-sdc-components to hidden.

deviantintegral’s picture

Assigned: deviantintegral » Unassigned

Thanks for following up!

mherchel’s picture

StatusFileSize
new2.57 MB
new4.94 MB

Heck yes! This totally fixes the issue for me. I'm attaching two videos:

  1. Part 1: The video showing the issue existing
  2. Part 2: The video showing patch installed, and the issue solved 🙌

Still leaving at NR, since we need a code review and I'm not super qualified for this level of PHP. But confirmed to fix the issue!

penyaskito’s picture

Status: Needs review » Reviewed & tested by the community
godotislate’s picture

acbramley changed the visibility of the branch 3490787-remove-exception-when to hidden.

quietone’s picture

I read the comments in the MR and everything reads well. I updated credit.

larowlan’s picture

Status: Reviewed & tested by the community » Needs work
Issue tags: +Needs change record

One comment about the deprecation notice

Fine to self RTBC after that change

acbramley’s picture

Status: Needs work » Reviewed & tested by the community
Issue tags: -Needs change record

  • larowlan committed e8c0942e on 11.2.x
    Issue #3522505 by godotislate, nicxvan, acbramley, mherchel,...

  • larowlan committed 9ee9a05f on 11.x
    Issue #3522505 by godotislate, nicxvan, acbramley, mherchel,...
larowlan’s picture

Version: 11.x-dev » 11.2.x-dev
Component: single-directory components » theme system
Status: Reviewed & tested by the community » Fixed

Committed to 11.x and 11.2.x

Published change record, thanks folks

Status: Fixed » Closed (fixed)

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