CakePHP 2.x upgrade shell
, (*1)
Helps automating the upgrade process from CakePHP 1.1/1.2/1.3 to CakePHP 2.x and above., (*2)
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., (*3)
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., (*4)
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., (*5)
It can also apply a lot of additional sugar and enforce coding standards etc. Those commands are not vital, but nice to have., (*6)
Installation
Composer (recommended)
Execute the following from within the folder where your composer.json file is located:, (*7)
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., (*8)
b) Copy this plugin into your /app/Plugin folder as /app/Plugin/Upgrade., (*9)
c) Manually rename /app/config folder to /app/Config (we need the bootstrap.php here)., (*10)
d) Put CakePlugin::load('Upgrade') or CakePlugin::loadAll(); in your app/Config bootstrap to make sure this plugin is loaded., (*11)
e) Either put the cake shell from the downloaded 2.x repository in app/Console or use the lib/Cake one., (*12)
f) Ready to go! Run any of the available commands (see details below). The most important one is locations and should be run first., (*13)
Don't forget to remove the old (1.x) /cake folder and manually clear the (persistent) cache before running the shell., (*14)
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., (*15)
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., (*16)
Also: Mind the casing! Uppercase/lowercase is important., (*17)
Usage
Upgrade shell
As this is a plugin, use it with:, (*18)
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)., (*19)
Note: If you use Unix the full command (relative from your app dir!) would be:, (*20)
../lib/Cake/Console/cake Upgrade.Upgrade [command]
On Windows:, (*21)
..\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):, (*22)
Console/cake Upgrade.Upgrade [command]
For Windows:, (*23)
.\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., (*24)
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, (*25)
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, (*26)
- request
- amp
- vis
- reference
- i18n
- forms
- conventions
- conventions2
- html5
- php53
with cake Upgrade.Correct [command], (*27)
Tip: You can use cake Upgrade.Correct all to quickly apply all relevant correction commands., (*28)
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, (*29)
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:, (*30)
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:, (*31)
cake Upgrade.Upgrade group [command1] [command1] -p *
This is necessary because 1 argument stands for a config group, (*32)
The not fully tested way of using the plugin wildcard would be, (*33)
cake Upgrade.Upgrade [command] -p *
which should just grab all files at once and process them, (*34)
Convert shell
The convert shell currenently handles:, (*35)
- 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., (*36)
UPDATE January 2012: Support for 2.1
Now supports
- Auth::allow(), Layout Stuff and more, (*37)
UPDATE September 2012: Support up to 2.3
Now supports
- request->query() and Set/Hash replacement, (*38)
UPDATE December 2012:
Now creates missing App classes that are required since 2.1
- AppHelper, AppModel and AppController (AppShell is not yet required), (*39)
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., (*40)
Also: This powerful plugin is not for N00bs. Do NOT use it if you don't know at least some Cake basics., (*41)
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., (*42)
So the ideal order might be:
- locations
- webroot
- routes
- database
- [the rest - the application might already be browsable again at this point], (*43)
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:, (*44)
- http://book.cakephp.org/2.0/en/appendices/2-0-migration-guide.html
- http://book.cakephp.org/2.0/en/appendices/2-1-migration-guide.html
- http://book.cakephp.org/2.0/en/appendices/2-2-migration-guide.html
- http://book.cakephp.org/2.0/en/appendices/2-3-migration-guide.html
- http://book.cakephp.org/2.0/en/appendices/2-4-migration-guide.html
- http://book.cakephp.org/2.0/en/appendices/2-5-migration-guide.html
- http://book.cakephp.org/2.0/en/appendices/2-6-migration-guide.html
- http://book.cakephp.org/2.0/en/appendices/2-7-migration-guide.html
Wallogit.com
