3.3 Migration Guide¶

Deprecations¶

• Router::mapResources() is deprecated. Use routing scopes and $routes->resources() instead.

• Router::redirect() is deprecated. Use routing scopes and $routes->redirect() instead.

• Router::parseNamedParams() is deprecated. Named parameter backwards compatibility will be removed in 4.0.0

• Cake\Http\Client\Response has had the following methods deprecated because they overlap with PSR-7 interface methods:

  • statusCode() use getStatusCode() instead.

  • encoding() use getEncoding() instead.

  • header() use getHeaderLine() instead.

  • cookie() use getCookie() instead.

  • version() use getProtocolVersion() instead.

• Dispatcher Filters are now deprecated. Use Middleware instead.

• RequestActionTrait has been deprecated. Refactor your code to use View Cells instead.

• Cake\\Utility\\Crypto\\Mcrypt engine has been deprecated as the mcrypt extension is deprecated in PHP 7.1. Use the openssl and Cake\Utility\Crypto\Openssl instead.

Behavior Changes¶

While these changes are API compatible, they represent minor variances in behavior that may effect your application:

• The default JSON encode format for Date and DateTime instances is now ISO-8601. This means that the timezone value contains a :. For example 2015-11-06T00:00:00+03:00

• Controller::referer() now consistently omits the application base path when generating application local URLs. Previously string URLs would have the base path prepended to them, while array URLs would not.

• The default ErrorController no longer disables Auth and Security components, as it does not extend AppController. If you are enabling these components through events, you will need to update your code.

• Entity::clean now cleans original values, clearing them on save. This behavior was a bug as the entity’s original state should not be retained after a save, but instead reflect the new state of the entity.

PSR-7 Middleware Support Added¶

In tandem with the deprecation of Dispatcher Filters, support for PSR-7 middleware has been added. Middleware is part of the new HTTP stack that is an opt-in component of CakePHP 3.3.0. By using the new HTTP stack, you can take advantage of features like:

• Using middleware from plugins, and libraries outside of CakePHP.

• Leverage the same response object methods in both the responses you get from Http\Client and the responses your application generates.

• Be able to augment the response objects emitted by error handling and asset delivery.

See the Middleware chapter and Adding the new HTTP Stack to an Existing Application sections for more information and how to add the new HTTP stack to an existing application.

Http Client is now PSR-7 Compatible¶

Cake\Network\Http\Client has been moved to Cake\Http\Client. Its request and response objects now implement the PSR-7 interfaces. Several methods on Cake\Http\Client\Response are now deprecated, see above for more information.

ORM Improvements¶

• Additional support has been added for mapping complex data types. This makes it easier to work with geo-spatial types, and data that cannot be represented by strings in SQL queries. See the Mapping Custom Datatypes to SQL Expressions for more information.

• A new JsonType was added. This new type lets you use the native JSON types available in MySQL and Postgres. In other database providers the json type will map to TEXT columns.

• Association::unique() was added. This method proxies the target table’s unique() method, but ensures that association conditions are applied.

• isUnique rules now apply association conditions.

• When entities are converted into JSON, the associated objects are no longer converted to an array first using toArray(). Instead, the jsonSerialize() method will be invoked on all associated entities. This gives you more flexibility and control on which properties are exposed in JSON representations of your entities.

• Table::newEntity() and Table::patchEntity() will now raise an exception when an unknown association is in the ‘associated’ key.

• RulesChecker::validCount() was added. This new method allows to apply rules to the number of associated records an entity has.

• The allowNullableNulls option was added to the existsIn rule. This option allows rules to pass when some columns are null.

• Saving translated records is now simpler. See the Saving Multiple Translations for more information.

Multiple Pagination Support Added¶

You can now paginate multiple queries in a single controller action/view template. See the Paginating Multiple Queries section for more details.

Cache Shell Added¶

To help you better manage cached data from the CLI environment, a shell command has been added that exposes methods for clearing cached data:

// Clear one cache config
bin/cake cache clear <configname>

// Clear all cache configs
bin/cake cache clear_all

FormHelper¶

• FormHelper will now automatically set the default value of fields to the default value defined in your database columns. You can disable this behavior by setting schemaDefault option to false.

Validation¶

• Validator::requirePresence(), Validator::allowEmpty() and Validator::notEmpty() now accept a list of fields. This allows you to more concisely define the fields that are required.

StringTemplate¶

StringTemplate::format() now throws an exception instead of returning null when requested template is not found.

Other Enhancements¶

• Collection::transpose() was added. This method allows you to tranpose the rows and columns of a matrix with equal length rows.

• The default ErrorController now loads RequestHandlerComponent to enable Accept header based content-type negotiation for error pages.