Vorbereitungen für Craft 4

Craft CMS 4 wird ein paar Wochen erscheinen. Aber schon jetzt können Entwickler Maßnahmen ergreifen, die einen Umstieg der eigenen Website auf die neuste Craft-Version erleichtern.

Update der Craft-Version

Eine Aktualisierung auf Craft 4 ist nur möglich, wenn mindestens Craft 3.7.11 installiert ist. Wer also gehofft hat, dass er von seinem alten Craft 2-Projekt direkt auf Craft 4 wechseln kann, wird enttäuscht sein.

Update auf die neueste Version von Craft CMS 3

Erster Schritt ist also, auf die neuste Craft 3-Version zu aktualisieren. Das geht entweder über das Control Panel oder über das Terminal.

Aktualisierung über das Control Panel

Wenn ein Update verfügbar ist, sehen Benutzer, mit der richtigen Berechtigung, einen Hinweis, im Control Panel neben dem Werkzeuge-Menü. Auf Werkzeuge und dann auf Aktualisierungen klicken.

In diesem Bereich werden Updates für Craft CMS und der installierten Plug-ins angezeigt. Die Updates lassen sich dann einzeln auswählen oder alle auf einmal starten lassen.

Aktualisierung über das Terminal

Mit dem Befehl `update` können Craft und Plug-ins aktualisiert werden. Um alle verfügbaren Aktualisierungen eines Craft-Projekts angezeigt zu bekommen, folgenden Befehl in die Kommandozeile des Terminals eingeben:

  php craft update

Um alle verfügbaren Updates auf einmal auszuführen, diesen Befehl eingeben:

  php craft update all

Wer einzelne Pakete aktualisieren möchte, sollte `all` mit dem entsprechenden Namen ersetzen. Also `craft` für das CMS oder eben den Handle für das jeweilige Plug-in. Wenn etwa das Plug-in SEOmatic aktualisiert werden soll, lautet der Befehl:

  php craft update seomatic

Standardmäßig aktualisiert Craft auf die neueste verfügbare Version. Wenn auf eine bestimmte Version aktualisiert werden soll, sollte `:<Version>` an das Handle angehängt werden:

  php craft update seomatic:3.4.23

Craft bietet auch einen `update/composer-install` Befehl an, der sich wie der `composer-install` verhält, aber nicht voraussetzt, dass Composer installiert ist.

Upgrade-Anleitungen

Manchmal gibt es signifikante Änderungen, die vor einem Update zu beachten sind. In diesem Falle sollten die Upgrade-Leitfaden für jede Version oder Edition gelesen werden:

Aktualisierung von PHP und MySQL

Craft 4 benötigt mindestens PHP 8 und MySQL 5.7.8 oder MariaDB 10.2.7.

Am besten die `composer.json` öffnen und dort den Plattform-Eintrag bearbeiten:

  {
	"config": {
		"platform": {
			"php": "8.0.2"
		}
	}
}

Danach einfach `composer update` mit dry-run-Option ausführen:

  composer update --dry-run

Dry-run simuliert den Update-Befehl, ohne die Abhängigkeiten tatsächlich zu aktualisieren. Es sieht also so aus, als würde ein Update erfolgen, während nur visuelle Hinweise ausgegeben werden, welche Paket auf welche Version aktualisiert würden, ohne dass die tatsächliche Aktualisierung der Abhängigkeiten erfolgt.

Läuft der Dry-Run-Befehl ohne Probleme durch, ist die Installation bereit, auf den lokalen und produktiven Server auf PHP 8 zu aktualisieren.

Dazu einfach das Composer-Update ohne Dry-Run starten:

  composer update

Behebung von Veralterungswarnungen

Als Erstes sollte die Debug-Symbolleiste aktiviert werden. Im Craft-Conrol Panel auf Mein Benutzerkonto klicken, dann auf Einstellungen und schließlich auf "Debug-Symbolleiste im Front-End anzeigen" klicken. Danach im Browser die Website durchsuchen und die gemeldeten Veralterungswarnungen beheben. Zusätzlich gibt es eine vollständige Lister aller zuletzt aufgetretenen Warnungen im Control Panel unter Werkzeuge → Veralteter Code.

Worauf ist zu achten?

Eine Reihe an Twig Tags, Funktionen und Datums-Formatierung haben sich geändert. Auch gibt es veraltete Element-Query-Params in Twig-Vorlagen. Zudem sollte alles, was mit GraphQL und angepassten PHP-Modulen oder Plug-ins untersucht werden.

