From 46414697693ee41c93519b778e052e9d361f6993 Mon Sep 17 00:00:00 2001
From: Thorsten Rinne <thorsten@phpmyfaq.de>
Date: Sat, 14 Feb 2026 16:04:54 +0100
Subject: [PATCH 1/5] feat: added theme manager

---
 docs/development.md                           |  43 ++++
 .../admin/assets/src/api/configuration.ts     |   7 +
 .../assets/src/configuration/configuration.ts |  22 ++
 .../admin/configuration/tab-list.twig         |   7 +
 .../admin/configuration/themes.upload.twig    |  31 +++
 .../Controller/AbstractController.php         |   6 +-
 .../Api/ConfigurationTabController.php        |  53 +++++
 phpmyfaq/src/phpMyFAQ/Instance/Client.php     |  51 ++++-
 .../src/phpMyFAQ/Template/ThemeManager.php    | 179 ++++++++++++++++
 phpmyfaq/src/phpMyFAQ/Twig/TwigWrapper.php    |  21 +-
 phpmyfaq/src/services.php                     |   6 +
 .../Api/ConfigurationTabControllerTest.php    |  12 ++
 tests/phpMyFAQ/Instance/ClientTest.php        |  25 ++-
 tests/phpMyFAQ/Template/ThemeManagerTest.php  | 200 ++++++++++++++++++
 tests/phpMyFAQ/Twig/TwigWrapperTest.php       |  19 ++
 15 files changed, 677 insertions(+), 5 deletions(-)
 create mode 100644 phpmyfaq/assets/templates/admin/configuration/themes.upload.twig
 create mode 100644 phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
 create mode 100644 tests/phpMyFAQ/Template/ThemeManagerTest.php

diff --git a/docs/development.md b/docs/development.md
index 29ac168743..678a9f955c 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -496,6 +496,49 @@ Example:
 
     {{ userId | userName }}
 
+### 9.2.3 Dynamic template set and theme upload
+
+phpMyFAQ v4.2 introduced dynamic template set loading and a storage-backed `ThemeManager`.
+
+- Runtime template set is read from configuration key `layout.templateSet`.
+- `TwigWrapper` now validates the requested set and falls back to `default` if the
+  configured set is invalid or missing on disk.
+- Tenant provisioning can skip physical template copies and only persist the
+  template reference in `faqconfig` (`layout.templateSet`).
+
+Theme uploads use `phpMyFAQ\Template\ThemeManager`:
+
+- Input format: ZIP archive.
+- Required file: `index.twig` (theme root or `<themeName>/index.twig`).
+- Allowed file extensions:
+  `.twig`, `.css`, `.js`, `.json`, `.png`, `.jpg`, `.jpeg`, `.svg`, `.webp`, `.gif`,
+  `.woff`, `.woff2`, `.ttf`, `.otf`.
+- Upload target: `StorageInterface` at `<themeRootPath>/<themeName>/...`
+  (default root path: `themes`).
+- Activation: `layout.templateSet` is updated via `ThemeManager::activateTheme()`.
+
+Example usage:
+
+```php
+use phpMyFAQ\Template\ThemeManager;
+
+$themeManager = new ThemeManager($configuration, $storage, 'themes');
+$themeManager->uploadTheme('tenant-theme', '/tmp/tenant-theme.zip');
+$themeManager->activateTheme('tenant-theme');
+```
+
+Admin UI:
+
+- Open `/admin/configuration`
+- Use the `layout` tab
+- Upload ZIP in the `layout` tab
+- Select the template in `layout.templateSet` and save configuration
+
+Security checks:
+
+- Requires `CONFIGURATION_EDIT` permission
+- CSRF token (`theme-manager`) is required for upload/activation
+
 ## 9.8 Working with the Docker containers
 
 ### 9.9.1 Create a new SSL certificate
diff --git a/phpmyfaq/admin/assets/src/api/configuration.ts b/phpmyfaq/admin/assets/src/api/configuration.ts
index 689e317674..1cca798924 100644
--- a/phpmyfaq/admin/assets/src/api/configuration.ts
+++ b/phpmyfaq/admin/assets/src/api/configuration.ts
@@ -146,3 +146,10 @@ export const saveConfiguration = async (data: FormData): Promise<Response> => {
     body: data,
   })) as Response;
 };
+
+export const uploadThemeArchive = async (data: FormData): Promise<Response> => {
+  return (await fetchJson('api/configuration/themes/upload', {
+    method: 'POST',
+    body: data,
+  })) as Response;
+};
diff --git a/phpmyfaq/admin/assets/src/configuration/configuration.ts b/phpmyfaq/admin/assets/src/configuration/configuration.ts
index 74161a8e6d..27a61975c0 100644
--- a/phpmyfaq/admin/assets/src/configuration/configuration.ts
+++ b/phpmyfaq/admin/assets/src/configuration/configuration.ts
@@ -28,6 +28,7 @@ import {
   fetchTemplates,
   fetchTranslations,
   fetchTranslationProvider,
+  uploadThemeArchive,
   saveConfiguration,
 } from '../api';
 import { handleWebPush } from './webpush';
@@ -51,6 +52,7 @@ export const handleConfiguration = async (): Promise<void> => {
             break;
           case '#layout':
             await handleTemplates();
+            await handleThemes();
             break;
           case '#records':
             await handleFaqsSortingKeys();
@@ -270,6 +272,26 @@ export const handleMailProvider = async (): Promise<void> => {
   }
 };
 
