2.0 Migration Guide¶

File names¶

All files containing classes should be named after the class it contains. No file should contain more than one class. So, no more lowercasing and underscoring your file names. Here are some examples:

• my_things_controller.php becomes MyThingsController.php

• form.php (a Helper) becomes FormHelper.php

• session.php (a Component) becomes SessionComponent.php

This makes file naming a lot more clear and consistent across applications, and also avoids a few edge cases where the file loader would get confused in the past and load files it should not.

Folder Names¶

Most folders should be also CamelCased, especially when containing classes. Think of namespaces, each folder represents a level in the namespacing hierarchy, folders that do not contain classes, or do not constitute a namespace on themselves, should be lowercased.

CamelCased Folders:

• Config

• Console

• Controller

• Controller/Component

• Lib

• Locale

• Model

• Model/Behavior

• Plugin

• Test

• Vendor

• View

• View/Helper

lowercased Folders:

• tmp

• webroot

Removed Constants¶

A number of constants were removed, as they were no longer accurate, or duplicated.

• APP_PATH

• BEHAVIORS

• COMPONENTS

• CONFIGS

• CONSOLE_LIBS

• CONTROLLERS

• CONTROLLER_TESTS

• ELEMENTS

• HELPERS

• HELPER_TESTS

• LAYOUTS

• LIB_TESTS

• LIBS

• MODELS

• MODEL_TESTS

• SCRIPTS

• VIEWS

Deprecated callbacks removed¶

All the deprecated callbacks in Component have not been transferred to ComponentCollection. Instead you should use the trigger() method to interact with callbacks. If you need to trigger a callback you could do so by calling:

$this->Components->trigger('someCallback', array(&$this));

Changes in disabling components¶

In the past you were able to disable components via $this->Auth->enabled = false; for example. In CakePHP 2.0 you should use the ComponentCollection’s disable method, $this->Components->disable(‘Auth’);. Using the enabled property will not work.

AclComponent¶

• AclComponent implementations are now required to implement AclInterface.

• AclComponent::adapter() has been added to allow runtime modification of the ACL implementation the component uses.

• AclComponent::grant() has been deprecated, it will be removed in a future version. Use AclComponent::allow() instead.

• AclComponent::revoke() has been deprecated, it will be removed in a future version. Use AclComponent::deny() instead.

RequestHandlerComponent¶

Many of RequestHandlerComponent’s methods are just proxies for CakeRequest methods. The following methods have been deprecated and will be removed in future versions:

• isSsl()

• isAjax()

• isPost()

• isPut()

• isFlash()

• isDelete()

• getReferer()

• getClientIp()

• accepts(), prefers(), requestedWith() All deal in mapped content types now. They no longer work with mime-types. You can use RequestHandler::setContent() to create new content types.

• RequestHandler::setContent() no longer accepts an array as a single argument, you must supply both arguments.

SecurityComponent¶

SecurityComponent no longer handles Basic and Digest Authentication. These are both handled by the new AuthComponent. The following methods have been removed from SecurityComponent:

• requireLogin()

• generateDigestResponseHash()

• loginCredentials()

• loginRequest()

• parseDigestAuthData()

In addition the following properties were removed:

• $loginUsers

• $requireLogin

Moving these features to AuthComponent was done to provide a single place for all types of authentication and to streamline the roles of each component.

AuthComponent¶

The AuthComponent was entirely re-factored for 2.0, this was done to help reduce developer confusion and frustration. In addition, AuthComponent was made more flexible and extensible. You can find out more in the Authentication guide.

EmailComponent¶

The EmailComponent has been deprecated and has created a new library class to send e-mails. See CakeEmail Email changes for more details.

SessionComponent¶

Session component has lost the following methods.

• activate()

• active()

• __start()

App¶

The API for App::build() has changed to App::build($paths, $mode). It now allows you to either append, prepend or reset/replace existing paths. The $mode param can take any of the following 3 values: App::APPEND, App::PREPEND, App::RESET. The default behavior of the function remains the same (ie. Prepending new paths to existing list).

App::uses('AuthComponent', 'Controller/Component');

App::import('Controller', 'Pages');
// becomes
App::uses('PagesController', 'Controller');

App::import('Component', 'Auth');
// becomes
App::uses('AuthComponent', 'Controller/Component');

App::import('View', 'Media');
// becomes
App::uses('MediaView', 'View');

App::import('Core', 'Xml');
// becomes
App::uses('Xml', 'Utility');

