CakePHP 4 security support has ended: a checklist for upgrading to CakePHP 5.4

CakePHP 5.0 was released on 10 September 2023. Under the project's support policy, the previous major line gets 24 months of active support and 36 months of security support after a new major ships, so CakePHP 4.x stopped receiving security fixes on 10 September 2026. If your application still runs on 4.x, every new vulnerability in the framework is now yours to patch.

The good news is that the upgrade path is well documented and partly automated. The CakePHP team publishes an upgrade guide, a migration guide listing every breaking change, and rector rules that rewrite much of the tedious code for you. The bad news is that 5.0 removed everything that was deprecated in 4.5, so an application that ignored deprecation warnings has more work ahead.

This checklist turns the official guides into an ordered plan you can track in a ticket or pull request. It targets CakePHP 5.4, the current minor in October 2026, and was checked against the CakePHP book on 7 October 2026.

Before you start: decide the target and the team

• Target version. Go straight to 5.4. It is the only 5.x minor with active support; 5.2 and 5.3 receive security fixes only. Use the constraint "cakephp/cakephp": "5.4.*".
• PHP version. CakePHP 5.0 needed PHP 8.1, but 5.3 and later require PHP 8.2. Plan the server upgrade to PHP 8.2 or newer (PHP 8.5 is supported) as its own deployable step.
• Databases. CakePHP 5 supports MySQL 5.7+, MariaDB 10.1+, PostgreSQL 9.6+, SQL Server 2012+ and SQLite. Check your production version.
• Plugins. List every CakePHP plugin in composer.json and confirm a 5.x-compatible release exists for each. Abandoned plugins are often the real blocker.
• Tests. Measure how much of the application your test suite exercises. Where coverage is thin, add a few integration tests for the critical flows (login, checkout, admin saves) before you begin.

Phase 1: get clean on the latest 4.x

The upgrade guide is explicit that the rector-based upgrade tool only works on applications running the latest CakePHP 4.x, and cannot be run after you have moved to 5.0. The migration guide asks you to be on at least 4.5 with all deprecations resolved; the last 4.x minor is 4.6.

1. Update to the latest 4.x release and deploy it.
2. Turn on all deprecation warnings in config/app.php:

// config/app.php (on 4.x, before upgrading)
'Error' => [
    'errorLevel' => E_ALL,
],

1. Run the test suite and click through the application, then fix every warning. The guide calls out Table::query(), deprecated in 4.5, as a likely one: replace it with selectQuery(), updateQuery(), insertQuery() or deleteQuery().
2. Upgrade PHP to 8.2 or later while still on 4.x, if your 4.x version supports it (the supported-versions table lists PHP 7.2 to 8.3 for 4.x). This separates the PHP risk from the framework risk.

Phase 2: run the upgrade tool

Install the upgrade tool in a separate directory, not inside your application:

git clone https://github.com/cakephp/upgrade
cd upgrade
git checkout 5.x
composer install --no-dev

Then run its rector rule sets against your application source. The 5.0 guide lists two: one for CakePHP itself and one for Chronos 3, the date library. Because you are going on to 5.4, also run the rules for each later minor, which each migration guide documents:

bin/cake upgrade rector --rules cakephp50 /path/to/app/src
bin/cake upgrade rector --rules chronos3 /path/to/app/src
bin/cake upgrade rector --rules cakephp51 /path/to/app/src
bin/cake upgrade rector --rules cakephp52 /path/to/app/src
bin/cake upgrade rector --rules cakephp53 /path/to/app/src
bin/cake upgrade rector --rules cakephp54 /path/to/app/src

Run them against tests/ and any plugin code you own as well. Commit after each rule set so that the diff stays reviewable.

Phase 3: update dependencies and the app skeleton

