Migration von 1.14 auf 1.15

Auf dieser Seite werden werden alle notwendigen Code-Änderungen für den Umstieg von Version 1.14 auf 1.15 beschrieben.

1. ConnectionManager

Um Angaben zu Port und/oder Socket einheitlich zu definieren wurde der Konfiguration die Möglichkeit mitgegeben nun auch DB.Port und DB.Socket zu definieren. Mit Einführung dieser Konfigurations-Parameter entfällt die Unterstützung im MySQLiHandler, den port aus dem Hostnamen zu extrahieren, entsprechend sind folgende Angaben in der Konfiguration:

Code

DB.Host = "localhost:1234"

fortan so zu definieren:

Code

DB.Host = "localhost"
DB.Port = "1234"

2. URL-Rewriting

Der Parameter für das URL-Rewriting wurde mit Version 1.15 von "apf-rewrited-query" auf "apf-rewritten-query" geändert. Für ein Update auf die neue Version ist es notwendig alle Rewrite-Rules anzupassen, die in bestehenden Projekten genutzt werden.

3. Usermanagement

3.1. Konfiguration

Die Konfiguration des Moduls wurde mit dem Release 1.15 komplett auf dependency injection umgestellt. Dies betrifft in erster Linie die Ablage der Konfigurationen und die Erzeugung des UmgtManager.

3.2.1. Ablage der Konfigurationen

Um auf die Version 1.15 zu wechseln, muss folgendes Schema für die Ablage der Konfigurationen eingehalten werden:

Code

/APF/config/modules/usermanagement/
                                   biz/{Context}/
                                                 {ENVIRONMENT}_actionconfig.ini
                                                 {ENVIRONMENT}_serviceobjects.ini
                                                 {ENVIRONMENT}_umgtconfig.ini
                                   data/{Context}/
                                                 {ENVIRONMENT}_umgt_domainobjects.ini
                                                 {ENVIRONMENT}_umgt_objects.ini
                                                 {ENVIRONMENT}_umgt_relations.ini
                                   pres/{Context}/
                                                 {ENVIRONMENT}_labels.ini
                                                 {ENVIRONMENT}_login.ini

Vorlagen für die genannten Konfigurations-Dateien finden sich im apf-configpack-*-Release. Details zu Inhalt und Bedeutung wird unter Benutzer-Verwaltung beschrieben.

3.1.2. Konfiguration des UmgtManager-Service

Der UmgtManager und die gleichnamige Implementierung wird ab der Version 1.15 ausschließlich über den DIServiceManager bezogen. Er erhält damit alle relevanten Informationen und Abhängigkeiten direkt über den dependency injection container.

Um den UmgtManager per

PHP-Code

$umgt = &$this->getDIServiceObject('modules::usermanagement::biz', 'UmgtManager');

beziehen zu können ist die Konfigurations-Datei *_serviceobjects.ini unter modules::usermanagement::biz (plus zugehörigem Context) erforderlich:

APF-Konfiguration

[UmgtManager]
servicetype = "SESSIONSINGLETON"
namespace = "modules::usermanagement::biz"
class = "UmgtManager"
setupmethod = "setup"
init.orm.method = "setORMapper"
init.orm.namespace = "modules::usermanagement::biz"
init.orm.name = "GORM"
conf.app-id.method = "setApplicationId"
conf.app-id.value = "1"

[GORM]
servicetype = "SESSIONSINGLETON"
namespace = "modules::genericormapper::data"
class = "GenericORRelationMapper"
setupmethod = "setup"
conf.namespace.method = "setConfigNamespace"
conf.namespace.value = "modules::usermanagement::data"
conf.affix.method = "setConfigNameAffix"
conf.affix.value = "umgt"
conf.db.method = "setConnectionName"
conf.db.value = "Umgt"
conf.debug.method = "setLogStatements"
conf.debug.value = "false"

Darüber hinaus müssen für die Verwendung des mitgelieferten Login die Login- und Logout-RedirectUrlProvider definiert werden (siehe Beispiel-Konfigurations-Dateien).

