CakePHP 5.4: What's New, Release History & EOL Status

What Is New in CakePHP 5.4

CakePHP 5.4 ships a focused set of upgrades: a smarter default for association loading, long-requested database query helpers, expanded collection utilities, and a more ergonomic command API. Nothing is ripped out -- this is an additive release with a few deliberate behavior changes worth knowing before you upgrade.

How Does the New Default Association Strategy Affect Your Queries?

HasMany and BelongsToMany associations now default to subquery strategy instead of select. In practice, this produces more correct results when pagination or custom conditions are applied to the parent query -- the old select strategy could silently return wrong counts in those scenarios.

If you need the old behavior, set it explicitly when defining the association:

$this->hasMany('Comments', [
    'strategy' => 'select',
]);

Review any association that depends on query result ordering or pagination before upgrading. The subquery strategy is generally safer, but it does add a subquery to the SQL, so benchmark if you have performance-sensitive reads on very large tables.

What Changed About afterSaveCommit and afterDeleteCommit Events?

Previously, Model.afterSaveCommit and Model.afterDeleteCommit were not fired when save() or delete() ran inside an outer transaction. That was a gap -- if you wrapped multiple saves in a transaction and relied on those events for side effects (sending emails, syncing caches), those side effects silently never ran.

In 5.4, those events fire correctly when the outer transaction commits. If you have code that deliberately worked around this by triggering side effects elsewhere, audit that logic -- you may now get duplicate execution.

What New Database Query Operators Does 5.4 Add?

Eight new query-building helpers landed in 5.4, covering gaps that previously required raw SQL fragments:

• notBetween($field, $from, $to) -- negated range check
• inOrNull($field, $values) -- matches the field when it equals one of the values OR is NULL
• notInOrNull($field, $values) -- inverse of the above
• isDistinctFrom($field, $value) -- NULL-safe not-equal (IS DISTINCT FROM in SQL)
• isNotDistinctFrom($field, $value) -- NULL-safe equal (IS NOT DISTINCT FROM in SQL)
• except() / exceptAll() -- set subtraction between two SELECT queries
• stringAgg($field, $separator) -- aggregate string concatenation, useful for grouped string rollups

The isDistinctFrom family is particularly useful for update-detection logic where NULL != NULL would otherwise break a simple equality check. In practice these methods replace a lot of $query->where(['field IS' => null]) workarounds.

What New Collection Methods Shipped in 5.4?

Five methods were added to the Collection class:

• keys() -- returns a collection of the current keys
• values() -- re-indexes the collection discarding existing keys
• implode($glue, $path = null) -- joins values into a string, optionally extracting a nested path first
• when($condition, $callback) -- applies a transformation only when the condition is truthy
• unless($condition, $callback) -- inverse of when()

when() and unless() are quality-of-life additions for conditional pipeline building -- they let you keep a fluent chain instead of breaking out into an if/else block mid-chain.

$result = collection($data)
    ->when($applyDiscount, function ($col) {
        return $col->map(fn($item) => $item * 0.9);
    })
    ->values()
    ->toList();

How Is the Command API Changing in 5.4?

Commands now have $this->io and $this->args injected by the framework before execute() is called. This is a forward-compatibility move -- in CakePHP 6.0, execute() will stop receiving $io and $args as parameters entirely.

In 5.4, both styles work, so you can migrate at your own pace. Start using $this->io and $this->args in new commands now to avoid a breaking change when 6.0 lands.

// 5.4+ style (forward-compatible with 6.0)
class MyCommand extends Command
{
    public function execute(Arguments $args, ConsoleIo $io): int
    {
        // $this->io and $this->args are also available
        $this->io->out('Hello from ' . $this->args->getArgument('name'));
        return static::CODE_SUCCESS;
    }
}

What Else Is New -- Testing, Filesystem, Security, and PostgreSQL

Testing: TestCase::mockModel()

TestCase::mockModel() lets you replace a table class with a Mockery mock directly from the test case, without manually wiring up the registry. This is the missing piece for unit-testing code that calls table methods -- you no longer need to set up a full fixture or a real DB connection just to assert that a save was called.

Filesystem Utilities

New fluent filesystem helpers cover two common pain points: discovering files by pattern (glob-style matching without raw glob() calls) and constructing paths that work correctly on both Windows and Unix. In practice this matters for console commands and plugins that manipulate files at runtime.

Security::encrypt() Key Improvements

Security::encrypt() can now derive separate encryption and authentication keys from a single provided key, and supports longer key material. This strengthens the default posture without requiring you to store two keys yourself -- pass a longer key and the derivation happens internally.

Text::mask()

Text::mask($str, $start, $end, $char) masks a substring with a repeated character -- useful for displaying partial credit card numbers, phone numbers, or email addresses in logs or UIs without exposing the full value.

// Mask the middle of a phone number
echo Text::mask('0987654321', 3, 7, '*');
// Output: 098****321

PostgreSQL Index Types

Schema migrations can now define brin, hash, gin, and spgist index types for PostgreSQL tables. Previously these required raw SQL or manual migration steps. gin is particularly useful for full-text search and JSONB columns; brin suits time-series or append-only tables where physical ordering matters.