+export const handleThemes = async (): Promise<void> => {
+  const uploadForm = document.getElementById('theme-upload-form') as HTMLFormElement | null;
+
+  if (uploadForm) {
+    uploadForm.addEventListener('submit', async (event: Event): Promise<void> => {
+      event.preventDefault();
+
+      const response = (await uploadThemeArchive(new FormData(uploadForm))) as unknown as Response;
+      if (typeof response.success === 'string') {
+        pushNotification(response.success);
+        await handleConfigurationTab('#layout');
+        await handleTemplates();
+        await handleThemes();
+      } else {
+        pushErrorNotification(response.error || 'Theme upload failed.');
+      }
+    });
+  }
+};
+
 export const handleConfigurationTab = async (target: string): Promise<void> => {
   const languageElement = document.getElementById('pmf-language') as HTMLInputElement;
   if (!languageElement) {
diff --git a/phpmyfaq/assets/templates/admin/configuration/tab-list.twig b/phpmyfaq/assets/templates/admin/configuration/tab-list.twig
index d73100c1d2..af91109b21 100644
--- a/phpmyfaq/assets/templates/admin/configuration/tab-list.twig
+++ b/phpmyfaq/assets/templates/admin/configuration/tab-list.twig
@@ -20,6 +20,13 @@
   </div>
 {% endfor %}
 
+{% if mode == 'layout' %}
+  {% include '@admin/configuration/themes.upload.twig' with {
+    csrfToken: themeCsrfToken,
+    activeTheme: activeTheme
+  } only %}
+{% endif %}
+
 <script>
   try {
     const generateUUID = () => {
diff --git a/phpmyfaq/assets/templates/admin/configuration/themes.upload.twig b/phpmyfaq/assets/templates/admin/configuration/themes.upload.twig
new file mode 100644
index 0000000000..42bb37a68e
--- /dev/null
+++ b/phpmyfaq/assets/templates/admin/configuration/themes.upload.twig
@@ -0,0 +1,31 @@
+<div class="row mb-3">
+  <div class="col-lg-12">
+    <div class="card shadow-sm">
+      <div class="card-body">
+        <h3 class="h5 mb-3">Upload Theme ZIP</h3>
+        <p class="text-muted small mb-3">
+          ZIP must include <code>index.twig</code>. Select the uploaded theme below using and save the configuration.
+        </p>
+        <form id="theme-upload-form" method="post" action="#" enctype="multipart/form-data">
+          <input type="hidden" name="pmf-csrf-token" value="{{ csrfToken }}">
+          <div class="row">
+            <div class="col-md-4 mb-3">
+              <label for="themeName" class="form-label">Theme Name</label>
+              <input type="text" class="form-control" id="themeName" name="themeName" placeholder="Theme Name">
+            </div>
+            <div class="col-md-6 mb-3">
+              <label for="themeArchive" class="form-label">ZIP File</label>
+              <input type="file" class="form-control" id="themeArchive" name="themeArchive" accept=".zip" required>
+            </div>
+            <div class="col-md-2 mb-3 d-flex align-items-end">
+              <button type="submit" class="btn btn-success w-100">
+                <i class="bi bi-upload" aria-hidden="true"></i>
+                Upload
+              </button>
+            </div>
+          </div>
+        </form>
+      </div>
+    </div>
+  </div>
+</div>
diff --git a/phpmyfaq/src/phpMyFAQ/Controller/AbstractController.php b/phpmyfaq/src/phpMyFAQ/Controller/AbstractController.php
index 3b314e8e81..353f0e1b71 100644
--- a/phpmyfaq/src/phpMyFAQ/Controller/AbstractController.php
+++ b/phpmyfaq/src/phpMyFAQ/Controller/AbstractController.php
@@ -130,7 +130,11 @@ public function json(mixed $data, int $status = 200, array $headers = []): JsonR
      */
     public function getTwigWrapper(): TwigWrapper
     {
-        $twigWrapper = new TwigWrapper(PMF_ROOT_DIR . '/assets/templates');
+        $twigWrapper = new TwigWrapper(
+            PMF_ROOT_DIR . '/assets/templates',
+            false,
+            $this->configuration->getTemplateSet(),
+        );
 
         foreach ($this->twigExtensions as $twigExtension) {
             $twigWrapper->addExtension($twigExtension);
diff --git a/phpmyfaq/src/phpMyFAQ/Controller/Administration/Api/ConfigurationTabController.php b/phpmyfaq/src/phpMyFAQ/Controller/Administration/Api/ConfigurationTabController.php
index fc95fccf16..8d86ad2077 100644
--- a/phpmyfaq/src/phpMyFAQ/Controller/Administration/Api/ConfigurationTabController.php
+++ b/phpmyfaq/src/phpMyFAQ/Controller/Administration/Api/ConfigurationTabController.php
@@ -28,9 +28,11 @@
 use phpMyFAQ\Helper\PermissionHelper;
 use phpMyFAQ\Session\Token;
 use phpMyFAQ\Strings;
+use phpMyFAQ\Template\ThemeManager;
 use phpMyFAQ\Translation;
 use phpMyFAQ\Twig\TemplateException;
 use Symfony\Component\HttpFoundation\Exception\BadRequestException;
+use Symfony\Component\HttpFoundation\File\UploadedFile;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
@@ -77,9 +79,44 @@ public function list(Request $request): Response
                 'ssoSupport' => Request::createFromGlobals()->server->get(key: 'REMOTE_USER'),
                 'buttonTes',
             ],
+            'themeCsrfToken' => Token::getInstance($this->session)->getTokenString('theme-manager'),
+            'activeTheme' => (string) $this->configuration->get('layout.templateSet'),
         ]);
     }
 
+    /**
+     * @throws \Exception
+     */
+    #[Route(path: 'configuration/themes/upload', name: 'admin.api.configuration.themes.upload', methods: ['POST'])]
+    public function uploadTheme(Request $request): JsonResponse
+    {
+        $this->userHasPermission(PermissionType::CONFIGURATION_EDIT);
+
+        if (!$this->hasValidThemeCsrfToken($request)) {
+            return $this->json(['error' => Translation::get(key: 'msgNoPermission')], Response::HTTP_UNAUTHORIZED);
+        }
+
+        $file = $request->files->get('themeArchive');
+        if (!$file instanceof UploadedFile || !$file->isValid()) {
+            return $this->json(['error' => 'No valid ZIP file uploaded.'], Response::HTTP_BAD_REQUEST);
+        }
+
+        $themeName = trim((string) $request->request->get('themeName', ''));
+        if ($themeName === '') {
+            $themeName = pathinfo((string) $file->getClientOriginalName(), PATHINFO_FILENAME);
+        }
+
+        try {
+            $uploadedFiles = $this->themeManager()->uploadTheme($themeName, $file->getPathname());
+
+            return $this->json([
+                'success' => sprintf('Theme "%s" uploaded (%d files).', $themeName, $uploadedFiles),
+            ], Response::HTTP_OK);
+        } catch (\RuntimeException $runtimeException) {
+            return $this->json(['error' => $runtimeException->getMessage()], Response::HTTP_BAD_REQUEST);
+        }
+    }
+
     /**
      * @throws \Exception
      */
@@ -472,4 +509,20 @@ private function convertToString(mixed $value): string
 
         return 'unknown';
     }
+
+    private function hasValidThemeCsrfToken(Request $request): bool
+    {
+        $csrfToken = (string) $request->request->get('pmf-csrf-token', '');
+        return Token::getInstance($this->session)->verifyToken('theme-manager', $csrfToken);
+    }
+
+    private function themeManager(): ThemeManager
+    {
+        $themeManager = $this->container->get(id: 'phpmyfaq.template.theme-manager');
+        if (!$themeManager instanceof ThemeManager) {
+            throw new BadRequestException('Theme manager service is not available.');
+        }
+
+        return $themeManager;
+    }
 }
