README

Helps automating the upgrade process from CakePHP 1.1/1.2/1.3 to CakePHP 2.x and above.

Important Notice - 2014-02

This plugin is now in "feature-freeze" in favor of the all new standalone CakePHP Upgrade Tool - built with CakePHP 3.x. Please help to migrate all 2.x and 3.x relevant upgrade commands to this new repo.

Improved version (built on top)

The original one lacks a lot of things that could be done automatically. Changes have been reported as ticket, but so far it has not yet made it into the official version.

Note: Some of the following "installation" steps are only necessary upgrading from 1.x (like folder renaming). Do not think of them as a perfectly adjusted worklist (also don't mind the order). Every app, every setup is different. It is more a small guide to get the basics straight.

It can also apply a lot of additional sugar and enforce coding standards etc. Those commands are not vital, but nice to have.

Installation

Composer (recommended)

Execute the following from within the folder where your composer.json file is located:

composer require --dev dereuromark/cakephp-upgrade dev-master

Custom

a) Make sure you got the lastest stable 2.x version of the CakePHP core. Usually you just copy the /lib folder of the current Cake master branch into a /lib folder next to your /app dir.

b) Copy this plugin into your /app/Plugin folder as /app/Plugin/Upgrade.

c) Manually rename /app/config folder to /app/Config (we need the bootstrap.php here).

d) Put CakePlugin::load('Upgrade') or CakePlugin::loadAll(); in your app/Config bootstrap to make sure this plugin is loaded.

e) Either put the cake shell from the downloaded 2.x repository in app/Console or use the lib/Cake one.

f) Ready to go! Run any of the available commands (see details below). The most important one is locations and should be run first.

Don't forget to remove the old (1.x) /cake folder and manually clear the (persistent) cache before running the shell.

I never really had to manually replace my core.php with the new 2.x core.php. But as there are many new features introduced, it might make sense to do that. Just don't forget to merge your existing settings like salt and cache/session/cookie settings. Or at least compare your config files to the current master ones.

Remember: At this point you are already using the shell as 2.x shell. "cake1.x" or whatever you used before is now officially dead.

Also: Mind the casing! Uppercase/lowercase is important.

Usage

Upgrade shell

As this is a plugin, use it with:

cake Upgrade.Upgrade [command]

Running it without any command will get you a list of possible commands to chose from. Make sure to check on this first. You might have to set the executable rights for your cake shell first in order to run any shell (on unix anyway).

Note: If you use Unix the full command (relative from your app dir!) would be:

../lib/Cake/Console/cake Upgrade.Upgrade [command]

On Windows:

..\lib\Cake\Console\cake Upgrade.Upgrade [command]

And if you use the app/Console shell instead (for this to work, you also need to copy over the Console files from /Templates/skel/ in the core repo):

Console/cake Upgrade.Upgrade [command]

For Windows:

.\Console\cake Upgrade.Upgrade [command]

The short version using APP/Console is preferred as you will need those files anyway at some point. It is also the documented approach to call shells in 2.x. Especially if you plan on using composer for your 2.x app.

This version supports now on top of the original commands/tasks:

webroot (important)
database (important)
routes (important)
legacy
name
constructors
report
estrict
views
paginator (run only once!)

and many more

New functionally also supported now:

svn (linux/windows)
group commands
except command (all except for a few, e.g. except paginator to skip paginator method)

Correct shell

Additionally you can use the CorrectShell to correct

request
amp
vis
reference
i18n
forms
conventions
conventions2
html5
php53

with cake Upgrade.Correct [command]

Tip: You can use cake Upgrade.Correct all to quickly apply all relevant correction commands.

Tip2: The probably most important feature for me is that my version cleanly separates app and plugins. Without -p PluginName it leaves them alone. If you want to upgrade plugins use

cake Upgrade.Upgrade [command] -p PluginName

I also added support for -p * - to address all plugins at once. This is only fully supported by the group command like so:

cake Upgrade.Upgrade group [command1] [command2] ... -p *

You need to supply at least two commands (if you want to use only one, type it twice:

cake Upgrade.Upgrade group [command1] [command1] -p *

This is necessary because 1 argument stands for a config group

The not fully tested way of using the plugin wildcard would be

cake Upgrade.Upgrade [command] -p *

which should just grab all files at once and process them

Convert shell

The convert shell currenently handles:

Array syntax from long array() to short [] (PHP5.3 to PHP5.4)

MyUpgrade shell

This is mainly Tools plugin and app specific stuff. You can disregard this shell.

UPDATE January 2012: Support for 2.1

Now supports

Auth::allow(), Layout Stuff and more

UPDATE September 2012: Support up to 2.3

Now supports

request->query() and Set/Hash replacement

UPDATE December 2012:

Now creates missing App classes that are required since 2.1

AppHelper, AppModel and AppController (AppShell is not yet required)

UPDATE Summer 2013: 2.4/2.5 (and some 3.0) support

onlyAllow() to allowMethod() etc

UPDATE Summer 2014: 2.6 support

Some validation rules changed

UPDATE 2015: 2.7 and 2.8 support

Disclaimer

Use this script ONLY after backing up your app folder.

Also: This powerful plugin is not for N00bs. Do NOT use it if you don't know at least some Cake basics.

Troubleshooting

Make sure you have debug mode enabled and/or cleared the cache.
Use a fresh 2.x app and play with the plugin to get a grasp on how the new major version works, and how the plugin operates, if it is your first trial with 2.x. Then - with some more insight - it will be easier to migrate 1.x apps to 2.x.

My recommendation

Either use git or svn or some other version control to verify the changes made. This way you are able to detect wrong replacements right away. So better use every upgrade command separatly and commit/push after each successful run. If sth goes wrong with one command you can easily revert to the last step this way. The regexp commands sometimes can be too eager and have not been tested to their full extend. So please be careful.

So the ideal order might be:

locations
webroot
routes
database
[the rest - the application might already be browsable again at this point]

Stuff you REALLY have to do on your own (imagine that^^)

make sure you add missing App::uses() statements to your class files
fix some more ESTRICT errors
apply missing configuration for new features

AND everything else that is not yet covered but meticulously documented in the migration guides:

dereuromark / cakephp-upgrade

Maintainers

Details