App::import('Datasource', 'MongoDb.MongoDbSource');
// becomes
App::uses('MongoDbSource', 'MongoDb.Model/Datasource');

App::import('Core', 'CakeRoute');
// becomes
App::uses('CakeRoute', 'Routing/Route');

App::import('Core', 'Sanitize');
// becomes
App::uses('Sanitize', 'Utility');

App::import('Core', 'HttpSocket');
// becomes
App::uses('HttpSocket', 'Network/Http');

App::build(array('controllers' => array('/full/path/to/controllers')));
//becomes
App::build(array('Controller' => array('/full/path/to/Controller')));

App::build(array('helpers' => array('/full/path/to/controllers')));
//becomes
App::build(array('View/Helper' => array('/full/path/to/View/Helper')));

CakeLog¶

• Log streams now need to implement CakeLogInterface. Exceptions will be raised if a configured logger does not.

Cache¶

• Cache is now a static class, it no longer has a getInstance() method.

• CacheEngine is now an abstract class. You cannot directly create instances of it anymore.

• CacheEngine implementations must extend CacheEngine, exceptions will be raised if a configured class does not.

• FileCache now requires trailing slashes to be added to the path setting when you are modifying a cache configuration.

• Cache no longer retains the name of the last configured cache engine. This means that operations you want to occur on a specific engine need to have the $config parameter equal to the config name you want the operation to occur on.

Cache::config('something');
Cache::write('key', $value);

// would become
Cache::write('key', $value, 'something');

Router¶

• You can no longer modify named parameter settings with Router::setRequestInfo(). You should use Router::connectNamed() to configure how named parameters are handled.

• Router no longer has a getInstance() method. It is a static class, call its methods and properties statically.

• Router::getNamedExpressions() is deprecated. Use the new router constants. Router::ACTION, Router::YEAR, Router::MONTH, Router::DAY, Router::ID, and Router::UUID instead.

• Router::defaults() has been removed. Delete the core routes file inclusion from your applications routes.php file to disable default routing. Conversely if you want default routing, you will have to add an include to Cake/Config/routes.php in your routes file.

• When using Router::parseExtensions() the extension parameter is no longer under $this->params['url']['ext']. Instead it is available at $this->request->params['ext'].

• Default plugin routes have changed. Plugin short routes are no longer built in for any actions other than index. Previously /users and /users/add would map to the UsersController in the Users plugin. In 2.0, only the index action is given a short route. If you wish to continue using short routes, you can add a route like:

  Router::connect(
    '/users/:action',
    array('controller' => 'users', 'plugin' => 'users')
  );
  

  To your routes file for each plugin you need short routes on.

Your app/Config/routes.php file needs to be updated adding this line at the bottom of the file:

require CAKE . 'Config' . DS . 'routes.php';

This is needed in order to generate the default routes for your application. If you do not wish to have such routes, or want to implement your own standard you can include your own file with custom router rules.

Dispatcher¶

• Dispatcher has been moved inside of cake/libs, you will have to update your app/webroot/index.php file.

• Dispatcher::dispatch() now takes two parameters. The request and response objects. These should be instances of CakeRequest & CakeResponse or a subclass thereof.

• Dispatcher::parseParams() now only accepts a CakeRequest object.

• Dispatcher::baseUrl() has been removed.

• Dispatcher::getUrl() has been removed.

• Dispatcher::uri() has been removed.

• Dispatcher::$here has been removed.

Configure¶

• Configure::read() with no parameter no longer returns the value of ‘debug’ instead it returns all values in Configure. Use Configure::read('debug'); if you want the value of debug.

• Configure::load() now requires a ConfigReader to be setup. Read Loading configuration files for more information.

• Configure::store() now writes values to a given Cache configuration. Read Loading configuration files for more information.

Scaffold¶

• Scaffold ‘edit’ views should be renamed to ‘form’. This was done to make scaffold and bake templates consistent.

  • views/scaffolds/edit.ctp -> View/Scaffolds/form.ctp

  • views/posts/scaffold.edit.ctp -> View/Posts/scaffold.form.ctp

Xml¶

• The class Xml was completely re-factored. Now this class does not manipulate data anymore, and it is a wrapper to SimpleXMLElement. You can use the following methods:

  • Xml::build(): static method that you can pass an xml string, array, path to file or url. The result will be a SimpleXMLElement instance or an exception will be thrown in case of error.

  • Xml::fromArray(): static method that returns a SimpleXMLElement from an array.

  • Xml::toArray(): static method that returns an array from SimpleXMLElement.

