feat: Composer-Support für theme/private inkl. Core-replace-Strategie

CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 1.5.0 - 2026-07-08
+
+- Die mitgelieferte `composer.json` für `theme/private` um einen `replace`-Block für zentrale REDAXO-Core-Libraries ergänzt.
+- Dadurch werden Core-Abhängigkeiten bei Composer-Auflösung im Theme-Projekt nicht erneut installiert.
+- Die gleiche `replace`-Strategie auf bestehende Projektdateien anwendbar dokumentiert.
+- Composer-Support für den Projekt-Theme-Ordner erweitert.
+- Automatisches Laden von `theme/private/vendor/autoload.php` in der Addon-Bootstrap-Phase ergänzt.
+- Neue Pfad-Methoden `theme_path::vendor()` und `theme_path::composerAutoload()` ergänzt.
+- Theme-Ordner-Installation erweitert, inklusive Anlage von `theme/private/vendor`.
+- Theme-Ordner-Installation erweitert, inklusive Startvorlage `theme/private/composer.json`.
+- README um ausführliche Composer-Anleitung erweitert (Installation, Update, Remove, Deployment).

README.md

@@ -13,6 +13,7 @@ Die weiteren Unterordner sind ein Vorschlag zur Strukturierung der Projektdateie
 
 Die vorgegebene Struktur hat den Vorteil, dass diese Ordner über [__PHP-Methoden__](#PHP-Methoden) ansprechbar sind, bzw. wie die entsprechenden Ordner eines AddOns automatisch eingebunden werden:
 * Alle im Ordner `lib` enthaltenen PHP-Klassen werden automatisch über __autoload__ eingebunden.
+* Wenn vorhanden, wird `private/vendor/autoload.php` automatisch eingebunden. Dadurch können Composer-Libraries direkt im Theme-Ordner genutzt werden.
 * Alle im Ordner `lang` enthaltenen Dateien mit der Endung `.lang` werden automatisch über __i18n__ eingebunden.
 * Alle Dateien mit der Endung `.php` im Ordner `inc` werden per `include_once` in der `boot.php` des AddOns eingebunden.
 * Der Ordner `fragments` wird über `rex_fragment::addDirectory` eingebunden.
@@ -62,6 +63,12 @@ $path = theme_path::lang($filename);
 // Gibt einen Pfad im Ordner "theme/private/lib" zurück.
 $path = theme_path::lib($filename);
 
+// Gibt einen Pfad im Ordner "theme/private/vendor" zurück.
+$path = theme_path::vendor($filename);
+
+// Gibt den Pfad zur Composer-Autoload-Datei zurück.
+$path = theme_path::composerAutoload();
+
 // Gibt einen Pfad im Ordner "theme/private/views" zurück.
 $path = theme_path::views($filename);
 
@@ -72,6 +79,69 @@ $path = theme_path::ytemplates($filename);
 $path = theme_path::assets($filename);
 ```
 
+## Composer im Theme-Ordner
+Das Theme-AddOn unterstützt Composer-Libraries direkt im Projektordner `theme/private`.
+
+Nach dem Installieren des Theme-Ordners wird eine `composer.json` als Startvorlage in `theme/private` angelegt.
+
+### Wo werden Abhängigkeiten installiert?
+Composer-Befehle werden in diesem Ordner ausgeführt:
+
+```text
+theme/private
+```
+
+Die installierten Abhängigkeiten liegen anschließend im Vendor-Ordner:
+
+```text
+theme/private/vendor/
+```
+
+Außerdem liegen die Projektdateien hier:
+
+* `theme/private/composer.json`
+* `theme/private/composer.lock`
+* `theme/private/vendor/`
+
+### Schnellstart
+```bash
+cd theme/private
+composer require monolog/monolog
+```
+
+Danach wird `theme/private/vendor/autoload.php` automatisch vom AddOn eingebunden.
+
+Die mitgelieferte `composer.json` enthält außerdem einen `replace`-Block für zentrale REDAXO-Core-Libraries. Dadurch werden diese Pakete bei Abhängigkeitsauflösung nicht erneut im Theme-Projekt installiert.
+
+### Häufige Composer-Befehle
+```bash
+# Paket installieren
+cd theme/private
+composer require nette/utils
+
+# Paket auf aktuelle kompatible Version aktualisieren
+composer update nette/utils
+
+# Alle Abhängigkeiten laut lock-Datei installieren (z. B. auf Server)
+composer install --no-dev --optimize-autoloader
+
+# Paket entfernen
+composer remove nette/utils
+```
+
+### Deployment-Hinweis
+Für reproduzierbare Deployments sollte `composer.lock` im Projekt versioniert werden.
+Je nach Deployment-Strategie gilt:
+
+* Entweder `vendor` mit deployen.
+* Oder auf dem Zielsystem `composer install --no-dev --optimize-autoloader` ausführen.
+
+Beispiel:
+```bash
+cd theme/private
+composer install --no-dev --optimize-autoloader
+```
+
 ### Daten
 #### theme_setting
 Eine einfache Registry mit der Möglichkeit, beim Abruf Default-Werte zu definieren.

boot.php

@@ -8,6 +8,12 @@
 // Load theme languages
 rex_i18n::addDirectory(theme_path::lang());
 
+// Load composer autoload from theme/private/vendor if available
+$composerAutoload = theme_path::composerAutoload();
+if (is_file($composerAutoload) && is_readable($composerAutoload)) {
+    include_once $composerAutoload;
+}
+
 // Autoload theme lib
 rex_autoload::addDirectory(theme_path::lib());
 

install/composer.json

@@ -0,0 +1,42 @@
+{
+    "name": "redaxo-project/theme-private",
+    "description": "Project specific Composer dependencies for the REDAXO theme folder",
+    "type": "project",
+    "require": {},
+    "replace": {
+        "composer/ca-bundle": "^1.5.12",
+        "enshrined/svg-sanitize": "^0.22",
+        "erusev/parsedown": "^1.8.0",
+        "erusev/parsedown-extra": "^0.9.0",
+        "filp/whoops": "^2.18.4",
+        "lbuchs/webauthn": "^2.2.0",
+        "psr/log": "^3.0.2",
+        "ramsey/http-range": "^2.0.0",
+        "symfony/console": "^7.4.13",
+        "symfony/http-foundation": "^7.4.13",
+        "symfony/var-dumper": "^7.4.8",
+        "symfony/yaml": "^7.4.13",
+        "voku/anti-xss": "^4.1.43",
+        "voku/portable-utf8": "^6.1.1",
+        "symfony/polyfill-ctype": "^1.0",
+        "symfony/polyfill-iconv": "^1.0",
+        "symfony/polyfill-intl-grapheme": "^1.0",
+        "symfony/polyfill-intl-normalizer": "^1.0",
+        "symfony/polyfill-mbstring": "^1.0",
+        "symfony/polyfill-php72": "^1.0",
+        "symfony/polyfill-php73": "^1.0",
+        "symfony/polyfill-php74": "^1.0",
+        "symfony/polyfill-php80": "^1.0",
+        "symfony/polyfill-php81": "^1.0",
+        "symfony/polyfill-php82": "^1.0",
+        "symfony/polyfill-php83": "^1.0"
+    },
+    "autoload": {
+        "psr-4": {
+            "Project\\Theme\\": "lib/"
+        }
+    },
+    "config": {
+        "sort-packages": true
+    }
+}

lib/pages/theme_page_settings.php

@@ -209,6 +209,9 @@ public static function install()
             if ($status) {
                 $status = rex_dir::create(rex_path::base($theme_folder.'/private/lib/yform/value'));
             }
+            if ($status) {
+                $status = rex_dir::create(rex_path::base($theme_folder.'/private/vendor'));
+            }
             if ($status) {
                 $status = rex_dir::create(rex_path::base($theme_folder.'/private/ytemplates'));
             }
@@ -241,6 +244,9 @@ public static function install()
             if ($status && !file_exists(rex_path::base($theme_folder.'/private/inc/functions.php'))) {
                 $status = rex_file::copy($addon->getPath('install/functions.php'), rex_path::base($theme_folder.'/private/inc/functions.php'));
             }
+            if ($status && !file_exists(rex_path::base($theme_folder.'/private/composer.json'))) {
+                $status = rex_file::copy($addon->getPath('install/composer.json'), rex_path::base($theme_folder.'/private/composer.json'));
+            }
 
             // Status
             if ($status) {

lib/theme_path.php

@@ -27,6 +27,27 @@ public static function lib($filename = '')
         return self::base('private/lib'.self::separator($filename));
     }
 
+    /**
+     * Return vendor path
+     *
+     * @param string $filename Optional filename
+     * @return string Path
+     */
+    public static function vendor($filename = '')
+    {
+        return self::base('private/vendor'.self::separator($filename));
+    }
+
+    /**
+     * Return composer autoload path
+     *
+     * @return string Path
+     */
+    public static function composerAutoload()
+    {
+        return self::vendor('autoload.php');
+    }
+
     /**
      * Return inc path
      *

package.yml

@@ -1,5 +1,5 @@
 package: theme
-version: '1.4.0'
+version: '1.5.0'
 author: Friends Of REDAXO
 supportpage: https://github.com/FriendsOfREDAXO/theme