3.5 Migration Guide

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

    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.

    • is deprecated. UseCake\Http\Cookie\CookieCollection instead.
    • Cake\View\Helper\RssHelper is deprecated. Due to infrequent use theRssHelper is deprecated.
    • Cake\Controller\Component\CsrfComponent is deprecated. UseCross Site Request Forgery (CSRF) Middleware instead.
    • Cake\Datasource\TableSchemaInterface is deprecated. UseCake\Database\TableSchemaAwareInterface instead.
    • Cake\Console\ShellDispatcher is deprecated. Applications should update touse Cake\Console\CommandRunner instead.
    • Cake\Database\Schema\TableSchema::column() is deprecated. UseCake\Database\Schema\TableSchema::getColumn() instead.
    • Cake\Database\Schema\TableSchema::constraint() is deprecated. UseCake\Database\Schema\TableSchema::getConstraint() instead.
    • Cake\Database\Schema\TableSchema::index() is deprecated. UseCake\Database\Schema\TableSchema::getIndex() instead.

    The following is a list of methods that are deprecated and replaced withgetX() and setX() methods:

    • Cake\Cache\Cache
      • config()
      • registry()
    • Cake\Console\Shell
      • io()
    • Cake\Console\ConsoleIo
      • outputAs()
    • Cake\Console\ConsoleOutput
      • outputAs()
    • Cake\Database\Connection
      • logger()
    • Cake\Database\TypedResultInterface
      • returnType()
    • Cake\Database\TypedResultTrait
      • returnType()
    • Cake\Database\Log\LoggingStatement
    • Cake\Datasource\ModelAwareTrait
      • modelType()
    • Cake\Database\Query
      • getter part of valueBinder() (now getValueBinder())
    • Cake\Database\Schema\TableSchema
      • columnType()
    • Cake\Datasource\QueryTrait
      • getter part of eagerLoaded() (now isEagerLoaded())
    • Cake\Event\EventDispatcherInterface
      • eventManager()
    • Cake\Event\EventDispatcherTrait
      • eventManager()
    • Cake\Error\Debugger
      • outputAs() (now getOutputFormat() / setOutputFormat())
    • Cake\Http\ServerRequest
      • env() (now getEnv() / withEnv())
      • charset() (now getCharset() / withCharset())
    • Cake\I18n\I18n
      • locale()
      • defaultLocale()
      • defaultFormatter()
    • Cake\ORM\Association\BelongsToMany
      • sort()
    • Cake\ORM\LocatorAwareTrait
      • tableLocator()
    • Cake\ORM\EntityTrait
      • invalid() (now getInvalid(), setInvalid(),setInvalidField(), and getInvalidField())
    • Cake\ORM\Table
      • validator()
    • Cake\Routing\RouteBuilder
      • extensions()
      • routeClass()
    • Cake\Routing\RouteCollection
      • extensions()
    • Cake\TestSuite\TestFixture
    • Cake\Utility\Security
      • salt()
    • Cake\View\View
      • template()
      • layout()
      • theme()
      • templatePath()
      • layoutPath()
      • autoLayout() (now isAutoLayoutEnabled() / enableAutoLayout())

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

    • BehaviorRegistry, HelperRegistry and ComponentRegistry will nowraise exceptions when unload() is called with an unknown object name. Thischange should help find errors easier by making possible typos more visible.
    • HasMany associations now gracefully handle empty values set for theassociation property, similar to BelongsToMany associations - that is theytreat false, null, and empty strings the same way as empty arrays. ForHasMany associations this now results in all associated records to bedeleted/unlinked when the replace save strategy is being used.As a result this allows you to use forms to delete/unlink all associatedrecords by passing an empty string. Previously this would have required custommarshalling logic.
    • ORM\Table::newEntity() now only marks association properties dirty if themarshalled association record is dirty. In scenarios where an associationentity is created that contains no properties the empty record will not beflagged for persistence.
    • Http\Client no longer uses the cookie() method results when buildingrequests. Instead the Cookie header and internal CookieCollection areused. This should only effect applications that have a custom HTTP adapter intheir clients.
    • Multi-word subcommand names previouly required camelBacked names to be usedwhen invoking shells. Now subcommands can be invoked with underscored_names.For example: cake tool initMyDb can now be called with cake tool
      init_my_db      . If your shells previously bound two subcommands with differentinflections, only the last bound command will function.
    • SecurityComponent will blackhole post requests that have no request datanow. This change helps protect actions that create records using databasedefaults alone.
    • Cake\ORM\Table::addBehavior() and removeBehavior() now return$this to assist in defining table objects in a fluent fashion.
    • Cache engines no longer throw an exception when they fail or are misconfigured,but instead fall back to the noop NullEngine. Fallbacks can also be on a per-engine basis.
    • Cake\Database\Type\DateTimeType will now marshal ISO-8859-1 formatteddatetime strings (e.g. 2017-07-09T12:33:00+00:02) in addition to thepreviously accepted format. If you have a subclass of DateTimeType you mayneed to update your code.

    Scoped Middleware

    New Console Runner

    3.5.0 adds Cake\Console\CommandRunner. This class alongsideCake\Console\CommandCollection integrate the CLI environment with the newApplication class. Application classes can now implement a console()hook that allows them to have full control over which CLI commands are exposed,how they are named and how the shells get their dependencies. Adopting this newclass requires replacing the contents of your bin/cake.php file with thefollowing file.

    Cache Engine Fallbacks

    Cache engines can now be configured with a key that defines acache configuration to fall back to if the engine is misconfigured (orunavailable). See Configuring Cache Fallbacks for more information onconfiguring fallbacks.

    dotenv Support added to Application Skeleton

    Console Integration Testing

    The Cake\TestSuite\ConsoleIntegrationTestCase class was added to makeintegration testing console applications easier. For more information, visitthe section. This test class is fullycompatible with the current Cake\Console\ShellDispatcher as well as the newCake\Console\CommandRunner.

    • Cake\Collection\Collection::avg() was added.
    • Cake\Collection\Collection::median() was added.

    Core

    • Cake\Core\Configure::read() now supports default values if the desired keydoes not exist.
    • Cake\Core\ObjectRegistry now implements the Countable andIteratorAggregate interfaces.

    Console

    • Cake\Console\ConsoleOptionParser::setHelpAlias() was added. This methodallows you to set the command name used when generating help output. Defaultsto cake.
    • Cake\Console\CommandRunnner was added replacingCake\Console\ShellDispatcher.
    • Cake\Console\CommandCollection was added to provide an interface forapplications to define the command line tools they offer.

    Database

    • SQLite driver had the mask option added. This option lets you set thefile permissions on the SQLite database file when it is created.

    Datasource

    • Cake\Datasource\SchemaInterface was added.
    • New abstract types were added for smallinteger and tinyinteger.Existing SMALLINT and TINYINT columns will now be reflected as thesenew abstract types. TINYINT(1) columns will continue to be treated asboolean columns in MySQL.
    • Cake\Datasource\PaginatorInterface was added. The PaginatorComponentnow uses this interface to interact with paginators. This allows otherORM-like implementations to be paginated by the component.
    • Cake\Datasource\Paginator was added to paginate ORM/Database Queryinstances.

    Event

    • Cake\Event\EventManager::on() and off() methods are now chainablemaking it simpler to set multiple events at once.
    • New Cookie & CookieCollection classes have been added. These classes allow youto work with cookies in an object-orientated way, and are available onCake\Http\ServerRequest, Cake\Http\Response, andCake\Http\Client\Response. See the andSetting Cookies for more information.
    • New middleware has been added to make applying security headers easier. See for more information.
    • New middleware has been added to transparently encrypt cookie data. SeeEncrypted Cookie Middleware for more information.
    • New middleware has been added to make protecting against CSRF easier. See for more information.
    • Cake\Http\Client::addCookie() was added to make it easy to add cookies toa client instance.

    InstanceConfigTrait

    • InstanceConfigTrait::getConfig() now takes a 2nd parameter $default.If no value is available for the specified $key, the $default valuewill be returned.

    ORM

    • Cake\ORM\Query::contain() now allows you to call it without the wrappingarray when containing a single association. contain('Comments', function ()
      { … });       will now work. This makes contain() consistent with othereagerloading related methods like leftJoinWith() and matching().

    Routing

    • Cake\Routing\Router::reverseToArray() was added. This method allow you toconvert a request object into an array that can be used to generate URLstrings.
    • Cake\Routing\RouteBuilder::resources() had the path optionadded. This option lets you make the resource path and controller name notmatch.
    • Cake\Routing\RouteBuilder now has methods to create routes forspecific HTTP methods. e.g get() and post().
    • Cake\Routing\RouteBuilder::loadPlugin() was added.
    • Cake\Routing\Route now has fluent methods for defining options.

    TestSuite

    • TestCase::loadFixtures() will now load all fixtures when no arguments areprovided.
    • IntegrationTestCase::head() was added.
    • IntegrationTestCase::options() was added.
    • IntegrationTestCase::disableErrorHandlerMiddleware() was added to makedebugging errors easier in integration tests.

    Validation

    • Cake\Validation\Validator::scalar() was added to ensure that fields do notget non-scalar data.
    • Cake\Validation\Validator::regex() was added for a more convenient wayto validate data against a regex pattern.
    • Cake\Validation\Validator::addDefaultProvider() was added. This methodlets you inject validation providers into all the validators created in yourapplication.
    • Cake\Validation\ValidatorAwareInterface was added to define the methodsimplemented by Cake\Validation\ValidatorAwareTrait.