3.2 Migration Guide

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

Minimum PHP 5.5 Required

CakePHP 3.2 requires at least PHP 5.5.9. By adopting PHP 5.5 we can providebetter Date and Time libraries and remove dependencies on password compatibilitylibraries.

Deprecations

As we continue to improve CakePHP, certain features are deprecated as they arereplaced with better solutions. Deprecated features will not be removed until4.0:

  • Shell::error() is deprecated because its name does not clearly indicatethat it both outputs a message and stops execution. Use Shell::abort()instead.
  • Cake\Database\Expression\QueryExpression::type() is deprecated. UsetieWith() instead.
  • Cake\Database\Type\DateTimeType::$dateTimeClass is deprecated. UseDateTimeType::useMutable() or DateTimeType::useImmutable() instead.
  • Cake\Database\Type\DateType::$dateTimeClass is deprecated. UseDateTimeType::useMutable() or DateType::useImmutable() instead.
  • Cake\ORM\ResultSet::_calculateTypeMap() is now unused and deprecated.
  • Cake\ORM\ResultSet::_castValues() is now unused and deprecated.
  • The action key for FormHelper::create() has been deprecated. Youshould use the url key directly.

Disabling Deprecation Warnings

Upon upgrading you may encounter several deprecation warnings. These warningsare emitted by methods, options and functionality that will be removed inCakePHP 4.x, but will continue to exist throughout the lifetime of 3.x. While werecommend addressing deprecation issues as they are encountered, that is notalways possible. If you’d like to defer fixing deprecation notices, you candisable them in your config/app.php:

  1. 'Error' => [
  2.     'errorLevel' => E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED,
  3. ]

The above error level will suppress deprecation warnings from CakePHP.

New Enhancements

Carbon Replaced with Chronos

The Carbon library has been replaced with cakephp/chronos.This new library is a fork of Carbon with no additional dependencies. It alsooffer a calendar date object, and immutable versions of both date and datetimeobjects.

New Date Object

The Date class allows you to cleanly map DATE columns into PHP objects.Date instances will always fix their time to 00:00:00 UTC. By default theORM creates instances of Date when mapping DATE columns now.

New Immutable Date and Time Objects

The FrozenTime, and FrozenDate classes were added. These classes offerthe same API as the Time object has. The frozen classes provide immutablevariants of Time and Date. By using immutable objects, you can preventaccidental mutations. Instead of in-place modifications, modifier methods returnnew instances:

  1. use Cake\I18n\FrozenTime;
  2.  
  3. $time = new FrozenTime('2016-01-01 12:23:32');
  4. $newTime = $time->modify('+1 day');

In the above code $time and $newTime are different objects. The$time object retains its original value, while $newTime has the modifiedvalue. See the Immutable Dates and Times section for more information. As of 3.2,the ORM can map date/datetime columns into immutable objects. See theEnabling Immutable DateTime Objects section for more information.

CorsBuilder Added

In order to make setting headers related to Cross Origin Requests (CORS) easier,a new CorsBuilder has been added. This class lets you define CORS relatedheaders with a fluent interface. See Setting Cross Origin Request Headers (CORS) for more information.

RedirectRoute raises an exception on redirect

Router::redirect() now raises Cake\Network\Routing\RedirectExceptionwhen a redirect condition is reached. This exception is caught by the routingfilter and converted into a response. This replaces calls toresponse->send() and allows dispatcher filters to interact with redirectresponses.

ORM Improvements

  • Containing the same association multiple times now works as expected, and thequery builder functions are now stacked.
  • Function expressions now correctly cast their results. This means thatexpressions like $query->func()->current_date() will return datetimeinstances.
  • Field data that fails validation can now be accessed in entities via theinvalid() method.
  • Entity accessor method lookups are now cached and perform better.

Improved Validator API

The Validator object has a number of new methods that make building validatorsless verbose. For example adding validation rules to a username field can nowlook like:

  1. $validator->email('username')
  2.     ->ascii('username')
  3.     ->lengthBetween('username', [4, 8]);

Console Improvements

  • Shell::info(), Shell::warn() and Shell::success() were added.These helper methods make using commonly used styling simpler.
  • Cake\Console\Exception\StopException was added.
  • Shell::abort() was added to replace error().

StopException Added

Shell::_stop() and Shell::error() no longer call exit(). Insteadthey raise Cake\Console\Exception\StopException. If your shells/tasks arecatching \Exception where these methods would have been called, those catchblocks will need to be updated so they don’t catch the StopException. By notcalling exit() testing shells should be easier and require fewer mocks.

Helper initialize() added

Helpers can now implement an initialize(array $config) hook method likeother class types.

Fatal Error Memory Limit Handling

A new configuration option Error.extraFatalErrorMemory can be set to thenumber of megabytes to increase the memory limit by when a fatal error isencountered. This allows breathing room to complete logging or error handling.

Migration Steps

Updating setToStringFormat()

Before CakePHP 3.2 using Time::setToStringFormat() was working on Date Objectsas well. After upgrading you will need to add Date::setToStringFormat() inaddition to see the formatted Date again.