3.3 Migration Guide

CakePHP 3.3 is an API compatible upgrade from 3.2. This page outlines thechanges and improvements made in 3.3.

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 backwardscompatibility will be removed in 4.0.0
  • Cake\Http\Client\Response has had the following methods deprecated because theyoverlap 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 Middlewareinstead.
  • RequestActionTrait has been deprecated. Refactor your code to useView Cells instead.
  • Cake\Utility\Crypto\Mcrypt engine has been deprecated as the mcryptextension is deprecated in PHP 7.1. Use the openssl andCake\Utility\Crypto\Openssl instead.

Behavior Changes

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

  • The default JSON encode format for Date and DateTime instances is nowISO-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 pathwhen generating application local URLs. Previously string URLs would have thebase path prepended to them, while array URLs would not.
  • The default ErrorController no longer disables Auth and Securitycomponents, as it does not extend AppController. If you are enabling thesecomponents through events, you will need to update your code.
  • Entity::clean now cleans original values, clearing them on save. Thisbehavior was a bug as the entity’s original state should not be retained aftera 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-7middleware has been added. Middleware is part of the new HTTP stack that is anopt-in component of CakePHP 3.3.0. By using the new HTTP stack, you can takeadvantage of features like:

  • Using middleware from plugins, and libraries outside of CakePHP.
  • Leverage the same response object methods in both the responses you get fromHttp\Client and the responses your application generates.
  • Be able to augment the response objects emitted by error handling and assetdelivery.
    See the Middleware chapter and Adding the new HTTP Stack to an Existing Applicationsections for more information and how to add the new HTTP stack to an existingapplication.

Http Client is now PSR-7 Compatible

Cake\Network\Http\Client has been moved to Cake\Http\Client. Its requestand response objects now implement thePSR-7 interfaces. Several methods onCake\Http\Client\Response are now deprecated, see above for moreinformation.

ORM Improvements

  • Additional support has been added for mapping complex data types. This makesit easier to work with geo-spatial types, and data that cannot be representedby strings in SQL queries. See theMapping Custom Datatypes to SQL Expressions for more information.
  • A new JsonType was added. This new type lets you use the native JSON typesavailable in MySQL and Postgres. In other database providers the json typewill map to TEXT columns.
  • Association::unique() was added. This method proxies the target table’sunique() 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 longerconverted to an array first using toArray(). Instead, thejsonSerialize() method will be invoked on all associated entities. Thisgives you more flexibility and control on which properties are exposed in JSONrepresentations of your entities.
  • Table::newEntity() and Table::patchEntity() will now raise anexception when an unknown association is in the ‘associated’ key.
  • RulesChecker::validCount() was added. This new method allows to applyrules to the number of associated records an entity has.
  • The allowNullableNulls option was added to the existsIn rule. Thisoption allows rules to pass when some columns are null.
  • Saving translated records is now simpler. See theSaving Multiple Translations for more information.

Multiple Pagination Support Added

You can now paginate multiple queries in a single controller action/viewtemplate. See the Paginating Multiple Queries section for moredetails.

Cache Shell Added

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

  1. // Clear one cache config
  2. bin/cake cache clear <configname>
  3.  
  4. // Clear all cache configs
  5. bin/cake cache clear_all

FormHelper

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

Validation

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

StringTemplate

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

Other Enhancements

  • Collection::transpose() was added. This method allows you to tranpose therows and columns of a matrix with equal length rows.
  • The default ErrorController now loads RequestHandlerComponent toenable Accept header based content-type negotiation for error pages.

Routing

  • Router::parse(), RouteCollection::parse() and Route::parse() hada $method argument added. It defaults to ‘GET’. This new parameter reducesreliance on global state, and necessary for the PSR-7 work integration to bedone.
  • When building resource routes, you can now define a prefix. This is usefulwhen defining nested resources as you can create specialized controllers fornested resources.
  • Dispatcher Filters are now deprecated. Use Middlewareinstead.

Console

  • Shell tasks that are invoked directly from the CLI no longer have their_welcome method invoked. They will also have the requested parameterset now.
  • Shell::err() will now apply the ‘error’ style to text. The defaultstyling is red text.

Request

  • Request::is() and Request::addDetector() now supports additionalarguments in detectors. This allows detector callables to operate onadditional parameters.

Debugging Functions

  • The pr(), debug(), and pj() functions now return the value beingdumped. This makes them easier to use when values are being returned.
  • dd() has been added to completely halt execution.