diff --git a/phpmyfaq/src/phpMyFAQ/Instance/Client.php b/phpmyfaq/src/phpMyFAQ/Instance/Client.php
index ac5674b095..54eee6b846 100644
--- a/phpmyfaq/src/phpMyFAQ/Instance/Client.php
+++ b/phpmyfaq/src/phpMyFAQ/Instance/Client.php
@@ -40,6 +40,8 @@ class Client extends Instance
 
     private string $clientUrl;
 
+    private string $clientTemplateSet = 'default';
+
     /**
      * Constructor.
      */
@@ -58,6 +60,16 @@ public function setClientUrl(string $clientUrl): void
         $this->clientUrl = $clientUrl;
     }
 
+    public function setClientTemplateSet(string $templateSet): void
+    {
+        $templateSet = trim($templateSet);
+        if ($templateSet === '') {
+            $templateSet = 'default';
+        }
+
+        $this->clientTemplateSet = $templateSet;
+    }
+
     /**
      * Sets the Filesystem.
      */
@@ -273,6 +285,17 @@ private function copyBaseDataToSchema(string $schema): void
             $sourcePrefix,
         );
 
+        $this->executeSchemaQuery(
+            sprintf(
+                "UPDATE %sfaqconfig SET config_value = '%s' WHERE config_name = 'layout.templateSet'",
+                $targetPrefix,
+                $this->configuration->getDb()->escape($this->clientTemplateSet),
+            ),
+            'UPDATE faqconfig',
+            $targetPrefix,
+            $sourcePrefix,
+        );
+
         $this->executeSchemaQuery(
             sprintf('INSERT INTO %sfaqright SELECT * FROM %sfaqright', $targetPrefix, $sourcePrefix),
             'INSERT faqright',
@@ -369,6 +392,13 @@ private function insertSeedRows(string $prefix, array $seedRows): void
                 $prefix,
                 $this->configuration->getDb()->escape($this->clientUrl),
             ));
+        $this->configuration
+            ->getDb()
+            ->query(sprintf(
+                "UPDATE %sfaqconfig SET config_value = '%s' WHERE config_name = 'layout.templateSet'",
+                $prefix,
+                $this->configuration->getDb()->escape($this->clientTemplateSet),
+            ));
 
         $this->insertRows($prefix . 'faqright', $seedRows['faqright'] ?? []);
         $this->insertRows($prefix . 'faquser_right', $seedRows['faquser_right'] ?? []);
@@ -451,6 +481,13 @@ public function createClientTables(string $prefix): void
                     $prefix,
                     $this->clientUrl,
                 ));
