3.6 Migration Guide

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

To upgrade to 3.6.x run the following composer command:

  1. php composer.phar require --update-with-dependencies "cakephp/cakephp:3.6.*"

Deprecations

The following is a list of deprecated methods, properties and behaviors. Thesefeatures will continue to function until 4.0.0 after which they will be removed.

  • bin/cake orm_cache is now bin/cake schema_cache.
  • Cake\Cache\Engine\ApcEngine has been renamed toCake\Cache\Engine\ApcuEngine to better reflect the extension name.
  • Cake\ORM\Table::association() is deprecated. Use getAssociation()instead.
  • The Xcache cache engine has been deprecated. The Xcache extension is nolonger actively maintained. If you are using xcache, consider adopting APCu,Memcached, or Redis instead.
  • Passing a list of arrays to Router::setRequestInfo() is now deprecated.Pass an instance of ServerRequest instead.
  • Cake\Controller\Controller:$name is protected now. UseController::getName()/setName() to access a controller’s name in othercontexts.
  • Cake\Controller\Controller:$plugin is protected now. UseController::getPlugin()/setPlugin() to access a controller’s plugin inother contexts.
  • Cake\Controller\Controller:$autoRender is protected now. UseenableAutoRender()/disableAutoRender()/isAutoRenderEnabled() instead.
  • The setter mode of ValidationSet::isPresenceRequired() andValidationSet::isEmptyAllowed() are deprecated. Use requirePresence()and allowEmpty() instead.
  • Cake\Form\Form::validator() is deprecated. Use getValidator() andsetValidator() instead.
  • Cake\ORM\TableRegistry static API has been deprecated. Use a table locatordirectly instead. A global Cake\ORM\Locator\TableLocator instance can beaccessed via Cake\ORM\TableRegistry::getTableLocator() or using aCake\ORM\Locator\LocatorAwareTrait.
  • Cake\View\Helper\FormHelper::widgetRegistry() is deprecated. UsegetWidgetLocator() and setWidgetLocator() instead.
  • Cake\ORM\Behavior\TranslateBehavior::locale() is deprecated. UsegetLocale() and setLocale() instead.
  • The getter part of Cake\Datasource\QueryTrait::formatResults() is deprecated. UsegetResultFormatters() instead.
  • The getter part of Cake\Datasource\QueryTrait::mapReduce() is deprecated. UsegetMapReducers() instead.
  • The getter part of Cake\ORM\Query::contain() is deprecated. UsegetContain() instead.
  • The getter part of Cake\Datasource\QueryInterface::repository()is deprecated. Use getRepository() instead.
  • The getter part of Cake\Database\Type::map() is deprecated. UsegetMap() instead.
  • Cake\Database\Type::map() to set complete types map is deprecated. UsesetMap() instead.

  • Passing $className as object to Cake\Database\Type::map() is deprecated. Useset() instead.
    Several classes were renamed. Their old names will continue to work until 4.0,but will emit deprecation warnings:

  • Cake\Network\Exception\BadRequestException has been renamed toCake\Http\Exception\BadRequestException.

  • Cake\Network\Exception\ConflictException has been renamed toCake\Http\Exception\ConflictException.
  • Cake\Network\Exception\ForbiddenException has been renamed toCake\Http\Exception\ForbiddenException.
  • Cake\Network\Exception\GoneException has been renamed toCake\Http\Exception\GoneException.
  • Cake\Network\Exception\HttpException has been renamed toCake\Http\Exception\HttpException.
  • Cake\Network\Exception\InternalErrorException has been renamed toCake\Http\Exception\InternalErrorException.
  • Cake\Network\Exception\InvalidCsrfTokenException has been renamed toCake\Http\Exception\InvalidCsrfTokenException.
  • Cake\Network\Exception\MethodNotAllowedException has been renamed toCake\Http\Exception\MethodNotAllowedException.
  • Cake\Network\Exception\NotAcceptableException has been renamed toCake\Http\Exception\NotAcceptableException.
  • Cake\Network\Exception\NotFoundException has been renamed toCake\Http\Exception\NotFoundException.
  • Cake\Network\Exception\NotImplementedException has been renamed toCake\Http\Exception\NotImplementedException.
  • Cake\Network\Exception\ServiceUnavailableException has been renamed toCake\Http\Exception\ServiceUnavailableException.
  • Cake\Network\Exception\UnauthorizedException has been renamed toCake\Http\Exception\UnauthorizedException.
  • Cake\Network\Exception\UnavailableForLegalReasonsException has beenrenamed to Cake\Http\Exception\UnavailableForLegalReasonsException.
  • Cake\Network\Session has been renamed to Cake\Http\Session.
  • Cake\Network\Session\DatabaseSession has been renamed toCake\Http\Session\DatabaseSession.
  • Cake\Network\Session\CacheSession has been renamed toCake\Http\Session\CacheSession.
  • Cake\Network\CorsBuilder has been renamed to Cake\Http\CorsBuilder.
  • Cake\View\Widget\WidgetRegistry has been renamed toCake\View\Widget\WidgetLocator.

