5.2 Migration Guide

The 5.2.0 release is a backwards compatible with 5.0. It adds new functionality and introduces new deprecations. Any functionality deprecated in 5.x will be removed in 6.0.0.

Upgrade Tool

The upgrade tool provides rector rules for automating some of the migration work. Run rector before updating your composer.json dependencies:

bin/cake upgrade rector --rules cakephp52 <path/to/app/src>

Behavior Changes

• ValidationSet::add() will now raise errors when a rule is added with a name that is already defined. This change aims to prevent rules from being overwritten by accident.
• Http\Session will now raise an exception when an invalid session preset is used.
• FormProtectionComponent now raises Cake\Controller\Exception\FormProtectionException. This class is a subclass of BadRequestException, and offers the benefit of being filterable from logging.
• NumericPaginator::paginate() now uses the finder option even when a SelectQuery instance is passed to it.

Deprecations

Console

• Arguments::getMultipleOption() is deprecated. Use getArrayOption() instead.

Datasource

• The ability to cast an EntityInterface instance to string has been deprecated. You should json_encode() the entity instead.
• Mass assigning multiple entity fields using EntityInterface::set() is deprecated. Use EntityInterface::patch() instead. For e.g. change usage like $entity->set(['field1' => 'value1', 'field2' => 'value2']) to $entity->patch(['field1' => 'value1', 'field2' => 'value2']).

Event

• Returning values from event listeners / callbacks is deprecated. Use $event->setResult() instead or $event->stopPropogation() to just stop the event propogation.

View

• The errorClass option of FormHelper has been deprecated in favour of using a template string. To upgrade move your errorClass definition to a template set. See Customizing Templates.

New Features

Console

• The cake counter_cache command was added. This command can be used to regenerate counters for models that use CounterCacheBehavior.
• ConsoleIntegrationTestTrait::debugOutput() makes it easier to debug integration tests for console commands.
• ConsoleInputArgument now supports a separator option. This option allows positional arguments to be delimited with a character sequence like ,. CakePHP will split the positional argument into an array when arguments are parsed.
• Arguments::getArrayArgumentAt(), and Arguments::getArrayArgument() were added. These methods allow you to read separator delimitered positional arguments as arrays.
• ConsoleInputOption now supports a separator option. This option allows option values to be delimited with a character sequence like ,. CakePHP will split the option value into an array when arguments are parsed.
• Arguments::getArrayArgumentAt(), Arguments::getArrayArgument(), and Arguments::getArrayOption() were added. These methods allow you to read separator delimitered positional arguments as arrays.

Database

• The nativeuuid type was added. This type enables uuid columns to be used in Mysql connections with MariaDB. In all other drivers, nativeuuid is an alias for uuid.
• Cake\Database\Type\JsonType::setDecodingOptions() was added. This method lets you define the value for the $flags argument of json_decode().
• CounterCacheBehavior::updateCounterCache() was added. This method allows you to update the counter cache values for all records of the configured associations. CounterCacheCommand was also added to do the same through the console.
• Cake\Database\Driver::quote() was added. This method provides a way to quote values to be used in SQL queries where prepared statements cannot be used.

Datasource

• Application rules can now use Closure to define the validation message. This allows you to create dynamic validation messages based on the entity state and validation rule options.

Error

• Custom exceptions can have specific error handling logic defined in ErrorController.

ORM

• CounterCacheBehavior::updateCounterCache() has been added. This method allows you to update the counter cache values for all records of the configured associations.
• BelongsToMany::setJunctionProperty() and getJunctionProperty() were added. These methods allow you to customize the _joinData property that is used to hydrate junction table records.
• Table::findOrCreate() now accepts an array as second argument to directly pass data in.

TestSuite

• TestFixture::$strictFields was added. Enabling this property will make fixtures raise an error if a fixture's record list contains fields that do not exist in the schema.

View

• FormHelper::deleteLink() has been added as convenience wrapper for delete links in templates using DELETE method.
• HtmlHelper::importmap() was added. This method allows you to define import maps for your JavaScript files.
• FormHelper now uses the containerClass template to apply a class to the form control div. The default value is input.