A few months back I upgraded docket and this site to CakePHP 4.5 from an earlier 4.x release. I wanted to share my notes from the upgrade process so that if you’re considering an upgrade you have a better idea of what to expect.
I think it is important to be transparent about the complexity of the applications I upgraded. Both my personal site and docket are relatively simple applications, with good test coverage. Having good test coverage is invaluable when performing upgrades as you can quickly validate that the functionality covered by tests still works correclty. If you don’t already have a good test suite, now is a great time to investing in automated testing.
Before attempting the 4.5 upgrade, I first made sure that I had all the deprecations for earlier 4.4 releases resolved and that my application’s tests passed with the most recent 4.4 release, and latest plugin releases. The CakePHP plugins often fix deprecation issues well before a new minor release ships to make upgrading easier, and I wanted to have as few deprecations as possible to resolve during the 4.5 upgrade.
Use the Upgrade Tool
For both docket and my personal blog, I started off the upgrade by using the CakePHP Upgrade Tool . To get the upgrade tool installed I ran:
- # Clone the repository
- git clone git://github.com/cakephp/upgrade
- # Check out the 4.x branch
- cd upgrade
- git checkout 4.x
- # Install dependencies
- php composer.phar install --no-dev
With the upgrade tool installed, it was time to run the rector refactorings:
bin/cake upgrade rector —rules cakephp45 ../docket-app/src
bin/cake upgrade rector —rules cakephp45 ../docket-app/tests
After running rector on the application code and tests, I didn’t have any failing tests, so it was onto manual fixes for the remaining deprecations.
While rector is able to take care of many of the typing related fixes, there were a few things that I needed to resolve manually.
I had several deprecations under PHP 8.2 related to dynamic properties. Fixing these was a simple but tedious change of adding property declarations to each class that needed them. The diffs for these changes generally look like:
- + use App\Model\Table\ProjectsTable
- + public ProjectsTable $Projects;
I chose to include types on the properties I was adding so that I would get better code completion in my editor, and better results from psalm.
In CakePHP 5.0, the Database and ORM packages contain operation specific query classes. In 4.5.0 the
Table::query() method emits a deprecation telling you to use one of
deleteQuery. These methods return operation specific query objects, that emit deprecations on non-sensical operations like calling
set() on a
For my 4.5.0 upgrade, I had a handful of query operations that needed to be update. Making these changes requires understanding the surrounding context and choosing the correct query class. An example of one of these changes is:
- - $query = $this->table->query()
- - ->update()
- - ->where($scopeConditions);
- + $query = $this->table->updateQuery()->where($scopeConditions);
Recommendations for larger applications
As mentioned before, my upgrades were both on small applications, and I was able to complete the upgrade in a single pull request. For larger applications, this may not be possible and you’ll need to upgrade in multiple changesets. My gameplan for a larger application would be:
- Use the upgrade tool to get as many mechanical changes done as possible.
- Upgrade CakePHP to 4.5.0
- Use the
Error.ignoredDeprecationsconfiguration value to disable deprecations for all paths still emitting deprecations.
- Get the basic upgrade tested and merged.
- Incrementally fix deprecations in reasonably sized batches. Once you’re done a batch remove those paths from the deprecation ignore list.
- Repeat this process until you have no more deprecations.
This process will let you incrementally complete your upgrade and resolve all the deprecations without disrupting your ability to ship new features and bugfixes that your customers care about. I’m interested to hear how this process plays out for folks in the community. If your team has a rough time upgrading to 4.5.0, please open a GitHub Issue as we’d like the upgrade process to be as smooth as possible.