You should see the Xml documentation for more information on the changes made to the Xml class.

Inflector¶

• Inflector no longer has a getInstance() method.

• Inflector::slug() no longer supports the $map argument. Use Inflector::rules() to define transliteration rules.

CakeSession¶

CakeSession is now a fully static class, both SessionHelper and SessionComponent are wrappers and sugar for it. It can now easily be used in models or other contexts. All of its methods are called statically.

Session configuration has also changed see the session section for more information

HttpSocket¶

• HttpSocket doesn’t change the header keys. Following other places in core, the HttpSocket does not change the headers. RFC 2616 says that headers are case insensitive, and HttpSocket preserves the values the remote host sends.

• HttpSocket returns responses as objects now. Instead of arrays, HttpSocket returns instances of HttpResponse. See the HttpSocket documentation for more information.

• Cookies are stored internally by host, not per instance. This means that, if you make two requests to different servers, cookies from domain1 won’t be sent to domain2. This was done to avoid possible security problems.

Constructor changed¶

In order to accommodate View being removed from the ClassRegistry, the signature of Helper::__construct() was changed. You should update any subclasses to use the following:

public function __construct(View $View, $settings = array())

When overriding the constructor you should always call parent::__construct as well. Helper::__construct stores the view instance at $this->_View for later reference. The settings are not handled by the parent constructor.

HelperCollection added¶

After examining the responsibilities of each class involved in the View layer, it became clear that View was handling much more than a single task. The responsibility of creating helpers is not central to what View does, and was moved into HelperCollection. HelperCollection is responsible for loading and constructing helpers, as well as triggering callbacks on helpers. By default, View creates a HelperCollection in its constructor, and uses it for subsequent operations. The HelperCollection for a view can be found at $this->Helpers

The motivations for refactoring this functionality came from a few issues.

• View being registered in ClassRegistry could cause registry poisoning issues when requestAction or the EmailComponent were used.

• View being accessible as a global symbol invited abuse.

• Helpers were not self contained. After constructing a helper, you had to manually construct several other objects in order to get a functioning object.

You can read more about HelperCollection in the Collections documentation.

Deprecated properties¶

The following properties on helpers are deprecated, you should use the request object properties or Helper methods instead of directly accessing these properties as they will be removed in a future release.

• Helper::$webroot is deprecated, use the request object’s webroot property.

• Helper::$base is deprecated, use the request object’s base property.

• Helper::$here is deprecated, use the request object’s here property.

• Helper::$data is deprecated, use the request object’s data property.

• Helper::$params is deprecated, use the $this->request instead.

XmlHelper, AjaxHelper and JavascriptHelper removed¶

The AjaxHelper and JavascriptHelper have been removed as they were deprecated in version 1.3. The XmlHelper was removed, as it was made obsolete and redundant with the improvements to Xml. The Xml class should be used to replace previous usage of XmlHelper.

The AjaxHelper, and JavascriptHelper are replaced with the JsHelper and HtmlHelper.

JsHelper¶

• JsBaseEngineHelper is now abstract, you will need to implement all the methods that previously generated errors.

PaginatorHelper¶

• PaginatorHelper::sort() now takes the title and key arguments in the reverse order. $key will always be first now. This was done to prevent needing to swap arguments when adding a second one.

• PaginatorHelper had a number of changes to the paging params used internally. The default key has been removed.

• PaginatorHelper now supports generating links with paging parameters in the querystring.

There have been a few improvements to pagination in general. For more information on that you should read the new pagination features page.

FormHelper¶

CacheHelper¶

CacheHelper has been fully decoupled from View, and uses helper callbacks to generate caches. You should remember to place CacheHelper after other helpers that modify content in their afterRender and afterLayout callbacks. If you don’t some changes will not be part of the cached content.

CacheHelper also no longer uses <cake:nocache> to indicate un-cached regions. Instead it uses special HTML/XML comments. <!--nocache--> and <!--/nocache-->. This helps CacheHelper generate valid markup and still perform the same functions as before. You can read more CacheHelper and View changes.

Helper Attribute format more flexible¶

The Helper class has more 3 protected attributes:

• Helper::_minimizedAttributes: array with minimized attributes (ie: array('checked', 'selected', ...));

