Umstieg von 2.1 auf 3.0

1. Einleitung

Die Version 3.0 des Adventure PHP Framework bringt eine große Anzahl an Neuerungen mit. Dieser Artikel zeigt Ihnen, welche neuen Funktionalitäten sich auf Ihre bestehende Anwendung auswirken und wie Sie diese auf die neue Version anpassen und gleichzeitig optimieren können.

Der Artikel richtet sich an Umsteiger von der 2.X-Linie. Sollten Sie noch eine ältere Version aus der 1.X-Generation einsetzen, migrieren Sie zunächst auf die Version 2.1. Unter Artikel finden Sie Hinweise und Anleitungen dazu.

2. APF-Parser

Der APF-Parser wurde in der Version 3.0 komplett neu geschrieben. Grund hierfür waren Einschränkungen, die die Entwicklung von Anwendungen erschwert haben und an einigen Stellen Workarounds erforderten.

Die bisherige Implementierung des Parsers konnte nicht alle Tag-Strukturen - vor allem hinsichtlich der Hierarchie-Zuordnung - auflösen, was entweder zu Parser-Fehlern und damit Applikationsabstürzen führte oder Tags nicht erkannt wurden und damit Funktionalität nicht gegeben war. Zusätzlich dazu erschwerte die wiederkehrende Registrierung von Tags pro Instanz.

Ein weiteres Problem ist das Timing. Durch die Analyse von Templates an Hand der Liste der bekannten Tags und nicht an Hand der Reihenfolge und Struktur von Tags in einem Template war es unter gewissen Umständen notwendig Workarounds zu implementieren.

All diese Themen wurden nun mit dem neuen Parser nun gelöst und daraus ergeben sich einige Optimierungsmöglichkeiten für Ihre Anwendung. Einige davon werden bereits im Artikel Migration von 2.1 auf 3.0 beschrieben.

Der Parser bietet nun folgende Vorteile gegenüber der Version 2.1:

  • Tags werden an Hand der Definition im Template analysiert und nicht mehr an Hand der Liste der bekannten Tags. Damit werden ab dem Release 3.0 alle Tag-Strukturen und -Schachtelungen unterstützt. Nicht mehr erkannte Tags oder Parser-Fehler auf Grund von nicht kompatiblen Tag-Strukturen gehören der Vergangenheit an.
  • Durch die Analyse von Tags an Hand des Templates kann die starre Abhängigkeit von Tags zu einer Hierarchie-Ebene komplett aufgelöst werden. Ab der Version 3.0 lässt sich jeder Tag (prinzipiell) in jeder Ebene mit der selben Kombination aus Präfix und Namen einsetzen. Dies erleichtert nicht nur die Implementierung, sondern spart auch Wrapper-Tags, die ausschließlich für den Einsatz in einer speziellen Ebene implementierung wurden.
  • Tags werden ab Version 3.0 global registriert. Dies bedeutet, dass eine Kombination aus Präfix und Namen durch eine einmalige Registrierung in allen Templates und allen Ebenen bekannt ist. Damit lassen sich Tags bequem in der Bootstrap-Datei zentral und einmalig für die gesamte Applikation registrieren.
  • Die erweiterte Templating-Syntax ist nun in allen Templates und allen Ebenen verfügbar. Details können Sie dem Kapitel Erweiterte Template-Funktionen entnehmen.
  • Viele neue Features (siehe Roadmap) können nun realisiert werden, wie z.B. ein Iterator in einem Formular oder ein Formular in einem <html:template />-Tag.

Die folgenden Kapitel zeigen die Optimierungsmöglichkeiten auf.

2.1. Automatisierte Migration

Als ersten Schritt des Umstiegs auf die neue Version aber auch der Optimierung Ihrer Anwendung führen Sie bitte die unter Migration von 2.1 auf 3.0 beschriebenen Migrations-Skripten aus. Diese optimieren bereits die Anwendung der mit dem APF ausgelieferten Komponenten.

2.2. Optimierung der Tag-Registrierung

