Migration from 3.1 to 3.2

1. Introduction

Version 3.2 is almost fully compatible with it's predecessor. After execution of the automatic migration only minor adaptions are necessary as described in chapter 3.

As of the 3.2 release enhancement of version version 3.1 will be discontinued. Security and bug fixes will be available until mid of 2017.

This article shows how to update your application to APF version 3.2. As you might already be familiar with from previous versions migration can be done in an automated fashion for nearly all changes. For this reason, the release contains two scripts: migrate-code.sh to update your HTML and PHP files and migrate-config.sh for configuration files.

The APF team recommends to use the migration scripts rather than upgrading manually. This not only saves time and money but also ensure that all relevant areas of your project code are covered.

The below chapters contain an in-depth description on how to switch to APF 3.2 and which kind of changes have to be applied to your existing application(s) to run them based on this version.

2. Automated migration

Migration can be done using the migration script shipped along with the release. This release includes changes to code, templates, and configuration files. Using migrate-code.sh and migrate-config.sh you can easily be adapted your existing application to the new scheme.

Please be sure to execute all steps described under Migration from 3.0 to 3.1. In case you are using an order version of the APF, please completely migrate to version 3.1. Instructions can be taken from Articles.
Please create a backup before execution of the scripts to be able to restore parts of your application if necessary!

In case your development environment is windows, please install the latest cygwin version (download under cygwin.com). Migration for Windows Batch Scripts is not supported.

To update the code files to the latest scheme, please execute the script as follows:

Please change to the code directory before execution to avoid unexpected results.
Code
$ /path/to/APF/migration/migrate-code.sh /cygdrive/c/xampp/php/php ############################################# # APF 3.2 automatic code migration # ############################################# Checking PHP executable available ... [OK] Using given php executable at /cygdrive/c/xampp/php/php. PHP Version: 5.6.12. ############################################# Starting migration ... * Migrate place holder methods ... * Rewrite deprecated registerAction() to addAction() ... ############################################# Migration done! Please check your code and follow instructions within migration documentation!

To update the configuration files to the latest scheme, please execute the script as follows:

Please change to the configuration directory before execution to avoid unexpected results.
Code
$ /path/to/APF/migration/migrate-config.sh /cygdrive/c/xampp/php/php ############################################# # APF 3.2 automatic configuration migration # ############################################# Checking PHP executable available ... [OK] Using given php executable at /cygdrive/c/xampp/php/php. PHP Version: 5.6.12. ############################################# Starting configuration migration ... ############################################# Migration done! Please check your configuration and follow instructions within migration documentation!

3. Manual steps

Unfortunately, not all components of your application can be migrated by the delivered scripts. This chapter lists all changes to be applied by hand.

3.1. API change place holder

In version 3.2 methods setPlaceHolderIfExist() and setPlaceHoldersIfExist() have veen removed from classes Document and BaseDocumentController due to Issues #284. This improved performance for setting place holders significantly.

During automated migration both methods will be removed from your project code automatically. Please ensure that both methods are removed from code that overwrites APF functionality.

Please use setPlaceHolder() and setPlaceHolders() instead. Both methods will no longer throw an InvalidArgumentException as of release 3.2 in case a place holder has not been found.

3.2. BenchmarkTimer report

With issues #214 performance of the BenchmarkTimer has been significantly improved. To ensure better extensibility the measuring and report generation functionality have been separated. Measuring events is now delivered by DefaultStopWatch and HtmlReport takes responsiblity for report generation.

To ease analysis of the HTML reports even before version 3.2 critical times are marked red. To adapt the default threshold for critical times you can use method setCriticalTime():

PHP code
$t = Singleton::getInstance(BenchmarkTimer::class); $t->setCriticalTime(0.15); echo $t->createReport();

Since report generation is now part of a separate component - HtmlReport - definition of critical times must be done with this new component. For this reason, please adapt all above code snippets as described in the subsequent code box:

PHP code
$t = Singleton::getInstance(BenchmarkTimer::class); $report = new HtmlReport(); $report->setCriticalTime(0.15); echo $t->createReport($report);

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.