Upgrade FLOW3

This page belongs to the FLOW3 Team (category Topic5/FLOW3)

Hint: everything below is reStructuredText - leave the rst tags in place. Thanks!

Upgrading Instructions

This following instructions contain the essential steps for upgrading your FLOW3 1.0 based applications to FLOW3 1.1.

Full Changelog

If in doubt, you'll find many answers to possible questions still unanswered after reading this document by browsing through the full changelogs.

Frozen packages

FLOW3 1.1 contains new mechanisms which improve the development and production speed. An important feature is the ability to freeze packages.

By default, all packages which are part of the FLOW3 distribution, are frozen. For performance reasons, the file monitor won't track modifications to files of frozen packages. After flushing the code caches with flow3:cache:flush FLOW3 will not reflect classes contained in frozen packages but instead retrieve reflection data from a special cache file which is preserved even during the cache flush.

If class files contained in frozen packages are modified, the whole application may behave rather unexpectedly. Therefore you need to make sure that the packages you are working on currently are not frozen.

There are few easy to use commands to control the frozen state of packages:

./flow3 package:list

will list all available packages and indicates which ones are currently frozen.

./flow3 package:freeze TYPO3.FLOW3

freezes the package TYPO3.FLOW3 and

./flow3 package:unfreeze TYPO3.FLOW3

unfreezes it again so that modifications are detected. If a package should stay frozen but its reflection data should be updated once, you can simply run:

./flow3 package:refreeze TYPO3.FLOW3

Instead of a package key you may also specify the magic keyword all. If your application behaves strangely, possibly due to a prior fatal error, you can still use the new --force option which empties all existing caches and runs in a special "safe mode":

./flow3 flow3:cache:flush --force

Code migration

The majority of code changes you will need to do to your applications can be done automatically with the new code migration tool provided with FLOW3 1.1. If you have your packages under Git version control and the working copies are clean a simple:

./flow3 core:migrate

will adjust your code as needed and commit the changes as a migration, recording the applied migration in the commit message.

Feel free to amend the commit as needed, if further adjustments are needed.

Hint

The migration tool will output a list of notes and warnings about things that you might need to adjust manually - make sure to read those.

Also, read the remainder of this document, it contains more details about the changes and possible solutions to problems. The code changes automated with the migration tool are explained in detail at the end of this document.

Package layout changes

The Doctrine package that was part of the FLOW3 1.0 base distributions has been split into three packages Doctrine.Common, Doctrine.DBAL and Doctrine.ORM. If you maintain your own Git submodule records, you should remove the old Doctrine submodule and add the split Doctrine packages to your super project instead.

Database schema changes

As always you should check the database migration status and apply new migrations if there are any. Use:

./flow3 doctrine:migrationstatus

to check and:

./flow3 doctrine:migrate

to apply any pending migrations.

This will take care of the schema updates for packages that supply their needed adjustments. For your own package you will most likely need to create (and adjust) a migration to accommodate it to new behavior in FLOW3 1.1. To do that use:

./flow3 doctrine:migrationgenerate

Here are the things that changed in FLOW3 that you should expect to see in a schema migration:

• long table names get shortened
• nullable column defaults and
• unique keys for identity properties of entities.

(Overly) long table names (more than 63 chars in most cases) are now shortened. Thus you should make sure that affected tables are renamed correctly in your generated schema migrations.

NULL handling for columns has changed. FLOW3 1.1 now defaults to non-nullable columns to behave like Doctrine. This means any column for a literal property will be generated as a non-nullable column. For existing columns you will see adjustments in the generated schema migration.

If you want your column to actually be able to contain NULL values, you must annotate your property with:

@ORM\Column(nullable=true)

Another change is caused by a new feature: the properties of an entity that are marked with the Identity annotation are now transformed into an unique index in the database. The needed index creation statements will also be part of the generated schema migration.

Security framework

Configuration

• The previously shipped DefaultProvider authentication provider configuration has been removed, you must configure all providers yourself now.

  Note

  The authentication provider name (previously: "DefaultProvider") must match the provider name which is stored with each account. Either configure your own authentication provider with the name "DefaultProvider" or configure a new one with a different name and update the accounts accordingly.

• providerClass is deprecated, use provider instead. Provider options are now given in providerOptions.

• Authentication entrypoint configuration needs to be changed from:

  entryPoint:
    WebRedirect:
      uri: login.html
  

  to:

  entryPoint: 'WebRedirect'
  entryPointOptions:
    uri: 'login.html'
  

Password hashing

The default hashing strategy for passwords was changed from PBKDF2 to BCrypt. Also it is now possible to use a mix of password hashing strategies, as the used strategy is stored in the credentialsSource property of an account.

One way to get existing accounts working again is to make sure your default strategy setting matches the used strategy for any accounts created before the change:

TYPO3:
  FLOW3:
    security:
      cryptography:
        hashingStrategies:
          default: pbkdf2