Bitte beachten Sie, dass der Wert von conf.db.value an Ihre lokale Datenbank-Konfiguration angepasst werden muss. Der Wert beschreibt eine Referenz auf eine Konfigurations-Sektion der Datei {ENVIRONMENT}_connections.ini unter /apps/config/core/database/{CONTEXT}/. Details zur Datenbank-Konfiguration können dem Kapitel ConnectionManager entnommen werden.

3.2. Domänen-Objekte

Wie in der Code-Box weiter oben zu erkennen ist, wurde das Modul auf das Domain-Objekt-Feature des Generischer O/R-Mapper umgestellt. Dies bedeutet, dass der GORM beim Laden der in der *_umgt_objects.ini definierten Objekte konkrete Typen statt dem GenericDomainObject zurückliefert. Dies erleichtert zum einen die Unterscheidung der behandelten Objekte und lässt die API des UmgtManager griffiger erscheinen.

Für die Migration auf die neue Version ist es daher notwendig, dass die Datei EXAMPLE_umgt_domainobjects.ini aus config/modules/usermanagement/data/ für die aktuelle Applikation konfiguriert wird. Erfolgt dies nicht, kann es zu Fehlern kommen, die besagen, dass ein GenericDomainObject statt eines erwarteten Typs UmgtUser (oder jedes weiteren neuen Types) bei einer Operation verwendet wird.

3.3. Update des Daten-Modells

Einhergehend mit der Erweiterung der Funktionen ist auch eine Erweiterung des Daten-Modells erfolgt. Um auf das neue Daten-Modell zu migrieren, kann das Update-Tool des GORM genutzt werden.

Bitte beachten Sie: Vor dem Update einer bestehenden Datenbank mit Inhalten, die nicht nur das UMGT betreffen, sollten Sie eine Sicherung Ihrer Datenbank durchführen. Bei einer fehlerhaften Konfiguration kann es zu Datenverlust kommen. Ausserdem müssen Sie das nachfolgende Beispiel an Ihre erweiterten Bedürfnisse anpassen!

Beispiel:

PHP-Code

require('./apps/core/pagecontroller/pagecontroller.php');

import('modules::genericormapper::data::tools', 'GenericORMapperUpdate');
$update = new GenericORMapperUpdate();
$update->setContext('xyz');
$update->updateDatabase('modules::usermanagement::data', 'umgt', 'Umgt', true);

Damit wird das aktuelle Schema aktualisiert und kann mit der Version 1.15 des APF genutzt werden.

4. API

Auch diese Version beinhaltet eine Reihe von API-Änderungen. Die folgende Liste zeigt die notwendigen Änderungen auf:

AbstractFilterChain::addFilter() wurde zu AbstractFilterChain::appendFilter() umbenannt. Zusätzlich dazu wurde die Methode AbstractFilterChain::prependFilter() eingeführt. Details können der Dokumentation unter Filter entnommen werden.
Die Unterstützung für das file-Attribute bei der Controller-Deklaration wurde entfernt, um die Deklarations-Konvention des APF besser zu unterstützten. Daraus folgt, dass der Klassen- und Dateiname von Dokumenten-Controller identisch sein muss.
Die Klasse stringAssistant wurde in StringAssistant umbenannt.
Die Klasse stringEncryptor wurde in StringEncryptor umbenannt.

5. Kontakt-Formular-Modul

Das Kontakt-Formular unterstützt nun per Konfiguration Sprach-abhängige Templates für den Versand der Bestätigungs- und Benachrichtigungs-E-Mails. Beim Update auf die neue Version ist es daher notwendig, die Konfiguration der Templates für die aktuelle Applikation anzulegen.

Als Vorlage kann die Beispiel-Konfiguration EXAMPLE_mail_templates.ini unter /config/modules/kontakt4/ genutzt werden. Diese hat folgenden Inhalt (gekürzt):

APF-Konfiguration

[de]
confirmation.namespace = "modules::kontakt4::pres::templates::mail"
confirmation.template = "confirmation_de"

notification.namespace = "modules::kontakt4::pres::templates::mail"
notification.template = "notification_de"

[en]
confirmation.namespace = "modules::kontakt4::pres::templates::mail"
confirmation.template = "confirmation_en"

notification.namespace = "modules::kontakt4::pres::templates::mail"
notification.template = "notification_en"

Das Modul erwartet die Konfiguration unter dem Pfad