Einsatz von Umgebungsvariablen

Mit Craft 4 wird die Unterstützung von `siteName` und `siteUrl` entfernt. Also `siteName`aus der `config/general.php` entfernen und im Control Panel an der richtigen Stelle eine Umgebungsvariable setzen. Wichtig ist übrigens zu wissen, dass der `{{siteUrl}}`-Tag nicht aus den Templates entfernt werden muss, lediglich die dazugehörige Konfigurationseinstellung wird nicht mehr unterstützt.

Die Umgebungsvariable wird in der `.env`-Datei definiert, beispielsweise :

BASE_URL="http://craftentries.test"

Das ergibt Sinn, da für die lokale Entwicklungsumgebung eine andere URL benötigt wird, als für den Live-Server. In dem Beispiel würde in der lokalen .env-Datei die eben genannte URL stehen, während die .env-Datei des Live-Servers den Wert:

BASE_URL="https://craftentries.io"

Es lassen sich in Craft für die verschiedensten Einstellungen Umgebungsvariablen setzen:

Allgemeine Einstellungen:

Systemname
Status
Zeitzone

Websites:

Name
Basis-URL

Sektionen:

Zielvorschau-URL

Dateivolumen:

Basis-URL
Lokaler Dateipfad

E-Mail:

System-E-Mail-Adresse
Name des Absenders
Template für HTML-E-Mails
Benutzername (SMTP oder Gmail)
Passwort (SMTP oder Gmail)
Hostname (SMTP)
Port (SMTP)
Authentifizierung verwenden (SMTP)
Encryption Method (SMTP)

Nachdem die Variablen in der `.env` Datei angelegt sind, können diese in den passenden Einstellungsoptionen im Control Panel ausgewählt werden. Einfach in das Feld ein `$`schreiben und dann den Namen der Variablen. Während des Tippens ist Auto-Complete aktiviert und dadurch wird eine Liste der verfügbaren Variablen angezeigt.

Wichtig ist zu wissen, dass nur der Variablenname in der Datenbank oder der Project Config gespeichert wird. Dadurch kann der Wert der Variable für jede Umgebung eine andere sein und es können auch sensible Informationen gespeichert werden.

Die Templates kompatibel mit Twig 3 machen

Craft 4 setzt auf Twig 3 und nicht mehr Twig 2 und das führt dazu, dass möglicherweise die Templates angepasst werden müssen.

Der `{% spaceless %}`-Tag wird nicht mehr unterstützt, da er künftig als Filter gehandhabt wird. Per `apply`-Tag lässt sich spaceless aber nach, wie vor verwenden, sofern man diese Syntax beachtet:

  {% apply spacepless %}
	{# ... #}
{% endapply %}

Der `{% filter %}`-Tag wurde entfernt, stattdessen soll `{% apply %}` verwendet werden.

If-Parameter funktionieren nicht mehr im `{% for %}`-Tag, stattdessen sollen `| filter` eingesetzt werden:

  {% for item in items | filter(item => item is not null) %}
{% ... %}
{% endfor %}

Änderungen bei GraphQL

Die GraphQL APIs haben sich geändert und so wird `enabledForSite` nicht mehr unterstützt und stattdessen sollte `status` verwendet werden. Allerdings sind die Änderungen tiefgreifender, da `enabledForSite` nur einen Boolean akzeptierte, während `status` ein Array akzeptiert.

Aus:

  {
	entries(enabbledForsite: true) {
	title
	}
}

Wird folglich:

  {
	entries(status: ["enabled"]) {
	title
	}
}

Fazit:

All die hier vorgestellten Änderungen lassen sich schon vor Craft 4 durchführen, so dass der Übergang zur neusten Version in ein paar Wochen etwas stressfreier wird.

Wichtig ist vorwiegend zu wissen, wie die PHP-Version aktualisiert wird und dass man nicht von Craft 2 direkt auf Craft 4 wechseln kann. In dem Falle muss zwingend vorher auf Craft 3.7 aktualisiert werden und von da dann zu Craft 4.0.

Selbstständiger Webentwickler, der 2005 mit WordPress-Websites anfing, dann zu ExpressionEngine wechselte und 2013 sein Herz an Craft CMS verlor. Als Gründer von Craftentries, berichtet er seit 2015 über das Craft-Ökosystem.

Thomas Sausen Web Developer

website twitter