Page Contents

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.

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 Creating DELETE Links.

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.