Migration from 1.14 to 1.15

This page describes all changes to your current code to update your APF installation from 1.14 to 1.15.

1. ConnectionManager

To be able to define database ports and sockets individually, the configuration of the database connection has changed. You may now specify the DB.Port and DB.Socket and old definitions (e.g. for your mysqli connection) such as

Code

DB.Host = "localhost:1234"

are no longer supported. Updating to 1.15, ports must be defined separately:

Code

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

2. Url rewriting

In 1.15 the request parameter containg the full url has been renamed from "apf-rewrited-query" to "apf-rewritten-query". To update to this version, please adapt all rewrite rules for your existing projects.

3. User management

3.1. Configuration

The configuration of the user management module is now completely built on dependency injection. This applies to creating and configuring the UmgtManager.

3.2.1. Configuration folders

In order to update to release 1.15, the following configuration scheme must be created/adapted:

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

Templates for these configuration files can be found in the apf-configpack-* release files. Details on the content and the meaning can be found under .

3.1.2. Configuration of the UmgtManager service

The UmgtManager and it's same-name implementation is created and managed by the DIServiceManager only as of release 1.15. Thus, the manager is provided all configuration and dependencies via dependency injection container.

To retrieve the UmgtManager via

PHP-Code

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

from the container, the configuration file *_serviceobjects.ini must be present under modules::usermanagement::biz plus the appropriate context path:

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"

Moreover, a login and logout redirect url provider must be configured as you can take from the sample configuration files.

Please note, that conf.db.value must be adapted to your local database. This value refers to the database configuration file {ENVIRONMENT}_connections.ini located under /apps/config/core/database/{CONTEXT}/. Details in database configuration can be taken from ConnectionManager.

3.2. Domain objects

As noted above, the user management module is now built on the domain object feature of the Generic OR mapper. This means, that the GORM returns dedicated object types defined within the *_umgt_objects.ini instead of GenericDomainObject instances. For your day-to-day work, this means ease of use and makes the API of the UmgtManager more valuable.

Migrating to the new version it is necessary to create the EXAMPLE_umgt_domainobjects.ini file under config/modules/usermanagement/data/. In case the configuration is missing, you are facing issues with incompatible object types e.g. accessing methods that are only defined for UmgtUser on an instance of GenericDomainObject.

3.3. Update of the data model

Together with updates to the functionality of the user management module the data model has been enhanced. To update an existing installation to the new scheme, you can use th Update-Tool of the GORM.

Please note: it is strongly recommended to create a backup of your existing database. In case of missing or wrong configuration data may get corrupted or get lost. Moreover, the below code sample must be adapted to your application case!

Sample:

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);

Executing the above code will update your database schema. You can now use the user management of the 1.15 release.

4. API

This release contains several API changes. Please refer to the following list to apply the changes to your projects:

AbstractFilterChain::addFilter() has been renamed to AbstractFilterChain::appendFilter(). In addition, the AbstractFilterChain::prependFilter() has been added. Details can be taken from the documentation under Filter.
The support for the file attribute within document controllers has been removed to guarantee consistent addressing of APF-based classes. This means, that class and file names must be equal until now.
stringAssistant has been renamed to StringAssistant.
stringEncryptor has been renamed to StringEncryptor.

5. Contact form module

The contact form module now supports language-dependent templates for confirmation and notification emails. Updating to 1.15 you need to add a template configuration for your application.

You may use the EXAMPLE_mail_templates.ini under /config/modules/kontakt4/ delivered with the apf-configpack-* release file as a basis for your configuration. It's content is like this:

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"

The contact form module expects the configuration file under

Code

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

6. Refactoring of the getstring tags

In 1.15 the *:getstring tag family has been refactored to ease usage. Therefore, the tag implementations have been moved from tools to core.

Updating from 1.14 to 1.15 this means, that all occurrences of

Html-Code

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

must be removed from the code. The tags are now automatically available for usage.

7. Custom ErrorHandler

Within release 1.15 the global error handling mechanism has been reworked. Configuration is now done by the GlobalErrorHandler class within your bootstrap file.

Custom error handlers are no longer defined via

PHP-Code

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

but using the following code:

PHP-Code

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

Please note, that the configuration must be placed after inclusion of the pagecontroller.php.

Details can be taken from Error handling.

8. Custom ExceptionHandler

Along with the error handler changes described in the previous chapter the exception handling mechanism has been reworked, too. Configuration is now done by the GlobalExceptionHandler class within your bootstrap file.

Custom exception handlers are no longer defined via

PHP-Code

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

but using the following code.

PHP-Code

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

Please note, that the configuration must be placed after inclusion of the pagecontroller.php.

Details can be taken from Exception handling.

9. Configuration of the Logger

The Logger now supports threshold definition (a.k.a. severity profiles) for log severity. In case a log statement's severity is above the threshold level (a.k.a. matches the profile) it is passed to the log file. Otherwise, the entry is discarded.

By default the following severity are included in the standard profile:

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

Compared to 1.14, DEBUG messages (e.g. from the database connection classes) are not written to the log file without adaption of the log threshold.

In order to restore the APF's behaviour before 1.15, you may add the following code to your bootstrap file after inclusion of the pagecontroller.php:

PHP-Code

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

Further, you may define your own profile like this:

PHP-Code

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

Comments

Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.

There are no comments belonging to this article.

Migration from 1.14 to 1.15

Comments

QUICKNAVI