Compare your composer.json with the current cakephp/app skeleton. In October 2026 the skeleton requires php >=8.2, cakephp/cakephp 5.4.*, cakephp/migrations ^5.0 and cakephp/plugin-installer ^2.0, with cakephp/bake ^3.6, cakephp/debug_kit ^5.2 and PHPUnit ^11.5.3 || ^12.1.3 || ^13.0 for development. Adjust your constraints, then:

composer update -W

Next, bring the rest of the application in line with the skeleton. Diff these files in particular: src/Application.php (the middleware queue and services()), config/app.php, config/bootstrap.php, config/routes.php, src/Controller/ErrorController.php, webroot/index.php and phpunit.xml.dist. The current skeleton, for example, adds a host-header check that requires App.fullBaseUrl in production.

Phase 4: work through the breaking changes

Rector handles signatures and renames. The changes below usually need a human. Use this as a checklist against the 5.0 migration guide:

Two later-minor changes deserve a place on the list because you will receive them in the same upgrade. CakePHP 5.4 changed the default eager-loading strategy for HasMany and BelongsToMany associations to subquery, and it now throws an exception when an entity is saved, deleted or patched through a table it does not belong to.

A note on large result sets

The 5.0 migration guide lists a known issue: results are always buffered, so iterating very large result sets can use more memory than on 4.x. For exports and batch jobs, disable buffering or hydration on those specific queries, or use the streaming JSON response added in 5.4 for API exports.

Phase 5: tests and tooling

• CakePHP 5 supports PHPUnit 11.5.3+ and 12.1.3+ (PHPUnit 12 needs PHP 8.3). PHPUnit 10 is no longer supported. Run vendor/bin/phpunit --migrate-configuration to update phpunit.xml.
• Replace the fixture extension entry with the bootstrap form: <bootstrap class="Cake\TestSuite\Fixture\Extension\PHPUnitExtension"/> inside <extensions>.
• Make data providers static, and replace withConsecutive() using the helper that CakePHP's TestCase provides.
• The TestSuite class is gone; use environment variables to customise test settings.
• Run a static analyser at a modest level. CakePHP 5 added type declarations throughout, which makes type errors in your own code much easier to find.

Phase 6: release safely

1. Deploy to a staging environment that mirrors production PHP, extensions and database versions.
2. Run database migrations, then clear and rebuild the ORM metadata cache with bin/cake schema_cache clear and bin/cake schema_cache build --connection default.
3. Check error logs for deprecation notices introduced by the newer minors and schedule them; they will be removed in 6.0.
4. Release behind a maintenance window or a load-balancer switch you can reverse. Keep the last 4.x build deployable until the new version has been stable for a while.

Printable checklist

• [ ] Target CakePHP 5.4.* and PHP 8.2+ agreed
• [ ] Every plugin has a CakePHP 5 release (or a replacement plan)
• [ ] On latest 4.x with E_ALL and zero deprecation warnings
• [ ] Rector rules cakephp50, chronos3 and cakephp51 to cakephp54 applied and committed
• [ ] composer.json matches the skeleton; composer update -W clean
• [ ] Application files diffed against cakephp/app 5.x
• [ ] Auth, pagination, shells, dates, email, errors and uploads migrated
• [ ] 5.4 eager-loading and entity-ownership changes tested
• [ ] PHPUnit 11 or 12 configuration migrated; suite green
• [ ] Staging deploy, schema cache rebuilt, rollback plan written

How long will it take?

There is no official estimate, and it depends heavily on the codebase. The biggest variables are how many deprecation warnings remain on 4.x, whether you still use AuthComponent or shells, how many third-party plugins you depend on, and how good your tests are. A practical approach is to time-box Phase 1 on one branch, count the remaining warnings and removed APIs in use, and estimate from that inventory rather than from the size of the application.

Next steps

Once you are on 5.4, stay current: minor releases are backwards compatible by policy, ship their own rector rules, and keep you inside the security window. Read our summary of what changed in CakePHP 5.4 for the behaviour changes to watch, and budget a short upgrade task for each new minor rather than another multi-year jump.