Setting the default strategy to match the one used for 1.0.x will not take advantage of the new (more secure) hashing. Therefore a new fallback configuration option was added. It allows to specify the strategy that was used to generate legacy credentials. It defaults to pbkdf2 and allows for a seamless migration from 1.0 to 1.1. New passwords will be hashed with the default strategy (bcrypt by default) and get the strategy identifier prepended.

Hint

For the strategy … your credentials look like …:

pbkdf2

7kP/laYDXxQ=,iMoNTRTcbY01Q9LSeAaoxV9hq … QEmHm3ottU1yJdw==

bcrypt

$2a$14$2zNPS6TfbMPCdnxuRlheu.2kZAJ … H3DaYwqqIeAgPzN6kTS

saltedmd5

2f1861241e1951f8696f80cf71b43dee,029fc4310e

YAML syntax

The YAML parser has been updated and now behaves stricter and more correct:

• Boolean values must no longer be written as y, yes, n, no but as TRUE and FALSE instead.
• When using backslashes in strings, those are now handled as escape characters inside double quotes. So if you write class names, better wrap them in single quotes.

Routing

Widget configuration in Routes.yaml has changed and needs to be adjusted. If you used e.g. @widget_0.currentPage in Routes.yaml you need to change that to use the correct widget identifier prefixed a double dash. By default the widget identifier is the lowercased fully qualified widget classname with dashes instead of backslashes. For the paginate viewhelper it would thus be typo3-fluid-viewhelpers-widget-paginateviewhelper.

To make things easier and more telling, you can also set a custom widget id in your template. On the widget tag simply set the "widgetId" attribute and use the same in Routes.yaml. This way you can use e.g. "--paginate":

Template.html:

<f:widget.paginate widgetId="paginate" …>

Routes.yaml:

uriPattern:    'posts/page/{--paginate.currentPage}'
defaults:
  '@controller': 'Post'
  '@action':     'index'
  '--paginate':
    '@controller':  ''
    '@package':     ''

Custom Request Handling

If you created custom RequestHandler/-Builder you most probably need to adjust those:

Custom RequestHandlers need to be registered in your Package.php:

public function boot(\TYPO3\FLOW3\Core\Bootstrap $bootstrap) {
      $bootstrap->registerRequestHandler(new Your\Package\Your\RequestHandler($bootstrap));
}

In your RequestHandler you probably want to create an HttpRequest first:

$this->request = \TYPO3\FLOW3\Http\Request::createFromEnvironment();

Then you can create an ActionRequest with:

$this->request->createActionRequest();

Some more pitfalls:

• RequestBuilders are not required anymore, instead you create request & response in the RequestHandler
• If you want to use the routing framework, have a look at \TYPO3\FLOW3\Http\RequestHandler::handleRequest()
• Some convenience methods were removed from \TYPO3\FLOW3\Utility\Environment. You can use corresponding functions of the HttpRequest mostly

Fluid

The form.textbox tag has been renamed to form.textfield.

Manual code migration

In case you do not want or cannot use the automated code migration, this is what needs to be adjusted:

• Replace
  • TYPO3\FLOW3\MVC\CLI with TYPO3\FLOW3\Cli
  • TYPO3\FLOW3\MVC\Web\Routing with TYPO3\FLOW3\Mvc\Routing
  • TYPO3\FLOW3\MVC\Web\Request with TYPO3\FLOW3\Mvc\ActionRequest
  • TYPO3\FLOW3\MVC\Web\Response with TYPO3\FLOW3\Http\Response
  • TYPO3\FLOW3\MVC\Web\SubRequest with TYPO3\FLOW3\Mvc\ActionRequest
  • TYPO3\FLOW3\MVC\Web\SubResponse with TYPO3\FLOW3\Http\Response
  • TYPO3\FLOW3\MVC\Controller\CommandController with TYPO3\FLOW3\Cli\CommandController
  • TYPO3\FLOW3\Property\DataType\Uri with TYPO3\FLOW3\Http\Uri
  • TYPO3\FLOW3\AOP with TYPO3\FLOW3\Aop
  • TYPO3\FLOW3\MVC with TYPO3\FLOW3\Mvc
  • TYPO3\FLOW3\MVC\RequestInterface with TYPO3\FLOW3\Http\Request
  • \AOP with \Aop
  • \MVC with \Mvc
• Use getMainRequest() instead of getRootRequest()
• Use $this->controllerContext->getRequest()->getHttpRequest()->getBaseUri() instead of $this->controllerContext->getRequest()->getBaseUri()
• \TYPO3\FLOW3\MVC\Web\RequestBuilder does not exist anymore. If you need to create requests, do new ActionRequest($parentRequest).
• \TYPO3\FLOW3\MVC\Web\SubRequestBuilder does not exist anymore. If you need to create sub requests, do new ActionRequest($parentRequest).
• \TYPO3\FLOW3\MVC\RequestInterface has been removed, use \TYPO3\FLOW3\Http\Request instead - e.g. if you implemented your own token.
• $supportedRequestTypes are not needed anymore in a controller.

Warning

Class names in pointcut expressions might not be fully qualified, check whether (more) adjustments are needed.