Migration from 1.15 to 1.16

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

1. Refactoring of the APF parser

1.1. Introduction

In 1.16 the internal representation of an APF tag and the respective mechanisms within the APF parser changed.

One disadvantage of the previous implementation is the tag class naming convention. PHP class names had to follow the XML prefix and class/tag name. The new implementation enables you to

  • re-use identical tag classes within all tag hierarchies using a different prefix and name and
  • naming of the tag implementation class using UCC notation.

Besides, a smaller amount of classes must be loaded what makes the application faster. Details on the discussion can be read about under http://forum.adventure-php-framework.org/viewtopic.php?f=10&t=1131.

1.2. Migration

Existing applications can be used with nearly no adaption, since the tag implementation of the <core:addtaglib /> tag supports both the new signature as well as the old one (Version <= 1.15). The old one works as described and is translated into the new scheme.

Migration consists of two parts. The first one is optional.

1.2.1. Adaption of the <core:addtaglib /> tags

In releases <= 1.15 (custom) tags can be published to the APF parser using

APF template
<core:addtaglib namespace="tools::form::taglib" prefix="html" class="form" />

Since this release developers are free to define the name of the tag themselves. For this reason, the tag expects the class attribute to contain the name of the tag implementation and name to contain the name of the tag.

Including the <html:form /> tag thus is as follows:

APF template
<core:addtaglib namespace="tools::form::taglib" class="html_taglib_form" prefix="html" name="form" />

In 1.16 both flavours are supported to use you applications without further adaptions. The fallback mechanism will be removed in further versions. Thus, it is recommended to migrate your application switching to 1.16.

In 1.16 not all classes have been adapted to UCC naming. This is planned for the next releases.

In case class names of existing application do not change, migration can be done with a little help of the following regular expressions:

Code
Search pattern: <core:addtaglib\W*?namespace="([A-Za-z0-9:\-_]+)"\W*?prefix="([A-Za-z0-9:\-_]+)"\W*?class="([A-Za-z0-9:\-_]+)"\W*?/> Replacement: <core:addtaglib namespace="$1" class="$2_taglib_$3" prefix="$2" name="$3" />
1.2.2. Adaption of taglib definitions

One of the main elements of the APF parser is the tag definition. In 1.16 the signature of the TagLib has changed as follows:

PHP code
final class TagLib { public function __construct($namespace, $class, $prefix, $name) { } }

The class now expects 4 instead of 3 parameters. It is now required to apply the name of the implementation ($class). The new parameter $name takes the name of the tag within APF templates. $namespace contains the namespace where the tag implementation (see $class) is located and $prefix defines the tag prefix.

In case class names of existing application do not change, migration can be done with a little help of the following regular expressions:

Code
Search pattern: new TagLib\('([A-Za-z0-9:\-_]+)', '([A-Za-z0-9:\-_]+)', '([A-Za-z0-9:\-_]+)'\) Replacement: new TagLib('$1', '$2_taglib_$3', '$2', '$3')

2. New behaviour of ServiceManager and DIServiceManager

2.1. Usage of context and language

Since 1.16, ServiceManager as well as the DIServiceManager use context and language to create Singleton or SessionSingleton objects. This means, that there is one instance for each context-language couple instead of a single instance within the current scope.

This behaviour can be influenced by applying an $instanceId manually.

2.2. Singletons without context and language

In order to create singletons that are unique within the current scope without respect to context and language it is recommended to use the $instanceId parameter:

PHP code
// within a class that inherits from APFObject ... $namespace = 'my::namespace'; $serviceName = 'ExampleClass'; $instanceId = $namespace . '::' . $serviceName; $ECO = $this->getServiceObject($namespace, $serviceName, APFService::SERVICE_TYPE_SINGLETON, $instanceId);

Using this method, $instanceId must be present as the 4th parameter every time the service is retrieved (see above sample).

$instanceId has been introduced with 1.16 and is not present in prior versions.
Please note, that with this service creation method there may be issues with services that do not fit to the current application configuration! Detail can be taken from the forum discussion: http://forum.adventure-php-framework.org/viewtopic.php?f=5&t=1146 (German).

2.3. New cache behaviour of the DIServiceManager

The DIServiceManager manages a cache that delivers objects that already have been created in prior calls. In case a service is already in the cache your request is served using the cached object.

Since 1.16 the cache respects context and language as described above for the ServiceManager. In contrast, services with the NORMAL type are created at each call.

In case of services that are not created using the Singleton or SessionSingleton wrappers and where caching is possible - or at least no problem - it is recommended to use the CACHED service type. This type equals NORMAL until release 1.15. For performance reasons using CACHED is explicitly recommended!

3. Adaption of the XmlParser

During feature discussion on Unterst├╝tzung " und ' als Attribut-Abgrenzung (German) the performance of the XmlParser has been improved again. Since 1.16 blanks within attribute values are no longer filtered. This improves performance up to 20%

Switching to 1.16 a place holder definition like

APF template
<html:placeholder name=" Foo" />

accessed by

PHP code
$this->setPlaceHolder('Foo', 'Bar');

will cause an error (place holder not found). Please be aware of this change and check your template code updating to release 1.16.

The handling of attribute names is still the same.

4. Adaption configuration of the StringEncryptor

In release 1.16 a typo within the {ENVIRONMENT}_encryption.ini configuration has been fixed. The content of the configuration must be updated from

APF configuration
[Standard] PasswortSalt = ""

to

APF configuration
[Standard] PasswordSalt = ""

The file can be found under config/tools/string/{CONTEXT} within your project.

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.