+            $this->configuration
+                ->getDb()
+                ->query(sprintf(
+                    "UPDATE %sfaqconfig SET config_value = '%s' WHERE config_name = 'layout.templateSet'",
+                    $prefix,
+                    $this->configuration->getDb()->escape($this->clientTemplateSet),
+                ));
             $this->configuration
                 ->getDb()
                 ->query(sprintf(
@@ -495,10 +532,20 @@ public function copyConstantsFile(string $destination): bool
      *
      * @param string $destination Destination folder
      * @param string $templateDir Template folder
+     * @param bool $copyTemplateFiles Set to false to only reference the template set in config
      * @throws Exception
      */
-    public function copyTemplateFolder(string $destination, string $templateDir = 'default'): void
-    {
+    public function copyTemplateFolder(
+        string $destination,
+        string $templateDir = 'default',
+        bool $copyTemplateFiles = true,
+    ): void {
+        $this->setClientTemplateSet($templateDir);
+
+        if (!$copyTemplateFiles) {
+            return;
+        }
+
         $sourceTpl = $this->filesystem->getRootPath() . '/assets/templates/' . $templateDir;
         $destTpl = $destination . '/assets/templates/';
 
diff --git a/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php b/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
new file mode 100644
index 0000000000..9ef16a6fc4
--- /dev/null
+++ b/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
@@ -0,0 +1,179 @@
+<?php
+
+/**
+ * Storage-backed theme upload and activation manager.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public License,
+ * v. 2.0. If a copy of the MPL was not distributed with this file, You can
+ * obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * @package   phpMyFAQ
+ * @author    Thorsten Rinne <thorsten@phpmyfaq.de>
+ * @copyright 2026 phpMyFAQ Team
+ * @license   https://www.mozilla.org/MPL/2.0/ Mozilla Public License Version 2.0
+ * @link      https://www.phpmyfaq.de
+ * @since     2026-02-14
+ */
+
+declare(strict_types=1);
+
+namespace phpMyFAQ\Template;
+
+use phpMyFAQ\Configuration;
+use phpMyFAQ\Storage\StorageInterface;
+use RuntimeException;
+use ZipArchive;
+
+readonly class ThemeManager
+{
+    public function __construct(
+        private Configuration $configuration,
+        private StorageInterface $storage,
+        private string $themeRootPath = 'themes',
+    ) {
+    }
+
+    /**
+     * Validates and uploads a ZIP-based theme into the configured storage.
+     *
+     * @throws RuntimeException
+     */
+    public function uploadTheme(string $themeName, string $archivePath): int
+    {
+        $this->assertValidThemeName($themeName);
+        $this->assertArchiveIsReadable($archivePath);
+
+        if (!class_exists(ZipArchive::class)) {
+            throw new RuntimeException('Theme upload requires the PHP zip extension (ZipArchive).');
+        }
+
+        $zip = new ZipArchive();
+        if ($zip->open($archivePath) !== true) {
+            throw new RuntimeException('Failed to open theme archive.');
+        }
+
+        $uploadedFiles = 0;
+        $containsIndexTemplate = false;
+
+        try {
+            for ($index = 0; $index < $zip->numFiles; $index++) {
+                $entryName = $zip->getNameIndex($index);
+                if ($entryName === false) {
+                    continue;
+                }
+
+                $normalizedEntryPath = $this->normalizeArchivePath($entryName, $themeName);
+                if ($normalizedEntryPath === '' || str_ends_with($normalizedEntryPath, '/')) {
+                    continue;
+                }
+
+                $this->assertAllowedFileExtension($normalizedEntryPath);
+
+                $contents = $zip->getFromIndex($index);
+                if (!is_string($contents)) {
+                    throw new RuntimeException(sprintf('Failed to read archive entry "%s".', $entryName));
+                }
+
+                if ($normalizedEntryPath === 'index.twig') {
+                    $containsIndexTemplate = true;
+                }
+
+                $storagePath = $this->themeStoragePath($themeName, $normalizedEntryPath);
+                $this->storage->put($storagePath, $contents);
+                $uploadedFiles++;
+            }
+        } finally {
+            $zip->close();
+        }
+
+        if (!$containsIndexTemplate) {
+            throw new RuntimeException('Invalid theme archive: missing required "index.twig".');
+        }
+
+        if ($uploadedFiles === 0) {
+            throw new RuntimeException('Theme archive does not contain uploadable files.');
+        }
+
+        return $uploadedFiles;
+    }
+
+    public function activateTheme(string $themeName): bool
+    {
+        $this->assertValidThemeName($themeName);
+        return $this->configuration->set('layout.templateSet', $themeName);
+    }
+
+    public function activateDefaultTheme(): bool
+    {
+        return $this->configuration->set('layout.templateSet', 'default');
+    }
+
+    public function getThemeRootPath(): string
+    {
+        return trim($this->themeRootPath, '/');
+    }
+
+    private function themeStoragePath(string $themeName, string $relativePath = ''): string
+    {
+        $basePath = trim($this->themeRootPath, '/') . '/' . $themeName;
+        $relativePath = ltrim($relativePath, '/');
+
+        if ($relativePath === '') {
+            return $basePath;
+        }
+
+        return $basePath . '/' . $relativePath;
+    }
+
+    private function assertValidThemeName(string $themeName): void
+    {
+        if (!preg_match('/^[A-Za-z0-9_-]{2,64}$/', $themeName)) {
+            throw new RuntimeException('Invalid theme name. Allowed: letters, numbers, "_" and "-".');
+        }
+    }
+
+    private function assertArchiveIsReadable(string $archivePath): void
+    {
+        if (!is_file($archivePath) || !is_readable($archivePath)) {
+            throw new RuntimeException('Theme archive file is missing or not readable.');
+        }
+    }
+
+    private function normalizeArchivePath(string $entryName, string $themeName): string
+    {
+        $normalizedPath = str_replace('\\', '/', trim($entryName));
+        $normalizedPath = ltrim($normalizedPath, '/');
+
+        // Flatten root folder archives: "mytheme/index.twig" -> "index.twig".
+        $pathParts = array_values(array_filter(
+            explode('/', $normalizedPath),
+            static fn(string $part): bool => $part !== '',
+        ));
+        if (count($pathParts) > 1 && $pathParts[0] === $themeName) {
+            $pathParts = array_slice($pathParts, 1);
+        }
+
+        $rebuiltPath = implode('/', $pathParts);
+        if ($rebuiltPath === '') {
+            return '';
+        }
+
+        if (str_contains($rebuiltPath, '..')) {
+            throw new RuntimeException('Theme archive contains invalid relative paths.');
+        }
+
+        return $rebuiltPath;
+    }
+
+    private function assertAllowedFileExtension(string $path): void
+    {
+        if (!$this->isAllowedFileExtension($path)) {
+            throw new RuntimeException(sprintf('Theme file type is not allowed: %s', $path));
+        }
+    }
+
+    private function isAllowedFileExtension(string $path): bool
+    {
+        return (bool) preg_match('/\.(twig|css|js|json|png|jpg|jpeg|svg|webp|gif|woff2?|ttf|otf)$/i', $path);
+    }
+}
diff --git a/phpmyfaq/src/phpMyFAQ/Twig/TwigWrapper.php b/phpmyfaq/src/phpMyFAQ/Twig/TwigWrapper.php
index 5f25bd5fb4..ac46f5627a 100644
--- a/phpmyfaq/src/phpMyFAQ/Twig/TwigWrapper.php
+++ b/phpmyfaq/src/phpMyFAQ/Twig/TwigWrapper.php
@@ -50,9 +50,13 @@ public function __construct(
         string $templatePath,
         /* @mago-ignore lint:no-boolean-flag-parameter */
         private bool $isSetup = false,
+        ?string $templateSetName = null,
     ) {
+        $resolvedTemplateSet = $this->resolveTemplateSetName($templatePath, $templateSetName);
+        self::$templateSetName = $resolvedTemplateSet;
+
         $filesystemLoader = new FilesystemLoader();
-        $filesystemLoader->addPath($templatePath . '/' . self::$templateSetName);
+        $filesystemLoader->addPath($templatePath . '/' . $resolvedTemplateSet);
         $filesystemLoader->addPath($templatePath . '/admin', namespace: 'admin');
         $filesystemLoader->addPath($templatePath . '/setup', namespace: 'setup');
 
@@ -126,4 +130,19 @@ public static function setTemplateSetName(string $tplSetName = 'default'): void
     {
         self::$templateSetName = $tplSetName;
     }
+
+    private function resolveTemplateSetName(string $templatePath, ?string $templateSetName): string
+    {
+        $requestedTemplateSet = trim((string) ($templateSetName ?? self::$templateSetName));
+        if ($requestedTemplateSet === '' || !preg_match('/^[A-Za-z0-9_-]+$/', $requestedTemplateSet)) {
+            $requestedTemplateSet = 'default';
+        }
+
+        $requestedPath = $templatePath . '/' . $requestedTemplateSet;
+        if (is_dir($requestedPath)) {
+            return $requestedTemplateSet;
+        }
+
+        return 'default';
+    }
 }
diff --git a/phpmyfaq/src/services.php b/phpmyfaq/src/services.php
index 819987a5e7..101fd55d18 100644
--- a/phpmyfaq/src/services.php
+++ b/phpmyfaq/src/services.php
@@ -106,6 +106,7 @@
 use phpMyFAQ\StopWords;
 use phpMyFAQ\System;
 use phpMyFAQ\Tags;
+use phpMyFAQ\Template\ThemeManager;
 use phpMyFAQ\Tenant\TenantContext;
 use phpMyFAQ\Tenant\TenantContextResolver;
 use phpMyFAQ\Tenant\TenantEventDispatcher;
@@ -523,6 +524,11 @@
         service('phpmyfaq.configuration'),
     ]);
 
+    $services->set('phpmyfaq.template.theme-manager', ThemeManager::class)->args([
+        service('phpmyfaq.configuration'),
+        service('phpmyfaq.storage'),
+    ]);
+
     // HTTP Client for Translation APIs
     $services
         ->set('phpmyfaq.http-client', HttpClientInterface::class)
diff --git a/tests/phpMyFAQ/Controller/Administration/Api/ConfigurationTabControllerTest.php b/tests/phpMyFAQ/Controller/Administration/Api/ConfigurationTabControllerTest.php
index 4ceb2ca149..a85cba5908 100644
--- a/tests/phpMyFAQ/Controller/Administration/Api/ConfigurationTabControllerTest.php
+++ b/tests/phpMyFAQ/Controller/Administration/Api/ConfigurationTabControllerTest.php
@@ -176,4 +176,16 @@ public function testSaveWithMissingCsrfTokenThrowsException(): void
         $this->expectException(\Exception::class);
         $controller->save($request);
     }
+
+    /**
+     * @throws \Exception
+     */
+    public function testUploadThemeRequiresAuthentication(): void
+    {
+        $request = new Request();
+        $controller = new ConfigurationTabController();
+
+        $this->expectException(\Exception::class);
+        $controller->uploadTheme($request);
+    }
 }
