cakephp upgrade from 2.10 to 3.x

Question

I need to upgrade a project from 2.10 to 3.x.

I am using the official migration tool https://book.cakephp.org/3/en/upgrade-tool.html, with below command:

bin/cake upgrade all

Even though this does several changes, it ends in an unusable installation with various fatal errors.

I know there are manual steps to be taken, but I cannot find them documented anywhere.

My questions are:

1. Is there a guide somewhere about the steps needed?

2. The tool doesn't actually update the version to 3.0. This I need to do as below. Is this correct? Should I update before running the migration tool, or after?

   $ composer require cakephp/cakephp:^3.0

3. Do I need to run the bin/cake upgrade skeleton command as well? F.e this creates the /src and /webroot files. Should I run this first?

4. Is there any cleanup needed at the end, as the tool leaves also the old structure.

Answer 1

I am currently working on the project migrating from 2.x to 3.x. Due to the size of the project and its complexity our approach is to migrate step by step.

The first phase was to add namespaces to all our classes except models, make them loaded by composer and get rid of dependency to ClassRegistry.

The second phase that we currently in is to migrate the model layer. We do it by using both 2.x models and 3.x model at the same time in the same project. https://github.com/cakephp/orm needs to be installed by composer and it does not conflict with 2.x classes. The process is this - take one method from 2.x model, migrate it to 3.x model (table class), adjust any code that uses this method to use entity object. This way we have User class in Model folder and UsersTable class in Model/Table folder at the same time.

In order to be able to use the entity objects with FormHelper we created Form3xHelper class that extends FormHelper, overrides create and _introspectModel methods to support the same method signature as the real 3.x FormHelper and to use the entity object for setting form fields.

The next phase will be to migrate all FormHelper changes from 2.x to 3.x what can also be done step by step by adjusting our Form3xHelper.

After migrating the model and FormHelper layer it will be not so hard to migrate controllers.

I almost forgot to mention that we use ShimPlugin - https://github.com/dereuromark/cakephp-shim/tree/cake2.

Answer 2

There's probably no 2.x application in existence anywhere in this universe that could be automatically upgraded into a working 3.x app, you will still have to fix up and migrate most of your application code and configuration manually, the upgrade tool is really just a helper that can do some of the repetitive tasks for you.

It is strongly recommended that you first make yourself familiar with CakePHP 3.x, to the point where you are confident in your ability to create solid working applications with it, this will help you solve many questions that can possibly come up in the migration process, and will improve the quality of your migrated application!

That being said:

1. I don't know of any exhaustive guide (which doesn't mean there isn't one), but you can easily find people writing about their upgrade experiences, for example https://www.dereuromark.de/2015/06/06/cakephp-3-0-migration-notes

2. The tool doesn't update the CakePHP dependency, no. It expects that you composerify your application yourself, and that you upgrade your dependencies yourself, it couldn't possibly solve the dependency conflicts that can arise when upgrading the core.

   Ideally it shouldn't matter if you upgrade the dependencies first or last, but to be on the safe side you should do it after running the upgrade tool.

3. You don't neccesarily have to run the skeleton task, you could also copy the files from the 3.x application skeleton manually if you know what you're doing - in any case, those files are required, and they should be added after all other tasks have been run, you wouldn't want any of the tasks to change the code of these files. Note that the skeleton task will overwrite some of your files, like for example bootstrap.php and routes.php!

4. Yes, you'll have to clean up possible remains yourself.