CakePHP 5.0 contains breaking changes, and is not backwards compatible with 4.x releases. Before attempting to upgrade to 5.0, first upgrade to 4.5 and resolve all deprecation warnings.
Refer to the 5.0 Upgrade Guide for step by step instructions on how to upgrade to 5.0.
All methods, properties and functionality that were emitting deprecation warnings as of 4.5 have been removed.
In addition to the removal of deprecated features there have been breaking changes made:
Type declarations were added to all function parameter and returns where possible. These are intended to match the docblock annotations, but include fixes for incorrect annotations.
Type declarations were added to all class properties where possible. These also include some fixes for incorrect annotations.
The SECOND
, MINUTE
, HOUR
, DAY
, WEEK
, MONTH
, YEAR
constants were removed.
Global functions are now opt-in. If your application uses global function
aliases be sure to add require CAKE . 'functions.php'
to you application’s
config/bootstrap.php
.
Auth has been removed. Use the cakephp/authentication and cakephp/authorization plugins instead.
The Wincache
engine was removed. The wincache extension is not supported
on PHP 8.
ConsoleIntegrationTestTrait::useCommandRunner()
was removed since it’s no longer needed.
Shell
has been removed and should be replaced with Command
The method signature for Controller::__constructor()
has changed.
So you need to adjust your code accordingly if you are overriding the constructor.
After loading components are no longer set as dynamic properties. Instead
Controller
uses __get()
to provide property access to components. This
change can impact applications that use property_exists()
on components.
The components’ Controller.shutdown
event callback has been renamed from
shutdown
to afterFilter
to match the controller one. This makes the callbacks more consistent.
PaginatorComponent
has been removed and should be replaced by calling $this->paginate()
in your controller or
using Cake\Datasource\Paging\NumericPaginator
directly
RequestHandlerComponent
has been removed. See the 4.4 migration guide for how to upgrade
SecurityComponent
has been removed. Use FormProtectionComponent
for form tampering protection
or HttpsEnforcerMiddleware
to enforce use of HTTPS for requests instead.
The function getTypeName()
has been dropped. Use PHP’s get_debug_type()
instead.
The dependency on league/container
was updated to 4.x
. This will
require the addition of typehints to your ServiceProvider
implementations.
deprecationWarning()
now has a $version
parameter.
The App.uploadedFilesAsObjects
configuration option has been removed
alongside of support for PHP file upload shaped arrays throughout the
framework.
ClassLoader
has been removed. Use composer to generate autoload files instead.
The DateTimeType
and DateType
now always return immutable objects.
Additionally the interface for Date
objects reflects the ChronosDate
interface which lacks all of the time related methods that were present in
CakePHP 4.x.
DateType::setLocaleFormat()
no longer accepts an array.
Query
now accepts only \Closure
parameters instead of callable
. Callables can be converted
to closures using the new first-class array syntax in PHP 8.1.
Query::execute()
no longer runs results decorator callbacks. You must use Query::all()
instead.
TableSchemaAwareInterface
was removed.
Driver::quote()
was removed. Use prepared statements instead.
Query::orderBy()
was added to replace Query::order()
.
Query::groupBy()
was added to replace Query::group()
.
SqlDialectTrait
has been removed and all its functionality has been moved
into the Driver
class itself.
CaseExpression
has been removed and should be replaced with
QueryExpression::case()
or CaseStatementExpression
The getAccessible()
method was added to EntityInterface
. Non-ORM
implementations will now need to implement this method.
Event payloads must be an array. Other object such as ArrayAccess
are no longer cast to array and will raise a TypeError
now.
ErrorHandler
and ConsoleErrorHandler
have been removed. See the 4.4 migration guide for how to upgrade
ExceptionRenderer
has been removed and should be replaced with WebExceptionRenderer
ErrorLoggerInterface::log()
has been removed and should be replaced with ErrorLoggerInterface::logException()
ErrorLoggerInterface::logMessage()
has been removed and should be replaced with ErrorLoggerInterface::logError()
The Filesystem package was removed, and Filesystem
class was moved to the Utility package.
ServerRequest
is no longer compatible with files
as arrays. This
behavior has been disabled by default since 4.1.0. The files
data will now
always contain UploadedFileInterfaces
objects.
Time
was renamed to DateTime to allow for future time-only types.
Date::parseDateTime()
was removed.
Date::parseTime()
was removed.
Date::setToStringFormat()
and Date::setJsonEncodeFormat()
no longer accept an array.
Date::i18nFormat()
and Date::nice()
no longer accept a timezone parameter.
Translation files for plugins with vendor prefixed names (FooBar/Awesome
) will now have that
prefix in the file name, e.g. foo_bar_awesome.po
to avoid collision with a awesome.po
file
from a corresponding plugin (Awesome
).
Log engine config now uses null
instead of false
to disable scopes.
So instead of 'scopes' => false
you need to use 'scopes' => null
in your log config.
Email
has been removed. Use Mailer instead.
EntityTrait::has()
now returns true
when an attribute exists and is
set to null
. In previous versions of CakePHP this would return false
.
See the release notes for 4.5.0 for how to adopt this behavior in 4.x.
Finder arguments are now required to be associative arrays as they were always expected to be.
TranslateBehavior
now defaults to the ShadowTable
strategy. If you are
using the Eav
strategy you will need to update your behavior configuration
to retain the previous behavior.
allowMultipleNulls
option for isUnique
rule now default to true matching
the original 3.x behavior.
Table::query()
has been removed in favor of query-type specific functions.
Table::updateQuery()
, Table::selectQuery()
, Table::insertQuery()
, and
Table::deleteQuery()
) were added and return the new type-specific query objects below.
SelectQuery
, InsertQuery
, UpdateQuery
and DeleteQuery
were added
which represent only a single type of query and do not allow switching between query types nor
calling functions unrelated to the specific query type.
Table::_initializeSchema()
has been removed and should be replaced by calling
$this->getSchema()
inside the initialize()
method.
SaveOptionsBuilder
has been removed. Use a normal array for options instead.
Static methods connect()
, prefix()
, scope()
and plugin()
of the Router
have been removed and
should be replaced by calling their non-static method variants via the RouteBuilder
instance.
RedirectException
has been removed. Use \Cake\Http\Exception\RedirectException
instead.
TestSuite
was removed. Users should use environment variables to customize
unit test settings instead.
TestListenerTrait
was removed. PHPUnit dropped support for these listeners.
IntegrationTestTrait::configRequest()
now merges config when called multiple times
instead of replacing the currently present config.
Validation::isEmpty()
is no longer compatible with file upload shaped
arrays. Support for PHP file upload arrays has been removed from
ServerRequest
as well so you should not see this as a problem outside of
tests.
ViewBuilder
options are now truly associative (string keys).
NumberHelper
and TextHelper
no longer accept an engine
config.
ViewBuilder::setHelpers()
parameter $merge
was removed. Use ViewBuilder::addHelpers()
instead.
Inside View::initialize()
, prefer using addHelper()
instead of loadHelper()
.
All configured helpers will be loaded afterwards, anyway.
View\Widget\FileWidget
is no longer compatible with PHP file upload shaped
arrays. This is aligned with ServerRequest
and Validation
changes.
FormHelper
no longer sets autocomplete=off
on CSRF token fields. This
was a workaround for a Safari bug that is no longer relevant.
The following is a list of deprecated methods, properties and behaviors. These features will continue to function in 5.x and will be removed in 6.0.
Query::order()
was deprecated. Use Query::orderBy()
instead now that
Connection
methods are no longer proxied. This aligns the function name
with the SQL statement.
Query::group()
was deprecated. Use Query::groupBy()
instead now that
Connection
methods are no longer proxied. This aligns the function name
with the SQL statement.
Calling Table::find()
with options array is deprecated. Use named arguments
instead. For e.g. instead of find('all', ['conditions' => $array])
use
find('all', conditions: $array)
. Similarly for custom finder options, instead
of find('list', ['valueField' => 'name'])
use find('list', valueField: 'name')
or multiple named arguments like find(type: 'list', valueField: 'name', conditions: $array)
.
CakePHP 5 leverages the expanded type system feature available in PHP 8.1+.
CakePHP also uses assert()
to provide improved error messages and additional
type soundness. In production mode, you can configure PHP to not generate
code for assert()
yielding improved application performance. See the
Improve Your Application’s Performance for how to do this.
The services()
method was added to PluginInterface
.
Query::all()
was added which runs result decorator callbacks and returns a result set for select queries.
Query::comment()
was added to add a SQL comment to the executed query. This makes it easier to debug queries.
EnumType
was added to allow mapping between PHP backed enums and a string or integer column.
getMaxAliasLength()
and getConnectionRetries()
were added
to DriverInterface
.
Supported drivers now automatically add auto-increment only to integer primary keys named “id” instead of all integer primary keys. Setting ‘autoIncrement’ to false always disables on all supported drivers.
Table finders can now have typed arguments as required instead of an options array. For e.g. a finder for fetching posts by category or user:
public function findByCategoryOrUser(SelectQuery $query, array $options)
{
if (isset($options['categoryId'])) {
$query->where(['category_id' => $options['categoryId']]);
}
if (isset($options['userId'])) {
$query->where(['user_id' => $options['userId']]);
}
return $query;
}
should now be written as:
public function findByCategoryOrUser(SelectQuery $query, ?int $categoryId = null, ?int $userId = null)
{
if ($categoryId) {
$query->where(['category_id' => $categoryId]);
}
if ($userId) {
$query->where(['user_id' => $userId]);
}
return $query;
}
The finder can then be called as find('byCategoryOrUser', userId: $somevar)
.
You can even include the special named arguments for setting query clauses.
find('byCategoryOrUser', userId: $somevar, conditions: ['enabled' => true])
.
Added support for PSR-17 factories
interface. This allows cakephp/http
to provide a client implementations to
libraries that allow automatic interface resolution like php-http.
IntegrationTestTrait::requestAsJson()
has been added to set JSON headers for the next request.