Upgrade: von 4.x, 5.x oder einer früheren 6.0.x auf den aktuellen Stand #

Diese Anleitung richtet sich an alle, die eine bestehende Installation betreiben und sie auf die aktuelle Linie Exponential 6.0 bringen möchten. Diese Linie ist 6.0.15; sie folgt auf v6.0.14 (siehe Changelog 6.0.15). Ermitteln Sie Ihre Version, folgen Sie dem Teil dafür und schließen Sie mit den Prüfungen am Ende ab. Sie zeigen Ihnen, dass das Ergebnis in Ordnung ist.

Warnung .htaccess bremst jede Anfrage. Sind .htaccess-Dateien erlaubt (AllowOverride alles außer None), geschweige denn genutzt, sucht Apache sie bei jeder Anfrage in jedem Verzeichnis des Pfads und liest und wertet sie aus, und die Ladezeiten der Seiten steigen drastisch (gemessen). Die einzige wirkliche Abhilfe ist, die Funktion für den virtuellen Host abzuschalten: AllowOverride None im virtuellen HTTPS-Host, und die Regeln in der Konfiguration des virtuellen Hosts selbst als mod_rewrite-Regeln. Das ist in Geschwindigkeitstests im Produktivbetrieb weit schneller und die Zeit für die Optimierung einer Produktivkonfiguration unbedingt wert. Stellen Sie sofort um: Übernehmen Sie die Regeln des Beispiels für einen virtuellen HTTPS-Host in Ihren virtuellen Host (mit dem statischen Cache auch staticcache_offload.conf), setzen Sie AllowOverride None, führen Sie apachectl configtest aus, laden Sie Apache neu und testen Sie die Website. Dieselben Regeln für andere Server: nginx, LiteSpeed, Caddy, IIS, Velocity (eingebaut); wohin Regeln für virtuelle Hosts in einem Control Panel gehören: Plesk, cPanel, DirectAdmin, ISPConfig. Unter LiteSpeed oder OpenLiteSpeed kann zusätzlich der Seiten-Cache des Servers anonyme Besucher und Crawler ohne PHP bedienen: Seiten-Caching mit LiteSpeed und OpenLiteSpeed.

Planen Sie für eine kleine Site zwanzig Minuten ein. Der riskante Schritt ist die Datenbank. Deshalb ist Schritt 1 eine Datensicherung.

Welchen Teil lese ich? #

Ermitteln Sie Ihre Version: In der Administration nennt sie die Seite Setup > Systeminformationen; auf der Kommandozeile:

mysql -u USER -p DATABASE -e "SELECT name, value FROM ezsite_data WHERE name LIKE 'ezpublish-%';"

(Verwenden Sie das Entsprechende für PostgreSQL oder SQLite; die Zeilennamen ezpublish-version und ezpublish-release behalten ihre historische Schreibweise absichtlich.) Erwartet: ein Wert wie 5.4.0 oder 6.0.14.

Umstieg von LoveStack #

LoveStack hat denselben Ursprung wie Exponential, und seine Datenbanken stehen denen von Exponential nahe. Ein einziger Befehl, der nur liest, listet auf, was eine solche Site mitbringt und was mit jedem Punkt zu tun ist:

./console exp:lovestack check --allow-root-user          # add --json for a machine-readable report

Er liest die Datenbank und die Einstellungen und schreibt nichts. Jede Zeile ist markiert:

Er endet mit OK (Exit-Code 0), wenn nichts zu tun ist, oder mit NEEDS ATTENTION (Exit-Code 1).

Erstellen Sie dann eine Datensicherung (Schritt 1), bringen Sie den neuen Code an seinen Platz und wenden Sie das Datenbank-Update aus Teil C an (C1 und C2). Danach kennzeichnet ein weiterer Befehl die Datenbank als die von Exponential und listet die Einstellungen auf, die von Hand zu ändern sind:

./console exp:lovestack migrate --allow-root-user            # a dry run: prints what it would write, writes nothing
./console exp:lovestack migrate --apply --allow-root-user    # writes it

Was er schreibt, in der Tabelle ezsite_data und nirgendwo sonst:

Er ändert niemals Inhalte, Benutzer oder Einstellungen, und ein erneuter Aufruf ändert nichts. Eine Datenbank, die nicht von LoveStack stammt (keine Versionszeile lovestack und keine Zeile db-schema-version), wird mit einer entsprechenden Meldung abgelehnt, und es wird nichts geschrieben. --json liefert denselben Bericht als ein JSON-Objekt.

Unter den Zeilen gibt er die von Hand zu ändernden Einstellungen und Extensions aus, übernommen aus check:

• Einstellungen, die es nur in LoveStack gibt, jeweils mit dem zu verwendenden Namen in Exponential oder dem Hinweis, dass Exponential sie nicht liest. Benennen Sie site.ini [Session] SameSite in CookieSameSite um. Bis dahin liest Exponential SameSite als CookieSameSite und protokolliert einen Hinweis auf die veraltete Einstellung (sind beide gesetzt, wird CookieSameSite verwendet).
• Die Extension legacy_2018, falls sie aktiv ist: Entfernen Sie sie aus ActiveExtensions[] und ActiveAccessExtensions[]. Exponential behält den Auswahl-Datentyp (ezenum) im Kernel, und die Extension würde ihn ein zweites Mal definieren.
• Das Paket mugoweb/ezpublish-legacy, falls composer.json es noch verlangt: Ersetzen Sie es durch das von Exponential.

Dank an Mugo Web, dessen dokumentierte Schemaschritte in LoveStack (update/database/mysql/lovestack/1.sql bis 4.sql) es möglich gemacht haben, eine LoveStack-Datenbank so genau zu erkennen.

Schritt 1: immer eine Datensicherung #

mysqldump -u USER -p DATABASE > backup-before-upgrade.sql      # MySQL or MariaDB
pg_dump -U USER DATABASE > backup-before-upgrade.sql           # PostgreSQL
sqlite3 var/storage/sqlite3/exponential.db ".backup 'backup-before-upgrade.db'"  # SQLite: use the path of your database file
tar czf backup-var-and-settings.tgz var settings/override settings/siteaccess extension design

Halten Sie settings/override/ sowie Ihre eigenen Extensions und Designs aus jedem Befehl heraus, der Dateien ersetzt. Die eine Prüfung, die belegt, dass die Datensicherung brauchbar ist: Stellen Sie sie auf einer Testmaschine wieder her, niemals auf der Live-Datenbank.

Teil A: von 3.10 bis 5.3 (die alte Kette) #

Die Datenbank-Update-Dateien bilden eine Kette; jede bringt Sie einen Schritt weiter. Wenden Sie sie der Reihe nach, jede genau einmal, für Ihre Engine an (mysql, postgresql, sqlite, wo vorhanden), aus dem Verzeichnis update/database/<engine>/ des neuen Codes:

Wenden Sie eine Datei mit dem Client Ihrer Datenbank an, zum Beispiel:

mysql -u USER -p DATABASE < update/database/mysql/4.1/dbupdate-4.0.0-to-4.1.0.sql

Regeln, die dies sicher machen:

• Überspringen Sie keine Datei und wenden Sie keine zweimal an. Schlägt eine Anweisung fehl, weil eine Spalte bereits existiert, wurde die Datei schon einmal angewendet: Halten Sie an und vergleichen Sie mit Ihrer Datensicherung.
• Wenn Sie den Datenbank-Cluster (DFS oder Datenbank-Dateihandler) verwenden, wenden Sie zusätzlich die Datei dbupdate-cluster-... desselben Schritts an, wo es eine gibt (4.3, 4.7, 5.2, 5.4).
• Die Verzeichnisse mit dem Namen unstable enthalten Dateien von Vorabversionen; wenden Sie sie nicht an.
• Die Verzeichnisse 6.12 und 7.3 gehören nicht zu diesem Weg; die 6.0-Dateien in Teil B bringen eine 5.4-Datenbank auf den aktuellen Stand.
• Mehrere Schritte liefern ein PHP-Skript mit, das Daten repariert; führen Sie die Skripte der Versionen aus, die Sie durchlaufen, aus dem Projektverzeichnis, zum Beispiel php update/common/scripts/4.1/updateimagesystem.php. Listen Sie sie mit ls update/common/scripts/* auf, und lesen Sie die ersten Zeilen eines Skripts (--help, wo es das anbietet), bevor Sie es ausführen. Was sich in jeder Release geändert hat und warum, steht in ihren Hinweisen: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 5.0, 5.1, 5.2, 5.3, 5.4.
• Die Update-Kette wird von ./console exp:checkdbfiles --allow-root-user geprüft, das fehlende oder überzählige Dateien des Upgrade-Wegs auflistet.

Lesen Sie dann die Hinweise der Linie 5.90, die den Wechsel zu PHP 7 und eine längere Passwortregel vorbereitet hat: Übersicht 5.90, PHP 7, Passwortlänge, Indizierung von Relationen.

Teil B: von 5.4 (oder 5.90) auf Exponential 6.0.0 #

1. Bringen Sie den neuen Code an seinen Platz. Entweder ein neuer Checkout, in den Sie Ihre settings/override/, settings/siteaccess/, extension/ und design/ kopieren, oder, wenn Sie die Site mit Composer verwalten, ändern Sie die Versionsbedingung von se7enxweb/exponential in der composer.json Ihres Projekts und führen composer update se7enxweb/exponential aus. Lassen Sie kein Werkzeug Ihre eigenen Einstellungen oder Extensions ersetzen.

2. Tragen Sie die neue Version in die Datenbank ein. Dieselbe Datei bringt das Schema auf den Stand, den der 6.0-Kernel verwendet: Sie verbreitert ezuser.password_hash vom varchar(50) jedes 5.x-Schemas auf 255 (mit dem Standard HashType=php_default und UpdateHash=true wird der Hash jedes Benutzers bei der ersten Anmeldung zu einem 60 Zeichen langen bcrypt-Hash, den die alte Spalte nicht aufnehmen kann), fügt ezcontentobject_trash.trashed hinzu (ohne diese Spalte schlägt das Verschieben von Inhalten in den Papierkorb fehl) und benennt unter PostgreSQL die Sequenzen in <table>_<column>_seq um (die Namen, aus denen der Kernel neue IDs liest). Jede Änderung lässt eine Datenbank, die sie bereits hat, unverändert:

   mysql -u USER -p DATABASE < update/database/mysql/6.0/dbupdate-5.4.0-6.0.0.sql

   PostgreSQL: update/database/postgresql/6.0/dbupdate-5.4-to-6.0.sql. Die MySQL-Datei beginnt mit SET default_storage_engine=InnoDB;, was MySQL (ab 5.5.3) und MariaDB akzeptieren, führen Sie also die ganze Datei aus. Kopien der Datei von vor Oktober 2026 begannen mit SET storage_engine=InnoDB;, was MySQL ab 5.7.5 und MariaDB ab 12.0 ablehnen; nehmen Sie die aktuelle Datei. Details: Changelog 6.0.0.

3. PHP: Exponential 6.0.15 läuft unter PHP 8.0 oder neuer (PHP 7.4 ohne Support nutzbar), Exponential Velocity unter 8.0 oder neuer (ab seinem Release 0.0.4.54; siehe Unterstützung für PHP 8.0 und Warum Exponential PHP 7.4 unterstützt). Eine Site unter PHP 7.4 kann ab 6.0.15 wieder die aktuelle Linie betreiben, ohne Support (6.0.8 bis 6.0.14 brauchen PHP 8.1); lesen Sie Unterstützung für PHP 8 für die Reihenfolge der Upgrade-Schritte, und prüfen Sie Ihre eigenen Extensions auf PHP-8-Warnungen (Klassen, die eZPersistentObject oder eZDataType erweitern, sind die üblichen Fälle).

4. Fahren Sie mit Teil C fort, der für jeden 6.0.x-Schritt dasselbe Verfahren ist.

Teil C: von einer beliebigen 6.0.x auf den aktuellen Stand #

C1. Den neuen Code an seinen Platz bringen #

Holen Sie den neuen Code wie in Teil B, Schritt 1 (Checkout des Tags oder Branches oder composer update). Erzeugen Sie dann die Class-Map neu und leeren Sie die Caches, in dieser Reihenfolge:

php bin/php/ezpgenerateautoloads.php -e
php bin/php/ezcache.php --clear-all --allow-root-user

Erwartet: Der erste Befehl gibt aus, wie viele Klassen er gefunden hat; der zweite endet mit einer Zeile, die besagt, dass die Caches geleert wurden. Verwenden Sie -k nicht auf einer Installation, die zusätzliche Arbeitskopien des Codes in ihrem Wurzelverzeichnis hält (zum Beispiel Ordner von git worktrees), ohne diese auszuschließen, z. B. mit --exclude='<folder>'; andernfalls werden Kernel-Klassen in diese Kopien gemappt. Laden Sie dann das PHP-FPM neu, das die Site ausliefert (systemctl reload <your-php-fpm-service>), und wenn Sie Velocity betreiben, zeigt ./console exp:velocity deploy --dry-run --allow-root-user jeden Schritt, den der echte Befehl ausführen würde.

Vergleichen Sie dann .htaccess und config.php mit den neuen Vorlagen. Eine Release kann .htaccess_root, .htaccess_root_static und config.php-RECOMMENDED ändern, und Ihre Kopien bleiben, wie sie sind:

./console exp:setup:status                     # ist .htaccess noch eine Kopie einer Vorlage?
./console exp:setup:htaccess                   # der Diff zwischen Ihrer .htaccess und der neuen Vorlage
./console exp:setup:htaccess --force --apply   # die neuen Regeln übernehmen (vorher Sicherung), wenn der Diff nichts Eigenes enthält
./console exp:config:list                      # Einstellungen, die neu in config.php-RECOMMENDED sind, erscheinen als (not set)

Setzen Sie die neuen Einstellungen, die Sie möchten, mit ./console exp:config:set <NAME> <value> --apply; die Einstellungen, die Sie hatten, behalten ihre Werte. Dasselbe gilt nach Teil A und B. Siehe .htaccess und config.php von der Konsole aus einrichten.

C2. Das Datenbank-Update anwenden #

Die Datei für die Linie ist update/database/<engine>/6.0/dbupdate-6.0.0-6.0.15.sql (es gibt Dateien für MySQL, PostgreSQL und SQLite). Sie trägt die Version ein, nimmt unter MySQL und PostgreSQL die Schemaänderungen der Datei aus Teil B vor (für eine Site, die mit einer älteren Kopie dieser Datei von 5.x gekommen ist; eine Datenbank, die sie bereits hat, bleibt unverändert) und fügt die Spalten hinzu, die spätere Änderungen benötigen (Fußzeile des PDF-Exports, OPML- und Podcast-Felder und mehr). Wenden Sie sie einmal, vollständig und der Reihe nach an; hat Ihre Datenbank bereits eine Spalte, schlägt die Anweisung fehl und nennt Ihnen die Spalte; überspringen Sie nur diese Anweisung. Eine Site von 5.x, die eine ältere Kopie dieser Datei angewendet hat und noch einen 50 Zeichen langen password_hash, kein ezcontentobject_trash.trashed oder (PostgreSQL) Sequenzen <table>_s hat, wendet sie nicht erneut an: Sie wendet die aktuelle Datei aus Teil B an und setzt die Versionszeile zurück mit UPDATE ezsite_data SET value='6.0.15stable' WHERE name='ezpublish-version';. Andernfalls:

mysql -u USER -p DATABASE < update/database/mysql/6.0/dbupdate-6.0.0-6.0.15.sql

Legen Sie dann einmalig die Index-Tabellen des Audit-Protokolls an (das Audit-Protokoll ist ab 6.0.15 standardmäßig eingeschaltet), und kopieren Sie, wer was in den Papierkorb gelegt hat, aus <VarDir>/trash/trashed.json in die neuen Spalten ezcontentobject_trash.trashed_by und trashed_via (einmal je var-Verzeichnis, auf jedem Webserver eines Clusters):

php update/common/scripts/6.0/createaudittables.php
php update/common/scripts/6.0/movetrashrecords.php --remove-file

Solange trashed_by und trashed_via nicht existieren, schreibt der Kernel weiterhin trashed.json; siehe die Papierkorbansicht.

Prüfen Sie die Versionszeile (dieselbe Abfrage wie oben; erwartet wird nach dieser Datei 6.0.15stable).

Eine neue Installation hat einen eindeutigen Index auf ezuser.login; die Datei fügt ihn bei einem Upgrade nicht hinzu, da er auf einer Datenbank fehlschlägt, in der sich zwei Konten einen Login teilen. Listen Sie solche Logins auf und fügen Sie den Index hinzu, wenn es keine gibt (andernfalls verweigert der Befehl die Ausführung und ändert nichts):

./console exp:user-login-check --allow-root-user
./console exp:user-login-check --fix-index --allow-root-user

Siehe ein Konto je Login.

C3. Die Checkliste jedes durchlaufenen Zeitraums lesen #

Die Upgrade-Hinweise sind nach Zeiträumen geschrieben. Lesen Sie jeden zwischen Ihrer Version und heute; jeder beginnt mit einer kurzen Checkliste und einer Spalte „Was zu tun ist“.

Die drei Änderungen, auf die man am häufigsten stößt:

• Konten ohne eine Zeile in ezuser_setting können sich nicht anmelden (August 2026): Stellen Sie sicher, dass jeder Benutzer eine hat.
• Overrides folgen Priority (Juli 2026): Überprüfen Sie jede override.ini, in der nur einige Blöcke eine Priority haben.
• Sicherheits-Header, Sitzungs-Cookies mit HttpOnly/SameSite und eine strengere Upload-Prüfung sind standardmäßig eingeschaltet (September und Oktober 2026): Wenn ein Host Ihre Administration in einem Frame einbettet, setzen Sie den Header bewusst.

Wenn WebDAV eingeschaltet ist: Seit 6.0.15 heißt sein Einstiegsskript index_webdav.php. webdav.php leitet nur noch dorthin weiter und wird in einer späteren Hauptversion entfernt. Ändern Sie den virtuellen Host (auch den für HTTPS) und die Rewrite-Regeln, und testen Sie mit curl -i -X PROPFIND -H 'Depth: 1' https://www.example.com/index_webdav.php/ (erwartet: 207 Multi-Status): Das WebDAV-Einstiegsskript heißt jetzt index_webdav.php.

Wenn SOAP eingeschaltet ist (soap.ini EnableSOAP=true, zum Beispiel für die Erweiterung syndication): Seit 6.0.15 heißt sein Einstiegsskript index_soap.php. soap.php leitet nur noch dorthin weiter und wird in einer späteren Hauptversion entfernt. Lassen Sie index_soap.php im HTTPS-Virtual-Host und in .htaccess durch, stellen Sie die SOAP-Clients darauf um, laden Sie den Webserver neu und testen Sie mit curl -sS -i 'https://www.example.com/index_soap.php?wsdl' (erwartet: 200 und Error: this web page does only understand POST methods; ein 404 oder eine Seite der Website bedeutet, dass die Regel fehlt): Das SOAP-Einstiegsskript heißt jetzt index_soap.php.

Das ist der Schritt, der am häufigsten vergessen wird. Eine Aktualisierung ersetzt die Skripte, aber der virtuelle Host, die Rewrite-Regeln und die Direktiven im Control Panel gehören Ihnen: Keine Aktualisierung ändert sie. Ändern Sie sie im HTTPS-Host (*:443), nicht nur im HTTP-Host, und führen Sie den curl-Test nach dem Neuladen aus, bevor Sie die Aktualisierung für abgeschlossen erklären.

Was sich Monat für Monat geändert hat, erzählt die Chronik; jede einzelne Änderung steht im Verzeichnis des Root-Repositorys.

C4. Ihre eigenen Extensions prüfen #

php bin/php/ezpgenerateautoloads.php -e
./console exp:checkclasses --allow-root-user

exp:checkclasses lädt jede deklarierte Klasse und meldet diejenigen, die PHP nicht laden will; so zeigt sich eine PHP-8-Inkompatibilität in einer Extension. Extensions tragen ihre eigene Version in ezinfo.php und extension.xml; die Extension-Liste der Administration (Setup > Extensions) zeigt jede an, siehe Extension-Liste. Die Reihenfolge, in der Extensions geladen werden, hat sich 2026 geändert: Ladereihenfolge der Extensions.

Das Upgrade überprüfen #

Führen Sie diese Befehle aus; jeder gibt an, wie ein gutes Ergebnis aussieht.

php bin/php/ezcache.php --clear-all --allow-root-user         # ends without an error
./console exp:checkdbfiles --allow-root-user                   # no file marked as missing for your line

Dann im Browser: Die Startseite lädt; melden Sie sich in der Administration an; öffnen Sie Setup > Systeminformationen und lesen Sie die Version ab; veröffentlichen Sie ein Testelement und sehen Sie es auf der Site. In der Administration listen Setup > Upgrade-Prüfung und Überprüfe Dateikonsistenz Dateien des Codes auf, die von der Release abweichen (Prüfung der Dateikonsistenz). Dateien, die Sie absichtlich geändert haben, werden dort erwartungsgemäß aufgeführt. Die Upgrade-Prüfung erklärt jeden Befund und die Datenbankprüfung auf derselben Seite.

Leeren Sie zuletzt den Inhalts-Cache und, wenn Sie Velocity verwenden, dessen Antwort-Cache, nach dem Neuladen von PHP-FPM, damit eine von altem Code gerenderte Seite nicht erneut ausgeliefert wird.

Wenn etwas schiefgeht #

Eine veröffentlichte Release kann nicht geändert werden; der Weg zu einer Korrektur ist die nächste Version. Um zu sehen, was eine Version enthält, öffnen Sie ihr Changelog: 6.0.0 bis 6.0.15.

USt-Regeln (6.0.15). An der Berechnung der Umsatzsteuer ändert sich nichts. USt-Regeln werden nur angewendet, wenn shop.ini [VATSettings] Handler einen Handler nennt (ezdefault), und die ausgelieferte settings/shop.ini nennt weiterhin keinen. Ein Shop, dessen Regeln nie angewendet wurden, sieht jetzt einen Hinweis unter Store > VAT rules; um sie anzuwenden, setzen Sie Handler=ezdefault in settings/override/shop.ini.append.php, stellen sicher, dass das Land des Kunden beim Checkout bekannt ist, und testen eine Bestellung, bevor Sie live gehen.

Migrationen (6.0.15). Ab 6.0.15 schreiben Sie die eigenen Änderungen einer Site nach dem Upgrade (eine Tabelle, eine Inhaltsklasse, Rollen, eine Korrektur von Inhalten) am besten als Migrationen: Dateien unter Versionskontrolle, die jede Installation der Site mit ./console exp:migration:migrate --apply in derselben Reihenfolge anwendet, mit einem Sicherungspunkt vor jedem Lauf. Die Upgrade-Schritte des Kernels sind darunter gelistet. Beginnen Sie mit Migrationen; das Wort meint etwas anderes als das Upgrade einer Site: Migrationen oder Umzug einer Site.

Demo-Modus (6.0.15). Die Umgebungsvariable EXP_DEMO_MODE=1 kennzeichnet eine öffentliche Demo; ohne sie ändert sich nichts. Upgrade einer Demo: Behalten Sie die Variable für den Webserver, Cron und die Konsole bei, und prüfen Sie danach das Banner. Upgrade einer echten Site: Stellen Sie sicher, dass die Variable für keinen ihrer Prozesse gesetzt ist. Demo-Modus.

Siehe auch #

• Erste Schritte: eine saubere Installation derselben Version, für eine Testkopie.
• Betrieb einer Site: Datensicherungen, Caches und Reparaturen nach dem Upgrade.
• Bereitstellung und Velocity-Engines: das richtige PHP-FPM neu laden oder auf einen schnelleren Server wechseln.
• Extensions: Versionen, Ladereihenfolge und Releases Ihrer eigenen Extensions.
• Upgrade mit der Konsole und Migrationen: das Upgrade als ein Befehl, und die eigenen Änderungen der Site danach.
• .htaccess und config.php von der Konsole aus einrichten: beide Dateien mit den neuen Vorlagen vergleichen.
• Release-Hinweise: Changelogs von Exponential 6.0 und die Release-Hinweise der Extensions.