If you have been using FLOW3 so far, chances are high you will want to follow up on TYPO3 Flow for all the new goodies it provides. But how hard is an upgrade of existing code? Let me show you…

What has changed

The most obvious change is the renaming of FLOW3 to TYPO3 Flow. Since the product name is reflected in the PHP namespace of classes, all code using FLOW3 needs to be adjusted and FLOW3 must be replaced by TYPO3\Flow.

The next big thing in TYPO3 Flow is the integration of composer for dependency management. This requires all code to follow the PSR-0 rules for class autoloading - something FLOW3 did not do fully. So the vendor and package name parts of the PHP namespaces need to be reflected in the Classes folder structure of a package.

Finally we added ittle change to your database schema - flow3_persistence_identifier has become persistence_object_identifier during the renaming.

Upgrading existing code

Here comes the easier part. As with earlier changes to FLOW3 that required code changes on the user side we provide a code migration tool. Given you have a TYPO3 Flow system with your (outdated) package in place you should run the following before attempting to fix anything by hand:

./flow core:migrate --package-key Acme.Demo

The package key is optional, if left out it will work on all packages it finds - for the first run you might want to limit things a little to keep the overview, though.

Inside core:migrate

The tool roughly works like this:

• Collect all code migrations from packages
• Collect all files from all packages (except Framework and Libraries)
• For each migration and package
• Check for clean git working copy (otherwise skip it)
• Check if migration is needed (looks for Migration footers in commit messages)
• Apply migration and commit the changes

Afterwards you probably get a list of warnings and notes from the migrations, check those to see if anything needs to be done manually.

Check the created commits and feel free to amend as needed, should things be missing or wrong. The only thing you must keep in place from the generated commit messages is the Migration: … footer. It is used to detect if a migration has been applied already, so if you drop it, things might get out of hands in the future.

Upgrading the database schema

Upgrading the schema is the harder part this time. You will probably start by running

./flow doctrine:migrationgenerate

as usual to create a migration based on the current state of database and code. This time things are a bit special, since the primary key of a lot of tables will change due to the renaming of the FLOW3_Persistence_Identifier property.

The hard part are the foreign key constraints that need to be updated with this. The migration generated by Doctrine will contain commands to rename that column for your package's models (tables) but will not handle any foreign keys from other packages that might point to them. We have a solution though.

When adjusting your generated migration (as usual you need to check it anyway), just follow the following recipe:

• Order SQL statements to (the file might look similar to this afterwards)
  • dropping foreign key constraints
  • renaming fields
  • adding foreign key constraints
• Remove any SQL statements dealing with foreign key constraints
• Before the remaining statements adjusting your package's primary key columns add

   // collect foreign keys pointing to "our" tables
  $tableNames = array(
   'acme_demo_foo', // change this!
   'acme_demo_bar', // change this!
  );
  $foreignKeyHandlingSql = Service::getForeignKeyHandlingSql($schema, $this->platform, $tableNames, 'flow3_persistence_identifier', 'persistence_object_identifier');
  
   // drop FK constraints
  foreach ($foreignKeyHandlingSql['drop'] as $sql) {
   $this->addSql($sql);
  }

• After the remaining statements add

   // add back FK constraints
  foreach ($foreignKeyHandlingSql['add'] as $sql) {
   $this->addSql($sql);
  }

In the code to add, you have to adjust the list of affected tables - it needs to list all tables in your package that have a flow3_persistence_identifier column. The file should now look roughly similar to this one.

Afterwards make sure to try your migration in up and down direction as usual before using it in production!

Famous last words

In a nutshell, running

./flow core:migrate
./flow doctrine:migrationgenerate

padded with some manual checking and adjustments needs to be done. That should result in a working package. *cough*

If it does not and you have no idea what to do next, please come over to #typo3-flow on freenode IRC or ask in the mailing list (news group) as you prefer.