diff --git a/tests/phpMyFAQ/Instance/ClientTest.php b/tests/phpMyFAQ/Instance/ClientTest.php
index 94dfe7ab03..038eedb325 100644
--- a/tests/phpMyFAQ/Instance/ClientTest.php
+++ b/tests/phpMyFAQ/Instance/ClientTest.php
@@ -60,10 +60,20 @@ public function testCreateClientTables(): void
         $dbMock = $this->createMock(DatabaseDriver::class);
         $this->configuration->method('getDb')->willReturn($dbMock);
 
-        $dbMock->expects($this->exactly(5))->method('query');
+        $queries = [];
+        $dbMock
+            ->method('query')
+            ->willReturnCallback(static function (string $query) use (&$queries): bool {
+                $queries[] = $query;
+                return true;
+            });
+        $dbMock->method('escape')->willReturnCallback(static fn(string $value): string => $value);
 
         $this->client->setClientUrl('https://example.com');
+        $this->client->setClientTemplateSet('tenant-theme');
         $this->client->createClientTables($prefix);
+
+        $this->assertTrue($this->queryContains($queries, "WHERE config_name = 'layout.templateSet'"));
     }
 
     public function testCopyConstantsFile(): void
@@ -86,6 +96,15 @@ public function testCopyTemplateFolder(): void
         $this->client->copyTemplateFolder($destination, $templateDir);
     }
 
+    public function testCopyTemplateFolderWithoutCopyOnlyUpdatesTemplateReference(): void
+    {
+        $this->filesystem->expects($this->never())->method('recursiveCopy');
+
+        $this->client->copyTemplateFolder('/path/to/destination', 'tenant-theme', false);
+
+        $this->assertTrue(true);
+    }
+
     public function testMoveClientFolder(): void
     {
         $sourceUrl = 'https://source.com';
@@ -142,6 +161,10 @@ public function testCreateClientDatabaseWithSchemaMode(): void
         $this->assertNotEmpty($queries);
         $this->assertTrue($this->queryContains($queries, 'SET search_path TO "tenant_schema"'));
         $this->assertContains('INSERT INTO "tenant_schema".faqconfig SELECT * FROM faqconfig', $queries);
+        $this->assertContains(
+            "UPDATE \"tenant_schema\".faqconfig SET config_value = 'default' WHERE config_name = 'layout.templateSet'",
+            $queries,
+        );
         $this->assertContains('INSERT INTO "tenant_schema".faqright SELECT * FROM faqright', $queries);
         $this->assertContains(
             'INSERT INTO "tenant_schema".faquser_right SELECT * FROM faquser_right WHERE user_id = 1',
diff --git a/tests/phpMyFAQ/Template/ThemeManagerTest.php b/tests/phpMyFAQ/Template/ThemeManagerTest.php
new file mode 100644
index 0000000000..6107c9922d
--- /dev/null
+++ b/tests/phpMyFAQ/Template/ThemeManagerTest.php
@@ -0,0 +1,200 @@
+<?php
+
+namespace phpMyFAQ\Template;
+
+use phpMyFAQ\Configuration;
+use phpMyFAQ\Storage\StorageInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+use ZipArchive;
+
+#[CoversClass(ThemeManager::class)]
+class ThemeManagerTest extends TestCase
+{
+    public function testUploadThemeStoresArchiveContentsInStorage(): void
+    {
+        if (!class_exists(ZipArchive::class)) {
+            $this->markTestSkipped('ZipArchive is not available in this environment.');
+        }
+
+        $archivePath = $this->createThemeArchive([
+            'tenant-theme/index.twig' => '<h1>Hello</h1>',
+            'tenant-theme/assets/theme.css' => 'body { color: #000; }',
+        ]);
+
+        try {
+            $configuration = $this->createStub(Configuration::class);
+            $storage = new InMemoryStorage();
+            $manager = new ThemeManager($configuration, $storage, 'themes');
+
+            $uploadedFiles = $manager->uploadTheme('tenant-theme', $archivePath);
+
+            $this->assertSame(2, $uploadedFiles);
+            $this->assertTrue($storage->exists('themes/tenant-theme/index.twig'));
+            $this->assertTrue($storage->exists('themes/tenant-theme/assets/theme.css'));
+            $this->assertSame('<h1>Hello</h1>', $storage->get('themes/tenant-theme/index.twig'));
+        } finally {
+            @unlink($archivePath);
+        }
+    }
+
+    public function testUploadThemeRejectsArchiveWithoutIndexTwig(): void
+    {
+        if (!class_exists(ZipArchive::class)) {
+            $this->markTestSkipped('ZipArchive is not available in this environment.');
+        }
+
+        $archivePath = $this->createThemeArchive([
+            'tenant-theme/assets/theme.css' => 'body { color: #000; }',
+        ]);
+
+        try {
+            $configuration = $this->createStub(Configuration::class);
+            $storage = new InMemoryStorage();
+            $manager = new ThemeManager($configuration, $storage, 'themes');
+
+            $this->expectException(RuntimeException::class);
+            $this->expectExceptionMessage('missing required "index.twig"');
+
+            $manager->uploadTheme('tenant-theme', $archivePath);
+        } finally {
+            @unlink($archivePath);
+        }
+    }
+
+    public function testUploadThemeRejectsDisallowedFileExtension(): void
+    {
+        if (!class_exists(ZipArchive::class)) {
+            $this->markTestSkipped('ZipArchive is not available in this environment.');
+        }
+
+        $archivePath = $this->createThemeArchive([
+            'tenant-theme/index.twig' => '<h1>Hello</h1>',
+            'tenant-theme/payload.php' => '<?php echo "x";',
+        ]);
+
+        try {
+            $configuration = $this->createStub(Configuration::class);
+            $storage = new InMemoryStorage();
+            $manager = new ThemeManager($configuration, $storage, 'themes');
+
+            $this->expectException(RuntimeException::class);
+            $this->expectExceptionMessage('Theme file type is not allowed');
+
+            $manager->uploadTheme('tenant-theme', $archivePath);
+        } finally {
+            @unlink($archivePath);
+        }
+    }
+
+    public function testActivateThemePersistsTemplateSetConfig(): void
+    {
+        $configuration = $this->createMock(Configuration::class);
+        $configuration
+            ->expects($this->once())
+            ->method('set')
+            ->with('layout.templateSet', 'tenant-theme')
+            ->willReturn(true);
+
+        $manager = new ThemeManager($configuration, new InMemoryStorage(), 'themes');
+        $this->assertTrue($manager->activateTheme('tenant-theme'));
+    }
+
+    public function testActivateDefaultThemePersistsDefaultTemplateSetConfig(): void
+    {
+        $configuration = $this->createMock(Configuration::class);
+        $configuration->expects($this->once())->method('set')->with('layout.templateSet', 'default')->willReturn(true);
+
+        $manager = new ThemeManager($configuration, new InMemoryStorage(), 'themes');
+        $this->assertTrue($manager->activateDefaultTheme());
+    }
+
+    public function testUploadThemeRejectsInvalidThemeName(): void
+    {
+        $configuration = $this->createStub(Configuration::class);
+        $manager = new ThemeManager($configuration, new InMemoryStorage(), 'themes');
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage('Invalid theme name');
+
+        $manager->activateTheme('../invalid');
+    }
+
+    /**
+     * @param array<string, string> $entries
+     */
+    private function createThemeArchive(array $entries): string
+    {
+        $archivePath = tempnam(sys_get_temp_dir(), 'pmf-theme-');
+        if ($archivePath === false) {
+            $this->fail('Failed to create temp archive file.');
+        }
+
+        $zip = new ZipArchive();
+        $opened = $zip->open($archivePath, ZipArchive::CREATE | ZipArchive::OVERWRITE);
+        if ($opened !== true) {
+            $this->fail('Failed to create zip archive.');
+        }
+
+        foreach ($entries as $name => $content) {
+            $zip->addFromString($name, $content);
+        }
+
+        $zip->close();
+        return $archivePath;
+    }
+}
+
+class InMemoryStorage implements StorageInterface
+{
+    /** @var array<string, string> */
+    private array $files = [];
+
+    public function put(string $path, string $contents): bool
+    {
+        $this->files[$path] = $contents;
+        return true;
+    }
+
+    public function putStream(string $path, mixed $stream): bool
+    {
+        $contents = stream_get_contents($stream);
+        if (!is_string($contents)) {
+            return false;
+        }
+
+        $this->files[$path] = $contents;
+        return true;
+    }
+
+    public function get(string $path): string
+    {
+        if (!isset($this->files[$path])) {
+            throw new RuntimeException('File not found in in-memory storage.');
+        }
+
+        return $this->files[$path];
+    }
+
+    public function delete(string $path): bool
+    {
+        unset($this->files[$path]);
+        return true;
+    }
+
+    public function exists(string $path): bool
+    {
+        return isset($this->files[$path]);
+    }
+
+    public function url(string $path): string
+    {
+        return 'memory://' . $path;
+    }
+
+    public function size(string $path): int
+    {
+        return strlen($this->get($path));
+    }
+}
diff --git a/tests/phpMyFAQ/Twig/TwigWrapperTest.php b/tests/phpMyFAQ/Twig/TwigWrapperTest.php
index d9bd5c5e03..1fd255252b 100644
--- a/tests/phpMyFAQ/Twig/TwigWrapperTest.php
+++ b/tests/phpMyFAQ/Twig/TwigWrapperTest.php
@@ -21,6 +21,7 @@ class TwigWrapperTest extends TestCase
      */
     protected function setUp(): void
     {
+        TwigWrapper::setTemplateSetName();
         $this->twigWrapper = new TwigWrapper($this->templatePath);
     }
 
@@ -106,4 +107,22 @@ public function testSetTemplateSetName(): void
         $this->assertEquals('newTemplateSet', TwigWrapper::getTemplateSetName());
         TwigWrapper::setTemplateSetName();
     }
+
+    public function testConstructorFallsBackToDefaultForMissingTemplateSet(): void
+    {
+        $twigWrapper = new TwigWrapper($this->templatePath, false, 'missing-template-set');
+        $template = $twigWrapper->loadTemplate('index.twig');
+
+        $this->assertInstanceOf(TemplateWrapper::class, $template);
+        $this->assertEquals('default', TwigWrapper::getTemplateSetName());
+    }
+
+    public function testConstructorFallsBackToDefaultForInvalidTemplateSetName(): void
+    {
+        $twigWrapper = new TwigWrapper($this->templatePath, false, '../invalid');
+        $template = $twigWrapper->loadTemplate('index.twig');
+
+        $this->assertInstanceOf(TemplateWrapper::class, $template);
+        $this->assertEquals('default', TwigWrapper::getTemplateSetName());
+    }
 }

