A Rapid Development Framework
Cake Software Foundation Inc.
Author and Editor: John Anderson
Author and Technical Editor: Larry E Masters
Author and Technical Editor: Larry E Masters Version 1.x.x.x (Incomplete)
Copyright©2006 Cake Software Foundation Inc.
Abstract
This is the official CakePHP manual,
This work is licensed under the NEED TO CHOOSE LICENSE; you can see the full terms of the license here [ht- tp://www.cakephp.org].
This is the official manual
These conditions may only be waived with prior consent from the Cake Software Foundation Inc..
1. Audience ... x
2. CakePHP is Free ... x
3. Community ... x
1. Introduction to CakePHP ... 1
1.1. What is CakePHP? ... 1
1.2. Why CakePHP? ... 1
1.3. History of CakePHP ... 1
2. Basic Concepts ... 2
2.1. Introduction ... 2
2.2. The MVC Pattern ... 2
2.3. Overview of the Cake File Layout ... 2
3. Installing CakePHP ... 4
3.1. Introduction ... 4
3.2. Requirements ... 4
3.2.1. Server Requirements ... 4
3.3. Installing CakePHP ... 4
3.3.1. Getting the most recent stable version ... 4
3.3.2. Unpacking ... 4
3.4. Setting Up CakePHP ... 5
3.4.1. Development Setup ... 5
3.4.2. Production Setup ... 5
3.4.3. Advanced Setup: Alternative Installation Options ... 6
3.5. Configuring Apache and mod_rewrite ... 8
3.6. Make Sure It's Working ... 8
4. Configuration ... 9
4.1. Database Configuration ... 9
4.2. Global Configuration ... 10
4.3. Routes Configuration ... 11
4.4. Advanced Routing Configuration: Admin Routing and Webservices ... 12
4.5. (Optional) Custom Inflections Configuration ... 14
5. Scaffolding ... 15
5.1. Cake's Scaffolding is Pretty Cool ... 15
5.2. Customizing Scaffold Views ... 15
6. Models ... 17
6.1. What is a model? ... 17
6.2. Model Functions ... 17
6.2.1. User-Defined Functions ... 18
6.2.2. Retrieving Your Data ... 18
6.2.3. Complex Find Conditions (using arrays) ... 21
6.2.4. Saving Your Data ... 23
6.2.5. Model Callbacks ... 24
6.3. Model Variables ... 26
6.4. Associations ... 27
6.4.1. Introduction ... 27
6.4.2. Defining and Querying with hasOne ... 28
6.4.3. Defining and Querying with belongsTo ... 29
6.4.4. Defining and Querying with hasMany ... 30
6.4.5. Defining and Querying with hasAndBelongsToMany ... 33
6.4.6. Saving Related Model Data ... 36
6.4.7. Saving hasAndBelongsToMany Relations ... 37
6.4.8. Changing Associations on the Fly using bindModel() and unbindModel() ... 39
7. Controllers ... 43
7.1. Controller Functions ... 43
7.1.1. Interacting with your Views ... 44
7.1.2. User Redirection ... 44
7.1.3. Controller Callbacks ... 45
7.1.4. Other Useful Functions ... 45
7.2. Controller Variables ... 48
7.3. Controller Parameters ... 49
8. Views ... 51
8.1. Views ... 51
8.1.1. Layouts ... 51
8.1.2. Elements ... 52
9. Components ... 54
9.1. Presentation ... 54
9.2. Creating your own ... 54
9.3. Making your components public ... 55
10. Helpers ... 56
10.1. Helpers ... 56
10.1.1. HTML ... 56
10.1.2. AJAX ... 62
10.1.3. Javascript ... 67
10.1.4. Number ... 68
10.1.5. Text ... 69
10.1.6. Time ... 70
10.1.7. Cache ... 72
10.2. Creating Your Own Helpers ... 72
10.2.1. Extending the Cake Helper Class ... 72
10.2.2. Including other Helpers ... 73
10.2.3. Using your Custom Helper ... 74
10.2.4. Contributing ... 74
11. Cake's Global Constants And Functions ... 75
11.1. Global Functions ... 75
11.2. CakePHP Core Definition Constants ... 78
11.3. CakePHP Path Constants ... 79
11.4. CakePHP Webroot Configuration Paths ... 80
12. Data Validation ... 81
12.1. Data Validation ... 81
13. Plugins ... 84
13.1. Creating a Plugin ... 84
13.2. Plugin Controllers ... 85
13.3. Plugin Models ... 86
13.4. Plugin Views ... 86
13.5. Working With Plugins ... 86
14. Access Control Lists ... 88
14.1. Understanding How ACL Works ... 88
14.2. Defining Permissions: Cake's INI-based ACL ... 91
14.3. Defining Permissions: Cake's Database ACL ... 91
14.3.1. Getting Started ... 91
14.3.2. Creating Access Request Objects (AROs) and Access Control Objects (ACOs) 92 14.3.3. Assigning Permissions ... 93
14.4. Checking Permissions: The ACL Component ... 94
15. Data Sanitization ... 96
15.1. Using Sanitize in Your Application ... 96
15.2. Making Data Safe for use in SQL and HTML ... 96
16. The Cake Session Component ... 98
16.1. Cake Session Storage Options ... 98
16.2. Using the Cake Session Component ... 98
17. The Request Handler Component ... 101
17.1. Introduction ... 101
17.2. Getting Client/Request Information ... 101
17.3. Stripping Data ... 104
17.4. Other Useful Functions ... 104
18. The Security Component ... 106
18.1. Introduction ... 106
18.2. Protecting Controller Actions ... 106
18.3. Handling Invalid Requests ... 107
18.4. Advanced Request Authentication ... 107
19. View Caching ... 108
19.1. What is it ? ... 108
19.2. How Does it Work ? ... 108
19.2.1. Activating the cache ... 108
19.2.2. The $cacheAction Controller Variable ... 108
19.2.3. Marking Content in the View ... 109
19.2.4. Clearing the cache ... 109
19.3. Things To Remember ... 110
A. The Cake Blog Tutorial ... 111
A.1. Introduction ... 111
A.2. Getting Cake ... 111
A.3. Creating the Blog Database ... 112
A.4. Cake Database Configuration ... 112
A.5. A Note On mod_rewrite ... 113
A.6. Create a Post Model ... 113
A.7. Create a Posts Controller ... 114
A.8. Creating Post Views ... 115
A.9. Adding Posts ... 117
A.10. Data Validation ... 118
A.11. Deleting Posts ... 120
A.12. Editing Posts ... 121
A.13. Routes ... 122
A.14. Conclusion ... 123
B. Example: Simple User Authentication ... 124
B.1. The Big Picture ... 124
B.2. Authentication and Persistence ... 125
B.3. Access Checking in your Application ... 127
C. Cake Conventions ... 129
C.1. Conventions, eh ? ... 129
C.2. Filenames ... 129
C.3. Models ... 129
C.4. Controllers ... 130
C.5. Views ... 130
C.6. Helpers ... 130
C.7. Components ... 131
C.8. Vendors ... 131
3.2. /app/webroot/index.php (partial, comments removed) ... 6
4.1. app/config/database.php ... 9
4.2. Route Pattern ... 11
4.3. Route Example ... 11
4.4. Route Handling in a Controller ... 11
4.5. Setting the Default Route ... 12
4.6. /app/config/core.php (partial) ... 13
4.7. messages_controller.php ... 13
5.1. Custom Scaffolding Views for a Single Controller ... 15
5.2. Custom Scaffolding Views for an Entire Application ... 16
6.1. Example User Model, saved in /app/models/user.php ... 17
6.2. Example Model Functions ... 18
6.3. Custom Sql Calls with query() ... 21
6.4. Basic find conditions array usage example: ... 21
6.5. /app/models/user.php hasOne ... 28
6.6. /app/models/profile.php belongsTo ... 29
6.7. /app/models/user.php hasMany ... 30
6.8. HABTM Join Tables: Sample models and their join table names ... 33
6.9. /app/models/post.php hasAndBelongsToMany ... 34
6.10. /app/controllers/posts_controller.php (partial) ... 36
6.11. /app/controllers/posts_controller.php (partial) ... 37
6.12. /app/views/posts/add.thtml Form for creating posts ... 38
6.13. /app/views/posts/add.thtml (Tag association code added) ... 39
6.14. leader.php and follower.php ... 39
6.15. leaders_controller.php (partial) ... 40
6.16. Generic unbindModel() example ... 41
6.17. leaders_controller.php (partial) ... 41
6.18. Generic bindModel() example ... 41
8.1. Calling an Element without parameters ... 52
8.2. Calling an Element passing a data array ... 52
9.1. A simple component ... 54
10.1. Edit Action inside of the NotesController ... 58
10.2. Edit View code (edit.thtml) sample ... 59
10.3. Concatenating time data before saving a model (excerpt from NotesController) ... 61
10.4. AjaxHelper $options Keys ... 62
10.5. /app/views/helpers/link.php ... 73
10.6. /app/views/helpers/link.php (logic added) ... 73
10.7. /app/views/helpers/link.php (using other helpers) ... 74
12.1. /app/models/user.php ... 81
12.2. Form-handling Action in /app/controllers/blog_controller.php ... 81
12.3. The add form view in /app/views/blog/add.thtml ... 82
13.1. Pizza Ordering Filesystem Layout ... 84
13.2. Pizza Plugin AppController: /app/plugins/pizza_app_controller.php ... 84
13.3. Pizza Plugin AppModel: /app/plugins/pizza_app_model.php ... 85
13.4. /app/plugins/pizza/controllers/pizza_orders_controller.php ... 85
13.5. /app/plugins/pizza/models/pizza_order.php ... 86
13.6. /app/plugins/pizza/views/pizza_orders/index.thtml ... 86
14.1. Initializing your database using acl.php ... 92
16.1. core.php Session Configuration ... 98
19.1. /app/config/core.php (partial) ... 108
19.2. ... 108
19.3. $cacheAction Examples ... 109
19.4. <cake:nocache> example ... 109
19.5. <cake:nocache> example ... 110
A.1. /app/models/post.php ... 113
A.2. /app/controllers/posts_controller.php ... 114
A.3. /app/controllers/posts_controller.php (index action added) ... 114
A.4. /app/views/posts/index.thtml ... 116
A.5. /app/controllers/posts_controller.php (view action added) ... 116
A.6. /app/views/posts/view.thtml ... 117
A.7. /app/controllers/posts_controller.php (add action added) ... 117
A.8. /app/views/posts/add.thtml ... 118
A.9. /app/models/post.php (validation array added) ... 119
A.10. /app/controllers/posts_controller.php (delete action only) ... 120
A.11. /app/views/posts/index.thtml (add and delete links added) ... 120
A.12. /app/controllers/posts_controller.php (edit action only) ... 121
A.13. /app/views/posts/edit.thtml ... 121
A.14. /app/views/posts/index.thtml (edit links added) ... 122
B.1. Table 'users', Fictional Client Management System Database ... 125
B.2. /app/views/users/login.thtml ... 125
B.3. /app/controllers/users_controller.php (partial) ... 126
B.4. /app/app_controller.php ... 127
B.5. Forcing authentication before all actions in a controller ... 127
B.6. Forcing authentication before a single controller action ... 128
1. Audience
This manual is written for people who want to build web applications faster and more en- joyably. CakePHP aims to assist PHP users of all levels to create robust, maintainable ap- plications quickly and easily.
This manual expects a basic knowledge of PHP and HTML. A familiarity with the Model- View-Controller programming pattern is helpful, but we will cover that along the way for those new to MVC. While this work will attempt to aid the reader in configuring and troubleshooting their web server, a full coverage of such issues is outside the scope of this manual.
Rudimentary knowledge in first aid (CPR), basic survival skills, dating & relationships is also generally recommended, though also outside the scope of this document.
2. CakePHP is Free
CakePHP is free. You don't have to pay for it, you can use it any way you want. CakePHP is developed under the MIT License [http://www.opensource.org/licenses/mit-license.php].
CakePHP is an Open Source project, this means you have full access to the source code.
The best place to get the most recent version is at the CakePHP web site (ht- tp://www.cakephp.org). You can also browse the latest and greatest code there.
3. Community
CakePHP is developed by a hard working community of people. They come from different countries all over the world and joined together to create the CakePHP framework for the benefit of the widest audience possible. For more information about Cake's active de- veloper and user communities, visit http://www.cakephp.org.
Our IRC channel is always filled with knowledgable, friendly Bakers. If you're stuck on a bit of code, need a listening ear, or want to start an argument about coding conventions, drop on by: we'd love to hear from you. Visit us at #cakephp on irc.freenode.com.
1.1. What is CakePHP?
CakePHP is a free open-source rapid development framework for PHP. Its a structure of libraries, classes and run-time infrastructure for programmers creating web applications ori- ginally inspired by the Ruby on Rails framework. Our primary goal is to enable you to work in a structured and rapid manner - without loss of flexibility.
1.2. Why CakePHP?
CakePHP has several features that make it a great choice as a framework for developing applications swiftly and with the least amount of hassle. Here are a few in no particular or- der:
1. Active, friendly community 2. Flexible Licensing
3. Compatibility with PHP4 and PHP5
4. Integrated CRUD for database interaction and simplified queries 5. Application Scaffolding
6. Model View Controller (MVC) Architecture
7. Request dispatcher with good looking, custom URLs 8. Built-in Validation
9. Fast and flexible templating (PHP syntax, with helpers) 1
0.
View Helpers for AJAX, Javascript, HTML Forms and more 1
1.
Security, Session, and Request Handling Components 1
2.
Flexible access control lists 1
3.
Data Sanitization 1
4.
Flexible View Caching 1
5.
Works from any web site subdirectory, with little to no Apache configuration involved
1.3. History of CakePHP
In 2005, Michal Tatarynowicz wrote a minimal version of a Rapid Application Framework in PHP. He found that it was the start of a very good framework. Michal published the frame- work under the MIT license, dubbing it Cake, and opened it up to a community of de- velopers, who now maintain Cake under the name CakePHP.
2.1. Introduction
This chapter is a short, casual introduction to MVC concepts as they are implemented in Cake. If you're new to MVC (Model View Controller) patterns, this chapter is definitely for you. We begin with a discussion of general MVC concepts, work our way into the specific application of MVC in CakePHP, and show some simple examples of CakePHP using the MVC pattern.
2.2. The MVC Pattern
Model-View-Controller is a software design pattern that helps you logically separate your code, make it more reusable, maintainable, and generally better. Model View Controller was first described by the author group Gang of Four. Dean Helman wrote (an extract from Objective Toolkit Pro white paper):
"The MVC paradigm is a way of breaking an application, or even just a piece of an application's interface, into three parts: the model, the view, and the controller. MVC was originally developed to map the traditional input, processing, output roles into the GUI realm.
Input -> Processing -> Output Controller -> Model -> View
"The user input, the modeling of the external world, and the visual feedback to the user are separated and handled by model, view port and controller objects. The con- troller interprets mouse and keyboard inputs from the user and maps these user ac- tions into commands that are sent to the model and/or view port to effect the appro- priate change. The model manages one or more data elements, responds to queries about its state, and responds to instructions to change state. The view port manages a rectangular area of the display and is responsible for presenting data to the user through a combination of graphics and text."
In Cake terms, the Model represents a particular database table/record, and it's relation- ships to other tables and records. Models also contain data validation rules, which are ap- plied when model data is inserted or updated. The View represents Cake's view files, which are regular HTML files embedded with PHP code. Cake's Controller handles re- quests from the server. It takes user input (URL and POST data), applies business logic, uses Models to read and write data to and from databases and other sources, and lastly, sends output data to the appropriate view file.
To make it as easy as possible to organize your application, Cake uses this pattern not only to manage how objects interact within your application, but also how files are stored, which is detailed next.
2.3. Overview of the Cake File Layout
When you unpack Cake on your server you will find three main folders -
app cake vendors
Thecakefolder is where the core libraries for Cake lay and you generally won't ever need to touch it.
Theapp folder is where your application specific folders and files will go. The separation between the cake folder and the app folder make it possible for you to have many app folders sharing a single set of Cake libraries. This also makes it easy to update CakePHP:
you just download the latest version of Cake and overwrite your current core libraries. No need to worry about overwriting something you wrote for your app.
You can use the vendors directory to keep third-party libraries in. You will learn more about vendors later, but the basic idea is that you can access classes you've placed in the vendors directory using Cake'svendor()function.
Let's look at the entire file layout:
/app
/config - Contains config files for your database, ACL, etc.
/controllers - Controllers go here /components - Components go here
/index.php - Allows you to deploy cake with /app as the DocumentRoot
/models - Models go here /plugins - Plugins go here
/tmp - Used for caches and logs
/vendors - Contains third-party libaries for this application
/views - Views go here
/elements - Elements, little bits of views, go here /errors - Your custom error pages go here
/helpers - Helpers go here
/layouts - Application layout files go here /pages - Static views go here
/webroot - The DocumentRoot for the application /css
/files /img /js
/cake - Cake's core libraries. Don't edit any files here.
index.php
/vendors - Used for server-wide third-party libraries.
VERSION.txt - Let's you know what version of Cake you're using.
3.1. Introduction
So now you know everything there is to know about the structure and purpose of all the CakePHP libraries, or you have skipped to this part because you don't care about that stuff and just want to start playing. Either way, you're ready to get your hands dirty.
This chapter will describe what must be installed on the server, different ways to configure your server, downloading and installing CakePHP, bringing up the default CakePHP page, and some troubleshooting tips just in case everything does not go as planned.
3.2. Requirements
In order use CakePHP you must first have a server that has all the required libraries and programs to run CakePHP:
3.2.1. Server Requirements
Here are the requirements for setting up a server to run CakePHP:
1. An HTTP server (like Apache) with the following enabled: sessions, mod_rewrite (not absolutely necessary but preferred)
2. PHP 4.3.2 or greater. Yes, CakePHP works great in either PHP 4 or 5.
3. A database engine (right now, there is support for MySQL, PostgreSQL and a wrapper for ADODB).
3.3. Installing CakePHP
3.3.1. Getting the most recent stable version
There are a few ways you can secure a copy of CakePHP: getting a stable release from CakeForge, grabbing a nightly build, or getting a fresh version of code from SVN.
To download a stable version of code, check out the files section of the CakePHP project at CakeForge by going to http://cakeforge.org/projects/cakephp/.
To grab a nightly, download one from http://cakephp.org/downloads/index/nightly. These nightly releases are stable, and often include the bug fixes between stable releases.
To grab a fresh copy from our SVN repository, use your favorite SVN client and connect to https://svn.cakephp.org/repo/trunk/cake/ and choose the version you're after.
3.3.2. Unpacking
Now that you've downloaded the most recent release, place that compressed package on your web server in the webroot. Now you need to unpack the CakePHP package. There are two ways to do this, using a development setup, which allows you to easily view many CakePHP applications under a single domain, or using the production setup, which allows for a single CakePHP application on the domain.
3.4. Setting Up CakePHP
The first way to setup CakePHP is generally only recommended for development environ- ments because it is less secure. The second way is considered more secure and should be used in a production environment.
Note
NOTE:/app/tmpmust be writable by the user that your web server runs as.
3.4.1. Development Setup
For development we can place the whole Cake installation directory inside the specified DocumentRoot like this:
/wwwroot /cake
/app /cake /vendors .htaccess index.php
In this setup the wwwroot folder acts a the web root so your URLs will look something like this (if you're also using mod_rewrite):
www.example.com/cake/controllerName/actionName/param1/param2
3.4.2. Production Setup
In order to utilize a production setup, you will need to have the rights to change the Docu- mentRoot on your server. Doing so, makes the whole domain act as a single CakePHP ap- plication.
The production setup uses the following layout:
../path_to_cake_install /app
/config /controllers /models /plugins /tmp /vendors /views
/webroot <-- This should be your new DocumentRoot .htaccess
index.php /cake
/vendors .htaccess index.php
Example 3.1. Suggested Production httpd.conf
DocumentRoot /path_to_cake/app/webroot
In this setup the webroot directory is acting as the web root so your URLs might look like this (if you're using mod_rewrite):
http://www.example.com/controllerName/actionName/param1/param2
3.4.3. Advanced Setup: Alternative Installation Options
There are some cases where you may wish to place Cake's directories on different places on disk. This may be due to a shared host restriction, or maybe you just want a few of your apps to share the same Cake libraries.
There are three main parts to a Cake application:
1. The core CakePHP libraries - Found in/cake
2. Your application code (e.g. controllers, models, layouts and views) - Found in/app 3. Your application webroot files (e.g. images, javascript and css) - Found in /
app/webroot
Each of these directories can be located anywhere on your file system, with the exception of the webroot, which needs to be accessible by your web server. You can even move the webrootfolder out of theappfolder as long as you tell Cake where you've put it.
To configure your Cake installation, you'll need to make some changes to / app/webroot/index.php (as it is distributed in Cake). There are three constants that you'll need to edit: ROOT, APP_DIR, and CAKE_CORE_INCLUDE_PATH.
• ROOT should be set to the path of the directory that contains yourappfolder.
• APP_DIR should be set to the path of yourappfolder.
• CAKE_CORE_INCLUDE_PATH should be set to the path of your Cake libraries folder.
Example 3.2. /app/webroot/index.php (partial, comments removed)
if (!defined('ROOT')) {
define('ROOT', dirname(dirname(dirname(__FILE__))));
}
if (!defined('APP_DIR')) {
define ('APP_DIR', basename(dirname(dirname(__FILE__))));
}
if (!defined('CAKE_CORE_INCLUDE_PATH')) {
define('CAKE_CORE_INCLUDE_PATH', ROOT);
}
An example might help illustrate this better. Imagine that I wanted to set up Cake to work with the following setup:
• I want my Cake libraries shared with other applications, and placed in/usr/lib/cake.
• My Cake webroot directory needs to be/var/www/mysite/.
• My application files will be stored in/home/me/mysite.
Here's what the file setup looks like:
/home /me
/mysite <-- Used to be /cake_install/app /config
/controllers /models /plugins /tmp /vendors /views index.php /var
/www
/mysite <-- Used to be
/cake_install/app/webroot /css
/files /img /js
.htaccess css.php favicon.ico index.php /usr
/lib
/cake <-- Used to be /cake_install/cake /cake
/config /docs /libs /scripts
app_controller.php app_model.php basics.php bootstrap.php dispatcher.php /vendors
Given this type of setup, I would need to edit my webroot index.php file (which should be at /var/www/mysite/index.php, in this example) to look like the following:
Note
It is recommended to use the 'DS' constant rather than slashes to delimit file paths. This pre- vents any 'missing file' errors you might get as a result of using the wrong delimiter, and it makes your code more portable.
if (!defined('ROOT')) {
define('ROOT', DS.'home'.DS.'me');
}
if (!defined('APP_DIR')) {
define ('APP_DIR', 'mysite');
}
if (!defined('CAKE_CORE_INCLUDE_PATH')) {
define('CAKE_CORE_INCLUDE_PATH', DS.'usr'.DS.'lib'.DS.'cake');
}
3.5. Configuring Apache and mod_rewrite
While CakePHP is built to work with mod_rewrite out of the box, we've noticed that a few users struggle with getting everything to play nicely on their systems. Here are a few things you might try to get it running correctly:
• Make sure that an .htaccess override is allowed: in your httpd.conf, you should have a section that defines a section for each Directory on your server. Make sure the Allo- wOverride is set to All for the correct Directory.
• Make sure you are editing the system httpd.conf rather than a user- or site-specific ht- tpd.conf.
• For some reason or another, you might have obtained a copy of CakePHP without the needed .htaccess files. This sometimes happens because some operating systems treat files that start with '.' as hidden, and don't copy them. Make sure your copy of CakePHP is from the downloads section of the site or our SVN repository.
• Make sure you are loading up mod_rewrite correctly! You should see something like LoadModule rewrite_module libexec/httpd/mod_rewrite.so and AddModule mod_rewrite.c in your httpd.conf.
• If you are installing Cake into a user directory (http://example.com/~myusername/), you'll need to modify the .htaccess file in the base directory of your Cake installation. Just add the line "RewriteBase /~myusername/".
• If for some reason your URLS are suffixed with a long, annoying session ID (http://example.com/posts/?CAKEPHP=4kgj577sgabvnmhjgkdiuy1956if6ska), you might also add "php_flag session.trans_id off" to the .htaccess file at the root of your installation as well.
3.6. Make Sure It's Working
Alright, lets see this baby in action. Depending on which setup you used, you should point your browser to http://www.example.com or http://www.example.com/cake. At this point, you'll be presented with CakePHP's default home, and a message that tells you the status of your current database connection.
Congratulations! You are ready to create your first Cake-based application.
4.1. Database Configuration
Your app/config/database.php file is where your database configuration all takes place. A fresh install doesn't have a database.php, so you'll need to make a copy of database.php.default. Once you've made a copy and renamed it you'll see the follow- ing:
Example 4.1. app/config/database.php
var $default = array('driver' => 'mysql',
'connect' => 'mysql_connect', 'host' => 'localhost', 'login' => 'user', 'password' => 'password', 'database' => 'project_name', 'prefix' => '');
Replace the information provided by default with the database connection information for your application.
One note about the prefix key: the string you enter there will be prepended to any SQL call that Cake makes to your database when working with tables. You define it here once so you don't have to specify it in other places. It also allows you to follow Cake's table naming conventions if you're on a host that only gives you a single database. Note: for HABTM join tables, you only add the prefix once: prefix_apples_bananas, not pre- fix_apples_prefix_bananas.
CakePHP supports the following database drivers:
• mysql
• postgres
• sqlite
• pear-drivername (so you might enter pear-mysql, for example)
• adodb-drivername
The 'connect' key in the $default connection allows you to specify whether or not the data- base connection will be treated as persistent or not. Read the comments in the data- base.php.default file for help on specifying connection types for your database setup.
Your database tables should also follow the following conventions:
• Table names used by Cake should consist of English words in plural, like "users", "au- thors" or "articles". Note that corresponding models have singular names.
• Your tables must have a primary key named 'id'.
• If you plan to relate tables, use foreign keys that look like: 'article_id'. The table name is singular, followed by an underscore, followed by 'id'.
• If you include a 'created' and/or 'modified' column in your table, Cake will automatically populate the field when appropriate.
You'll also notice that there is a $test connection setting included in the database.php file.
Fill out this configuration (or add other similarly formatted configurations) and use it in your application by placing something like:
var $useDbConfig = 'test';
Inside one of your models. You can add any number of additional connection settings in this manner.
4.2. Global Configuration
CakePHP's global configuration can be found inapp/config/core.php. While we really dislike configuration files, it just had to be done. There are a few things you can change here, and the notes on each of these settings can be found within the comments of the core.phpfile.
DEBUG: Set this to different values to help you debug your application as you build it. Spe- cifying this setting to a non-zero value will force Cake to print out the results of pr( ) and de- bug( ) function calls, and stop flash messages from forwarding automatically. Setting it to 2 or higher will result in SQL statements being printed at the bottom of the page.
Also when in debug mode (where DEBUG is set to 1 or higher), Cake will render certain generated error pages, i.e. "Missing Controller," "Missing Action," etc. In production mode, however (where DEBUG is set to 0), Cake renders the "Not Found" page, which can be overridden inapp/views/errors/error404.thtml.
CAKE_SESSION_COOKIE: Change this value to the name of the cookie you'd like to use for user sessions in your Cake app.
CAKE_SECURITY: Change this value to indicate your preferred level of sessions check- ing. Cake will timeout sessions, generate new session ids, and delete old session files based on the settings you provide here. The possible values are:
• high: sessions time out after 10 minutes of inactivity, and session id's are regenerated on each request
• medium: sessions time out after 20 minutes of inactivity
• low: sessions time out after 30 minutes of inactivity
CAKE_SESSION_SAVE: Specify how you'd like session data saved. Possible values are:
• cake: Session data is saved in tmp/ inside your Cake installation
• php: Session data saved as defined in php.ini
• database: Session data saved to database connection defined by the 'default' key.
4.3. Routes Configuration
"Routing" is a pared-down pure-PHP mod_rewrite-alike that can map URLs to controller/ac- tion/params and back. It was added to Cake to make pretty URLs more configurable and to divorce us from the mod_rewrite requirement. Using mod_rewrite, however, will make your address bar look much more tidy.
Routes are individual rules that map matching URLs to specific controllers and actions.
Routes are configured in theapp/config/routes.phpfile. They are set-up like this:
Example 4.2. Route Pattern
<?php
$Route->connect ( 'URL',
array('controller'=>'controllername', 'action'=>'actionname', 'firstparam') );
?>
Where:
• URL is the regular expression Cake URL you wish to map,
• controllername is the name of the controller you wish to invoke,
• actionname is the name of the controller's action you wish to invoke,
• and firstparam is the value of the first parameter of the action you've specified.
Any parameters following firstparam will also be passed as parameters to the controller ac- tion.
The following example joins all the urls in /blog to the BlogController. The default action will be BlogController::index().
Example 4.3. Route Example
<?php
$Route->connect ('/blog/:action/*', array('controller'=>'Blog', 'action'=>'index'));
?>
A URL like /blog/history/05/june can then be handled like this:
Example 4.4. Route Handling in a Controller
<?php
class BlogController extends AppController {
function history ($year, $month=null)
{
// .. Display appropriate content }
}
?>
The 'history' from the URL was matched by :action from the Blog's route. URL elements matched by * are passed to the active controller's handling method as parameters, hence the $year and $month. Called with URL /blog/history/05, history() would only be passed one parameter, 05.
The following example is a default CakePHP route used to set up a route for PagesCon- troller::display('home'). Home is a view which can be overridden by creating the file / app/views/pages/home.thtml.
Example 4.5. Setting the Default Route
<?php
$Route->connect ('/', array('controller'=>'Pages', 'action'=>'display', 'home'));
?>
4.4. Advanced Routing Configuration: Admin Routing and Webservices
There are some settings in /app/config/core.php you can take advantage of in order to or- ganize your application and craft URLs that make the most sense to you and your users.
The first of these is admin routing. If your application has a ProductsController as well as a NewsController, you might want to set up some special URLs so users with administrative privileges can access special actions in those controllers. To keep the URLs nice and easy to read, some people prefer /admin/products/add and /admin/news/post to something like / products/adminAdd and /news/adminPost.
To enable this, first, uncomment the CAKE_ADMIN line in your /app/config/core.php file.
The default value of CAKE_ADMIN is 'admin', but you can change it to whatever you like.
Remember this string, because you'll need to prepend it to your administrative actions in your controller. So, admin actions in this case would be named admin_actionName().
Here's some examples of desired URLs and possible CAKE_ADMIN and controller action settings:
/admin/products/add CAKE_ADMIN = 'admin'
name of action in ProductsController = 'admin_add()'
/superuser/news/post CAKE_ADMIN = 'superuser'
name of action in NewsController = 'superuser_post()'
/admin/posts/delete CAKE_ADMIN = 'admin'
name of action in PostsController = 'admin_delete()'
Using admin routes allows you to keep your logic organized while making the routing very easy to accomplish.
Note
Please note that enabling admin routes or using them does not enable any sort of authentica- tion or security. You'll need implement those yourself.
Similarly, you can enable Cake's webservices routing to make easier there as well. Have a controller action you'd like to expose as a webservice? First, set WEBSERVICES in / app/config/core.php to 'on'. This enables some automatic routing somewhat similar to ad- min routing, except that a certain set of route prefixes are enabled:
• rss
• xml
• rest
• soap
• xmlrpc
What this does is allows you to provide an alternate views that will automatically be avail- able at /rss/controllerName/actionName or /soap/controllerName/actionName. This allows you to create a single action that can have two views: one for normal HTML viewiers, and another for webservices users. By doing this, you can easily allow much of the functionality of your application to be available via webservices.
For example, let's say I have some logic in my application that tells users who is on the phone in my office. I already have a HTML view for this data, but I want to offer it in XML so it can be used in a desktop widget or handheld application. First I need to enable Cake's webservice routing:
Example 4.6. /app/config/core.php (partial)
/**
* The define below is used to turn cake built webservices
* on or off. Default setting is off.
*/
define('WEBSERVICES', 'on');
Next, I can structure the logic in my controller just as I normally would:
Example 4.7. messages_controller.php
<?php
class PhonesController extends AppController {
function doWhosOnline() {
// this action is where we do all the work of seeing who's on the phone...
// If I wanted this action to be available via Cake's xml
webservices route,
// I'd need to include a view at /app/views/posts/xml/do_whos_online.thtml.
// Note: the default view used here is at /app/views/layouts/xml/default.thtml.
// If a user requests /phones/doWhosOnline, they will get an HTML version.
// If a user requests /xml/phones/doWhosOnline, they will get the XML version.
} }
?>
4.5. (Optional) Custom Inflections Configura- tion
Cake's naming conventions can be really nice - you can name your model Box, your con- troller Boxes, and everything just works out. There are occasions (especially for our non- english speaking friends) where you may run into situations where Cake's inflector (the class that pluralizes, singularizes, camelCases, and under_scores) might not work as you'd like. If Cake won't recognize your Foci or Fish, editing the custom inflections configuration file is where you'll need to go.
Found at /app/config/inflections.php is a list of Cake variables you can use to adjust the pluralization, singularization of classnames in Cake, along with definining terms that shouldn't be inflected at all (like Fish and Deer, for you outdoorsman cakers) along with ir- regularities.
Follow the notes inside the file to make adjustments, or use the examples in the file by un- commenting them. You may need to know a little regex before diving in.
5.1. Cake's Scaffolding is Pretty Cool
So cool that you'll want to use it in production apps. Now, we think its cool, too, but please realize that scaffolding is... well... just scaffolding. It's a bunch of stuff you throw up real quick during the beginning of a project in order to get started. It isn't meant to be com- pletely flexible. So, if you find yourself really wanting to customize your logic and your views, its time to pull your scaffolding down in order to write some code.
Scaffolding is a great way of getting the early parts of developing a web application started.
Early database schemas are volatile and subject to change, which is perfectly normal in the early part of the design process. This has a downside: a web developer hates creating forms that never will see real use. To reduce the strain on the developer, scaffolding has been included in Cake. Scaffolding analyzes your database tables and creates standard lists with add, delete and edit buttons, standard forms for editing and standard views for in- specting a single item in the database. To add scaffolding to your application, in the con- troller, add the $scaffold variable:
<?php
class CategoriesController extends AppController {
var $scaffold;
}
?>
One important thing to note about scaffold: it expects that any field name that ends with _id is a foreign key to a table which has a name that precedes the underscore. So, for ex- ample, if you have nested categories, you'd probably have a column called parent_id. With this release, it would be best to call this parentid. Also, when you have a foreign key in your table (e.g. titles table has category_id), and you have associated your models appropriately (see Understanding Associations, 6.2), a select box will be automatically populated with the rows from the foreign table (category) in the show/edit/new views. To set which field in the foreign table is shown, set the $displayField variable in the foreign model. To continue our example of a category having a title:
<?php
class Title extends AppModel {
var $name = 'Title';
var $displayField = 'title';
}
?>
5.2. Customizing Scaffold Views
If you're looking for something a little different in your scaffolded views, you can create them yourself. We still don't recommend using this technique for production applications, but such a customization may be extremely useful for prototyping iterations.
If you'd like to change your scaffolding views, you'll need to supply your own:
Example 5.1. Custom Scaffolding Views for a Single Controller
Custom scaffolding views for a PostsController should be placed like so:
/app/views/posts/scaffold/index.scaffold.thtml /app/views/posts/scaffold/show.scaffold.thtml /app/views/posts/scaffold/edit.scaffold.thtml /app/views/posts/scaffold/new.scaffold.thtml
Example 5.2. Custom Scaffolding Views for an Entire Application
Custom scaffolding views for all controllers should be placed like so:
/app/views/scaffold/index.scaffold.thtml /app/views/scaffold/show.scaffold.thtml /app/views/scaffold/edit.scaffold.thtml /app/views/scaffold/new.scaffold.thtml
If you find yourself wanting to change the controller logic at this point, it's time to take the scaffolding down from your application and start building it.
One feature you might find helpful is Cake's code generator: Bake. Bake allows you to gen- erate a coded version of scaffolded code you can then move on to modify and customize as your application requires.
6.1. What is a model?
What is a model? It is the M of the MVC pattern.
What does it do? It separates domain logic from the presentation, isolating application lo- gic.
A model is generally an access point to the database, and more specifically, to a certain ta- ble in the database. By default, each model uses the table who's name is plural of its own, i.e. a 'User' model uses the 'users' table. Models can also contain data validation rules, as- sociation information, and methods specific to the table it uses. Here's what a simple User model might look like in Cake:
Example 6.1. Example User Model, saved in /app/models/user.php
<?php
//AppModel gives you all of Cake's Model functionality class User extends AppModel
{
// Its always good practice to include this variable.
var $name = 'User';
// This is used for validation, see Chapter 11.
var $validate = array();
// You can also define associations.
// See section 6.3 for more information.
var $hasMany = array('Image' =>
array('className' => 'Image') );
// You can also include your own functions:
function makeInactive($uid) {
//Put your own logic here...
} }
?>
6.2. Model Functions
From a PHP view, models are classes extending the AppModel class. The AppModel class is originally defined in the cake/ directory, but should you want to create your own, place it inapp/app_model.php. It should contain methods that are shared between two or more models. It itself extends the Model class which is a standard Cake library defined incake/
libs/model.php.
Important
While this section will treat most of the often-used functions in Cake's Model, it's important to
remember to use http://api.cakephp.org for a full reference.
6.2.1. User-Defined Functions
An example of a table-specific method in the model is a pair of methods for hiding/unhiding posts in a blog.
Example 6.2. Example Model Functions
<?php
class Post extends AppModel {
var $name = 'Post';
function hide ($id=null) {
if ($id) {
$this->id = $id;
$this->saveField('hidden', '1');
} }
function unhide ($id=null) {
if ($id) {
$this->id = $id;
$this->saveField('hidden', '0');
} } }
?>
6.2.2. Retrieving Your Data
Below are a few of the standard ways of getting to your data using a model:
findAll($conditions, $fields, $order, $limit, $page, $recursive);
string $conditions;
array $fields;
string $order;
int $limit;
int $page;
int $recursive;
Returns the specified fields up to $limit records matching $conditions (if any), start listing from page $page (default is page 1). $conditions should look like they would in an SQL statement: $conditions = "race = 'wookie' AND thermal_detonators > 3", for example.
When the $recursive option is set to an integer value greater than 1, the findAll() operation will make an effort to return the models associated to the ones found by the findAll(). If your property has many owners who in turn have many contracts, a recursive findAll() on your Property model will return those associated models.
find($conditions, $fields, $order, $recursive);
string $conditions;
array $fields;
string $order;
int $recursive;
Returns the specified (or all if not specified) fields from the first record that matches
$conditions.
When the $recursive option is set to an integer value between 1 and 3, the find() operation will make an effort to return the models associated to the ones found by the find(). The re- cursive find can go up to three levels deep. If your property has many owners who in turn have many contracts, a recursive find() on your Property model will return up to three levels deep of associated models.
findAllBy<fieldName>($value);
string $value;
These magic functions can be used as a shortcut to search your tables for a row given a certain field, and a certain value. Just tack on the name of the field you wish to search, and CamelCase it. Examples (as used in a Controller) might be:
$this->Post->findByTitle('My First Blog Post');
$this->Author->findByLastName('Rogers');
$this->Property->findAllByState('AZ');
$this->Specimen->findAllByKingdom('Animalia');
The returned result is an array formatted just as would be from find() or findAll().
findNeighbours($conditions, $field, $value);
string $conditions;
array $field;
string $value;
Returns an array with the neighboring models (with only the specified fields), specified by
$field and $value, filtered by the SQL conditions, $conditions.
This is useful in situations where you want 'Previous' and 'Next' links that walk users through some ordered sequence through your model entries. It only works for numeric and date based fields.
class ImagesController extends AppController {
function view($id) {
// Say we want to show the image...
$this->set('image', $this->Image->find("id = $id");
// But we also want the previous and next images...
$this->set('neighbours', $this->Image->findNeighbours(null, 'id', $id);
}
}
This gives us the full $image['Image'] array, along with $neighbours['prev']['Image']['id'] and
$neighbours['next']['Image']['id'] in our view.
field($name, $conditions, $order);
string $name;
string $conditions;
string $order;
Returns as a string a single field from the first record matched by $conditions as ordered by $order.
findCount($conditions);
string $conditions;
Returns the number of records that match the given conditions.
generateList($conditions, $order, $limit, $keyPath, $valuePath);
string $conditions;
string $order;
int $limit;
string $keyPath;
string $valuePath;
This function is a shortcut to getting a list of key value pairs - especially handy for creating a html select tag from a list of your models. Use the $conditions, $order, and $limit para- meters just as you would for a findAll() request. The $keyPath and $valuePath are where you tell the model where to find the keys and values for your generated list. For example, if you wanted to generate a list of roles based on your Role model, keyed by their integer ids, the full call might look something like:
$this->set(
'Roles',
$this->Role->generateList(null, 'role_name ASC', null, '{n}.Role.id', '{n}.Role.role_name')
);
//This would return something like:
array(
'1' => 'Account Manager', '2' => 'Account Viewer', '3' => 'System Manager', '4' => 'Site Visitor' );
read($fields, $id);
string $fields;
string $id;
Use this function to get the fields and their values from the currently loaded record, or the
record specified by $id.
Please note that read() operations will only fetch the first level of associated models re- gardless of the value of $recursive in the model. To gain additional levels, use find() or fin- dAll().
query($query);
string $query;
execute($query);
string $query;
Custom SQL calls can be made using the model's query() and execute() methods. The dif- ference between the two is that query() is used to make custom SQL queries (the results of which are returned), and execute() is used to make custom SQL commands (which require no return value).
Example 6.3. Custom Sql Calls with query()
<?php
class Post extends AppModel {
var $name = 'Post';
function posterFirstName() {
$ret = $this->query("SELECT first_name FROM posters_table WHERE poster_id = 1");
$firstName = $ret[0]['first_name'];
return $firstName;
} }
?>
6.2.3. Complex Find Conditions (using arrays)
Most of the model's finder calls involve passing sets of conditions in one way or another.
The simplest approach to this is to use a WHERE clause snippet of SQL, but if you need more control, you can use arrays. Using arrays is clearer and easier to read, and also makes it very easy to build queries. This syntax also breaks out the elements of your query (fields, values, operators, etc.) into discreet, manipulatable parts. This allows Cake to gen- erate the most efficient query possible, ensure proper SQL syntax, and properly escape each individual part of the query.
At it's most basic, an array-based query looks like this:
Example 6.4. Basic find conditions array usage example:
$conditions = array("Post.title" => "This is a post");
//Example usage with a model:
$this->Post->find($conditions);
The structure is fairly self-explanatory: it will find any post where the title matches the string
"This is a post". Note that we could have used just "title" as the field name, but when build- ing queries, it is good practice to always specify the model name, as it improves the clarity of the code, and helps prevent collisions in the future, should you choose to change your schema. What about other types of matches? These are equally simple. Let's say we wanted to find all the posts where the title is not "This is a post":
array("Post.title" => "<> This is a post")
All that was added was '<>' before the expression. Cake can parse out any valid SQL com- parison operator, including match expressions using LIKE, BETWEEN, or REGEX, as long as you leave a space between the operator an the expression or value. The one exception here is IN (...)-style matches. Let's say you wanted to find posts where the title was in a given set of values:
array("Post.title" => array("First post", "Second post", "Third post"))
Adding additional filters to the conditions is as simple as adding additional key/value pairs to the array:
array (
"Post.title" => array("First post", "Second post", "Third post"),
"Post.created" => "> " . date('Y-m-d', strtotime("-2 weeks")) )
By default, Cake joins multiple conditions with boolean AND; which means, the snippet above would only match posts that have been created in the past two weeks, and have a title that matches one in the given set. However, we could just as easily find posts that match either condition:
array ("or" =>
array (
"Post.title" => array("First post", "Second post", "Third post"),
"Post.created" => "> " . date('Y-m-d', strtotime("-2 weeks"))
) )
Cake accepts all valid SQL boolean operations, including AND, OR, NOT, XOR, etc., and they can be upper or lower case, whichever you prefer. These conditions are also infinitely nestable. Let's say you had a hasMany/belongsTo relationship between Posts and Au- thors, which would result in a LEFT JOIN on the find done on Post. Let's say you wanted to find all the posts that contained a certain keyword or were created in the past two weeks, but you want to restrict your search to posts written by Bob:
array
("Author.name" => "Bob", "or" => array (
"Post.title" => "LIKE %magic%",
"Post.created" => "> " . date('Y-m-d', strtotime("-2 weeks")
) )
6.2.4. Saving Your Data
To save data to your model, you need to supply it with the data you wish to save. The data handed to the save() method should be in the following form:
Array (
[ModelName] => Array (
[fieldname1] => 'value' [fieldname2] => 'value' )
)
In order to get your data posted to the controller in this manner, it's easiest just to use the HTML Helper to do this, because it creates form elements that are named in the way Cake expects. You don't need to use it however: just make sure your form elements have names that look like data[Modelname][fieldname]. Using $html->input('Model/fieldname') is the easiest, however.
Data posted from forms is automatically formatted like this and placed in $this->data inside of your controller, so saving your data from web forms is a snap. An edit function for a property controller might look something like the following:
function edit($id) {
//Note: The property model is automatically loaded for us at
$this->Property.
// Check to see if we have form data...
if (empty($this->data)) {
$this->Property->id = $id;
$this->data = $this->Property->read();//populate the form fields with the current row
} else {
// Here's where we try to save our data. Automagic validation checking
if ($this->Property->save($this->data['Property'])) {
//Flash a message and redirect.
$this->flash('Your information has been saved.', '/properties/view/'.$this->data['Property']['id'], 2);
}
//if some fields are invalid or save fails the form will render
} }
Notice how the save operation is placed inside a conditional: when you try to save data to your model, Cake automatically attempts to validate your data using the rules you've provided. To learn more about data validation, see Chapter 12. If you do not want save() to try to validate your data, use save($data, false).
Other useful save functions:
del($id, $cascade);
string $id;
boolean $cascade;
Deletes the model specified by $id, or the current id of the model.
If this model is associated to other models, and the 'dependent' key has been set in the as- sociation array, this method will also delete those associated models if $cascade is set to true.
Returns true on success.
saveField($name, $value);
string $name;
string $value;
Used to save a single field value.
getLastInsertId();
;
Returns the ID of the most recently created record.
6.2.5. Model Callbacks
We've added some model callbacks that allow you to sneak in logic before or after certain model operations. To gain this functionality in your applications, use the parameters provided and override these functions in your Cake models.
beforeFind($conditions);
string $conditions;
The beforeFind() callback is executed just before a find operation begins. Place any pre- find logic in this method. When you override this in your model, return true when you want the find to execute, and false when you want it to abort.
afterFind($results);
array $results;
Use this callback to modify results that have been returned from a find operation, or per- form any other post-find logic. The parameter for this function is the returned results from the model's find operation, and the return value is the modified results.
beforeValidate();
;
Use this callback to modify model data before it is validated. It can also be used to add ad- ditional, more complex validation rules, using Model::invalidate(). In this context, model data is accessible via $this->data. This function must also return true, otherwise save() ex- ecution will abort.
beforeSave();
;
Place any pre-save logic in this function. This function executes immediately after model data has been validated (assuming it validates, otherwise the save() call aborts, and this callback will not execute), but before the data is saved. This function should also return true if you want the save operation to continue, and false if you want to abort.
One usage of beforeSave might be to format time data for storage in a specifc database engine:
// Date/time fields created by HTML Helper:
// This code would be seen in a view
$html->dayOptionTag('Event/start');
$html->monthOptionTag('Event/start');
$html->yearOptionTag('Event/start');
$html->hourOptionTag('Event/start');
$html->minuteOptionTag('Event/start');
/*=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-*/
// Model callback functions used to stitch date // data together for storage
// This code would be seen in the Event model:
function beforeSave() {
$this->data['Event']['start'] = $this->_getDate('Event', 'start');
return true;
}
function _getDate($model, $field) {
return date('Y-m-d H:i:s', mktime(
intval($this->data[$model][$field . '_hour']), intval($this->data[$model][$field . '_min']), null,
intval($this->data[$model][$field . '_month']), intval($this->data[$model][$field . '_day']), intval($this->data[$model][$field . '_year'])));
}
afterSave();
;
Place any logic that you want to be executed after every save in this callback method.
beforeDelete();
;
Place any pre-deletion logic in this function. This function should return trueif you want the deletion to continue, andfalse if you want to abort.
afterDelete();
;
Place any logic that you want to be executed after every deletion in this callback method.
6.3. Model Variables
When creating your models, there are a number of special variables you can set in order to gain access to Cake functionality:
$primaryKey
If this model relates to a database table, and the table's primary key is not named 'id', use this variable to tell Cake the name of the primary key.
$recursive
This sets the number of levels you wish Cake to fetch associated model data in find() and findAll() operations.
Imagine you have Groups which have many Users which in turn have many Articles.
Table 6.1. Model::recursive options
$recursive = 0 Cake fetches Group data
$recursive = 1 Cake fetches a Group and its associated Users
$recursive = 2 Cake fetches a Group, its associated Users, and
the Users' associated Articles
$transactional
Tells Cake whether or not to enable transactions for this model (i.e. begin/commit/rollback).
Set to a boolean value. Only available for supporting databases.
$useTable
If the database table you wish to use isn't the plural form of the model name (and you don't wish to change the table name), set this variable to the name of the table you'd like this model to use.
$validate
An array used to validate the data passed to this model. See chapter 12.
$useDbConfig
Remember the database settings you can configure in /app/config/database.php?
Use this variable to switch between them - just use the name of the database connection variable you've created in your database configuration file. The default is, you guessed it, 'default'.
6.4. Associations
6.4.1. Introduction
One of the most powerful features of CakePHP is the relational mapping provided by the model. In CakePHP, the links between tables are handled through associations. Associ- ations are the glue between related logical units.
There are four types of associations in CakePHP:
• hasOne
• hasMany
• belongsTo
• hasAndBelongsToMany
When associations between models have been defined, Cake will automagically fetch models related to the model you are working with. For example, if a Post model is related to an Author model using a hasMany association, making a call to $this->Post->findAll() in a controller will fetch Post records, as well as all the Author records they are related to.
To use the association correctly it is best to follow the CakePHP naming conventions (see Appendix B). If you use CakePHP's naming conventions, you can use scaffolding to visual- ize your application data, because scaffolding detects and uses the associations between models. Of course you can always customize model associations to work outside of Cake's naming conventions, but we'll save those tips for later. For now, let's just stick to the con- ventions. The naming conventions that concern us here are the foreign keys, model names, and table names.
Here's a review of what Cake expects for the names of these different elements: (see Ap- pendix B for more information on naming)
• Foreign Keys: [singular model name]_id. For example, a foreign key in the "authors" ta- ble pointing back to the Post a given Author belongs to would be named "post_id".
• Table Names: [plural object name]. Since we'd like to store information about blog posts and their authors, the table names are "posts" and "authors", respectively.
• Model Names: [CamelCased, singular form of table name]. The model name for the
"posts" table is "Post", and the model name for the "authors" table is "Author".
Note
CakePHP's scaffolding expects your associations to be in the same order as your colums. So if I have an Article that belongsTo three other models (Author, Editor, and Publisher), I would need three keys: author_id, editor_id, and publisher_id. Scaffolding would expect your associ- ations in the same order as the keys in the table (e.g. first Author, second Editor, lastly Pub- lisher).
In order to illustrate how some of these associations work, let's continue using the blog ap-
plication as an example. Imagine that we're going to create a simple user management system for the blog. I suppose it goes without saying we'll want to keep track of Users, but we'd also like each user to have an associated Profile (User hasOne Profile). Users will also be able to create comments and remain associated to them (User hasMany Com- ments). Once we have the user system working, we'll move to allowing Posts to be related to Tag objects using the hasAndBelongsToMany relationship (Post hasAndBelongsTo- Many Tags).
6.4.2. Defining and Querying with hasOne
In order to set up this association, we'll assume that you've already created the User and Profile models. To define the hasOne assocation between them, we'll need to add an array to the models to tell Cake how they relate. Here's how that looks like:
Example 6.5. /app/models/user.php hasOne
<?php
class User extends AppModel {
var $name = 'User';
var $hasOne = array('Profile' =>
array('className' => 'Profile', 'conditions' => '',
'order' => '', 'dependent' => true, 'foreignKey' => 'user_id' )
);
}
?>
The $hasOne array is what Cake uses to build the association between the User and Pro- file models. Each key in the array allows you to further configure the association:
• className (required): the classname of the model you'd like to associate For our example, we want to specify the 'Profile' model class name.
• conditions: SQL condition fragments that define the relationship
We could use this to tell Cake to only associate a Profile that has a green header, if we wished. To define conditions like this, you'd specify a SQL conditions fragment as the value for this key: "Profile.header_color = 'green'".
• order: the ordering of the associated models
If you'd like your associated models in a specific order, set the value for this key using an SQL order predicate: "Profile.name ASC", for example.
• dependent: if set to true, the associated model is destroyed when this one is.
For example, if the "Cool Blue" profile is associated to "Bob", and I delete the user "Bob", the profile "Cool Blue" will also be deleted.
• foreignKey: the name of the foreign key that points to the associated model.
This is here in case you're working with a database that doesn't follow Cake's naming conventions.
Now, when we execute find() or findAll() calls using the Profile model, we should see our associated User model there as well:
$user = $this->User->read(null, '25');
print_r($user);
//output:
Array (
[User] => Array (
[id] => 25
[first_name] => John [last_name] => Anderson [username] => psychic [password] => c4k3roxx )
[Profile] => Array (
[id] => 4
[name] => Cool Blue
[header_color] => aquamarine [user_id] = 25
) )
6.4.3. Defining and Querying with belongsTo
Now that a User can see its Profile, we'll need to define an association so Profile can see its User. This is done in Cake using the belongsTo assocation. In the Profile model, we'd do the following:
Example 6.6. /app/models/profile.php belongsTo
<?php
class Profile extends AppModel {
var $name = 'Profile';
var $belongsTo = array('User' =>
array('className' => 'User', 'conditions' => '', 'order' => '',
'foreignKey' => 'user_id' )
);
}
?>
The $belongsTo array is what Cake uses to build the association between the User and Profile models. Each key in the array allows you to further configure the association:
• className (required): the classname of the model you'd like to associate For our example, we want to specify the 'User' model class name.
• conditions: SQL condition fragments that define the relationship
We could use this to tell Cake to only associate a User that is active. You would do this by setting the value of the key to be "User.active = '1'", or something similar.
• order: the ordering of the associated models
If you'd like your associated models in a specific order, set the value for this key using an SQL order predicate: "User.last_name ASC", for example.
• foreignKey: the name of the foreign key that points to the associated model.
This is here in case you're working with a database that doesn't follow Cake's naming conventions.
Now, when we execute find() or findAll() calls using the Profile model, we should see our associated User model there as well:
$profile = $this->Profile->read(null, '4');
print_r($profile);
//output:
Array (
[Profile] => Array (
[id] => 4
[name] => Cool Blue
[header_color] => aquamarine [user_id] = 25
)
[User] => Array (
[id] => 25
[first_name] => John [last_name] => Anderson [username] => psychic [password] => c4k3roxx )
)
6.4.4. Defining and Querying with hasMany
Now that User and Profile models are associated and working properly, let's build our sys- tem so that User records are associated to Comment records. This is done in the User model like so:
Example 6.7. /app/models/user.php hasMany
<?php
class User extends AppModel {
var $name = 'User';
var $hasMany = array('Comment' =>
array('className' => 'Comment', 'conditions' =>
'Comment.moderated = 1',
'order' => 'Comment.created DESC',