Zur Vereinfachung Ihrer Templates empfiehlt das APF-Team folgende Maßnahmen für Ihre Applikation:

  • Extrahieren Sie zunächst alle Vorkommen des <core:addtaglib />-Tags aus Ihren Templates und ersetzen diese durch ein Document::addTagLib()-Statement in Ihrer Bootstrap-Datei. Finden Sie in Ihren Templates beispielsweise die Tags
    APF-Template
    <template:addtaglib class="DOCS\pres\taglib\InternalLinkTag" prefix="int" name="link" /> <core:addtaglib class="DOCS\pres\taglib\InternalLinkTag" prefix="int" name="link" />
    so ersetzen sie die beiden durch ein
    PHP-Code
    Document::addTagLib('DOCS\pres\taglib\InternalLinkTag', 'int', 'link');
    Bitte beachten Sie, das die Tag-Registrierung vor dem Starten des Frontcontrollers erfolgen muss.
  • Extrahieren Sie alle self::addTagLib()-Statements aus Ihrer Applikation - z.B.
    PHP-Code
    class FooTag extends Document { public function __contruct() { self::addTagLib('DOCS\pres\taglib\InternalLinkTag', 'int', 'link'); } ... }
    - und fügen Sie diese ebenfalls zur Liste in der Bootstrap-Datei hinzu.
  • Konsolidieren Sie nun die erstellte Liste und entfernen alle mehrfachen Tag-Registrierungen.
Sofern ein Modul aus einem zentralen Haupt-Template und mehreren Unter-Templates besteht, so kann die Tag-Registrierung auch via <core:addtaglib /> im Haupt-Template vorgenommen werden. Da das Haupt-Template vom Parser vor den Unter-Templates analysiert wird, sind die dort per <core:importdesign /> registrierten Tags (zeitlich betrachtet!) auch in den Unter-Templates bekannt.

2.3. Wiederverwendung von registrierten Tags

Der APF-Parser wurde in der Version 3.0 so optimiert, dass er Tags mit gleichem Präfix und Namen in unterschiedlichen Hierarchien korrekt auflösen kann. Die Tag-Struktur

APF-Template
<core:addtaglib class="..." prefix="template" name="link"/> <int:link /> <html:template> <template:addtaglib class="..." prefix="template" name="link"/> <template:link /> </html:template>

lässt sich zukünftig zu

APF-Template
<core:addtaglib class="..." prefix="template" name="link"/> <int:link /> <html:template> <int:link /> </html:template>

vereinfachen. Der <int:link />-Tag muss daher nur einmal innerhalb der Applikation registrieren werden: entweder konsolidiert per <core:addtaglib />-Tag in einem Template oder in der index.php.

2.4. Entfernen von Wrapper-Tags

In vorangegangenen Version war es notwendig, Wrapper-Tags zu definieren oder Tag-Implementierungen unter einem anderen Präfix und/oder Namen zu registrieren um die Schwächen des APF-Parses auszugleichen. Bis Version 2.1 konnte der Parser Tags mit gleichem Präfix und Namen nicht korrekt zu den im Template definierten Hierarchie-Stufen zu ordnen, da die Analyse des Templates an Hand der registrierten Tags ausgeführt wurde.

In Version 3.0 wurde diese Schwäche beseitigt und in Ihrer Applikation vorhandene Workarounds können entfernt werden. Um Ihre Anwendung auf Basis der Version 3.X optimieren zu können, zeigt das folgende Beispiel das Potential des neuen APF-Parser auf.

Um in vorangegangenen Versionen die Tag-Struktur

APF-Template
<html:iterator name=""> ... <iterator:fallback> ... [<fallback:placeholder name="" />] [<fallback:getstring namespace="" config="" entry="" />] [<fallback:addtaglib class="" prefix="" name="" />] ... </iterator:fallback>] ... </html:iterator>

realisieren zu können (Details der Tag-Signatur siehe Spezielle Tags), war ein Wrapper-Tag notwendig, der die Registrierung der Kind-Tags so deklariert, dass diese nicht schon bei der Analyse des direkten Inhalts des <html:iterator />-Tags erfasst und falsch zugeordnet wurden.

Der zugehörige Quellcode des APF gestaltete sich wie folgt:

