Guide to CakePHP 2.0 Conventions

With the release of CakePHP 2.0 you will see some big changes. With the release of 2.0 I decided it was time to start tinkering and getting ready for 1.x migrations and will start new development with 2.x. This page serves as a quick intro and reference to these changes. If you are familiar with 1.x I’ve provided some side-by-side comparison of code.

Using git to clone CakePHP 2.0

prompt> git clone https://github.com/cakephp/cakephp.git myapp
prompt> cd myapp
prompt> git checkout 2.0

CamelCase directories and filenames

A late decision to 2.x is to use CamelCase class names and filenames. This is a welcome change as the CakePHP 1.x convention did not feel very natural. Also notice directories are not plural any more, ie controllers is now Controller, views is now View.

CakePHP 1.x

File: app/controllers/users_controller.php

class UsersController {
    var $name = 'Users';

}

CakePHP 2.x

File: app/Controller/UsersController.php

class UsersController {
    var $name = 'Users';

}

Views will follow the same convention for directories but not the actual .ctp view files.

Location of AppController.php (app_controller.php)

AppController now lives in app/Controller with all of your other controllers.

CakePHP 1.x

app/app_controller.php

CakePHP 2.x

app/Controller/AppController.php

Note: AppModel and AppController files do not exist in a new installation but it’s best practice to create and use these files.

Location of AppModel.php (app_model.php)

Like AppController, AppModel now lives in app/Model with all of your other models.

CakePHP 1.x

app/app_model.php

CakePHP 2.x

app/Model/AppModel.php

Location of AppHelper.php and AppShell.php

app/Helper/AppHelper.php
app/Console/Command/AppShell.php

Note: The AppModel, AppController, AppHelper and AppShell classes do not exist in a new installation but it’s best practice to create and use these files. In the latest 2.1 release these files already exists in app/ and no long exist in lib/Cake.

CakePHP 2.x Themes

Themes are enabled by setting two attributes on controllers. If you want to enable an application wide theme then you will apply this code to your AppController.

CakePHP 2.x

File: app/Controller/AppController.php

class AppController extends Controller {
    public function beforeRender() {
        $this->viewClass = 'Theme';
        $this->theme = 'MyTheme';
    }
}

The theme files as specified will need to be located in app/View/Themed/MyTheme/ and this directory will mirror the structure of View directory. Example, the default layout will be app/View/Themed/MyTheme/Layouts/default.ctp

app/Config/email.php

CakePHP 2.x introduces a new email.php configuration file. The syntax of this file will feel like database.php but deals with email specific configurations. You can specifiy multiple configurations for production, development, and testing.

File: app/Config/email.php.default

<?php
/**
 * This is email configuration file.
 *
 * Use it to configure email transports of Cake.
 *
 * PHP 5
 *
 * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
 * Copyright 2005-2011, Cake Software Foundation, Inc. (http://cakefoundation.org)
 *
 * Licensed under The MIT License
 * Redistributions of files must retain the above copyright notice.
 *
 * @copyright     Copyright 2005-2011, Cake Software Foundation, Inc. (http://cakefoundation.org)
 * @link          http://cakephp.org CakePHP(tm) Project
 * @package       app.config
 * @since         CakePHP(tm) v 2.0.0
 * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
 */
/**
 * In this file you set up your send email details.
 *
 * @package       cake.config
 */
/**
 * Email configuration class.
 * You can specify multiple configurations for production, development and testing.
 *
 * transport => The name of a supported transport; valid options are as follows:
 *		mail 		- Send using PHP mail function
 *		smtp		- Send using SMTP
 *
 * You can add custom transports (or override existing transports) by adding the
 * appropriate file to app/Network/Email.  Transports should be named 'YourTransport.php',
 * where 'Your' is the name of the transport.
 *
 * from =>
 * The origin email. See CakeEmail::from() about the valid values
 *
 */
class EmailConfig {

	public $default = array(
		'transport' => 'mail',
		'from' => 'you@localhost'
	);

	public $smtp = array(
		'transport' => 'smtp',
		'from' => array('My Site', 'site@localhost'),
		'host' => 'localhost',
		'port' => 25,
		'timeout' => 30,
		'username' => 'user',
		'password' => 'secret',
		'client' => null
	);

	public $fast = array(
		'from' => 'you@localhost',
		'sender' => null,
		'to' => null,
		'cc' => null,
		'bcc' => null,
		'replyTo' => null,
		'readReceipt' => null,
		'returnPath' => null,
		'messageId' => true,
		'subject' => null,
		'message' => null,
		'headers' => null,
		'viewRender' => null,
		'template' => false,
		'layout' => false,
		'viewVars' => null,
		'attachments' => null,
		'emailFormat' => null,
		'transport' => 'smtp',
		'host' => 'localhost',
		'port' => 25,
		'timeout' => 30,
		'username' => 'user',
		'password' => 'secret',
		'client' => null
	);

}

CakeRequest

CakePHP 2.0 has done a good job to centralize data such as POST, GET, url parameters, and most of the functionality of RequestHandlerComponent into the CakeRequest object, available within your controller as $this->request.

CakePHP 1.3

...Context of a Controller Action...
$username = $this->data['User']['username'];
$urlpart = $this->param['url']

CakePHP 2.0

...Context of a Controller Action...
$username = $this->request->data['User']['username'];
$urlparth = $this->request->url;

App::import() becomes App::uses()

All classes are now loaded using the App::uses() static method.

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

App::import('Component', 'Email');
// becomes
App::uses('EmailComponent', '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')

Removed Constants

The following constants where removed mostly due to duplication.

APP_PATH
BEHAVIORS
COMPONENTS
CONFIGS
CONSOLE_LIBS
CONTROLLERS
CONTROLLER_TESTS
ELEMENTS
HELPERS
HELPER_TESTS
LAYOUTS
LIB_TESTS
LIBS
MODELS
MODEL_TESTS
SCRIPTS
VIEWS

A list of valid global constants for CakePHP can be found here.

I will add more as I explore and begin developing apps with CakePHP 2.0. As always, your comments are welcome below.