WoltLab Suite 6.0 und bestehende Plugins

Hallo,

nachdem wir mit Neues Controller-Konzept auf Basis von PSR-15 bereits die spannendste konzeptionelle Änderung in WoltLab Suite 6.0 für neuen Code vorgestellt haben, möchten wir mit diesem Thema kurz auf notwendige Änderungen für bestehende Plugins eingehen.

Wir haben die Entwickler-Doku im Laufe der Entwicklung bereits fortlaufend angepasst und insbesondere den „Migration Guide“ zeitnah gepflegt: https://docs.woltlab.com/6.0/migration/wsc55/php/. Unsere eigenen Apps und Plugins haben wir jeweils unmittelbar nach Integration von Änderungen in WoltLab Suite Core angepasst – oder zumindest eine Issue erstellt – um sicherzustellen, dass die notwendigen Änderungen nicht in Vergessenheit geraten und alle Anwendungsfälle berücksichtigt sind.

Auf Basis dessen möchten wir folgende Dinge, die in der Entwickler-Dokumentation bereits genannt wurden noch einmal explizit hervorheben:

Icons

Die wohl größte zwingende Anpassung mit WoltLab Suite 6.0 ist die Aktualisierung auf FontAwesome 6. Hierzu verweise ich auf den Beitrag von Alexander:

Post

RE: Font Awesome 6

Für Entwickler:
Wir haben die Integration von Font Awesome 6 bereits vor einigen Wochen abgeschlossen, es sind gegenwärtig keine Änderungen mehr geplant. Die bisherige Icon-Implementierung ist sehr alt (ursprünglich auf Basis von Font Awesome 3 entwickelt) und weist eine Menge an Designschwächen auf. Die neuen Icons sind nicht abwärtskompatibel, es wird daher notwendig sein, alle verwendeten Icons zu modernisieren. Icons werden ausschließlich über dedizierte HTML-Elemente unterstützt,…

Alexander Ebert

Oct 28th 2022

Typisierung in PHP

Wir haben an diversen Stellen Typen in Methodensignaturen ergänzt. In Bezug auf Rückgabetypen ist dies ein breaking change für abgeleitete Klassen bzw. implementierte Interfaces. Die Änderung ist aber vorwärtskompatibel: Die notwendigen Rückgabetypen können auf Wunsch bereits mit WoltLab Suite 5.5 ergänzt werden, um die Unterschiede zwischen der Version für 5.5 und 6.0 klein zu halten. Für kleine Plugins mit einer Hand voll Klassen empfehlen wir die Typisierung wo möglich bereits in der Version für 5.5 vorzunehmen, gerne prüfen wir diese bereits jetzt und schalten sie frei.

Insbesondere sind getTitle() und getLink()-Methoden betroffen, diese sollten einen expliziten : string-Rückgabetyp erhalten.

Hinweis in der Dokumentation: https://docs.woltlab.com/6.0/m…ter-return-property-types

config.inc.php für Apps

Die Datei ist schon seit vielen Versionen deprecated und bindet einfach nur die app.config.inc.php ein, wurde aber auch von uns noch vor kurzem eingebunden. Mit WoltLab Suite 6.0 entfällt die config.inc.php, es muss die app.config.inc.php eingebunden werden. Auch diese Änderung ist vorwärtskompatibel und kann mit WoltLab Suite 5.5 vorgenommen werden. Wir empfehlen die Änderung bereits mit dem nächsten Update für 5.5 zu inkludieren.

Die Änderung für WoltLab Suite: Calender sieht beispielhaft so aus:

diff --git a/files/acp/global.php b/files/acp/global.php
index 54cc180..53c2ac0 100644
--- a/files/acp/global.php
+++ b/files/acp/global.php
@@ -11,7 +11,7 @@
 \define('RELATIVE_CALENDAR_DIR', '../');
 
 // include config
-require_once(\dirname(__DIR__) . '/config.inc.php');
+require_once(\dirname(__DIR__) . '/app.config.inc.php');
 
 // include WCF
 require_once(RELATIVE_WCF_DIR . 'acp/global.php');
diff --git a/files/global.php b/files/global.php
index 445b09f..b259ae1 100644
--- a/files/global.php
+++ b/files/global.php
@@ -8,7 +8,7 @@
  */
 
 // include config
-require_once(__DIR__ . '/config.inc.php');
+require_once(__DIR__ . '/app.config.inc.php');
 
 // include wcf
 require_once(RELATIVE_WCF_DIR . 'global.php');

Hinweis in der Dokumentation: https://docs.woltlab.com/6.0/m…recations_removals/#files

Deprecations allgemein + andere inkompatible Änderungen

Diverse APIs, die seit längerem deprecated sind, sind endgültig entfernt worden. Auch hier können Änderungen in der Regel vorab vorgenommen werden. Am einfachsten ergeben sich notwendige Anpassungen, wenn man das Plugin in WoltLab Suite 6.0 testet: Wenn Inkompatibilitäten unvermeidbar waren, haben wir versucht die alte API vollständig zu entfernen, sodass notwendige Anpassungen sich in einem „Fatal Error“ niederschlagen, anstatt subtile Änderungen im Verhalten herbei zu führen. Plugins, die für WoltLab Suite 5.5 in einem guten Zustand in Bezug auf Deprecations sind, sollten mit WoltLab Suite 6.0 wenig Probleme bekommen.

Hinweis in der Dokumentation: https://docs.woltlab.com/6.0/m…55/deprecations_removals/

Aufräumen mit WoltLab Suite 6.0 und neue Features