• Helper::_attributeFormat: how attributes will be generated (ie: %s="%s");

• Helper::_minimizedAttributeFormat: how minimized attributes will be generated: (ie %s="%s")

By default the values used in CakePHP 1.3 were not changed. But now you can use boolean attributes from HTML, like <input type="checkbox" checked />. To this, just change $_minimizedAttributeFormat in your AppHelper to %s.

To use with Html/Form helpers and others, you can write:

$this->Form->checkbox('field', array('checked' => true, 'value' => 'some_value'));

Other facility is that minimized attributes can be passed as item and not as key. For example:

$this->Form->checkbox('field', array('checked', 'value' => 'some_value'));

Note that checked have a numeric key.

Pagination¶

Pagination has traditionally been a single method in Controller, this created a number of problems though. Pagination was hard to extend, replace, or modify. For 2.0 pagination has been extracted into a component. Controller::paginate() still exists, and serves as a convenience method for loading and using the PaginatorComponent.

For more information on the new features offered by pagination in 2.0, see the Pagination documentation.

View no longer registered in ClassRegistry¶

The view being registered ClassRegistry invited abuse and affectively created a global symbol. In 2.0 each Helper receives the current View instance in its constructor. This allows helpers access to the view in a similar fashion as in the past, without creating global symbols. You can access the view instance at $this->_View in any helper.

Deprecated properties¶

• View::$webroot is deprecated, use the request object’s webroot property.

• View::$base is deprecated, use the request object’s base property.

• View::$here is deprecated, use the request object’s here property.

• View::$data is deprecated, use the request object’s data property.

• View::$params is deprecated, use the $this->request instead.

• View::$loaded has been removed. Use the HelperCollection to access loaded helpers.

• View::$model has been removed. This behavior is now on Helper

• View::$modelId has been removed. This behavior is now on Helper

• View::$association has been removed. This behavior is now on Helper

• View::$fieldSuffix has been removed. This behavior is now on Helper

• View::entity() has been removed. This behavior is now on Helper

• View::_loadHelpers() has been removed, used View::loadHelpers() instead.

• How View::element() uses caching has changed, see below for more information.

• View callbacks have been shifted around, see below for more information

• API for View::element() has changed. Read here for more info.

The deprecated properties on View will be accessible through a __get() method. This method will be removed in future versions, so it’s recommended that you update your application.

Removed methods¶

• View::_triggerHelpers() Use $this->Helpers->trigger() instead.

• View::_loadHelpers() Use $this->loadHelpers() instead. Helpers now lazy load their own helpers.

Added methods¶

• View::loadHelper($name, $settings = array()); Load a single helper.

• View::loadHelpers() Loads all the helpers indicated in View::$helpers.

View->Helpers¶

By default View objects contain a HelperCollection at $this->Helpers.

Themes¶

To use themes in your Controller you no longer set public $view = 'Theme';. Use public $viewClass = 'Theme'; instead.

Callback positioning changes¶

beforeLayout used to fire after scripts_for_layout and content_for_layout were prepared. In 2.0, beforeLayout is fired before any of the special variables are prepared, allowing you to manipulate them before they are passed to the layout. The same was done for beforeRender. It is now fired well before any view variables are manipulated. In addition to these changes, helper callbacks always receive the name of the file about to be rendered. This combined with helpers being able to access the view through $this->_View and the current view content through $this->_View->output gives you more power than ever before.

Helper callback signature changes¶

Helper callbacks now always get one argument passed in. For beforeRender and afterRender it is the view file being rendered. For beforeLayout and afterLayout it is the layout file being rendered. Your helpers function signatures should look like:

public function beforeRender($viewFile) {

}

public function afterRender($viewFile) {

}

public function beforeLayout($layoutFile) {

}

public function afterLayout($layoutFile) {

}

Element caching, and view callbacks have been changed in 2.0 to help provide you with more flexibility and consistency. Read more about those changes.

CacheHelper decoupled¶

In previous versions there was a tight coupling between CacheHelper and View. For 2.0 this coupling has been removed and CacheHelper just uses callbacks like other helpers to generate full page caches.

CacheHelper <cake:nocache> tags changed¶

In previous versions, CacheHelper used a special <cake:nocache> tag as markers for output that should not be part of the full page cache. These tags were not part of any XML schema, and were not possible to validate in HTML or XML documents. For 2.0, these tags have been replaced with HTML/XML comments:

<cake:nocache> becomes <!--nocache-->
</cake:nocache> becomes <!--/nocache-->

The internal code for full page view caches has also changed, so be sure to clear out view cache files when updating.

MediaView changes¶

MediaView::render() now forces download of unknown file types instead of just returning false. If you want you provide an alternate download filename you now specify the full name including extension using key ‘name’ in the array parameter passed to the function.

No more group tests¶

PHPUnit does not differentiate between group tests and single test cases in the runner. Because of this, the group test options, and support for old style group tests has been removed. It is recommended that GroupTests be ported to PHPUnit_Framework_Testsuite subclasses. You can find several examples of this in CakePHP’s test suite. Group test related methods on TestManager have also been removed.

Testsuite shell¶

The testsuite shell has had its invocation simplified and expanded. You no longer need to differentiate between case and group. It is assumed that all tests are cases. In the past you would have done cake testsuite app case models/post you can now do cake testsuite app Model/Post.

The testsuite shell has been refactored to use the PHPUnit CLI tool. It now supports all the command line options supported by PHPUnit. cake testsuite help will show you a list of all possible modifiers.

Database objects¶

CakePHP 2.0 introduces some changes to Database objects that should not greatly affect backwards compatibility. The biggest one is the adoption of PDO for handling database connections. If you are using a vanilla installation of PHP 5 you will already have installed the needed extensions, but you may need to activate individual extensions for each driver you wish to use.

Using PDO across all DBOs let us homogenize the code for each one and provide more reliable and predictable behavior for all drivers. It also allowed us to write more portable and accurate tests for database related code.

The first thing users will probably miss is the “affected rows” and “total rows” statistics, as they are not reported due to the more performant and lazy design of PDO, there are ways to overcome this issue but very specific to each database. Those statistics are not gone, though, but could be missing or even inaccurate for some drivers.

A nice feature added after the PDO adoption is the ability to use prepared statements with query placeholders using the native driver if available.

BehaviorCollection¶

• BehaviorCollection no longer strtolower()'s mappedMethods. Behavior mappedMethods are now case sensitive.

AclBehavior and TreeBehavior¶

• No longer supports strings as configuration. Example:

  public $actsAs = array(
      'Acl' => 'Controlled',
      'Tree' => 'nested'
  );
  

  became:

  public $actsAs = array(
      'Acl' => array('type' => 'Controlled'),
      'Tree' => array('type' => 'nested')
  );
  

Plugin App Controller and Plugin App Model¶

The plugin AppController and AppModel are no longer located directly in the plugin folder. They are now placed into the plugin’s Controller and Model folders as such:

/app
    /Plugin
        /Comment
            /Controller
                CommentAppController.php
            /Model
                CommentAppModel.php

Backwards incompatible Shell API changes¶

• Shell no longer has an AppModel instance. This AppModel instance was not correctly built and was problematic.

• Shell::_loadDbConfig() has been removed. It was not generic enough to stay in Shell. You can use the DbConfigTask if you need to ask the user to create a db config.

• Shells no longer use $this->Dispatcher to access stdin, stdout, and stderr. They have ConsoleOutput and ConsoleInput objects to handle that now.

• Shells lazy load tasks, and use TaskCollection to provide an interface similar to that used for Helpers, Components, and Behaviors for on the fly loading of tasks.

• Shell::$shell has been removed.

• Shell::_checkArgs() has been removed. Configure a ConsoleOptionParser

• Shells no longer have direct access to ShellDispatcher. You should use the ConsoleInput, and ConsoleOutput objects instead. If you need to dispatch other shells, see the section on ‘Invoking other shells from your shell’.

Backwards incompatible ShellDispatcher API changes¶

• ShellDispatcher no longer has stdout, stdin, stderr file handles.

• ShellDispatcher::$shell has been removed.

• ShellDispatcher::$shellClass has been removed.

• ShellDispatcher::$shellName has been removed.

• ShellDispatcher::$shellCommand has been removed.

• ShellDispatcher::$shellPaths has been removed, use App::path('shells'); instead.

• ShellDispatcher no longer uses ‘help’ as a magic method that has special status. Instead use the --help/-h options, and an option parser.

Backwards incompatible Shell Changes¶

• Bake’s ControllerTask no longer takes public and admin as passed arguments. They are now options, indicated like --admin and --public.

It’s recommended that you use the help on shells you use to see what if any parameters have changed. It’s also recommended that you read the console new features for more information on new APIs that are available.