Upgrading instructions ====================== This file contains instructions for upgrading your FLOW3 1.0 based applications to FLOW3 1.1. 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 accomodate 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: * nullable column defaults and * unique keys for identity properties of entities. 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. * ``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': '' 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.