Klassen-Umbenennung beim Update von Contao 4 auf 5 automatisieren

Wer ein Contao-4-Projekt auf Version 5 hebt, merkt es spätestens beim ersten Blick ins Frontend: Das Stylesheet greift ins Leere. Mit der Umstellung auf Twig-Templates hat Contao 5 auch die CSS-Klassen umbenannt – aus dem vertrauten Präfix .ce_ wurde durchgängig .content-. Jede dieser Klassen steckt in gewachsenen Stylesheets, oft an Dutzenden Stellen.

Bei Projekten mit umfangreichem CSS- oder SCSS-Code kommen so schnell mehrere hundert Anpassungen zusammen. Von Hand ersetzen? Fehleranfällig und zäh. Eleganter geht es mit dem PythonScript-Plugin für Notepad++: ein Skript, ein Durchlauf, alle Ersetzungen – rückgängig machbar mit einem einzigen Undo.

1. In Notepad++ den Menüpunkt Plugins → Plugin-Verwaltung öffnen.
2. Das Plugin Python Script suchen, auswählen und installieren.
3. Nach Abschluss der Installation Notepad++ neu starten.

Um die Klassennamen konsistent an die neue Contao-5-Struktur anzupassen, empfiehlt sich ein Skript, das alle Änderungen auf einen Schlag durchführt.

Python Script anlegen:

1. Neues Script unter Plugins → Python Script → New Script anlegen.
2. Code in neue .py-Datei eintragen und speichern.
3. Script über Plugins → Python Script → Scripts ausführen.

Die folgende Routine zeigt ein Beispiel für häufige Ersetzungen, wie sie im Zuge des Updates erforderlich sind:

Die Umstellung auf Twig in Contao 5 bringt nicht nur eine modernere Template-Struktur mit sich, sondern auch eine konsistente Namenskonvention für CSS-Klassen. Während in Contao 4 Inhalte noch über das Präfix .ce_ („content element“) gekennzeichnet waren, setzt Contao 5 auf die einheitliche Schreibweise .content-.

Darüber hinaus wurden weitere Bezeichner angepasst, etwa zur Vereinheitlichung von Bild- und Text-Containern oder zur semantisch korrekten Auszeichnung von Bildunterschriften (caption → figcaption).

Um die Umstellung greifbarer zu machen, zeigt das folgende Beispiel, wie ein typischer Contao-4-Codeblock angepasst werden muss.

Durch die automatisierte Ersetzung mit dem PythonScript werden alle .ce_-Klassen wie .ce_text oder .ce_image zuverlässig in die neuen .content--Klassen umgewandelt. Dies spart nicht nur Zeit, sondern reduziert auch Fehler bei umfangreichen Projekten.

<?php
// contao/migrations/Version20260101000000.php
namespace App\Migration;

use Contao\CoreBundle\Migration\AbstractMigration;
use Contao\CoreBundle\Migration\MigrationResult;
use Doctrine\DBAL\Connection;

class KlassenMigration extends AbstractMigration
{
    public function __construct(private Connection $db) {}

    public function shouldRun(): bool
    {
        return (bool) $this->db->fetchOne(
            "SELECT COUNT(*) FROM tl_content
             WHERE cssID REGEXP '(^|[^a-z0-9_-])alt-klasse([^a-z0-9_-]|$)'"
        );
    }

    public function run(): MigrationResult
    {
        $anzahl = $this->db->executeStatement(
            "UPDATE tl_content
                SET cssID = REGEXP_REPLACE(cssID,
                    '(^|[^a-z0-9_-])alt-klasse([^a-z0-9_-]|$)', '\\\\1neue-klasse\\\\2')
              WHERE cssID REGEXP '(^|[^a-z0-9_-])alt-klasse([^a-z0-9_-]|$)'"
        );

        return $this->createResult(true, $anzahl . ' Inhaltselemente angepasst.');
    }
}

Ausgeführt wird das Ganze mit vendor/bin/contao-console contao:migrate – dieselbe Stelle, an der auch die Kern-Migrationen laufen. Contao merkt sich, dass die Migration erledigt ist; ein zweiter Aufruf richtet keinen Schaden an.

Was neben der Datenbank noch anzufassen ist

• Templates: grep -rl "alt-klasse" templates/ – Treffer werden von Hand geprüft, nicht blind ersetzt.
• Stylesheets: alte und neue Klasse übergangsweise parallel definieren, dann die alte entfernen. So bleibt die Website während des Umbaus funktionsfähig.
• Eigene Module und Erweiterungen: Hier stecken Klassennamen oft in PHP-Strings – die Suche muss den ganzen src/-Ordner einschließen.

Die Reihenfolge, die Nerven spart

Zuerst die neue Klasse zusätzlich vergeben (beide gelten), dann Templates und CSS umstellen, danach die alte Klasse aus der Datenbank entfernen. Wer umgekehrt vorgeht – erst Datenbank, dann CSS –, hat für die Dauer des Umbaus eine kaputte Website. Bei einem Livegang am Freitagnachmittag ist das der Unterschied zwischen einem ruhigen Wochenende und einem sehr wachen.

Die Klassen-Umbenennung ist der Teil des Contao-5-Updates, der sich am besten automatisieren lässt – und genau deshalb sollte niemand ihn von Hand erledigen. Das PythonScript-Skript erledigt in Sekunden, was manuell einen Nachmittag kostet, und macht die Änderung dank Undo-Klammer sogar reversibel.

Für alles, was über Stylesheets hinausgeht – Klassen in der Datenbank, in Templates, in eigenem Modulcode –, ist die im Update gezeigte Contao-Migration der sauberere Weg: versioniert, wiederholbar, identisch auf Staging und Live. Beides zusammen macht aus dem gefürchteten Major-Update ein planbares Projekt.