Contao Preconfigure Bundle

Mit diesem Contao-5-Bundle lässt sich die Grundstruktur einer Website als YAML-Datei beschreiben, im Contao-Backend bearbeiten, prüfen und wiederholt anwenden. Typische Anwendungsfälle sind neue Projekt-Setups, reproduzierbare Seitenstrukturen, standardisierte Themes und Module sowie die kontrollierte Übernahme derselben Basiskonfiguration in mehrere Installationen.

Das Repository enthält das Bundle sowie ein eigenständiges PHAR (bin/contao-preconfigure.phar), das die Bundle-Befehle direkt im Contao-5- Kernel eines Zielprojekts ausführt, ohne dass das Bundle dort per Composer installiert sein muss (siehe INSTALL.md). Eine vollständige Contao-Installation oder eine eigene Authentifizierung gehören weiterhin nicht zum Paket.

Funktionsumfang

Das Bundle verarbeitet derzeit folgende Bereiche:

• globale Contao-Einstellungen,
• hierarchische Seitenbäume,
• Artikel und Inhaltselemente,
• Themes und Seitenlayouts,
• Frontend-Module,
• ausgewählte Einträge der composer.json,
• stabile Schlüssel zur Referenzierung erzeugter Contao-Datensätze,
• protokollierte Apply-Läufe und Rollbacks.

Der Backend-Editor bietet:

• Laden und Bearbeiten mehrerer YAML-Dateien,
• YAML- und JSON-Schema-Validierung,
• atomisches Speichern mit Konflikterkennung,
• einen Dry-Run ohne Schreibzugriffe,
• ein ausdrücklich zu bestätigendes Apply,
• einen Verlauf der Apply-Läufe,
• einen ebenfalls zu bestätigenden Rollback.

Voraussetzungen

• PHP 8.1 oder neuer
• Contao 5.3 oder neuer
• Installation als Composer-Paket in einer Contao Managed Edition
• ein Backend-Benutzer mit Administratorrechten

Das Backend-Modul ist aktuell bewusst auf ROLE_ADMIN beschränkt. Beim Anwenden werden zusätzlich die CRUD-Berechtigungen des jeweiligen Contao Data Containers geprüft.

Installation

composer require lindesbs/contao-preconfigure

Das enthaltene Contao Manager Plugin registriert das ReconfigureContaoBundle nach dem ContaoCoreBundle und lädt dessen Services und Backend-Route. Anschließend sollte der übliche Deployment-Ablauf der Zielinstallation ausgeführt werden, insbesondere Cache-Aufbau und Contao-Migrationen.

Weitere Hinweise stehen in INSTALL.md.

Verwendung im Backend

Nach der Installation befindet sich das Modul unter:

System → YAML-Konfiguration

Konfigurationsdateien liegen im installierenden Contao-Projekt unter:

config/contao-preconfigure/

Erlaubt sind ausschließlich einfache Dateinamen mit .yml oder .yaml, zum Beispiel site.yaml oder corporate-de.yaml. Unterverzeichnisse und relative Pfade werden abgewiesen.

Der empfohlene Ablauf ist:

1. YAML-Konfiguration laden oder neu anlegen.
2. Inhalt validieren.
3. Datei validiert speichern.
4. Dry-Run ausführen und die geplanten Änderungen prüfen.
5. Apply bestätigen und ausführen.
6. Bei Bedarf den protokollierten Lauf über den Verlauf zurücksetzen.

Composer-Änderungen sind beim Apply eine separate Option und standardmäßig deaktiviert, da sie Dateien verändern und externe Composer-Prozesse starten können.

YAML-Aufbau

Eine Konfiguration besitzt mindestens den Wurzelbereich contao. Der optionale Bereich composer wird außerhalb der DCA-Pipeline verarbeitet.

contao:
  settings:
    adminEmail: admin@example.org
    timeZone: Europe/Berlin

  pages:
    - key: root_de
      title: Beispiel-Website
      type: root
      alias: root
      language: de
      fallback: true
      children:
        - key: home
          title: Startseite
          alias: startseite

  articles:
    - key: article_home
      pageKey: home
      title: Startseite
      column: main

  content:
    - articleKey: article_home
      elements:
        - key: welcome
          type: headline
          headline: Willkommen
        - type: text
          text: Die Website wurde aus einer YAML-Konfiguration aufgebaut.

  themes:
    - key: main_theme
      name: Haupt-Theme
      layouts:
        - key: layout_default
          name: Standardlayout
          template: fe_page

  modules:
    - key: main_navigation
      name: Hauptnavigation
      type: navigation

composer:
  minimum-stability: stable
  prefer-stable: true
  require:
    contao/news-bundle: null

Eine umfangreichere Vorlage befindet sich in docs/example-site.yaml. Die vollständigen zulässigen Strukturen und Pflichtfelder definiert schema/contao-preconfigure.schema.json.

Schlüssel und Referenzen

Felder wie key, pageKey, articleKey, layoutKey und moduleKey vermeiden fest codierte Datenbank-IDs:

• key vergibt eine stabile, frei wählbare Kennung.
• pageKey verweist beispielsweise auf eine zuvor beschriebene Seite.
• articleKey ordnet Inhaltselemente einem Artikel zu.
• layoutKey und moduleKey verbinden Layouts beziehungsweise Module.

Das Bundle speichert die Zuordnung zwischen Schlüssel und Contao-ID in einer internen Mapping-Tabelle. Diese wird erst beim ersten schreibenden Lauf angelegt. Validierung und Dry-Run verändern das Datenbankschema nicht.

DCA, Hooks und Callbacks

Contao-Datensätze werden nicht direkt von den fachlichen Applern in tl_page, tl_article, tl_content, tl_theme, tl_layout oder tl_module geschrieben. Alle unterstützten Schreiboperationen laufen über einen gemeinsamen DCA-Writer.

Der Ablauf berücksichtigt insbesondere:

• die zur Laufzeit geladene DCA einschließlich Erweiterungen anderer Bundles,
• Create-, Update- und Delete-Berechtigungen,
• Feldvalidierung und Wertnormalisierung,
• save_callback, oncreate, onload, onbeforesubmit, onsubmit und ondelete,
• Contao-Versionierung,
• Record-Cache und Cache-Tag-Invalidierung,
• das Apply-Protokoll für spätere Rollbacks.

Callbacks, die zwingend eine konkrete DC_Table-Instanz, Widgets, Redirects oder einen echten Formular-Request benötigen, werden als inkompatibel erkannt. Das Apply wird in diesem Fall abgebrochen, anstatt den Callback unbemerkt zu umgehen. Details enthält docs/dca-import-export.md.

Globale Einstellungen und Composer-Konfiguration besitzen keinen passenden Contao-DCA-Datensatz und werden deshalb über eigene, klar getrennte Persistenzpfade verarbeitet.

Validieren, Dry-Run und Apply

Die Aktionen haben unterschiedliche Auswirkungen:

• Validieren: YAML parsen, normalisieren und gegen das JSON-Schema prüfen.
• Validieren & speichern: nur eine gültige Datei atomisch schreiben.
• Dry-Run: Konfiguration fachlich auswerten und Änderungen ausgeben, ohne Datenbank- oder Dateischreibzugriffe und ohne unbekannte Callback-Nebenwirkungen.
• Apply: Contao-Änderungen transaktional ausführen und mit einer Lauf-ID protokollieren.
• Rollback: protokollierte Creates löschen und Updates auf den vorherigen Zustand zurückführen; auch dieser Weg verwendet den DCA-Writer.

Ein SHA-256-Hash schützt beim Speichern davor, Änderungen eines anderen Prozesses zu überschreiben. Dateien sind auf 2 MiB begrenzt und werden zuerst in eine temporäre Datei desselben Verzeichnisses geschrieben und anschließend atomar umbenannt.

Weitere Informationen zum Editor stehen in docs/backend-editor.md.

Interne Daten

Beim ersten schreibenden Lauf legt das Bundle bei Bedarf zwei interne Tabellen an:

• contao_preconfigure_map für deklarative Schlüssel und Contao-IDs,
• contao_preconfigure_log für Apply-Läufe und Rollback-Daten.

Die eigentlichen Contao-Inhalte verbleiben vollständig in den regulären Contao-Tabellen. YAML-Dateien verbleiben als lesbare Quelldateien im Projektverzeichnis.

Grenzen

• Das Backend-Modul ist derzeit nur für Administratoren verfügbar.
• Nicht jeder fremde DCA-Callback kann ohne echten Formular-Request sicher ausgeführt werden.
• Composer-Operationen gehören nicht zur Datenbanktransaktion und müssen daher separat bestätigt werden.
• Ein Rollback umfasst die protokollierten Datenbankänderungen eines Apply-Laufs, nicht beliebige externe Nebenwirkungen fremder Callbacks oder bereits ausgeführte Composer-Installationen.
• Eine vollständige Contao-Anwendung wird bewusst nicht in diesem Repository mitgeführt.

Projektstruktur

config/                 Symfony-Servicekonfiguration
schema/                 JSON-Schema der Konfigurationsdateien
src/Config/             sichere YAML-Dateiverwaltung
src/Controller/         Contao-Backend-Controller
src/EventListener/      Backend-Menüintegration
src/Contao/Applier/     fachliche Verarbeitung der YAML-Bereiche
src/Contao/Dca/         DCA-Registry, Normalisierung, Callbacks und Writer
src/Service/            Apply-, Rollback- und Verbindungsdienste
templates/backend/      Backend-Oberfläche
tests/                  Unit- und SQLite-Integrationstests
docs/                   Architektur und Beispiele

Entwicklung und Qualitätssicherung

composer install
composer test
composer ecs
composer phpstan

Zusätzliche Skripte:

composer test:unit
composer test:integration
composer test:coverage
composer ecs:fix

Eine reale Contao-Integrationstestanwendung wird außerhalb dieses Bundle-Quellbaums aufgebaut. Dadurch bleibt das Repository ein installierbares, eigenständiges Bundle ohne eingebettete Managed Edition oder vendor/.

Lizenz

Dieses Projekt steht unter der MIT-Lizenz.