Neue Features sollten sich sinnvollerweise die neuen Funktionen von WoltLab Suite 6.0 zu Nutze machen, um die Arbeit zu erleichtern. Im Rahmen der Plugin-Prüfung haben wir bereits auf einige Dinge aufmerksam gemacht, wenn es sich ergeben hat.

Dazu:

• Neues Controller-Konzept auf Basis von PSR-15
• RE: Illegal offset type in Suche

AMA

Gerne stehen wir für Unklarheiten zu notwendigen Anpassungen an WoltLab Suite 6.0 zur Verfügung, auf GitHub in Issues, allgemein im Plugin-Entwicklungs-Bereich (es gibt bereits ein Label für WoltLab Suite 6.0!) oder auch hier im Thema. Sollte es Unklarheiten in der Dokumentation geben oder etwas übersehen worden sein, dann schickt gerne einen Pull Request zur Verbesserung, oder erstellt eine Tracking-Issue im WoltLab/docs.woltlab.com-Repository. Ein paar offene Issues für 6.0 gibt es aktuell bereits: https://github.com/WoltLab/docs.woltlab.com/issues

Hallo,

Quote from SoftCreatR

Wann werdet ihr selbst denn Gebrauch von den Neuerungen machen?

Es gibt meines Wissens keine neuen Funktionen, die unsere Pakete nicht selbst irgendwo verwenden. Ohne Dogfooding, nur auf Basis irgendwelcher theoretischer Anforderungen, ist es unglaublich schwierig eine sinnvolle API zu schaffen, die auch auf Dauer stabil bleibt.

Quote from SoftCreatR

Als Beispiel fällt mir hier etwa die neue pagination-Komponente ein. Die existiert zwar, wird von euch aber gar nicht verwendet.

Die Komponente wird implizit vom {pages}-Template-Plugin erzeugt und ist damit automatisch bei allen Paketen, die das {pages}-Plugin nutzen im Einsatz. Die Ersetzung von {pages} in bestehenden Templates erfolgt sinnvollerweise im Rahmen einer allgemeinen Überarbeitung der jeweiligen Seite, beispielsweise wenn in einer zukünftigen Version auch Seiten auf PSR-15 umgestellt werden.

Hallo,

Quote from Syntafin

Gerade im Hinblick auf einige Entwickler mit sehr großen Produktportfolio denke ich wird vieles nicht direkt verfügbar sein.

neben der Antwort von Alexander, überschätzt du vermutlich auch, wie viele Anpassungen tatsächlich notwendig sind. Die allermeisten internen APIs sind kompatibel geblieben bzw. erst einmal nur als deprecated markiert worden. Bei den tatsächlich notwendigen Änderungen, sind die Änderungen oftmals auch sehr einfach „mechanisch“ durchführbar, ohne viel geistige Leistung aufwenden zu müssen.

Als Beispiel: Die Ergänzung der Rückgabetypen für getTitle() und getLink() lässt sich über eine Regex-Suche nach function getTitle\(\)(?!:) bewerkstelligen. Das findet alle Vorkommnisse, bei denen auf die Definition kein Doppelpunkt folgt, d.h. der Rückgabetyp noch fehlt. Da kann man dann einfach das : string mit Ctrl+V reinkopieren – oder wenn man besonders mutig ist und einen sauberen Codestil (im Sinne von Formatierung) hat, einfach über Suchen- und Ersetzen ergänzen.

Als Fallbeispiel für ein nicht-triviales Plugin habe ich mir gerade mal die Modern Shoutbox Pro von Darkwood.Design in WoltLab Suite 6.0 installiert. Ich musste ich zwei Änderungen und zusätzlich eine Korrektur für PHP 8.2 vornehmen. Die Icons habe ich für diesen Test nicht angefasst, für die gibt es aber das Hilfsskript:

• Ergänzung der Rückgabetypen für getTitle() und getLink() in einer Klasse: Kann mit 5.5 vorgenommen werden.
• Ersetzung von {@SECURITY_TOKEN_INPUT_TAG} durch {csrfToken}: Kann mit 5.3 oder so vorgenommen werden.
• Korrektur für eine Verwendung einer dynamic Property für PHP 8.2: Ist unabhängig von der WoltLab Suite-Version.

Die Terms of use von SoftCreatR liegen nach meinem Kenntnisstand bereits in einer angepassten Version vor. Das Spenden-System 3.0 mit Banküberweisungs-Erweiterung von Cyperghost erfordert neben den Icons lediglich eine Anpassung von package.xml (Anpassung der minversion und Entfernung der API-Version) und Ersetzung von SECURITY_TOKEN_INPUT_TAG.

Natürlich war der Test der Plugins jetzt äußerst oberflächlich, auch, da mir nicht alle Funktionen der Plugins bekannt sind. Die Kernfunktionalität konnte aber durch diese sehr simplen Handgriffe angepasst werden. Bei unseren eigenen Paketen sieht es ganz ähnlich aus, wir haben aber die Gelegenheit genutzt, noch weitere Aufräumarbeiten zu erledigen. Statt nur die Rückgabetypen nur speziell bei getTitle() und getLink() zu ergänzen, haben wir jeweils eine komplette Klasse oder einen kompletten Namespace angepasst. Mit WoltLab Suite 6.0 haben wir auch alle Pakete (außer WoltLab Suite Core selbst) auf die PHP-DDL umgestellt.

Und wie schon eingangs gesagt: Gerne beantworten wir konkrete Rückfragen zur notwendigen Anpassung. Im Rahmen der Plugin-Prüfung gebe wir auch bereits jetzt Tipps für mögliche Fallstricke, die sich ergeben könnten.