From 87d1ce8bd9e3bdbe182e4d94bb41d86081b7332f Mon Sep 17 00:00:00 2001
From: Thorsten Rinne <thorsten@phpmyfaq.de>
Date: Sat, 14 Feb 2026 16:18:12 +0100
Subject: [PATCH 2/5] fix: corrected review notes

---
 docs/development.md                           | 88 +++++++++----------
 .../admin/configuration/themes.upload.twig    |  2 +-
 .../src/phpMyFAQ/Template/ThemeManager.php    | 15 ++--
 tests/phpMyFAQ/Template/ThemeManagerTest.php  | 13 ++-
 4 files changed, 67 insertions(+), 51 deletions(-)

diff --git a/docs/development.md b/docs/development.md
index 678a9f955c..81efda476e 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -160,12 +160,55 @@ You can then use the `dump` function in your templates.
 
 For more detailed information, visit the [Twig documentation](https://twig.symfony.com/doc/).
 
-### 9.2.2 Admin backend templates
+### 9.2.3 Admin backend templates
 
 The admin backend templates are located in the **assets/templates/admin** directory.
 Usually, you don't need to modify these templates, but if you want to, you can do so.
 Please be aware that changes to the admin backend templates can break the functionality of phpMyFAQ.
 
+### 9.2.4 Dynamic template set and theme upload
+
+phpMyFAQ v4.2 introduced dynamic template set loading and a storage-backed `ThemeManager`.
+
+- Runtime template set is read from configuration key `layout.templateSet`.
+- `TwigWrapper` now validates the requested set and falls back to `default` if the
+  configured set is invalid or missing on disk.
+- Tenant provisioning can skip physical template copies and only persist the
+  template reference in `faqconfig` (`layout.templateSet`).
+
+Theme uploads use `phpMyFAQ\Template\ThemeManager`:
+
+- Input format: ZIP archive.
+- Required file: `index.twig` (theme root or `<themeName>/index.twig`).
+- Allowed file extensions:
+  `.twig`, `.css`, `.js`, `.json`, `.png`, `.jpg`, `.jpeg`, `.svg`, `.webp`, `.gif`,
+  `.woff`, `.woff2`, `.ttf`, `.otf`.
+- Upload target: `StorageInterface` at `<themeRootPath>/<themeName>/...`
+  (default root path: `themes`).
+- Activation: `layout.templateSet` is updated via `ThemeManager::activateTheme()`.
+
+Example usage:
+
+```php
+use phpMyFAQ\Template\ThemeManager;
+
+$themeManager = new ThemeManager($configuration, $storage, 'themes');
+$themeManager->uploadTheme('tenant-theme', '/tmp/tenant-theme.zip');
+$themeManager->activateTheme('tenant-theme');
+```
+
+Admin UI:
+
+- Open `/admin/configuration`
+- Use the `layout` tab
+- Upload ZIP in the `layout` tab
+- Select the template in `layout.templateSet` and save configuration
+
+Security checks:
+
+- Requires `CONFIGURATION_EDIT` permission
+- CSRF token (`theme-manager`) is required for upload/activation
+
 ## 9.3 Themes
 
 The default CSS theme is located in the **assets/templates/default** directory and is stored in the file **theme.css**.
@@ -496,49 +539,6 @@ Example:
 
     {{ userId | userName }}
 
-### 9.2.3 Dynamic template set and theme upload
-
-phpMyFAQ v4.2 introduced dynamic template set loading and a storage-backed `ThemeManager`.
-
-- Runtime template set is read from configuration key `layout.templateSet`.
-- `TwigWrapper` now validates the requested set and falls back to `default` if the
-  configured set is invalid or missing on disk.
-- Tenant provisioning can skip physical template copies and only persist the
-  template reference in `faqconfig` (`layout.templateSet`).
-
-Theme uploads use `phpMyFAQ\Template\ThemeManager`:
-
-- Input format: ZIP archive.
-- Required file: `index.twig` (theme root or `<themeName>/index.twig`).
-- Allowed file extensions:
-  `.twig`, `.css`, `.js`, `.json`, `.png`, `.jpg`, `.jpeg`, `.svg`, `.webp`, `.gif`,
-  `.woff`, `.woff2`, `.ttf`, `.otf`.
-- Upload target: `StorageInterface` at `<themeRootPath>/<themeName>/...`
-  (default root path: `themes`).
-- Activation: `layout.templateSet` is updated via `ThemeManager::activateTheme()`.
-
-Example usage:
-
-```php
-use phpMyFAQ\Template\ThemeManager;
-
-$themeManager = new ThemeManager($configuration, $storage, 'themes');
-$themeManager->uploadTheme('tenant-theme', '/tmp/tenant-theme.zip');
-$themeManager->activateTheme('tenant-theme');
-```
-
-Admin UI:
-
-- Open `/admin/configuration`
-- Use the `layout` tab
-- Upload ZIP in the `layout` tab
-- Select the template in `layout.templateSet` and save configuration
-
-Security checks:
-
-- Requires `CONFIGURATION_EDIT` permission
-- CSRF token (`theme-manager`) is required for upload/activation
-
 ## 9.8 Working with the Docker containers
 
 ### 9.9.1 Create a new SSL certificate
diff --git a/phpmyfaq/assets/templates/admin/configuration/themes.upload.twig b/phpmyfaq/assets/templates/admin/configuration/themes.upload.twig
index 42bb37a68e..f1aa27a2a1 100644
--- a/phpmyfaq/assets/templates/admin/configuration/themes.upload.twig
+++ b/phpmyfaq/assets/templates/admin/configuration/themes.upload.twig
@@ -4,7 +4,7 @@
       <div class="card-body">
         <h3 class="h5 mb-3">Upload Theme ZIP</h3>
         <p class="text-muted small mb-3">
-          ZIP must include <code>index.twig</code>. Select the uploaded theme below using and save the configuration.
+          ZIP must include <code>index.twig</code>. Select the uploaded theme below and save the configuration.
         </p>
         <form id="theme-upload-form" method="post" action="#" enctype="multipart/form-data">
           <input type="hidden" name="pmf-csrf-token" value="{{ csrfToken }}">
diff --git a/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php b/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
index 9ef16a6fc4..e5a01bcbd0 100644
--- a/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
+++ b/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
@@ -52,9 +52,11 @@ public function uploadTheme(string $themeName, string $archivePath): int
             throw new RuntimeException('Failed to open theme archive.');
         }
 