PHP-Code
class HtmlIteratorTag extends Document { public function __construct() { $this->tagLibs[] = new TagLib('APF\tools\html\taglib\HtmlIteratorFallbackTag', 'iterator', 'fallback'); ... } ... } class HtmlIteratorFallbackTag extends TemplateTag { public function __construct() { $this->tagLibs[] = new TagLib('APF\core\pagecontroller\PlaceHolderTag', 'fallback', 'placeholder'); $this->tagLibs[] = new TagLib('APF\core\pagecontroller\AddTaglibTag', 'fallback', 'addtaglib'); $this->tagLibs[] = new TagLib('APF\core\pagecontroller\LanguageLabelTag', 'fallback', 'getstring'); } }

Da der Parser ab Release 3.0 jeden Tag zur richtigen Hierarchie-Stufe zuordnen kann, lässt sich der (separat implementierte) <iterator:fallback />-Tag einfach durch einen "echten" TemplateTag ersetzen. Für Ihr Projekt bedeutet dies folgendes:

  • Der HtmlIteratorFallbackTag kann komplett entfernt werden und die Tag-Registrierung für den <iterator:fallback />-Tag lässt sich auf
    PHP-Code
    Document::addTagLib('APF\core\pagecontroller\TemplateTag', 'iterator', 'fallback');
    umstellen.
  • Anschließend können Sie die Tag-Struktur auf
    APF-Template
    <html:iterator name=""> ... <iterator:fallback> ... [<html:placeholder name="" />] [<html:getstring namespace="" config="" entry="" />] [<core:addtaglib class="" prefix="" name="" />] ... </iterator:fallback>] ... </html:iterator>
    umstellen, da beispielsweise der <html:placeholder />-Tag auch innerhalb von <iterator:fallback /> korrekt erkannt und diesem zugeordnet wird.

Eine Reduktion von Tag-Registrierungen und -Implementierungen spart nicht nur Code, sondern reduziert auch die Komplexität Ihrer Anwendung. Es lohnt sich daher, nach ähnlichen Mustern zu suchen und diese mit den neuen Möglichkeiten des APF-Parsers aufzulösen.

2.5. Umstellen auf Extended Templating Syntax

Zur Optimierung der Übersichtlichkeit Ihrer Templates wird empfohlen, die Platzhalter-Notation <html:placeholder /> auf die verkürzte Schreibweise der erweiterten Templating Syntax umzustellen.

Diese Änderung lässt sich auf der Kommandozeile mit dem mitgelieferten Migrations-Skript sehr einfach für alle Template-Dateien erledigen:

Bitte wechseln Sie vor der Ausführung in das Code-Verzeichnis Ihrer Applikation um unerwartete Ergebnisse zu vermeiden.
Code
$ /path/to/migration/migrate-place-holders.sh /cygdrive/c/xampp/php/php ############################################# # APF 3.0 automatic place holder migration # ############################################# Checking PHP executable available ... [OK] Using given php executable at /cygdrive/c/xampp/php/php. PHP Version: 5.4.16. ############################################# Starting migration ... ############################################# Migration done! Place holders are now written in extended templating syntax.
Bitte stellen Sie sicher, dass Sie zunächst die automatisierte Migration Ihrer Code-Basis ausgeführt haben. Details dazu erfahren Sie unter Migration von 2.1 auf 3.0.

3. Autoloading

Version 3.0 des APF unterstützt die Nutzung von Composer zur Strukturierung und Organisation Ihrer Projekte. Um Probleme mit dem Laden von Klassen zu vermeiden empfiehlt das APF-Team die im PHP-Standard PSR-2 beschriebenen Vorgehen zur Quellcode-Strukturierung zu folgen.

Wichtig in diesem Zusammenhang ist die Einhaltung der eine Klasse pro Datei-Regel.

Bitte beachten Sie, dass das APF die im PSR-2- bzw. PSR-4-Standard beschriebenen Vorgaben zu sehr großen Teilen befolgt. Bei der Formattierung des Quellcodes hat das APF-Team davon abweichende Regeln definiert. Detais hierzu können im Wiki unter APF Coding Standard nachgelesen werden.

Kommentare

Möchten Sie den Artikel eine Anmerkung hinzufügen, oder haben Sie ergänzende Hinweise? Dann können Sie diese hier einfügen. Die bereits verfassten Anmerkungen und Kommentare finden Sie in der untenstehenden Liste.
Für diesen Artikel liegen aktuell keine Kommentare vor.