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? Fe 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

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.