3.7 Migration Guide

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

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

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

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.

  • Cake\Form\Form::errors() is deprecated. Use getErrors() instead.
  • Cake\Http\Client\Response::$headers is deprecated. Use getHeaders() orgetHeaderLine() instead.
  • Cake\Http\Client\Response::$body is deprecated. Use getStringBody()instead.
  • Cake\Http\Client\Response::$json is deprecated. Use getJson()instead.
  • Cake\Http\Client\Response::$xml is deprecated. Use getXml()instead.
  • Cake\Http\Client\Response::$cookies is deprecated. Use getCookies()instead.
  • Cake\Http\Client\Response::$code is deprecated. Use getStatusCode()instead.
  • Cake\Http\Client\Response::body() is deprecated. Use getStringBody()instead.
  • Cake\ORM\Association::className() has been deprecated. UsegetClassName() and setClassName() instead.
  • Using Cake\Database\Query::join() to read information is deprecated.Instead use Query::clause('join').
  • Using Cake\Database\Query::from() to read information is deprecated.Instead use Query::clause('from').
  • Cake\Database\Connection::logQueries() is deprecated. UseenableQueryLogging() and isQueryLoggingEnabled() instead.
  • The string/array parameter set for Cake\Http\Response::withCookie() isdeprecated. Instead you need to pass in Cake\Http\Cookie\Cookie instances.
  • Cake\Validation\Validation::cc() has been renamed to creditCard().
  • Cake\View\ViewVarsTrait::viewOptions() is deprecated. UseviewBuilder()->setOptions() instead.
  • Cake\View\View::$request is protected now. UseView::getRequest()/setRequest() to access a View’s request instance inother contexts.
  • Cake\View\View::$response is protected now. UseView::getResponse()/setResponse() to access a View’s response instance inother contexts.
  • Cake\View\View::$templatePath is protected now. UsegetTemplatePath()/setTemplatePath() instead.
  • Cake\View\View::$template is protected now. UsegetTemplate()/setTemplate() instead.
  • Cake\View\View::$layout is protected now. Use getLayout()/setLayout()instead.
  • Cake\View\View::$layoutPath is protected now. UsegetLayoutPath()/setLayoutPath() instead.
  • Cake\View\View::$autoLayout is protected now. UseenableAutoLayout()/isAutoLayoutEnabled() instead.
  • Cake\View\View::$theme is protected now. UsegetTheme()/setTheme() instead.
  • Cake\View\View::$subDir is protected now. Use getSubDir()/setSubDir() instead.
  • Cake\View\View::$plugin is protected now. Use getPlugin()/setPlugin()instead.
  • Cake\View\View::$name is protected now. Use getName()/setName()instead.
  • Cake\View\View::$elementCache is protected now. UsegetElementCache()/setElementCache() instead.
  • Cake\View\View::$Blocks is protected now. Use public methods on View tointeract with blocks.
  • Cake\View\View:$helpers is protected now. Use helpers() to interactwith the HelperRegistry instead.
  • Cake\View\View::$uuids is deprecated and will be removed in 4.0
  • Cake\View\View::uuid() is deprecated and will be removed in 4.0
  • Cake\View\Cell::$template is protected now. UseviewBuilder()->getTemplate()/setTemplate() instead.
  • Cake\View\Cell::$plugin is protected now. UseviewBuilder()->getPlugin()/setPlugin() instead.
  • Cake\View\Cell::$helpers is protected now. UseviewBuilder()->getHelpers()/setHelpers() instead.
  • Cake\View\Cell::$action is protected now.
  • Cake\View\Cell::$args is protected now.
  • Cake\View\Cell::$View is protected now.
  • Cake\View\Cell::$request is protected now.
  • Cake\View\Cell::$response is protected now.
  • Cake\View\ViewVarsTrait::$viewVars is deprecated. This public propertywill be removed in 4.0.0. Use set() instead.
  • Cake\Filesystem\Folder::normalizePath() is deprecated. You should usecorrectSlashFor() instead.
  • Cake\Mailer\Email::setConfigTransport() is deprecated. UseCake\Mailer\TransportFactory::setConfig() instead.
  • Cake\Mailer\Email::getConfigTransport() is deprecated. UseCake\Mailer\TransportFactory::getConfig() instead.
  • Cake\Mailer\Email::configTransport() is deprecated. UseCake\Mailer\TransportFactory::getConfig()/setConfig() instead.
  • Cake\Mailer\Email::configuredTransport() is deprecated. UseCake\Mailer\TransportFactory::configured() instead.
  • Cake\Mailer\Email::dropTransport() is deprecated. UseCake\Mailer\TransportFactory::drop() instead.
  • Following view related methods of Cake\Mailer\Email have been deprecated:setTemplate(), getTemplate(), setLayout(), getLayout(),setTheme(), getTheme(), setHelpers(), getHelpers().Use the same methods through Email’s view builder instead. For e.g.$email->viewBuilder()->getTemplate().
  • Cake\Mailer\Mailer::layout() is deprecated.Use $mailer->viewBuilder()->setLayout() instead.
  • Helper::$theme is removed. Use View::getTheme() instead.
  • Helper::$plugin is removed. Use View::getPlugin() instead.
  • Helper::$fieldset and Helper::$tags are deprecated as they are unused.
  • Helper::$helpers is now protected and should not be accessed from outsidea helper class.
  • Helper::$request is removed.Use View::getRequest(), View::setRequest() instead.
  • Cake\Core\Plugin::load() and loadAll() are deprecated. Instead youshould use Application::addPlugin().
  • Cake\Core\Plugin::unload() is deprecated. UsePlugin::getCollection()->remove() or clear() instead.
  • The following properties of Cake\Error\ExceptionRender are now protected:$error, $controller, $template and $method.
  • Using underscored fixtures names in TestCase::$fixtures is deprecated.Use CamelCased names instead. For e.g. app.FooBar, plugin.MyPlugin.FooBar.

