README

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:

YAML-Konfiguration laden oder neu anlegen.
Inhalt validieren.
Datei validiert speichern.
Dry-Run ausführen und die geplanten Änderungen prüfen.
Apply bestätigen und ausführen.
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:contao-demo
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/.

Der Integrationstest verwendet dafür die offizielle Contao Demo in der zum Bundle passenden 5.7-Version. Er legt die Anwendung temporär an, erlaubt die von Contao benötigten Composer-Plugins explizit, installiert das lokale Bundle als Composer-Paket und erzeugt in DDEV eine eigene temporäre MariaDB-Datenbank. Er importiert die Demo-Daten, führt Export → Validierung → Import aus und vergleicht den anschließenden Export bytegenau mit dem Ausgangsexport:

ddev exec --dir=/var/www/html/entwicklung/lindesbs/contao-preconfigure composer test:contao-demo

Der Test benötigt Netzwerkzugriff auf Packagist und DDEV. Datenbank und Demo-Installation werden danach entfernt. Standardmäßig verwendet er die DDEV-Root-Verbindung auf db:3306; abweichende Werte können über CONTAO_DEMO_DB_HOST, CONTAO_DEMO_DB_PORT, CONTAO_DEMO_DB_USER und CONTAO_DEMO_DB_PASSWORD gesetzt werden.

Lizenz

Dieses Projekt steht unter der MIT-Lizenz.

lindesbs / contao-preconfigure

Package info

Security

Statistics