-        $uploadedFiles = 0;
         $containsIndexTemplate = false;
 
+        /** @var array<string, string> */
+        $validatedEntries = [];
+
         try {
             for ($index = 0; $index < $zip->numFiles; $index++) {
                 $entryName = $zip->getNameIndex($index);
@@ -79,8 +81,7 @@ public function uploadTheme(string $themeName, string $archivePath): int
                 }
 
                 $storagePath = $this->themeStoragePath($themeName, $normalizedEntryPath);
-                $this->storage->put($storagePath, $contents);
-                $uploadedFiles++;
+                $validatedEntries[$storagePath] = $contents;
             }
         } finally {
             $zip->close();
@@ -90,11 +91,15 @@ public function uploadTheme(string $themeName, string $archivePath): int
             throw new RuntimeException('Invalid theme archive: missing required "index.twig".');
         }
 
-        if ($uploadedFiles === 0) {
+        if ($validatedEntries === []) {
             throw new RuntimeException('Theme archive does not contain uploadable files.');
         }
 
-        return $uploadedFiles;
+        foreach ($validatedEntries as $storagePath => $contents) {
+            $this->storage->put($storagePath, $contents);
+        }
+
+        return count($validatedEntries);
     }
 
     public function activateTheme(string $themeName): bool
diff --git a/tests/phpMyFAQ/Template/ThemeManagerTest.php b/tests/phpMyFAQ/Template/ThemeManagerTest.php
index 6107c9922d..7b1a303abc 100644
--- a/tests/phpMyFAQ/Template/ThemeManagerTest.php
+++ b/tests/phpMyFAQ/Template/ThemeManagerTest.php
@@ -110,7 +110,7 @@ public function testActivateDefaultThemePersistsDefaultTemplateSetConfig(): void
         $this->assertTrue($manager->activateDefaultTheme());
     }
 
-    public function testUploadThemeRejectsInvalidThemeName(): void
+    public function testActivateThemeRejectsInvalidThemeName(): void
     {
         $configuration = $this->createStub(Configuration::class);
         $manager = new ThemeManager($configuration, new InMemoryStorage(), 'themes');
@@ -121,6 +121,17 @@ public function testUploadThemeRejectsInvalidThemeName(): void
         $manager->activateTheme('../invalid');
     }
 
+    public function testUploadThemeRejectsInvalidThemeName(): void
+    {
+        $configuration = $this->createStub(Configuration::class);
+        $manager = new ThemeManager($configuration, new InMemoryStorage(), 'themes');
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage('Invalid theme name');
+
+        $manager->uploadTheme('../invalid', '/tmp/nonexistent.zip');
+    }
+
     /**
      * @param array<string, string> $entries
      */

