Von LASR 4 auf LASR 5 migrieren

LASR 5 bringt einige strukturelle Änderungen mit, die bei der Migration eines bestehenden Projekts beachtet werden müssen. Diese Anleitung führt dich durch die wichtigsten Schritte.

Empfehlung: Plane die Migration nicht zwischen Tür und Angel. Lege ein Backup an, arbeite in einer Staging-Umgebung und teste vor dem Live-Schalten alle Seiten und Module gründlich.

Voraussetzungen

Bevor du mit der Migration beginnst, sollte folgendes gegeben sein:

  • Du hast ein vollständiges Backup der Dateien und der Datenbank.
  • Du arbeitest in einer Staging-Umgebung und nicht auf dem Live-System.
  • Du hast die Staging-Umgebung auf Contao 5.7 oder neuer aktualisiert (für das Template Studio).

Wenn dein Projekt noch auf Contao 4.13 oder einer älteren 5er-Version läuft, führe zuerst das Contao-Update durch und stelle sicher, dass alles fehlerfrei läuft. Erst danach folgt die Theme-Migration.

Überblick der Änderungen

Bereich LASR 4.x LASR 5.x
Templates HTML5-Templates (*.html5) Twig-Templates (*.html.twig)
Template-Anpassungen templates/-Ordner Template Studio
Theme-Dateien files/theme/ layout/lasr-theme/
Theme-Toolbox 3.x 4.x
Contao 5.3 / 5.7 5.7

1. Composer-Abhängigkeiten aktualisieren

Aktualisiere das Theme-Bundle und die zugehörigen Erweiterungen über den Contao Manager oder per Composer:

composer require erdmannfreunde/lasr-theme-bundle:^5.0

Das Bundle zieht die passenden Versionen der Theme-Toolbox (4.x), des Nutshell Frameworks (2.x) und der Element-Bundles automatisch mit.

Lasse anschließend das Datenbank-Schema über den Contao Manager (oder den Install-Tool-Bereich) aktualisieren.

2. Theme Udate durchführen!!!

Der SCSS-Speicherort hat sich geändert:

  • Alt: files/theme/scss/
  • Neu: layout/lasr-theme/

Wenn du in LASR 4 eigene Anpassungen an den SCSS-Dateien (z.B. _variables.scss, _article.scss oder eigene Partials) vorgenommen hast, gehe so vor:

  1. Sichere die alten SCSS-Dateien aus files/theme/scss/.
  2. Übernimm die neue Verzeichnisstruktur aus dem LASR-5-Paket nach layout/lasr-theme/.
  3. Übertrage deine projektspezifischen Anpassungen Stück für Stück in die neuen Dateien – nicht 1:1 kopieren, da sich Variablen und Defaults zwischen den Versionen unterscheiden können.

Hinweis: Prüfe nach der Migration mit Hilfe der Browser-DevTools, ob alle Custom Properties korrekt aufgelöst werden.

3. Templates auf Twig umstellen

Dies ist der größte und aufwändigste Migrationsschritt: In LASR 5 sind alle .html5-Templates entfernt. Anpassungen erfolgen nun ausschließlich über Twig-Templates.

Vorgehen

  1. Liste alle Templates in deinem alten templates/-Ordner auf, die projektspezifisch angepasst wurden.
  2. Öffne im Backend System » Template Studio.
  3. Suche das jeweilige Twig-Pendant (z.B. mod_navigation.html.twig statt mod_navigation.html5).
  4. Lege im Template Studio eine projektspezifische Kopie an.
  5. Übertrage deine Anpassungen sinngemäß in die Twig-Syntax. PHP-Konstrukte wie <?php if ($foo): ?> werden zu {% if foo %}, Ausgaben wie <?= $bar ?> zu {{ bar }}.
  6. Entferne die alte .html5-Datei erst, wenn das Twig-Pendant funktioniert.

Hinweise zur Twig-Syntax

Eine vollständige Einführung in Twig-Templates für Contao findest du in der offiziellen Contao-Dokumentation. Die wichtigsten Unterschiede zur HTML5-Syntax:

  • Variablen-Ausgabe: <?= $foo ?> → {{ foo }}
  • Bedingung: <?php if ($foo): ?>...<?php endif; ?> → {% if foo %}...{% endif %}
  • Schleife: <?php foreach ($items as $item): ?> → {% for item in items %}
  • Block-Vererbung: <?php $this->extend('parent'); ?> → {% extends '@Contao/parent.html.twig' %}

Tipp: Wenn du viele individuelle Templates hattest, plane diesen Schritt großzügig. Es lohnt sich, beim Umzug gleich aufzuräumen und nicht mehr benötigte Anpassungen zu entfernen.

4. Theme-Toolbox-Klassen prüfen

Die Theme-Toolbox wurde auf Version 4.x aktualisiert. Die in LASR 4 verwendeten Hilfsklassen (m-t-0 bis m-t-5, article--hero, article--highlight usw.) bleiben grundsätzlich erhalten.

Prüfe nach der Migration im Backend unter Theme-Toolbox, ob alle gewünschten Klassen für deine Mandanten weiterhin verfügbar sind. Eigene Toolbox-Einträge, die du angelegt hattest, sollten beim Update erhalten bleiben.

5. Cache leeren und testen

Nach Abschluss der Migration:

  1. Im Contao Manager unter Systemwartung den Button „Prod.-Cache erneuern“ betätigen.
  2. Im Backend unter Systemwartung die Option „Skript Cache umgehen (im Produktivbetrieb)“ aktivieren – solange du noch testest und Anpassungen vornimmst.
  3. Frontend gründlich durchklicken: alle Seitentypen, Module, Elemente.
  4. Testen, ob Formulare, News, Events und ggf. Portfolio-Inhalte korrekt angezeigt werden.
  5. Browser-Konsole auf Fehler prüfen.

Checkliste

  • Backup erstellt
  • Contao auf 5.7 (oder neuer) aktualisiert
  • lasr-theme-bundle auf 5.x aktualisiert
  • Datenbank aktualisiert
  • SCSS-Dateien von files/theme/scss/ nach layout/lasr-theme/ migriert
  • Eigene SCSS-Anpassungen übertragen
  • Eigene .html5-Templates auf Twig umgestellt (über Template Studio)
  • Theme-Toolbox-Klassen geprüft
  • Cache erneuert
  • Frontend vollständig getestet
  • lasr
  • migration
  • update
  • twig
  • template-studio

Zur Übersicht