Soft Deprecations

The following methods, properties and features have been deprecated but will notbe removed until 5.0.0:

  • Cake\TestSuite\ConsoleIntegrationTestCase is deprecated. You shouldinclude Cake\TestSuite\ConsoleIntegrationTestTrait into your test caseclass instead.

Behavior Changes

  • Cake\Database\Type\IntegerType will now raise an exception when valuesare not numeric when preparing SQL statements and converting database resultsto PHP types.
  • Cake\Database\Statement\StatementDecorator::fetchAll() now returns anempty array instead of false when no result is found.
  • Cake\Database\Statement\BufferedStatement no longer inherits fromStatementDecorator and no longer implements the IteratorAggregateinterface. Instead it directly implements the Iterator interface to bettersupport using statements with collections.
  • When marshalling data from the request into entities, the ORM will now convertnon-scalar data into null for boolean, integer, float, and decimal types.
  • ExceptionRenderer will now always call handler methods for customapplication exception classes. Previously, custom exception class handlermethods would only be invoked in debug mode.
  • Router::url() will now default the _method key to GET whengenerating URLs with Router::url().

New Features

Cache

  • The ArrayEngine was added. This engine provides an ephemeral in memorycache implementation. It is ideal for test suites or long running processeswhere you don’t want persistent cache storage.

Database

  • Cake\Database\FunctionsBuilder::rand() was added.

Datasource

  • Paginator will now match unprefixed sort values in the query string tothe primary model if there also exists a matching model prefixed default sortfield. As an example, if your controller defines a default sort of['Users.name' => 'desc'] you can now use either Users.name or nameas your sort key.

Error

  • ExceptionRenderer will now look for prefixed error controllers whenhandling exceptions. This allows you to define custom error controller logicfor each routing prefix in your application.
  • ErrorHandlerMiddleware will now include previous exceptions in logging.

Filesystem

  • Cake\Filesystem\Folder::normalizeFullPath() was added.

Form

  • Cake\Form\Form::setData() was added. This method makes defining defaultvalues for forms simpler.
  • Cake\Form\Form::getData() was added.

Http

  • Cake\Http\ServerRequest::setTrustedProxies() was added.
  • Cake\Http\Client will now default to use a Curl based adapter if thecurl extension is installed.
  • New constants have been added to the SecurityHeadersMiddleware. The newconstants are used to build the components of HTTP headers.

Mailer

  • Cake\Mailer\TransportFactory and Cake\Mailer\TransportRegistry wereadded. This class extracts transport creation out of Email, allowing Email tobecome simpler in the future.

ORM

  • Cake\ORM\EntityTrait::hasErrors() was added. This method can be used tocheck whether or not an entity has errors more efficiently thangetErrors() does.
  • Updating has many association data now respects _ids. This makes patchinghas many associations work the same as creating new entities, and createsconsistency with belongs to many associations.

Shell

  • cake i18n extract has a new —relative-paths option that makes pathcomments in POT files relative to the application root directory instead ofabsolute paths.
  • cake i18n extract has a new —marker-error option that enablesreporting of translation functions that use non-static values as comments inPOT files.

TestSuite

  • New assertion methods were added to IntegrationTestCase:
    • assertResponseNotEquals()
    • assertHeaderNotContains()
    • assertRedirectNotContains()
    • assertFlashElement()
    • assertFlashElementAt()
  • The custom assertions provided by IntegrationTestCase andConsoleIntegrationTestCase are now implemented through constraint classes.
  • TestCase::loadPlugins(), removePlugins() and clearPlugins() wereadded to make working with dynamically loaded plugins easier now thatPlugin::load() and Plugin::unload() are deprecated.
  • getMockForModel() now supports null for the $methods parameter.This allows you to create mocks that still execute the original code. Thisaligns the behavior with how PHPUnit mock objects work.
  • Added EmailTrait to help facilitate testing emails.
  • The default messages for integration assertions have been improved to providemore context from the exception that was raised if possible.

Utility

  • Cake\Utility\Text::getTransliterator() was added.
  • Cake\Utility\Text::setTransliterator() was added.
  • Cake\Utility\Xml::loadHtml() was added.

Validation

  • Cake\Validation\Validation::iban() was added for validating internationalbank account numbers.
  • Cake\Validation\Validator::allowEmptyString(), allowEmptyArray(),allowEmptyDate(), allowEmptyTime(), allowEmptyDateTime(), andallowEmptyFile() were added. These new methods replace allowEmpty()and give you more control over what a field should consider empty.

View

  • FormHelper now supports a confirmJs template variable which allows thejavascript snippet generated for confirmation boxes to be customized.
  • FormHelper now has a autoSetCustomValidity option for setting HTML5validity messages from custom validation messages. See: Displaying validation messages in HTML5 validity messages
  • ViewBuilder had setVar(), setVars(), getVar(), getVars() andhasVar() added. These methods will replace the public viewVarsproperty defined in ViewVarsTrait.
  • PaginatorHelper will now match unprefixed sort keys to model prefixed oneson the default model. This allow smooth operation with the changes made inCake\Datasource\Paginator
  • FormHelper will now read maxLength validator rules and use them toautomatically define the maxlength attribute on HTML inputs if a maxlength is not provided in the input options.