From e4c41b0231c0da727666376348b66829f0e97f7e Mon Sep 17 00:00:00 2001
From: Thorsten Rinne <thorsten@phpmyfaq.de>
Date: Sat, 14 Feb 2026 16:30:55 +0100
Subject: [PATCH 3/5] fix: moved the directory-entry up

---
 phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php b/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
index e5a01bcbd0..d5dc2bafe5 100644
--- a/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
+++ b/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
@@ -60,12 +60,12 @@ public function uploadTheme(string $themeName, string $archivePath): int
         try {
             for ($index = 0; $index < $zip->numFiles; $index++) {
                 $entryName = $zip->getNameIndex($index);
-                if ($entryName === false) {
+                if ($entryName === false || $entryName === '' || str_ends_with($entryName, '/')) {
                     continue;
                 }
 
                 $normalizedEntryPath = $this->normalizeArchivePath($entryName, $themeName);
-                if ($normalizedEntryPath === '' || str_ends_with($normalizedEntryPath, '/')) {
+                if ($normalizedEntryPath === '') {
                     continue;
                 }
 

From b9146f0e7d414fb6a73adf177497871c4922911d Mon Sep 17 00:00:00 2001
From: Thorsten Rinne <thorsten@phpmyfaq.de>
Date: Sat, 14 Feb 2026 16:40:48 +0100
Subject: [PATCH 4/5] fix: added check that index.twig exists in storage

---
 CHANGELOG.md                                    |  1 +
 phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php |  9 +++++++++
 tests/phpMyFAQ/Template/ThemeManagerTest.php    | 16 +++++++++++++++-
 3 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 24b84ef82c..129a251138 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ This is a log of major user-visible changes in each phpMyFAQ release.
 - added support for Flesch readability tests (Thorsten)
 - added storage abstraction layer with support for local filesystem, and Amazon S3 (Thorsten)
 - added support for SendGrid, AWS SES, and Mailgun (Thorsten)
+- added theme manager with support for multiple themes and theme switching (Thorsten)
 - added experimental support for API key authentication via OAuth2 (Thorsten)
 - added experimental per-tenant quota enforcement, and API request rate limits (Thorsten)
 - improved audit and activity log with comprehensive security event tracking (Thorsten)
diff --git a/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php b/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
index d5dc2bafe5..24a7ccc8c6 100644
--- a/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
+++ b/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
@@ -105,6 +105,15 @@ public function uploadTheme(string $themeName, string $archivePath): int
     public function activateTheme(string $themeName): bool
     {
         $this->assertValidThemeName($themeName);
+
+        $indexPath = $this->themeStoragePath($themeName, 'index.twig');
+        if (!$this->storage->exists($indexPath)) {
+            throw new RuntimeException(sprintf(
+                'Cannot activate theme "%s": missing required "index.twig".',
+                $themeName,
+            ));
+        }
+
         return $this->configuration->set('layout.templateSet', $themeName);
     }
 
diff --git a/tests/phpMyFAQ/Template/ThemeManagerTest.php b/tests/phpMyFAQ/Template/ThemeManagerTest.php
index 7b1a303abc..fde191d003 100644
--- a/tests/phpMyFAQ/Template/ThemeManagerTest.php
+++ b/tests/phpMyFAQ/Template/ThemeManagerTest.php
@@ -97,10 +97,24 @@ public function testActivateThemePersistsTemplateSetConfig(): void
             ->with('layout.templateSet', 'tenant-theme')
             ->willReturn(true);
 
-        $manager = new ThemeManager($configuration, new InMemoryStorage(), 'themes');
+        $storage = new InMemoryStorage();
+        $storage->put('themes/tenant-theme/index.twig', '<h1>Hello</h1>');
+
+        $manager = new ThemeManager($configuration, $storage, 'themes');
         $this->assertTrue($manager->activateTheme('tenant-theme'));
     }
 
+    public function testActivateThemeRejectsMissingIndexTemplate(): void
+    {
+        $configuration = $this->createStub(Configuration::class);
+        $manager = new ThemeManager($configuration, new InMemoryStorage(), 'themes');
+
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage('missing required "index.twig"');
+
+        $manager->activateTheme('tenant-theme');
+    }
+
     public function testActivateDefaultThemePersistsDefaultTemplateSetConfig(): void
     {
         $configuration = $this->createMock(Configuration::class);

From 68911f32e65d254bb4db7be00e9b295ff89102ad Mon Sep 17 00:00:00 2001
From: Thorsten Rinne <thorsten@phpmyfaq.de>
Date: Sat, 14 Feb 2026 16:52:37 +0100
Subject: [PATCH 5/5] fix: improved checks

---
 phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php |  5 +++++
 tests/phpMyFAQ/Template/ThemeManagerTest.php    | 14 +++++++++++++-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php b/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
index 24a7ccc8c6..2e3b6342e0 100644
--- a/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
+++ b/phpmyfaq/src/phpMyFAQ/Template/ThemeManager.php
@@ -119,6 +119,11 @@ public function activateTheme(string $themeName): bool
 
     public function activateDefaultTheme(): bool
     {
+        $indexPath = $this->themeStoragePath('default', 'index.twig');
+        if (!$this->storage->exists($indexPath)) {
+            return false;
+        }
+
         return $this->configuration->set('layout.templateSet', 'default');
     }
 
diff --git a/tests/phpMyFAQ/Template/ThemeManagerTest.php b/tests/phpMyFAQ/Template/ThemeManagerTest.php
index fde191d003..8e8ab11f78 100644
--- a/tests/phpMyFAQ/Template/ThemeManagerTest.php
+++ b/tests/phpMyFAQ/Template/ThemeManagerTest.php
@@ -120,10 +120,22 @@ public function testActivateDefaultThemePersistsDefaultTemplateSetConfig(): void
         $configuration = $this->createMock(Configuration::class);
         $configuration->expects($this->once())->method('set')->with('layout.templateSet', 'default')->willReturn(true);
 
-        $manager = new ThemeManager($configuration, new InMemoryStorage(), 'themes');
+        $storage = new InMemoryStorage();
+        $storage->put('themes/default/index.twig', '<h1>Default</h1>');
+
+        $manager = new ThemeManager($configuration, $storage, 'themes');
         $this->assertTrue($manager->activateDefaultTheme());
     }
 
+    public function testActivateDefaultThemeReturnsFalseWhenIndexTemplateMissing(): void
+    {
+        $configuration = $this->createMock(Configuration::class);
+        $configuration->expects($this->never())->method('set');
+
+        $manager = new ThemeManager($configuration, new InMemoryStorage(), 'themes');
+        $this->assertFalse($manager->activateDefaultTheme());
+    }
+
     public function testActivateThemeRejectsInvalidThemeName(): void
     {
         $configuration = $this->createStub(Configuration::class);