Disabling Deprecation Warnings

Deprecation warnings are intended to help you prepare for future versions ofCakePHP, but updating your code will likely be an incremental process. You candisable deprecation warnings while you work towards adopting the new methods. Inyour config/app.php you can set Error.errorLevel:

  1. // in config/app.php
  2. 'Error' => [
  3.     'errorLevel' => E_ALL ^ E_USER_DEPRECATED
  4. ]

Once you have no remaining deprecation warnings you can set your error level toE_ALL to help prevent future use of deprecated methods.

Behavior Changes

The following changes are API compatible, but they represent minor variances inbehavior that may affect your application:

  • Cake\Utility\Security::randomBytes() will now throw exceptions whena secure source of entropy cannot be found in PHP5.
  • Tokens generated by SecurityComponent now include the user’s session id,to prevent token reuse between users/sessions. This changes the value ofsecurity tokens and will cause forms created in earlier versions of CakePHP tofail validation in 3.6.
  • Cake\Database\Query::page() now raises exceptions when page values are< 1.
  • Pagination now allows sorting on multiple fields across all pages. Previouslyonly the first page could be sorted by more than one column. Furthermore, sortconditions defined in the query string are prepended to the default orderparameters now instead of fully replacing the default ordering.
  • Shell classes will now throw exceptions when task classes cannot be found.Previously invalid tasks would be silently ignored.
  • CakePHP internals now chain exceptions where possible, allowing root causes oferrors to be exposed.
  • MySQL connections now default to utf8mb4 (4 byte unicode) as theirencoding. If you want to continue using the old default of utf8, setyour application’s datasource’ encoding in config/app.php to ‘utf8’.
  • APCu and Wincache engines no longer set separate _expires keys for datawith a TTL. Instead they rely on the native TTL features of the cache engine.By default all entries created with APCu for a single request/CLI script willhave the same expiration time. You can use apc.use_request_time to changethis behavior.
  • Router::parseNamedParams() no longer mutates the request object in-place.Instead you will need to use the return value of this method to access themodified request.
  • Hash::extract() no longer matches integer 0 when using attributematchers for string values.
  • The console environment no longer automatically loads plugins specified by the—plugin option. Instead you must ensure that your applicationbootstrapping loads all the required plugins.
  • Cake\Http\CorsBuilder::build() no longer mutates the response in place.You must now use the updated response that build() returns.

Cache

  • Fallback engines can be disabled by setting fallback = false for any cacheconfiguration.

Collection

  • The appendItem(), prepend(), prependItems() methods were added toCollectionTrait.

Configure

  • consumeOrFail() has been added to complete the API for reading with the expectation of data being present.

Console

A new way to build CLI tools has been added. Shells & Tasks have severalshortcomings that are hard to correct without breaking compatibility.Cake\Console\Command will replace Shell long term as the recommended wayto build console applications. See the Console Commandssection for more information.

  • ConsoleOptionParse::enableSubcommandSort() was added. This method allowsyou to disable the automatic sorting of subcommands in generated help text.

Core

  • Plugins can now define Plugin Objects. These classes are optional andallow a plugin to add middleware and console commands to the host application.They are a class based way to configure and define a plugin.
  • getTypeName() was added to assist in getting correct class/type name whenbuilding more descriptive error messages.