Code

/APF/config/modules/kontakt4/{CONTEXT}/{ENVIRONMENT}_mail_templates.ini

6. Refactoring der *:getstring-Tags

Das Release 1.15 beinhaltet ein umfassendes Refactoring der *:getstring-Tag-Familie. Diese wurden vom tools- in den core-Namespace umgezogen um die Einbindung und Verwendung zu erleichtern.

Für die Migration bedeutet das, dass alle Stellen von

Html-Code

<*:addtaglib
   namespace="*"
   prefix="*"
   class="getstring"
/>

aus dem Code entfernt werden. Die Tags sind nun automatisch zur Verwendung bekannt.

7. Eigene ErrorHandler

Mit dem Release 1.15 wurde die globale Fehler-Behandlung refactored. Die Konfiguration eines eigenen ErrorHandler funktioniert damit nicht mehr über die Registry, sondern über die Klasse GlobalErrorHandler innerhalb der Boostrap-Datei.

Eigene ErrorHandler werden nicht wie bisher per

PHP-Code

Registry::register(
   'apf::core',
   'ErrorHandler',
   new ErrorHandlerDefinition(
      'my::errorhandler::namespace',
      'MyErrorHandler'
   )
);

sondern via

PHP-Code

import('my::errorhandler::namespace', 'MyErrorHandler');
GlobalErrorHandler::registerErrorHandler(new MyErrorHandler());

nach dem Einbinden der pagecontroller.php konfiguriert.

Details können der Dokumentation unter Fehlerbehandlung entnommen werden.

8. Eigene ExceptionHandler

Wie im vorangegangenen Kapitel für die globale Fehlerbehandlung beschrieben, wurde auch die globale Exception-Behandlung im Release 1.15 refactored. Die Konfiguration eines eigenen ExceptionHandler funktioniert damit nicht mehr über die Registry, sondern über die Klasse GlobalExceptionHandler innerhalb der Boostrap-Datei.

Eigene ExceptionHandler werden nicht wie bisher per

PHP-Code

Registry::register(
   'apf::core',
   'ExceptionHandler',
   new ExceptionHandlerDefinition(
      'my::exceptionhandler::namespace',
      'MyExceptionHandler'
   )
);

sondern via

PHP-Code

import('my::exceptionhandler::namespace', 'MyExceptionHandler');
GlobalExceptionHandler::registerExceptionHandler(new MyExceptionHandler());

nach dem Einbinden der pagecontroller.php konfiguriert.

Details können der Dokumentation unter Exception-Behandlung entnommen werden.

9. Konfiguration Logger

Mit dem vorliegenden Release wurde der Logger um die Konfiguration von Schwellwerten bzw. Profilen für Log-Einträge erweitert. Liegt ein Eintrag mit einer definierten severity oberhalb des definierten Schwellwertes bzw. innerhalb des gewählten Profils, so wird der Eintrag in die Log-Datei geschrieben. Falls dies nicht zutrifft, wird er verworfen.

Im Auslieferungszustand werden die severities

LogEntry::SEVERITY_WARNING
LogEntry::SEVERITY_INFO
LogEntry::SEVERITY_ERROR
LogEntry::SEVERITY_FATAL

als gültige Eintragstypen definiert.

DEBUG-Ausgaben (z.B. aus den Datenbank-Verbindungs-Klassen) werden daher ohne Anpassung der Konfiguration zunächst nicht mehr in die Log-Dateien geschrieben.

Um den Zustand vor 1.15 wiederherzustellen, ist folgender Code in der Bootstrap-Datei nach dem Einbinden der pagecontroller.php notwendig:

PHP-Code

import('core::logging', 'Logger');
$log = &Singleton::getInstance('Logger');
$log->setLogThreshold(Logger::$LOGGER_THRESHOLD_ALL);

Alternativ dazu können Sie eigene Profile z.B. per

PHP-Code

import('core::logging', 'Logger');
$log = &Singleton::getInstance('Logger');
$log->setLogThreshold(array(
   LogEntry::SEVERITY_TRACE,
   LogEntry::SEVERITY_INFO
));

definieren.

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.

Migration von 1.14 auf 1.15

Kommentare

QUICKNAVI