3.1 Migration Guide

CakePHP 3.1 is a fully API compatible upgrade from 3.0. This page outlinesthe changes and improvements made in 3.1.

Routing

  • The default route class has been changed to DashedRoute in thecakephp/app repo. Your current code base is not affected by this, but it isrecommended to use this route class from now on.
  • Name prefix options were added to the various route builder methods. See theUsing Named Routes section for more information.

Console

  • Shell::dispatchShell() no longer outputs the welcome message from thedispatched shell.
  • The breakpoint() helper function has been added. This function providesa snippet of code that can be put into eval() to trigger an interactiveconsole. This is very helpful when debugging in test cases, or other CLIscripts.
  • The —verbose and —quiet console options now control stdout/stderrlogging output levels.

Shell Helpers Added

  • Console applications can now create helper classes that encapsulate re-usableblocks of output logic. See the Shell Helpers sectionfor more information.

RoutesShell

  • RoutesShell has been added and now provides you a simple to use CLIinterface for testing and debugging routes. See theRoutes Shell section for more information.

Controller

  • The following Controller properties are now deprecated:

    • layout
    • view - replaced with template
    • theme
    • autoLayout
    • viewPath - replaced with templatePath
    • viewClass - replaced with className
    • layoutPath
      Instead of setting these properties on your controllers, you should set themon the view using methods with matching names:
  1. // In a controller, instead of
  2. $this->layout = 'advanced';
  3.  
  4. // You should use
  5. $this->viewBuilder()->layout('advanced');

These methods should be called after you’ve determined which view class will beused by a controller/action.

AuthComponent

  • New config option storage has been added. It contains the storage class name thatAuthComponent uses to store user record. By default SessionStorage is used.If using a stateless authenticator you should configure AuthComponent touse MemoryStorage instead.
  • New config option checkAuthIn has been added. It contains the name of theevent for which auth checks should be done. By default Controller.startupis used, but you can set it to Controller.initialize if you wantauthentication to be checked before you controller’s beforeFilter() methodis run.
  • The options scope and contain for authenticator classes have beendeprecated. Instead, use the new finder option to configure a custom findermethod and modify the query used to find a user there.
  • The logic for setting Auth.redirect session variable, which is used to getthe URL to be redirected to after login, has been changed. It is now set only whentrying to access a protected URL without authentication. So Auth::redirectUrl()returns the protected URL after login. Under normal circumstances, when a userdirectly accesses the login page, Auth::redirectUrl() returns the value setfor loginRedirect config.

FlashComponent

  • FlashComponent now stacks Flash messages when set with the set()or __call() method. This means that the structure in the Session forstored Flash messages has changed.

CsrfComponent

  • CSRF cookie expiry time can now be set as a strtotime() compatible value.
  • Invalid CSRF tokens will now throwa Cake\Network\Exception\InvalidCsrfTokenException instead of theCake\Network\Exception\ForbiddenException.

RequestHandlerComponent

  • RequestHandlerComponent now switches the layout and template based onthe parsed extension or Accept header in the beforeRender() callbackinstead of startup().
  • addInputType() and viewClassMap() are deprecated. You should useconfig() to modify this configuration data at runtime.
  • When inputTypeMap or viewClassMap are defined in the componentsettings, they will overwrite the default values. This change makes itpossible to remove the default configuration.

Network

HttpClient

  • The default mime type used when sending requests has changed. Previouslymultipart/form-data would always be used. In 3.1, multipart/form-datais only used when file uploads are present. When there are no file uploads,application/x-www-form-urlencoded is used instead.

ORM

You can now Lazily Eager Load Associations. This feature allows you to conditionallyload additional associations into a result set, entity or collection ofentities.

The patchEntity() and newEntity() method now support the onlyIdsoption. This option allows you to restrict hasMany/belongsToMany associationmarshalling to only use the _ids list. This option defaults to false.

Query

  • Query::notMatching() was added.
  • Query::leftJoinWith() was added.
  • Query::innerJoinWith() was added.
  • Query::select() now supports Table and Association objects asparameters. These parameter types will select all the columns on the providedtable or association instance’s target table.
  • Query::distinct() now accepts a string to distinct on a single column.
  • Table::loadInto() was added.
  • EXTRACT, DATE_ADD and DAYOFWEEK raw SQL functions have beenabstracted to extract(), dateAdd() and dayOfWeek().

View

  • You can now set _serialized to true for JsonView and XmlViewto serialize all view variables instead of explicitly specifying them.
  • View::$viewPath is deprecated. You should use View::templatePath()instead.
  • View::$view is deprecated. You should use View::template()instead.
  • View::TYPE_VIEW is deprecated. You should use View::TYPE_TEMPLATEinstead.

Helper

SessionHelper

  • The SessionHelper has been deprecated. You can use$this->request->session() directly.

FlashHelper

  • FlashHelper can render multiple messages if multiple messages whereset with the FlashComponent. Each message will be rendered in its ownelement. Messages will be rendered in the order they were set.

FormHelper

  • New option templateVars has been added. templateVars allows you topass additional variables to your custom form control templates.

Email

  • Email and Transport classes have been moved under the Cake\Mailernamespace. Their former namespaces are still usable as class aliases havebeen set for them.
  • The default email profile is now automatically set when an Emailinstance is created. This behavior is similar to what is done in 2.x.

Mailer

  • The Mailer class was added. This class helps create reusable emails in anapplication.

I18n

Time

  • Time::fromNow() has been added. This method makes it easier to calculatedifferences from ‘now’.
  • Time::i18nFormat() now supports non-gregorian calendars when formattingdates.

Validation

  • Validation::geoCoordinate() was added.
  • Validation::latitude() was added.
  • Validation::longitude() was added.
  • Validation::isInteger() was added.
  • Validation::ascii() was added.
  • Validation::utf8() was added.

Testing

TestFixture

model key is now supported to retrieve the table name for importing.