Database

  • Query::identifier() was added. This method makes it easier to createidentifier expressions for use in complex queries.
  • Database connections will automatically be re-established when connectionstimeout during long running scripts.
  • Cake\Database\Type\BatchCastingInterface was added. This interface allowstype classes to optimize casting operations by operating on all columns inbulk. This interface can be used in custom types now, and will be used in coretypes in 4.x.
  • Cake\Database\Type\DateTimeType::setTimezone() was added. This method letsyou set the timezone that datetime objects should be converted to beforeinserting into the database. It does not change datetime data being read fromthe database.
  • Cake\Database\Statement\StatementDecorator::fetchAssoc() was added.
  • Cake\Database\Statement\BufferedStatement::fetchAssoc() was added.
  • Cake\Database\Statement\StatementDecorator::FETCH_TYPE_NUM was added.
  • Cake\Database\Statement\StatementDecorator::FETCH_TYPE_ASSOC was added.
  • Cake\Database\Statement\StatementDecorator::FETCH_TYPE_OBJ was added.

Datasource

  • A new abstract type was added for binaryuuid. In MySQL and SQLite,BINARY(16) will be used as the column type. While in SQLServer, andPostgres will use their native UUID types.

Event

  • Cake\Event\EventInterface was added to give allow better typehinting inthe future.

Form

  • Form classes now support the _validatorClass property which works the sameas it does on ORM\Table.

Http

  • Response::withAddedLink() was added to make creating Link headerssimpler.
  • BodyParserMiddleware was added.

I18n

  • The two leftover FormHelper i18n translation strings 'Edit %s' and 'New
    %s'     are now 'Edit {0}' and 'New {0}'. If you are using translatingmessages from CakePHP, please make sure you adjust those translations in yourPO file.

Mailer

  • The various email address setter methods on Email now accept []allowing individual properties to be reset.

ORM

  • EntityTrait::isEmpty() and EntityTrait::hasValue() were added.
  • Table::getAssociation() can now read deeply nested associations using. separated paths. e.g Users.Comments. This method will raiseexceptions when getting an unknown association now.
  • Table::addBehaviors() was added making it simpler to add multiplebehaviors at once.
  • Table::getBehavior() was added.
  • CounterCacheBehavior callback functions can now return false to skipupdating the counter value.
  • TimestampBehavior now uses the correct mutable/immutable class type whencreating time objects instead of always using a mutable time instance.
  • Query::selectAllExcept() was added.
  • Query::whereInList()/Query::whereNotInList() have been added as standalone wrappers around IN/NOT IN conditions.

Routing

  • Cake\Routing\Route\EntityRoute was added. This route class makes buildingroutes that need data from entities easier. See the Entity Routingsection for more information.
  • Routing variables can now use {var} style placeholders. This style allowsmid-word variables to be defined. You cannot combine {var} placeholderswith :var style placeholders.
  • Router::routeExists() was added. This method lets you check if a routearray can be resolved into a valid route.
  • Route connection can now use compact ‘string targets’ e.gBookmarks::index. See Connecting Routes for more information.
  • RoutingMiddleware can now cache the route collection created by yourroutes. Caching routes greatly improves application startup times.It now also requires to be instantiated and the current object ($this) passed for plugin routing.

Shell

  • The cake assets copy command now features an —overwrite option foroverwriting plugin assets if they already exist in the application webroot.

Utility

  • Security::randomString() was added.

Validation

  • Validation::compareFields() was added as a more flexible version ofValidation::compareWith().
  • Validator::notSameAs() was added to make iteasier to check if a field is not the same as another field.
  • New field comparison methods were added. equalToField(),notEqualToField(), greaterThanField(),greaterThanOrEqualToField(), lessThanField(),lessThanOrEqualToField() were added.
  • Validator rules will now use the rule alias as the rule method when therule key is not defined.
  • Validator::addNested() and addNestedMany() now support the whenand message parameters like other validator methods.

View

  • UrlHelper::script(), css(), and image() methods now supporta timestamp option which allows you to set the Asset.timestampsetting for a single method call.
  • Cell classes now have an initialize() hook method.
  • PaginatorHelper will now reset the page to 1 each time sort directions arechanged.