refactor!: make favicon generation settings-driven

Move favicon form work into a dedicated class.

Remove runtime fallback generation from page attachments.

Attach only existing favicon packages at runtime.

Add lifecycle docs and smoke coverage for the policy.

Author: Callin Mullaney

.github/scripts/favicon-portability-smoke.php

@@ -1,5 +1,10 @@
 <?php
 
+/**
+ * @file
+ * Mode-driven favicon portability smoke helper.
+ */
+
 declare(strict_types=1);
 
 use Drupal\emulsify\Favicon\FaviconPackageGenerator;
@@ -75,7 +80,10 @@ function emulsify_favicon_assert_invalid(callable $callback, string $expected_me
     $callback();
   }
   catch (\InvalidArgumentException $exception) {
-    emulsify_favicon_assert(str_contains($exception->getMessage(), $expected_message), sprintf('Expected exception containing "%s", got "%s".', $expected_message, $exception->getMessage()));
+    emulsify_favicon_assert(
+      str_contains($exception->getMessage(), $expected_message),
+      sprintf('Expected exception containing "%s", got "%s".', $expected_message, $exception->getMessage()),
+    );
     return;
   }
 
@@ -128,9 +136,12 @@ function emulsify_favicon_run_sanitizer_matrix(FaviconPackageGenerator $generato
   emulsify_favicon_assert(str_contains((string) $analysis['sanitized_svg'], 'linearGradient'), 'Inline gradients should be preserved.');
 
   $analysis = $generator->validateSourceSvg($raster, FALSE);
-  emulsify_favicon_assert(!empty($analysis['has_embedded_raster_images']), 'Base64 embedded raster images should be detected.');
+  emulsify_favicon_assert(
+    !empty($analysis['has_embedded_raster_images']),
+    'Base64 embedded raster images should be detected.',
+  );
 
-  // Dangerous markup should be stripped without rejecting otherwise usable SVGs.
+  // Dangerous markup should be stripped without rejecting usable SVGs.
   $analysis = $generator->validateSourceSvg('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><script>alert(1)</script><rect width="64" height="64"/></svg>', FALSE);
   emulsify_favicon_assert(!str_contains((string) $analysis['sanitized_svg'], '<script'), 'Script tags should be stripped from sanitized SVG output.');
 

.github/scripts/favicon-smoke.php

@@ -1,18 +1,23 @@
 <?php
 
+/**
+ * @file
+ * Runtime favicon package attachment smoke helper.
+ */
+
 declare(strict_types=1);
 
 use Drupal\emulsify\Favicon\FaviconPackageGenerator;
 use Drupal\emulsify\Favicon\FaviconSettings;
 use Drupal\emulsify\Hook\FaviconHooks;
 
 /**
- * Smoke-tests runtime favicon package generation for a bootstrapped theme.
+ * Smoke-tests favicon package attachment for a bootstrapped theme.
  *
- * favicon-smoke.sh executes this file through `drush php:eval`, so Drupal
+ * Favicon-smoke.sh executes this file through `drush php:eval`, so Drupal
  * services, config, and theme hooks are available exactly as they are during a
- * request. The test stores a portable SVG in theme config, lets the page
- * attachment hook generate the package, then verifies files and head tags.
+ * request. The test proves page attachments do not generate missing files,
+ * then pre-generates a package and verifies existing package head tags.
  */
 $argv = $_SERVER['argv'] ?? [];
 $theme_name = getenv('EMULSIFY_FAVICON_THEME');
@@ -29,17 +34,31 @@
 </svg>
 SVG;
 
+/**
+ * Fails the smoke script with a clear message.
+ */
 function emulsify_favicon_smoke_fail(string $message): void {
   fwrite(STDERR, $message . PHP_EOL);
   exit(1);
 }
 
+/**
+ * Asserts a condition and exits if it fails.
+ */
 function emulsify_favicon_smoke_assert(bool $condition, string $message): void {
   if (!$condition) {
     emulsify_favicon_smoke_fail($message);
   }
 }
 
+/**
+ * Loads normalized theme settings.
+ */
+function emulsify_favicon_smoke_load_settings(string $theme_name, string $site_name): array {
+  $stored = \Drupal::configFactory()->get($theme_name . '.settings')->getRawData();
+  return FaviconSettings::normalize(is_array($stored) ? $stored : [], $site_name);
+}
+
 // The generator can store SVG config without these extensions, but producing
 // PNG/ICO files for the release smoke requires both rasterization stacks.
 if (!class_exists('Imagick')) {
@@ -50,8 +69,8 @@ function emulsify_favicon_smoke_assert(bool $condition, string $message): void {
   emulsify_favicon_smoke_fail('GD is required for favicon smoke tests.');
 }
 
-// Reset package metadata before invoking the hook so this smoke proves package
-// creation rather than accepting files from a previous fixture run.
+// Reset package metadata before invoking the hook so this smoke proves page
+// requests do not create missing package files.
 $config = \Drupal::configFactory()->getEditable($theme_name . '.settings');
 $config
   ->set('favicon_package_enabled', TRUE)
@@ -74,9 +93,23 @@ function emulsify_favicon_smoke_assert(bool $condition, string $message): void {
   ->set('favicon_package_generated_at', 0)
   ->save();
 
-/** @var \Drupal\Core\Theme\ThemeInitializationInterface $theme_initialization */
+$generator = new FaviconPackageGenerator(
+  \Drupal::service('file_system'),
+  \Drupal::service('file_url_generator'),
+  \Drupal::service('config.factory'),
+  \Drupal::service('cache_tags.invalidator'),
+  \Drupal::service('datetime.time'),
+  \Drupal::service('lock'),
+);
+$settings = emulsify_favicon_smoke_load_settings($theme_name, $site_name);
+$definition = $generator->getPackageDefinition($theme_name, $settings, $svg);
+$realpath = \Drupal::service('file_system')->realpath($definition['path']);
+if ($realpath && is_dir($realpath)) {
+  \Drupal::service('file_system')->deleteRecursive($realpath);
+}
+
 $theme_initialization = \Drupal::service('theme.initialization');
-/** @var \Drupal\Core\Theme\ThemeManagerInterface $theme_manager */
+
 $theme_manager = \Drupal::service('theme.manager');
 $theme_manager->setActiveTheme($theme_initialization->initTheme($theme_name));
 
@@ -90,28 +123,31 @@ function emulsify_favicon_smoke_assert(bool $condition, string $message): void {
   ],
 ];
 
-/** @var \Drupal\emulsify\Hook\FaviconHooks $hook_handler */
 $hook_handler = \Drupal::service('class_resolver')->getInstanceFromDefinition(FaviconHooks::class);
 $hook_handler->pageAttachmentsAlter($attachments);
 
-$settings = [];
-foreach (FaviconSettings::DEFAULTS as $key => $default) {
-  $settings[$key] = $config->get($key);
-}
-$settings = FaviconSettings::normalize($settings, $site_name);
+emulsify_favicon_smoke_assert(!$generator->packageExists($definition['path']), 'Runtime page attachments must not generate missing favicon package files.');
+emulsify_favicon_smoke_assert($attachments['#attached']['html_head_link'] === [], 'Runtime page attachments should skip missing favicon packages.');
+emulsify_favicon_smoke_assert($attachments['#attached']['html_head'] === [], 'Runtime page attachments should not add favicon metadata for missing packages.');
 
-$generator = new FaviconPackageGenerator(
-  \Drupal::service('file_system'),
-  \Drupal::service('file_url_generator'),
-  \Drupal::service('config.factory'),
-  \Drupal::service('cache_tags.invalidator'),
-  \Drupal::service('datetime.time'),
-  \Drupal::service('lock'),
+$result = $generator->generateFromSvg(
+  $theme_name,
+  $svg,
+  $settings,
+  [
+    'filename' => 'release-check.svg',
+  ],
 );
-$definition = $generator->getPackageDefinition($theme_name, $settings, $svg);
-$realpath = \Drupal::service('file_system')->realpath($definition['path']);
+$config = \Drupal::configFactory()->getEditable($theme_name . '.settings');
+$config
+  ->set('favicon_package_hash', $result['hash'])
+  ->set('favicon_package_path', $result['path'])
+  ->set('favicon_package_generated_at', $result['generated_at'])
+  ->save();
+
+$realpath = \Drupal::service('file_system')->realpath($result['path']);
 
-emulsify_favicon_smoke_assert((bool) $realpath && is_dir($realpath), "Expected generated favicon package at {$definition['path']}.");
+emulsify_favicon_smoke_assert((bool) $realpath && is_dir($realpath), "Expected generated favicon package at {$result['path']}.");
 
 $expected_files = [
   'favicon.svg',
@@ -135,6 +171,14 @@ function emulsify_favicon_smoke_assert(bool $condition, string $message): void {
 emulsify_favicon_smoke_assert(($manifest_data['display'] ?? '') === 'standalone', 'Generated site.webmanifest is missing the standalone display mode.');
 emulsify_favicon_smoke_assert(($manifest_data['theme_color'] ?? '') === '#005b99', 'Generated site.webmanifest is missing the expected theme color.');
 
+$attachments = [
+  '#attached' => [
+    'html_head' => [],
+    'html_head_link' => [],
+  ],
+];
+$hook_handler->pageAttachmentsAlter($attachments);
+
 $rels = [];
 foreach ($attachments['#attached']['html_head_link'] as $item) {
   $rel = $item[0]['rel'] ?? NULL;
@@ -157,4 +201,4 @@ function emulsify_favicon_smoke_assert(bool $condition, string $message): void {
   emulsify_favicon_smoke_assert(in_array($required_meta, $meta_names, TRUE), "Missing {$required_meta} meta tag.");
 }
 
-fwrite(STDOUT, "Verified favicon package generation and head attachments at {$realpath}.\n");
+fwrite(STDOUT, "Verified favicon package attachment without runtime generation at {$realpath}.\n");

docs/favicon-generation.md

@@ -0,0 +1,62 @@
+# Favicon Package Generation
+
+Emulsify 7.x generates a complete favicon package from one SVG source configured in the Drupal theme settings form for `emulsify` or an Emulsify child theme.
+
+## Requirements
+
+Generated PNG and ICO assets require both PHP extensions:
+
+- GD
+- Imagick
+
+The uploaded source must be an SVG file with a square `viewBox`. If root `width` and `height` values are present, they must also describe a square. The generator accepts embedded raster image data inside the SVG, but the theme settings UI warns that fully vector sources usually scale more cleanly.
+
+Source uploads are limited to 5 MB. The sanitized portable SVG copy is stored in theme config for portability; copies larger than 256 KB are allowed but flagged as review noise because they make config exports harder to inspect.
+
+## Generated Package
+
+Packages are written to the public files directory using a deterministic hash:
+
+```text
+public://favicon-package/<theme_name>/<package_hash>
+```
+
+The hash is derived from the sanitized source SVG and favicon rendering settings. The package path, hash, timestamp, sanitized SVG source, and source filename are stored in `<theme>.settings` so the package can be regenerated in another environment after config import.
+
+Each generated package contains:
+
+- `favicon.svg`
+- `favicon.ico`
+- `favicon-96x96.png`
+- `apple-touch-icon.png`
+- `web-app-manifest-192x192.png`
+- `web-app-manifest-512x512.png`
+- `web-app-manifest-512x512-maskable.png`
+- `site.webmanifest`
+- `metadata.json`
+
+`metadata.json` records the theme name, package hash, generation timestamp, source metadata, normalized favicon settings, source warnings, and generated file list. It is used as the package existence marker.
+
+Do not manually edit generated package files. Change the source SVG or favicon settings, then regenerate the package so metadata, hash, and head attachments stay consistent.
+
+## Lifecycle
+
+Generated favicon packages are environment-local build artifacts. They are expected to exist in each deployed environment, but they should be recreated from configuration rather than treated as hand-maintained source files.
+
+Generation happens only in these workflows:
+
+1. Save the Emulsify Drupal theme settings form after configuring or changing favicon-related settings.
+2. Run the Emulsify Tools Drush generate command after deploy or config import:
+
+```bash
+drush emulsify_tools:favicon-generate [theme_name]
+```
+
+Use Emulsify Tools for deployment diagnostics and reset workflows:
+
+```bash
+drush emulsify_tools:favicon-status [theme_name]
+drush emulsify_tools:favicon-reset [theme_name]
+```
+
+Normal page requests do not create, modify, or regenerate favicon files. At runtime, Emulsify only attaches head tags for an existing generated package. If the configured package path is missing, page rendering continues without generated favicon head tags until the theme settings form or Emulsify Tools command creates the package.

src/Favicon/FaviconHeadBuilder.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Drupal\emulsify\Favicon;
 
 use Drupal\Core\File\FileUrlGeneratorInterface;
@@ -39,31 +41,36 @@ public function apply(array &$attachments, array $settings): void {
       'rel' => 'icon',
       'href' => $this->fileUrlGenerator->generateString($package_path . '/favicon.ico'),
       'sizes' => 'any',
-    ], 'emulsify_favicon_ico'];
+    ], 'emulsify_favicon_ico',
+    ];
 
     $attachments['#attached']['html_head_link'][] = [[
       'rel' => 'icon',
       'type' => 'image/svg+xml',
       'href' => $this->fileUrlGenerator->generateString($package_path . '/favicon.svg'),
-    ], 'emulsify_favicon_svg'];
+    ], 'emulsify_favicon_svg',
+    ];
 
     $attachments['#attached']['html_head_link'][] = [[
       'rel' => 'apple-touch-icon',
       'href' => $this->fileUrlGenerator->generateString($package_path . '/apple-touch-icon.png'),
-    ], 'emulsify_favicon_ios'];
+    ], 'emulsify_favicon_ios',
+    ];
 
     $attachments['#attached']['html_head_link'][] = [[
       'rel' => 'manifest',
       'href' => $this->fileUrlGenerator->generateString($package_path . '/site.webmanifest'),
-    ], 'emulsify_favicon_manifest'];
+    ], 'emulsify_favicon_manifest',
+    ];
 
     $attachments['#attached']['html_head'][] = [[
       '#tag' => 'meta',
       '#attributes' => [
         'name' => 'theme-color',
         'content' => $theme_color,
       ],
-    ], 'emulsify_favicon_theme_color'];
+    ], 'emulsify_favicon_theme_color',
+    ];
 
     if ($icon_name !== '') {
       $attachments['#attached']['html_head'][] = [[
@@ -72,7 +79,8 @@ public function apply(array &$attachments, array $settings): void {
           'name' => 'apple-mobile-web-app-title',
           'content' => $icon_name,
         ],
-      ], 'emulsify_favicon_ios_title'];
+      ], 'emulsify_favicon_ios_title',
+      ];
     }
   }