Welcome to The Cookbook

1. You visit the site and notice an error, something that is incomplete, something that hasn't been covered at all, or something that just isn't worded to your liking.
2. Log in to Cookbook using your Bakery account.
3. Submit additions/edits for review using valid, semantic HTML.
4. Check back in the next day or so to see your changes approved.
5. Please review the guidelines for submitting to the Cookbook to ensure consistency.

Email John David Anderson (docs at cakephp dot org) or on IRC (#cakephp on freenode as _psychic_) to discuss any translation efforts you would like to participate in.

Translator tips:

• Browse and edit in the language you want the content to be translated to - otherwise you won't see what has already been translated.
• Feel free to dive right in if your chosen language already exists on the book.
• Use the to do list (top right) to see where attention is needed for your language.
• Use Informal Form.
• Translate both the content and the title at the same time.
• Do compare to the English content before submitting a correction (if you correct something, but don't integrate an 'upstream' change your submission won't be accepted).
• If you need to write an English term, wrap it in <em> tags. E.g. "asdf asdf Controller asdf" or "asdf asdf Kontroller (Controller) asfd" as appropriate.
• Do not edit a section with a pending change.
• Do not use html entities for accented characters, the book uses UTF-8.
• Do not significantly change the markup (HTML) or add new content - If the original content is missing some info, submit an edit for that first.

We're committed to making the documentation for CakePHP better than it has ever been. We hope you'll join us by using the Cookbook and giving back to a project that we've all benefited so much from.

Welcome to the Cookbook, the manual for the CakePHP web application framework that makes developing a piece of cake!

This manual assumes that you have a general understanding of PHP and a basic understanding of object-oriented programming (OOP). Different functionality within the framework makes use of different technologies — such as SQL, JavaScript, and XML — and this manual does not attempt to explain those technologies, only how they are used in context.

CakePHP is a free, open-source, rapid development framework for PHP. It’s a foundational structure for programmers to create web applications. Our primary goal is to enable you to work in a structured and rapid manner–without loss of flexibility.

CakePHP takes the monotony out of web development. We provide you with all the tools you need to get started coding what you really need to get done: the logic specific to your application. Instead of reinventing the wheel every time you sit down to a new project, check out a copy of CakePHP and get started with the real guts of your application.

CakePHP has an active developer team and community, bringing great value to the project. In addition to keeping you from wheel-reinventing, using CakePHP means your application’s core is well tested and is being constantly improved.

Here’s a quick list of features you’ll enjoy when using CakePHP:

• Active, friendly community
• Flexible licensing
• Compatible with versions 4 and 5 of PHP
• Integrated CRUD for database interaction
• Application scaffolding
• Code generation
• MVC architecture
• Request dispatcher with clean, custom URLs and routes
• Built-in validation
• Fast and flexible templating (PHP syntax, with helpers)
• View Helpers for AJAX, JavaScript, HTML Forms and more
• Email, Cookie, Security, Session, and Request Handling Components
• Flexible ACL
• Data Sanitization
• Flexible Caching
• Localization
• Works from any web site directory, with little to no Apache configuration involved

http://www.cakephp.org

The Official CakePHP website is always a great place to visit. It features links to oft-used developer tools, screencasts, donation opportunities, and downloads.

http://book.cakephp.org

This manual should probably be the first place you go to get answers. As with many other open source projects, we get new folks regularly. Try your best to answer your questions on your own first. Answers may come slower, but will remain longer–and you'll also be lightening our support load. Both the manual and the API have an online component.

http://bakery.cakephp.org

The CakePHP Bakery is a clearing house for all things CakePHP. Check it out for tutorials, case studies, and code examples. Once you’re acquainted with CakePHP, log on and share your knowledge with the community and gain instant fame and fortune.

http://api.cakephp.org/1.2

Straight to the point and straight from the core developers, the CakePHP API (Application Programming Interface) is the most comprehensive documentation around for all the nitty gritty details of the internal workings of the framework. Its a straight forward code reference, so bring your propeller hat.

http://www.cakeforge.org

CakeForge is another developer resource you can use to host your CakePHP projects to share with others. If you’re looking for (or want to share) a killer component or a praiseworthy plugin, check out CakeForge.

http://api.cakephp.org/tests

If you ever feel the information provided in the API is not sufficient, check out the code of the test cases provided with CakePHP 1.2. They can serve as practical examples for function and data member usage for a class. To get the core test cases you need to download a nightly package or do a svn branch checkout. The test cases will be located under

cake/tests/cases

1. cake/tests/cases

#cakephp @ irc.freenode.net

If you’re stumped, give us a holler in the CakePHP IRC channel. Someone from the development team is usually there, especially during the daylight hours for North and South America users. We’d love to hear from you, whether you need some help, want to find users in your area, or would like to donate your brand new sports car.

http://groups.google.com/group/cake-php

CakePHP also has a very active Google Group. It can be a great resource for finding archived answers, frequently asked questions, and getting answers to immediate problems.

CakePHP follows the MVC software design pattern. Programming using MVC separates your application into three main parts:

1. The Model represents the application data
2. The View renders a presentation of model data
3. The Controller handles and routes requests made by the client

Figure: 1: A Basic MVC Request

Figure: 1 shows an example of a bare-bones MVC request in CakePHP. To illustrate, assume a client named "Ricardo" just clicked on the “Buy A Custom Cake Now!” link on your application’s home page.

• Ricardo clicks the link pointing to http://www.example.com/cakes/buy, and his browser makes a request to your web server.
• The dispatcher checks the request URL (/cakes/buy), and hands the request to the correct controller.
• The controller performs application specific logic. For example, it may check to see if Ricardo has logged in.
• The controller also uses models to gain access to the application’s data. Models usually represent database tables, but they could also represent LDAP entries, RSS feeds, or files on the system. In this example, the controller uses a model to fetch Ricardo’s last purchases from the database.
• Once the controller has worked its magic on the data, it hands it to a view. The view takes this data and gets it ready for presentation to the client. Views in CakePHP are usually in HTML format, but a view could just as easily be a PDF, XML document, or JSON object depending on your needs.
• Once the view has used the data from the controller to build a fully rendered view, the content of that view is returned to Ricardo’s browser.

Almost every request to your application will follow this basic pattern. We'll add some details later on which are specific to CakePHP, so keep this in mind as we proceed.

Why use MVC? Because it is a tried and true software design pattern that turns an application into a maintainable, modular, rapidly developed package. Crafting application tasks into separate models, views, and controllers makes your application very light on its feet. New features are easily added, and new faces on old features are a snap. The modular and separate design also allows developers and designers to work simultaneously, including the ability to rapidly prototype. Separation also allows developers to make changes in one part of the application without affecting others.

If you've never built an application this way, it takes some time getting used to, but we're confident that once you've built your first application using CakePHP, you won't want to do it any other way.

The CakePHP framework provides a robust base for your application. It can handle every aspect, from the user’s initial request all the way to the final rendering of a web page. And since the framework follows the principles of MVC, it allows you to easily customize and extend most aspects of your application.

The framework also provides a basic organizational structure, from filenames to database table names, keeping your entire application consistent and logical. This concept is simple but powerful. Follow the conventions and you’ll always know exactly where things are and how they’re organized.

CakePHP features Controller, Model, and View classes, but it also features some additional classes and objects that make development in MVC a little quicker and more enjoyable. Components, Behaviors, and Helpers are classes that provide extensibility and reusability to quickly add functionality to the base MVC classes in your applications. Right now we’ll stay at a higher level, so look for the details on how to use these tools later on.

A Component is a class that aids in controller logic. If you have some logic you want to share between controllers (or applications), a component is usually a good fit. As an example, the core EmailComponent class makes creating and sending emails a snap. Rather than writing a controller method in a single controller that performs this logic, you can package the logic so it can be shared.

Controllers are also fitted with callbacks. These callbacks are available for your use, just in case you need to insert some logic between CakePHP’s core operations. Callbacks available include:

• beforeFilter(), executed before any controller action logic
• beforeRender(), executed after controller logic, but before the view is rendered
• afterFilter(), executed after all controller logic, including the view render. There may be no difference between afterRender() and afterFilter() unless you’ve manually made a call to render() in your controller action and have included some logic after that call.

A Helper is a class that aids in view logic. Much like a component used among controllers, helpers allow presentational logic to be accessed and shared between views. One of the core helpers, AjaxHelper, makes Ajax requests within views much easier.

Most applications have pieces of view code that are used repeatedly. CakePHP facilitates view code reuse with layouts and elements. By default, every view rendered by a controller is placed inside a layout. Elements are used when small snippets of content need to be reused in multiple views.

Similarly, Behaviors work as ways to add common functionality between models. For example, if you store user data in a tree structure, you can specify your User model as behaving like a tree, and gain free functionality for removing, adding, and shifting nodes in your underlying tree structure.

Models also are supported by another class called a DataSource. DataSources are an abstraction that enable models to manipulate different types of data consistently. While the main source of data in a CakePHP application is often a database, you might write additional DataSources that allow your models to represent RSS feeds, CSV files, LDAP entries, or iCal events. DataSources allow you to associate records from different sources: rather than being limited to SQL joins, DataSources allow you to tell your LDAP model that it is associated to many iCal events.

Just like controllers, models are featured with callbacks as well:

• beforeFind()
• afterFind()
• beforeValidate()
• beforeSave()
• afterSave()
• beforeDelete()
• afterDelete()

The names of these methods should be descriptive enough to let you know what they do. You can find the details in the models chapter.

Controllers, helpers and models each have a parent class you can use to define application-wide changes. AppController (located at /app/app_controller.php), AppHelper (located at /app/app_helper.php) and AppModel (located at /app/app_model.php) are great places to put methods you want to share between all controllers, helpers or models.

Although they aren’t classes or files, routes play a role in requests made to CakePHP. Route definitions tell CakePHP how to map URLs to controller actions. The default behavior assumes that the URL “/controller/action/var1/var2” maps to Controller::action($var1, $var2), but you can use routes to customize URLs and how they are interpreted by your application.

Some features in an application merit packaging as a whole. A plugin is a package of models, controllers and views that accomplishes a specific purpose that can span multiple applications. A user management system or a simplified blog might be a good fit for CakePHP plugins.

We’ve covered the basic ingredients in CakePHP, so let’s look at how objects work together to complete a basic request. Continuing with our original request example, let’s imagine that our friend Ricardo just clicked on the “Buy A Custom Cake Now!” link on a CakePHP application’s landing page.

Figure: 2. Typical Cake Request.

Black = required element, Gray = optional element, Blue = callback

1. Ricardo clicks the link pointing to http://www.example.com/cakes/buy, and his browser makes a request to your web server.
2. The Router parses the URL in order to extract the parameters for this request: the controller, action, and any other arguments that will affect the business logic during this request.
3. Using routes, a request URL is mapped to a controller action (a method in a specific controller class). In this case, it’s the buy() method of the CakesController. The controller’s beforeFilter() callback is called before any controller action logic is executed.
4. The controller may use models to gain access to the application’s data. In this example, the controller uses a model to fetch Ricardo’s last purchases from the database. Any applicable model callbacks, behaviors, and DataSources may apply during this operation. While model usage is not required, all CakePHP controllers initially require at least one model.
5. After the model has retrieved the data, it is returned to the controller. Model callbacks may apply.
6. The controller may use components to further refine the data or perform other operations (session manipulation, authentication, or sending emails, for example).
7. Once the controller has used models and components to prepare the data sufficiently, that data is handed to the view using the controller’s set() method. Controller callbacks may be applied before the data is sent. The view logic is performed, which may include the use of elements and/or helpers. By default, the view is rendered inside of a layout.
8. Additional controller callbacks (like afterFilter) may be applied. The complete, rendered view code is sent to Ricardo’s browser.

After you've downloaded and extracted CakePHP, these are the files and folders you should see:

• app
• cake
• vendors
• .htaccess
• index.php
• README

You'll notice three main folders:

• The app folder will be where you work your magic: it’s where your application’s files will be placed.
• The cake folder is where we’ve worked our magic. Make a personal commitment not to edit files in this folder. We can’t help you if you’ve modified the core.
• Finally, the vendors folder is where you’ll place third-party PHP libraries you need to use with your CakePHP applications.

CakePHP’s app folder is where you will do most of your application development. Let’s look a little closer at the folders inside of app.

We are big fans of convention over configuration. While it takes a bit of time to learn CakePHP’s conventions, you save time in the long run: by following convention, you get free functionality, and you free yourself from the maintenance nightmare of tracking config files. Convention also makes for a very uniform system development, allowing other developers to jump in and help more easily.

CakePHP’s conventions have been distilled out of years of web development experience and best practices. While we suggest you use these conventions while developing with CakePHP, we should mention that many of these tenets are easily overridden–something that is especially handy when working with legacy systems.

In general, filenames are underscored while classnames are CamelCased. So if you have a class MyNiftyClass, then in Cake, the file should be named my_nifty_class.php. Below are examples of how to name the file for each of the different types of classes you would typically use in a CakePHP application:

• The Controller class KissesAndHugsController would be found in a file named kisses_and_hugs_controller.php (notice _controller in the filename)
• The Component class MyHandyComponent would be found in a file named my_handy.php
• The Model class OptionValue would be found in a file named option_value.php
• The Behavior class EspeciallyFunkableBehavior would be found in a file named especially_funkable.php
• The View class SuperSimpleView would be found in a file named super_simple.ctp
• The Helper class BestEverHelper would be found in a file named best_ever.php

Each file would be located in or under (can be in a subfolder) the appropriate folder in your app folder.

Model classnames are singular and CamelCased. Person, BigPerson, and ReallyBigPerson are all examples of conventional model names.

Table names corresponding to CakePHP models are plural and underscored. The underlying tables for the above mentioned models would be people, big_people, and really_big_people, respectively.

Foreign keys in hasMany, belongsTo or hasOne relationships are recognized by default as the (singular) name of the related model followed by _id. So if a baker hasMany cakes, the cakes table will refer to the baker in the bakers table via a baker_id foreign key.

Join tables, used in hasAndBelongsToMany (HABTM) relationships between models should be named after the model tables they will join in alphabetical order (apples_zebras rather than zebras_apples).

All tables with which CakePHP models interact (with the exception of join tables), require a singular primary key to uniquely identify each row. If you wish to model a table which does not have a single-field primary key, such as the rows of your posts_tags join table, CakePHP's convention is that a single-field primary key is added to the table.

CakePHP does not support composite primary keys. If you want to directly manipulate your join table data, use direct query calls or add a primary key to act on it as a normal model. E.g.:

CREATE TABLE posts_tags (
id INT(10) NOT NULL AUTO_INCREMENT,
post_id INT(10) NOT NULL,
tag_id INT(10) NOT NULL,
PRIMARY KEY(id)); 

Controller classnames are plural, CamelCased, and end in Controller. PeopleController and LatestArticlesController are both examples of conventional controller names.

The first method you write for a controller might be the index() method. When a request specifies a controller but not an action, the default CakePHP behavior is to execute the index() method of that controller. For example, a request for http://www.example.com/apples/ maps to a call on the index() method of the ApplesController, whereas http://www.example.com/apples/view/ maps to a call on the view() method of the ApplesController.

You can also change the visibility of controller methods in CakePHP by prefixing controller method names with underscores. If a controller method has been prefixed with an underscore, the method will not be accessible directly from the web but is available for internal use. For example:

<?php
class NewsController extends AppController {

	function latest() {
		$this->_findNewArticles();
	}
	
	function _findNewArticles() {
		//Logic to find latest news articles
	}
}

?>

1. <?php
2. class NewsController extends AppController {
3. function latest() {
4. $this->_findNewArticles();
5. }
7. function _findNewArticles() {
8. //Logic to find latest news articles
9. }
10. }
11. ?>

While the page http://www.example.com/news/latest/ would be accessible to the user as usual, someone trying to get to the page http://www.example.com/news/_findNewArticles/ would get an error, because the method is preceded with an underscore.

As you've just seen, single word controllers map easily to a simple lower case URL path. For example, ApplesController (which would be defined in the file name 'apples_controller.php') is accessed from http://example.com/apples.

Multiple word controllers can be any 'inflected' form which equals the controller name so:

• /redApples
• /RedApples
• /Red_apples
• /red_apples

will all resolve to the index of the RedApples controller. However, the convention is that your urls are lowercase and underscored, therefore /red_apples/go_pick is the correct form to access the RedApplesController::go_pick action.

For more information on CakePHP URLs and parameter handling, see Routes Configuration.

View template files are named after the controller functions they display, in an underscored form. The getReady() function of the PeopleController class will look for a view template in /app/views/people/get_ready.ctp.

The basic pattern is /app/views/controller/underscored_function_name.ctp.

By naming the pieces of your application using CakePHP conventions, you gain functionality without the hassle and maintenance tethers of configuration. Here’s a final example that ties the conventions

• Database table: "people"
• Model class: "Person", found at /app/models/person.php
• Controller class: "PeopleController", found at /app/controllers/people_controller.php
• View template, found at /app/views/people/index.ctp

Using these conventions, CakePHP knows that a request to http://example.com/people/ maps to a call on the index() function of the PeopleController, where the Person model is automatically available (and automatically tied to the ‘people’ table in the database), and renders to a file. None of these relationships have been configured by any means other than by creating classes and files that you’d need to create anyway.

Now that you've been introduced to CakePHP's fundamentals, you might try a run through the CakePHP Blog Tutorial to see how things fit together.

Now you’re cooking.

• HTTP Server. Apache with mod_rewrite is preferred, but by no means required.
• PHP 4.3.2 or greater. Yes, CakePHP works great on PHP 4 and 5.

Technically a database engine isn’t required, but we imagine that most applications will utilize one. CakePHP supports a variety of database storage engines:

• MySQL (4 or greater)
• PostgreSQL
• Firebird DB2
• Microsoft SQL Server
• Oracle
• SQLite
• ODBC
• ADOdb

CakePHP is fast and easy to install. The minimum requirements are a webserver and a copy of Cake, that's it! While this manual focuses primarily on setting up with Apache (because it's the most common), you can configure Cake to run on a variety of web servers such as LightHTTPD or Microsoft IIS.

Installation preparation consists of the following steps:

• Downloading a copy of CakePHP
• Configuring your web server to handle php if necessary
• Checking file permissions

There are two main ways to get a fresh copy of CakePHP. You can either download an archive copy (zip/tar.gz/tar.bz2) from the main website, or check out the code from the SVN repository.

To download the latest major release of CakePHP. Visit the main website http://www.cakephp.org and follow the "Download Now" link.

All current releases of CakePHP are hosted at CakeForge, the home of CakePHP. This site also contains links to many other CakePHP projects, including plugins and applications for CakePHP. The CakePHP releases are available at http://cakeforge.org/projects/cakephp.

Alternatively nightly builds are produced which include bug-fixes and up to the minute(well, to the day) enhancements. These can be accessed from the download index here: http://cakephp.org/downloads/index/nightly. For true up to the minute updates, you can check out directly from the development branch of the svn repository here: https://svn.cakephp.org/repo/branches/1.2.x.x.

CakePHP uses the /app/tmp directory for a number of different operations. Model descriptions, cached views, and session information are just a few examples.

As such, make sure the /app/tmp directory in your cake installation is writable by the web server user.

Installing CakePHP can be as simple as slapping it in your web server’s document root, or as complex and flexible as you wish. This section will cover the three main installation types for CakePHP: development, production, and advanced.

• Development: easy to get going, URLs for the application include the CakePHP installation directory name, and less secure.
• Production: Requires the ability to configure the web server’s document root, clean URLs, very secure.
• Advanced: With some configuration, allows you to place key CakePHP directories in different parts of the filesystem, possibly sharing a single CakePHP core library folder amongst many CakePHP applications.

A development installation is the fastest method to setup Cake. This example will help you install a CakePHP application and make it available at http://www.example.com/cake_1_2/. We assume for the purposes of this example that your document root is set to /var/www/html.

Unpack the contents of the Cake archive into /var/www/html. You now have a folder in your document root named after the release you've downloaded (e.g. cake_1.2.0.7962). Rename this folder to cake_1_2. Your development setup will look like this on the file system:

• /var/www/html
  • /cake_1_2
    • /app
    • /cake
    • /vendors
    • /.htaccess
    • /index.php
    • /README

If your web server is configured correctly, you should now find your Cake application accessible at http://www.example.com/cake_1_2/.

A production installation is a more flexible way to setup Cake. Using this method allows an entire domain to act as a single CakePHP application. This example will help you install Cake anywhere on your filesystem and make it available at http://www.example.com. Note that this installation may require the rights to change the DocumentRoot on an Apache webservers.

Unpack the contents of the Cake archive into a directory of your choosing. For the purposes of this example, we assume you choose to install Cake into /cake_install. Your production setup will look like this on the filesystem:

• /cake_install/
  • /app
    • /webroot (this directory is set as the DocumentRoot directive)
  • /cake
  • /vendors
  • /.htaccess
  • /index.php
  • /README

Developers using Apache should set the DocumentRoot directive for the domain to:

DocumentRoot /cake_install/app/webroot

If your web server is configured correctly, you should now find your Cake application accessible at http://www.example.com.

There may be some situations where you wish to place CakePHP's directories on different places on the filesystem. 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. This section describes how to spread your CakePHP directories across a filesystem.

First, realize that there are three main parts to a Cake application:

1. The core CakePHP libraries, in /cake.
2. Your application code, in /app.
3. The application’s webroot, usually 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 webroot folder out of the app folder 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. 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 your app folder.
• APP_DIR should be set to the (base)name of your app folder.
• CAKE_CORE_INCLUDE_PATH should be set to the path of your CakePHP libraries folder.

Let’s run through an example so you can see what an advanced installation might look like in practice. Imagine that I wanted to set up CakePHP to work as follows:

• The CakePHP core libraries will be placed in /usr/lib/cake.
• My application’s webroot directory will be /var/www/mysite/.
• My application’s app directory will be stored in /home/me/mysite.

Given this type of setup, I would need to edit my webroot/index.php file (which will end up at /var/www/mysite/index.php, in this example) to look like the following:

// /app/webroot/index.php (partial, comments removed) 

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');
}

1. // /app/webroot/index.php (partial, comments removed)
2. if (!defined('ROOT')) {
3. define('ROOT', DS.'home'.DS.'me');
4. }
5. if (!defined('APP_DIR')) {
6. define ('APP_DIR', 'mysite');
7. }
8. if (!defined('CAKE_CORE_INCLUDE_PATH')) {
9. define('CAKE_CORE_INCLUDE_PATH', DS.'usr'.DS.'lib');
10. }

It is recommended to use the DS constant rather than slashes to delimit file paths. This prevents any missing file errors you might get as a result of using the wrong delimiter, and it makes your code more portable.

It’s occasionally useful to be able to share MVC classes between applications on the same system. If you want the same controller in both applications, you can use CakePHP’s bootstrap.php to bring these additional classes into view.

In bootstrap.php, define some specially-named variables to make CakePHP aware of other places to look for MVC classes:

$viewPaths        = array();
$controllerPaths  = array();
$modelPaths       = array();
$helperPaths      = array();
$componentPaths   = array();
$behaviorPaths    = array();
$pluginPaths      = array();
$vendorPaths      = array();
$localePaths      = array();
$shellPaths       = array();

1. $viewPaths = array();
2. $controllerPaths = array();
3. $modelPaths = array();
4. $helperPaths = array();
5. $componentPaths = array();
6. $behaviorPaths = array();
7. $pluginPaths = array();
8. $vendorPaths = array();
9. $localePaths = array();
10. $shellPaths = array();

Each of these special variables can be set to an array of absolute filesystem paths where extra classes can be found when requested. Make sure that each path specified includes a trailing slash.

While CakePHP is built to work with mod_rewrite out of the box–and usually does–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. First look at your httpd.conf (Make sure you are editing the system httpd.conf rather than a user- or site-specific httpd.conf).

1. Make sure that an .htaccess override is allowed and that AllowOverride is set to All for the correct DocumentRoot. You should see a something similar to:

   #
   # Each directory to which Apache has access can be configured with respect
   # to which services and features are allowed and/or disabled in that
   # directory (and its subdirectories). 
   #
   # First, we configure the "default" to be a very restrictive set of 
   # features.  
   #
   <Directory />
       Options FollowSymLinks
       AllowOverride All
   #    Order deny,allow
   #    Deny from all
   </Directory>
   

   1. #
   2. # Each directory to which Apache has access can be configured with respect
   3. # to which services and features are allowed and/or disabled in that
   4. # directory (and its subdirectories).
   5. #
   6. # First, we configure the "default" to be a very restrictive set of
   7. # features.
   8. #
   9. <Directory />
   10. Options FollowSymLinks
   11. AllowOverride All
   12. # Order deny,allow
   13. # Deny from all
   14. </Directory>

2. Make sure you are loading up mod_rewrite correctly. You should see something like:

   LoadModule rewrite_module libexec/apache2/mod_rewrite.so

   1. LoadModule rewrite_module libexec/apache2/mod_rewrite.so

   In many systems these will be commented out (by being prepended with a #) by default, so you may just need to remove those leading # symbols.

   After you make changes, restart Apache to make sure the settings are active.

   Verify that you your .htaccess files are actually in the right directories.
   This can happen during copying because some operating systems treat files that start with '.' as hidden and therefore won't see them to copy.

3. Make sure your copy of CakePHP is from the downloads section of the site or our SVN repository, and has been unpacked correctly by checking for .htaccess files.

   Cake root directory (needs to be copied to your document, this redirects everything to your Cake app):

   <IfModule mod_rewrite.c>
      RewriteEngine on
      RewriteRule    ^$ app/webroot/    [L]
      RewriteRule    (.*) app/webroot/$1 [L]
   </IfModule>
   

   1. <IfModule mod_rewrite.c>
   2. RewriteEngine on
   3. RewriteRule ^$ app/webroot/ [L]
   4. RewriteRule (.*) app/webroot/$1 [L]
   5. </IfModule>

   Cake app directory (will be copied to the top directory of your application by bake):

   <IfModule mod_rewrite.c>
       RewriteEngine on
       RewriteRule    ^$    webroot/    [L]
       RewriteRule    (.*) webroot/$1    [L]
    </IfModule>
   

   1. <IfModule mod_rewrite.c>
   2. RewriteEngine on
   3. RewriteRule ^$ webroot/ [L]
   4. RewriteRule (.*) webroot/$1 [L]
   5. </IfModule>

   Cake webroot directory (will be copied to your application's web root by bake):

   <IfModule mod_rewrite.c>
       RewriteEngine On
       RewriteCond %{REQUEST_FILENAME} !-d
       RewriteCond %{REQUEST_FILENAME} !-f
       RewriteRule ^(.*)$ index.php?url=$1 [QSA,L]
   </IfModule>
   

   1. <IfModule mod_rewrite.c>
   2. RewriteEngine On
   3. RewriteCond %{REQUEST_FILENAME} !-d
   4. RewriteCond %{REQUEST_FILENAME} !-f
   5. RewriteRule ^(.*)$ index.php?url=$1 [QSA,L]
   6. </IfModule>

   For many hosting services (GoDaddy, 1and1), your web server is actually being served from a user directory that already uses mod_rewrite. If you are installing CakePHP into a user directory (http://example.com/~username/cakephp/), or any other URL structure that already utilizes mod_rewrite, you'll need to add RewriteBase statements to the .htaccess files CakePHP uses (/.htaccess, /app/.htaccess, /app/webroot/.htaccess).

   This can be added to the same section with the RewriteEngine directive, so for example your webroot .htaccess file would look like:

   <IfModule mod_rewrite.c>
       RewriteEngine On
       RewriteBase /
       RewriteCond %{REQUEST_FILENAME} !-d
       RewriteCond %{REQUEST_FILENAME} !-f
       RewriteRule ^(.*)$ index.php?url=$1 [QSA,L]
   </IfModule>
   

   1. <IfModule mod_rewrite.c>
   2. RewriteEngine On
   3. RewriteBase /
   4. RewriteCond %{REQUEST_FILENAME} !-d
   5. RewriteCond %{REQUEST_FILENAME} !-f
   6. RewriteRule ^(.*)$ index.php?url=$1 [QSA,L]
   7. </IfModule>

   The details of those changes will depend on your setup, and can include additional things that are not Cake related. Please refer to Apache's online documentation for more information.

While lighttpd features a rewrite module, it is not an equivalent of Apache's mod_rewrite. Full mod_rewrite functionalities are spread amongst Lighttpd's mod_rewrite, mod_magnet and mod_proxy.

CakePHP, however, mostly needs mod_magnet to redirect requests in order to work with pretty URLs.

To use pretty URLs with CakePHP and Lighttp, place this lua script in /etc/lighttpd/cake.

-- little helper function
function file_exists(path)
  local attr = lighty.stat(path)
  if (attr) then
      return true
  else
      return false
  end
end
function removePrefix(str, prefix)
  return str:sub(1,#prefix+1) == prefix.."/" and str:sub(#prefix+2)
end

-- prefix without the trailing slash
local prefix = ''

-- the magic ;)
if (not file_exists(lighty.env["physical.path"])) then
    -- file still missing. pass it to the fastcgi backend
    request_uri = removePrefix(lighty.env["uri.path"], prefix)
    if request_uri then
      lighty.env["uri.path"]          = prefix .. "/index.php"
      local uriquery = lighty.env["uri.query"] or ""
      lighty.env["uri.query"] = uriquery .. (uriquery ~= "" and "&" or "") .. "url=" .. request_uri
      lighty.env["physical.rel-path"] = lighty.env["uri.path"]
      lighty.env["request.orig-uri"]  = lighty.env["request.uri"]
      lighty.env["physical.path"]     = lighty.env["physical.doc-root"] .. lighty.env["physical.rel-path"]
    end
end
-- fallthrough will put it back into the lighty request loop
-- that means we get the 304 handling for free. ;)

1. -- little helper function
2. function file_exists(path)
3. local attr = lighty.stat(path)
4. if (attr) then
5. return true
6. else
7. return false
8. end
9. end
10. function removePrefix(str, prefix)
11. return str:sub(1,#prefix+1) == prefix.."/" and str:sub(#prefix+2)
12. end
13. -- prefix without the trailing slash
14. local prefix = ''
15. -- the magic ;)
16. if (not file_exists(lighty.env["physical.path"])) then
17. -- file still missing. pass it to the fastcgi backend
18. request_uri = removePrefix(lighty.env["uri.path"], prefix)
19. if request_uri then
20. lighty.env["uri.path"] = prefix .. "/index.php"
21. local uriquery = lighty.env["uri.query"] or ""
22. lighty.env["uri.query"] = uriquery .. (uriquery ~= "" and "&" or "") .. "url=" .. request_uri
23. lighty.env["physical.rel-path"] = lighty.env["uri.path"]
24. lighty.env["request.orig-uri"] = lighty.env["request.uri"]
25. lighty.env["physical.path"] = lighty.env["physical.doc-root"] .. lighty.env["physical.rel-path"]
26. end
27. end
28. -- fallthrough will put it back into the lighty request loop
29. -- that means we get the 304 handling for free. ;)

If you run your CakePHP installation from a subdirectory, you must set prefix = 'subdirectory_name' in the above script.

Then tell Lighttpd about your vhost:

$HTTP["host"] =~ "example.com" {
        server.error-handler-404  = "/index.php"

        magnet.attract-physical-path-to = ( "/etc/lighttpd/cake.lua" )

        server.document-root = "/var/www/cake-1.2/app/webroot/"

        # Think about getting vim tmp files out of the way too
        url.access-deny = (
                "~", ".inc", ".sh", "sql", ".sql", ".tpl.php",
                ".xtmpl", "Entries", "Repository", "Root",
                ".ctp", "empty"
        )
}

Alright, let's see CakePHP in action. Depending on which setup you used, you should point your browser to http://example.com/ or http://example.com/cake_install/. 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 CakePHP application.

Configuring a CakePHP application is a piece of cake. After you have installed CakePHP, creating a basic web application requires only that you setup a database configuration.

There are, however, other optional configuration steps you can take in order to take advantage of CakePHP flexible architecture. You can easily add to the functionality inherited from the CakePHP core, configure additional/different URL mappings (routes), and define additional/different inflections.

CakePHP expects database configuration details to be in a file at app/config/database.php. An example database configuration file can be found at app/config/database.php.default. A finished configuration should look something like this.

var $default = array('driver'      => 'mysql',
                     'persistent'  => false,
                     'host'        => 'localhost',
                     'login'       => 'cakephpuser',
                     'password'    => 'c4k3roxx!',
                     'database'    => 'my_cakephp_project',
                     'prefix'      => '');

1. var $default = array('driver' => 'mysql',
2. 'persistent' => false,
3. 'host' => 'localhost',
4. 'login' => 'cakephpuser',
5. 'password' => 'c4k3roxx!',
6. 'database' => 'my_cakephp_project',
7. 'prefix' => '');

The $default connection array is used unless another connection is specified by the $useDbConfig property in a model. For example, if my application has an additional legacy database in addition to the default one, I could use it in my models by creating a new $legacy database connection array similar to the $default array, and by setting var $useDbConfig = ‘legacy’; in the appropriate models.

Fill out the key/value pairs in the configuration array to best suit your needs.

The prefix setting is for tables, not models. For example, if you create a join table for your Apple and Flavor models, you name it prefix_apples_flavors (not prefix_apples_prefix_flavors), and set your prefix setting to 'prefix_'.

At this point, you might want to take a look at the CakePHP Conventions. The correct naming for your tables (and the addition of some columns) can score you some free functionality and help you avoid configuration. For example, if you name your database table big_boxes, your model BigBox, your controller BigBoxesController, everything just works together automatically. By convention, use underscores, lower case, and plural forms for your database table names - for example: bakers, pastry_stores, and savory_cakes.

Application configuration in CakePHP is found in /app/config/core.php. This file is a collection of Configure class variable definitions and constant definitions that determine how your application behaves. Before we dive into those particular variables, you’ll need to be familiar with Configure, CakePHP’s configuration registry class.

Despite few things needing to be configured in CakePHP, it’s sometimes useful to have your own configuration rules for your application. In the past you may have defined custom configuration values by defining variable or constants in some files. Doing so forces you to include that configuration file every time you needed to use those values.

CakePHP’s new Configure class can be used to store and retrieve application or runtime specific values. Be careful, this class allows you to store anything in it, then use it in any other part of your code: a sure temptation to break the MVC pattern CakePHP was designed for. The main goal of Configure class is to keep centralized variables that can be shared between many objects. Remember to try to live by "convention over configuration" and you wont end up breaking the MVC structure we’ve set in place.

This class acts as a singleton and its methods can be called from anywhere within your application, in a static context.

<?php Configure::read('debug'); ?>

1. <?php Configure::read('debug'); ?>

write(string $key, mixed $value)

Use write() to store data in the application’s configuration.

Configure::write('Company.name','Pizza, Inc.');
Configure::write('Company.slogan','Pizza for your body and soul');

1. Configure::write('Company.name','Pizza, Inc.');
2. Configure::write('Company.slogan','Pizza for your body and soul');

The dot notation used in the $key parameter can be used to organize your configuration settings into logical groups.

The above example could also be written in a single call:

Configure::write(
    'Company',array('name'=>'Pizza, Inc.','slogan'=>'Pizza for your body and soul')
);

1. Configure::write(
2. 'Company',array('name'=>'Pizza, Inc.','slogan'=>'Pizza for your body and soul')
3. );

You can use Configure::write('debug', $int) to switch between debug and production modes on the fly. This is especially handy for AMF or SOAP interactions where debugging information can cause parsing problems.

read(string $key = 'debug')

Used to read configuration data from the application. Defaults to CakePHP’s important debug value. If a key is supplied, the data is returned. Using our examples from write() above, we can read that data back:

Configure::read('Company.name');    //yields: 'Pizza, Inc.'
Configure::read('Company.slogan');  //yields: 'Pizza for your body and soul'
 
Configure::read('Company');
 
//yields: 
array('name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul');

1. Configure::read('Company.name'); //yields: 'Pizza, Inc.'
2. Configure::read('Company.slogan'); //yields: 'Pizza for your body and soul'
4. Configure::read('Company');
6. //yields:
7. array('name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul');

delete(string $key)

Used to delete information from the application’s configuration.

Configure::delete('Company.name');

1. Configure::delete('Company.name');

load(string $path)

Use this method to load configuration information from a specific file.

// /app/config/messages.php:
<?php
$config['Company']['name'] = 'Pizza, Inc.';
$config['Company']['slogan'] = 'Pizza for your body and soul';
$config['Company']['phone'] = '555-55-55';
?>
 
<?php
Configure::load('messages');
Configure::read('Company.name');
?>

1. // /app/config/messages.php:
2. <?php
3. $config['Company']['name'] = 'Pizza, Inc.';
4. $config['Company']['slogan'] = 'Pizza for your body and soul';
5. $config['Company']['phone'] = '555-55-55';
6. ?>
8. <?php
9. Configure::load('messages');
10. Configure::read('Company.name');
11. ?>

Every configure key-value pair is represented in the file with the $config array. Any other variables in the file will be ignored by the load() function.

version()

Returns the CakePHP version for the current application.

The Configure class is used to manage a set of core CakePHP configuration variables. These variables can be found in app/config/core.php. Below is a description of each variable and how it affects your CakePHP application.

Cache configuration is also found in core.php — We’ll be covering that later on, so stay tuned.

The Configure class can be used to read and write core configuration settings on the fly. This can be especially handy if you want to turn the debug setting on for a limited section of logic in your application, for instance.

While most configuration options are handled by Configure, there are a few constants that CakePHP uses during runtime.

Loading additional classes has become more streamlined in CakePHP. In previous versions there were different functions for loading a needed class based on the type of class you wanted to load. These functions have been deprecated, all class and library loading should be done through App::import() now. App::import() ensures that a class is only loaded once, that the appropriate parent class has been loaded, and resolves paths automatically in most cases.

App::import($type, $name, $parent, $search, $file, $return);

At first glance App::import seems complex, however in most use cases only 2 arguments are required.

Core libraries such as Sanitize, and Xml can be loaded by:

App::import('Core', 'Sanitize');

1. App::import('Core', 'Sanitize');

The above would make the Sanitize class available for use.

All application related class should also be loaded with App::import(). The following examples illustrate how to do so.

App::import('Controller', 'MyController');

Calling App::import is equivalent to require'ing the file. It is important to realize that the class subsequently needs to be initialized.

<?php
// The same as require('controllers/users_controller.php');
App::import('Controller', 'Users');

// We need to load the class
$Users = new UsersController;

// If we want the model associations, components, etc to be loaded
$Users->constructClasses();
?>

1. <?php
2. // The same as require('controllers/users_controller.php');
3. App::import('Controller', 'Users');
4. // We need to load the class
5. $Users = new UsersController;
6. // If we want the model associations, components, etc to be loaded
7. $Users->constructClasses();
8. ?>

App::import('Model', 'MyModel');

App::import('Component', 'Auth');

App::import('Behavior', 'Tree');

App::import('Helper', 'Html');

Loading classes in plugins works much the same as loading app and core classes except you must specify the plugin you are loading from.

App::import('Model', 'PluginName.Comment');

1. App::import('Model', 'PluginName.Comment');

The vendor() function has been deprecated. Vendor files should now be loaded through App::import() as well. The syntax and additional arguments are slightly different, as vendor file structures can differ greatly, and not all vendor files contain classes.

The following examples illustrate how to load vendor files from a number of path structures. These vendor files could be located in any of the vendor folders.

To load vendors/geshi.php

App::import('Vendor', 'geshi');

1. App::import('Vendor', 'geshi');

To load vendors/flickr/flickr.php

App::import('Vendor', 'flickr/flickr');

1. App::import('Vendor', 'flickr/flickr');

To load vendors/some.name.php

App::import('Vendor', 'SomeName', array('file' => 'some.name.php'));

1. App::import('Vendor', 'SomeName', array('file' => 'some.name.php'));

To load vendors/services/well.named.php

App::import('Vendor', 'WellNamed', array('file' => 'services'.DS.'well.named.php'));

1. App::import('Vendor', 'WellNamed', array('file' => 'services'.DS.'well.named.php'));

Routing is a feature that maps URLs to controller actions. It was added to CakePHP to make pretty URLs more configurable and flexible. Using Apache’s mod_rewrite is not required for using routes, but it will make your address bar look much more tidy.

As will be explained later, routes in CakePHP 1.2 have been expanded and are now very powerful.

Before you learn about configuring your own routes, you should know that CakePHP comes configured with a default set of routes. CakePHP’s default routing will get you pretty far in any application. You can access an action directly via the URL by putting its name in the request. You can also pass parameters to your controller actions using the URL.

    URL pattern default routes: 
    http://example.com/controller/action/param1/param2/param3

The URL /posts/view maps to the view() action of the PostsController, and /products/view_clearance maps to the viewClearance() action of the ProductsController. If no action is specified in the URL, the index() method is assumed.

The default routing setup also allows you to pass parameters to your actions using the URL. A request for /posts/view/25 would be equivalent to calling view(25) on the PostsController, for example.

New in CakePHP 1.2 is the ability to use named parameters. You can name parameters and send their values using the URL. A request for /posts/view/title:first+post/category:general would result in a call to the view() action of the PostsController. In that action, you’d find the values of the title and category parameters inside $this->passedArgs[‘title’] and $this->passedArgs[‘category’] respectively.

Some summarizing examples for default routes might prove helpful.

URL to controller action mapping using default routes:  
    
URL: /monkeys/jump
Mapping: MonkeysController->jump();
 
URL: /products
Mapping: ProductsController->index();
 
URL: /tasks/view/45
Mapping: TasksController->view(45);
 
URL: /donations/view/recent/2001
Mapping: DonationsController->view('recent', '2001');

URL: /contents/view/chapter:models/section:associations
Mapping: ContentsController->view();
$this->passedArgs['chapter'] = 'models';
$this->passedArgs['section'] = 'associations';

Defining your own routes allows you to define how your application will respond to a given URL. Define your own routes in the /app/config/routes.php file using the Router::connect() method.

The connect() method takes up to three parameters: the URL you wish to match, the default values for your route elements, and regular expression rules to help the router match elements in the URL.

The basic format for a route definition is:

Router::connect(
    'URL',
    array('paramName' => 'defaultValue'),
    array('paramName' => 'matchingRegex')
)

1. Router::connect(
2. 'URL',
3. array('paramName' => 'defaultValue'),
4. array('paramName' => 'matchingRegex')
5. )

The first parameter is used to tell the router what sort of URL you're trying to control. The URL is a normal slash delimited string, but can also contain a wildcard (*) or route elements (variable names prefixed with a colon). Using a wildcard tells the router what sorts of URLs you want to match, and specifying route elements allows you to gather parameters for your controller actions.

Once you've specified a URL, you use the last two parameters of connect() to tell CakePHP what to do with a request once it has been matched. The second parameter is an associative array. The keys of the array should be named after the route elements in the URL, or the default elements: :controller, :action, and :plugin. The values in the array are the default values for those keys. Let's look at some basic examples before we start using the third parameter of connect().

Router::connect(
    '/pages/*',
    array('controller' => 'pages', 'action' => 'display')
);

1. Router::connect(
2. '/pages/*',
3. array('controller' => 'pages', 'action' => 'display')
4. );

This route is found in the routes.php file distributed with CakePHP (line 40). This route matches any URL starting with /pages/ and hands it to the display() method of the PagesController(); The request /pages/products would be mapped to PagesController->display('products'), for example.

Router::connect(
    '/government',
    array('controller' => 'products', 'action' => 'display', 5)
);

1. Router::connect(
2. '/government',
3. array('controller' => 'products', 'action' => 'display', 5)
4. );

This second example shows how you can use the second parameter of connect() to define default parameters. If you built a site that features products for different categories of customers, you might consider creating a route. This allows you link to /government rather than /products/display/5.

Another common use for the Router is to define an "alias" for a controller. Let's say that instead of accessing our regular URL at /users/someAction/5, we'd like to be able to access it by /cooks/someAction/5. The following route easily takes care of that:

Router::connect(
    '/cooks/:action/*', array('controller' => 'users', 'action' => 'index')
);

1. Router::connect(
2. '/cooks/:action/*', array('controller' => 'users', 'action' => 'index')
3. );

This is telling the Router that any url beginning with /cooks/ should be sent to the users controller.

When generating urls, routes are used too. Using array('controller' => 'users', 'action' => 'someAction', 5) as a url will output /cooks/someAction/5 if the above route is the first match found

If you are planning to use custom named arguments with your route, you have to make the router aware of it using the Router::connectNamed function. So if you want the above route to match urls like /cooks/someAction/type:chef we do:

Router::connectNamed(array('type'));
Router::connect(
    '/cooks/:action/*', array('controller' => 'users', 'action' => 'index')
);

1. Router::connectNamed(array('type'));
2. Router::connect(
3. '/cooks/:action/*', array('controller' => 'users', 'action' => 'index')
4. );

You can specify your own route elements, doing so gives you the power to define places in the URL where parameters for controller actions should lie. When a request is made, the values for these route elements are found in $this->params of the controller. This is different than named parameters are handled, so note the difference: named parameters (/controller/action/name:value) are found in $this->passedArgs, whereas custom route element data is found in $this->params. When you define a custom route element, you also need to specify a regular expression - this tells CakePHP how to know if the URL is correctly formed or not.

Router::connect(
    '/:controller/:id',
    array('action' => 'view'),
    array('id' => '[0-9]+')
);

1. Router::connect(
2. '/:controller/:id',
3. array('action' => 'view'),
4. array('id' => '[0-9]+')
5. );

This simple example illustrates how to create a quick way to view models from any controller by crafting a URL that looks like /controllername/id. The URL provided to connect() specifies two route elements: :controller and :id. The :controller element is a CakePHP default route element, so the router knows how to match and identify controller names in URLs. The :id element is a custom route element, and must be further clarified by specifying a matching regular expression in the third parameter of connect(). This tells CakePHP how to recognize the ID in the URL as opposed to something else, such as an action name.

Once this route has been defined, requesting /apples/5 is the same as requesting /apples/view/5. Both would call the view() method of the ApplesController. Inside the view() method, you would need to access the passed ID at $this->params['id'].

One more example, and you'll be a routing pro.

Router::connect(
    '/:controller/:year/:month/:day',
    array('action' => 'index', 'day' => null),
    array(
        'year' => '[12][0-9]{3}',
        'month' => '0[1-9]|1[012]',
        'day' => '0[1-9]|[12][0-9]|3[01]'
    )
);

1. Router::connect(
2. '/:controller/:year/:month/:day',
3. array('action' => 'index', 'day' => null),
4. array(
5. 'year' => '[12][0-9]{3}',
6. 'month' => '0[1-9]|1[012]',
7. 'day' => '0[1-9]|[12][0-9]|3[01]'
8. )
9. );

This is rather involved, but shows how powerful routes can really become. The URL supplied has four route elements. The first is familiar to us: it's a default route element that tells CakePHP to expect a controller name.

Next, we specify some default values. Regardless of the controller, we want the index() action to be called. We set the day parameter (the fourth element in the URL) to null to flag it as being optional.

Finally, we specify some regular expressions that will match years, months and days in numerical form. Note that parenthesis (grouping) are not supported in the regular expressions. You can still specify alternates, as above, but not grouped with parenthesis.

Once defined, this route will match /articles/2007/02/01, /posts/2004/11/16, and /products/2001/05 (as defined, the day parameter is optional as it has a default), handing the requests to the index() actions of their respective controllers, with he date parameters in $this->params.

Assuming your action was defined like this and you want to access the arguments using $articleID instead of $this->params['id'], just add an extra array in the 3rd parameter of Router::connect().

// some_controller.php
function view($articleID = null, $slug = null) {
    // some code here...
}

// routes.php
Router::connect(
    // E.g. /blog/3-CakePHP_Rocks
    '/blog/:id-:slug',
    array('controller' => 'blog', 'action' => 'view'),
    array(
        // order matters since this will simply map ":id" to $articleID in your action
        'pass' => array('id', 'slug'),
        'id' => '[0-9]+'
    )
);

1. // some_controller.php
2. function view($articleID = null, $slug = null) {
3. // some code here...
4. }
5. // routes.php
6. Router::connect(
7. // E.g. /blog/3-CakePHP_Rocks
8. '/blog/:id-:slug',
9. array('controller' => 'blog', 'action' => 'view'),
10. array(
11. // order matters since this will simply map ":id" to $articleID in your action
12. 'pass' => array('id', 'slug'),
13. 'id' => '[0-9]+'
14. )
15. );

And now, thanks to the reverse routing capabilities, you can pass in the url array like below and Cake will know how to form the URL as defined in the routes.

// view.ctp
// this will return a link to /blog/3-CakePHP_Rocks
<?php echo $html->link('CakePHP Rocks', array(
    'controller' => 'blog',
    'action' => 'view',
    'id' => 3,
    'slug' => Inflector::slug('CakePHP Rocks')
)); ?>

1. // view.ctp
2. // this will return a link to /blog/3-CakePHP_Rocks
3. <?php echo $html->link('CakePHP Rocks', array(
4. 'controller' => 'blog',
5. 'action' => 'view',
6. 'id' => 3,
7. 'slug' => Inflector::slug('CakePHP Rocks')
8. )); ?>

Many applications require an administration section where privileged users can make changes. This is often done through a special URL such as /admin/users/edit/5. In CakePHP, admin routing can be enabled from within the core configuration file by setting the admin path for Routing.admin.

Configure::write('Routing.admin', 'admin');

1. Configure::write('Routing.admin', 'admin');

In your controller, any action with an admin_ prefix will be called. Using our users example, accessing the url /admin/users/edit/5 would call the method admin_edit of our UsersController passing 5 as the first parameter.

You can map the url /admin to your admin_index action of pages controller using following route

Router::connect('/admin', array('controller' => 'pages', 'action' => 'index', 'admin' => true)); 

1. Router::connect('/admin', array('controller' => 'pages', 'action' => 'index', 'admin' => true));

You can configure the Router to use multiple prefixes too:

Router::connect('/profiles/:controller/:action/*', array('prefix' => 'profiles', 'profiles' => true)); 

1. Router::connect('/profiles/:controller/:action/*', array('prefix' => 'profiles', 'profiles' => true));

Any calls to the profiles section would look for the profiles_ prefix on the method calls. Our users example would have a URL structure that looks like /profiles/users/edit/5 would call the profiles_edit method within the UsersController. Also important to remember, using the HTML helper to build your links will help maintain the prefix calls. Here's how to built this link using the HTML helper:

echo $html->link('Edit your profile', array('profiles' => true, 'controller' => 'users', 'action' => 'edit', 'id' => 5)); 

1. echo $html->link('Edit your profile', array('profiles' => true, 'controller' => 'users', 'action' => 'edit', 'id' => 5));

You can set up multiple prefixed routes using this approach to create a flexible URL structure for your application.

Cake's naming conventions can be really nice - you can name your database table big_boxes, your model BigBox, your controller BigBoxesController, and everything just works together automatically. The way CakePHP knows how to tie things together is by inflecting the words between their singular and plural forms.

There are occasions (especially for our non-English speaking friends) where you may run into situations where CakePHP's inflector (the class that pluralizes, singularizes, camelCases, and under_scores) might not work as you'd like. If CakePHP won't recognize your Foci or Fish, editing the inflections configuration file is where you can tell CakePHP about your special cases. This file is found in /app/config/inflections.php.

In this file, you will find six variables. Each allows you to fine-tune CakePHP inflection behavior.

If you have any additional configuration needs, use CakePHP’s bootstrap file, found in /app/config/bootstrap.php. This file is executed just after CakePHP’s core bootstrapping.

This file is ideal for a number of common bootstrapping tasks:

• Defining convenience functions
• Registering global constants
• Defining additional model, view, and controller paths

Be careful to maintain the MVC software design pattern when you add things to the bootstrap file: it might be tempting to place formatting functions there in order to use them in your controllers.

Resist the urge. You’ll be glad you did later on down the line.

You might also consider placing things in the AppController class. This class is a parent class to all of the controllers in your application. AppController is handy place to use controller callbacks and define methods to be used by all of your controllers.

A controller is used to manage the logic for a part of your application. Most commonly, controllers are used to manage the logic for a single model. For example, if you were building a site for an online bakery, you might have a RecipesController and a IngredientsController managing your recipes and their ingredients. In CakePHP, controllers are named after the model they handle, in plural form.

The Recipe model is handled by the RecipesController, the Product model is handled by the ProductsController, and so on.

Your application's controllers are classes that extend the CakePHP AppController class, which in turn extends a core Controller class. The AppController class can be defined in /app/controllers/app_controller.php and it should contain methods that are shared between all of your application’s controllers. It extends the Controller class which is a standard CakePHP library.

Controllers can include any number of methods which are usually referred to as actions. Actions are controller methods used to display views. An action is a single method of a controller.

CakePHP’s dispatcher calls actions when an incoming request matches a URL to a controller’s action (refer to "Routes Configuration" for an explanation on how controller actions and parameters are mapped from the URL).

Returning to our online bakery example, our RecipesController might contain the view(), share(), and search() actions. The controller would be found in /app/controllers/recipes_controller.php and contain:

    <?php
    
    # /app/controllers/recipes_controller.php

    class RecipesController extends AppController {
        function view($id)     {
            //action logic goes here..
        }

        function share($customer_id, $recipe_id) {
            //action logic goes here..
        }

        function search($query) {
            //action logic goes here..
        }
    }

    ?>

1. <?php
3. # /app/controllers/recipes_controller.php
4. class RecipesController extends AppController {
5. function view($id) {
6. //action logic goes here..
7. }
8. function share($customer_id, $recipe_id) {
9. //action logic goes here..
10. }
11. function search($query) {
12. //action logic goes here..
13. }
14. }
15. ?>

In order for you to use a controller effectively in your own application, we’ll cover some of the core attributes and methods provided by CakePHP’s controllers.

As stated in the introduction, the AppController class is the parent class to all of your application's controllers. AppController itself extends the Controller class included in the CakePHP core library. As such, AppController is defined in /app/app_controller.php like so:

<?php
class AppController extends Controller {
}
?>

1. <?php
2. class AppController extends Controller {
3. }
4. ?>

Controller attributes and methods created in your AppController will be available to all of your application's controllers. It is the ideal place to create code that is common to all of your controllers. Components (which you'll learn about later) are best used for code that is used in many (but not necessarily all) controllers.

While normal object-oriented inheritance rules apply, CakePHP also does a bit of extra work when it comes to special controller attributes, like the list of components or helpers used by a controller. In these cases, AppController value arrays are merged with child controller class arrays.

Please also remember to call AppController's callbacks within child controller callbacks for best results:

function beforeFilter(){
	parent::beforeFilter();
}

1. function beforeFilter(){
2. parent::beforeFilter();
3. }

For a complete list of controller attributes and their descriptions visit the CakePHP API. Check out http://api.cakephp.org/class/controller.

PHP4 users should start out their controller definitions using the $name attribute. The $name attribute should be set to the name of the controller. Usually this is just the plural form of the primary model the controller uses. This takes care of some PHP4 classname oddities and helps CakePHP resolve naming.

<?php

#   $name controller attribute usage example

class RecipesController extends AppController {
   var $name = 'Recipes';
}

?>	

1. <?php
2. # $name controller attribute usage example
3. class RecipesController extends AppController {
4. var $name = 'Recipes';
5. }
6. ?>

The next most often used controller attributes tell CakePHP what helpers, components, and models you’ll be using in conjunction with the current controller. Using these attributes make these MVC classes available to the controller as a class variable ($this->ModelName, for example).

Each controller has some of these classes available by default, so you may not need to configure your controller at all.

Controllers have access to their primary model available by default. Our RecipesController will have the Recipe model class available at $this->Recipe, and our ProductsController also features the Product model at $this->Product. However, when allowing a controller to access additional models through the $uses variable, the name of the current controller's model must also be included. This is illustrated in the example below.

The Html, Form, and Session Helpers are always available by default, as is the SessionComponent. To learn more about these classes, be sure to check out their respective sections later in this manual.

Let’s look at how to tell a CakePHP controller that you plan to use additional MVC classes.

<?php
class RecipesController extends AppController {
    var $name = 'Recipes';

    var $uses = array('Recipe', 'User');
    var $helpers = array('Ajax');
    var $components = array('Email');
}
?>   

1. <?php
2. class RecipesController extends AppController {
3. var $name = 'Recipes';
4. var $uses = array('Recipe', 'User');
5. var $helpers = array('Ajax');
6. var $components = array('Email');
7. }
8. ?>

Each of these variables are merged with their inherited values, therefore it is not necessary (for example) to redeclare the Form helper, or anything that is declared in your App controller.

If you do not wish to use a Model in your controller, set var $uses = null or var $uses = array(). This will allow you to use a controller without a need for a corresponding Model file.

A few attributes exist in CakePHP controllers that give you control over how your view is set inside of a layout.

The $layout attribute can be set to the name of a layout saved in /app/views/layouts. You specify a layout by setting $layout equal to the name of the layout file minus the .ctp extension. If this attribute has not been defined, CakePHP renders the default layout, default.ctp. If you haven’t defined one at /app/views/layouts/default.ctp, CakePHP’s core default layout will be rendered.

<?php

//   Using $layout to define an alternate layout

class RecipesController extends AppController {
    function quickSave() {
        $this->layout = 'ajax';
    }
}

?>

1. <?php
2. // Using $layout to define an alternate layout
3. class RecipesController extends AppController {
4. function quickSave() {
5. $this->layout = 'ajax';
6. }
7. }
8. ?>

You can also change the title of the page (that is located in the bar at the top of your browser) using $pageTitle. In order for this to work properly, your layout needs to include the $title_for_layout variable, at least between the <title> and </title> tags in the head of the HTML document.

<?php

//   Using $pageTitle to define the page title

class RecipesController extends AppController {
    function quickSave() {
        $this->pageTitle = 'My search engine optimized title';
    }
}

?>

1. <?php
2. // Using $pageTitle to define the page title
3. class RecipesController extends AppController {
4. function quickSave() {
5. $this->pageTitle = 'My search engine optimized title';
6. }
7. }
8. ?>

You can also set the page title from the view using $this->pageTitle (You must include the $this-> part.) This is recommended, as it better separates the logic from the layout and content. For a static page you must use $this->pageTitle in the view if you want a different title.

If $this->pageTitle is not set, a title will be automatically generated based on the controller name, or the view file name in the case of a static page.

Controller parameters are available at $this->params in your CakePHP controller. This variable is used to provide access to information about the current request. The most common usage of $this->params is to get access to information that has been handed to the controller via POST or GET operations.

$this->params['form']

Any POST data from any form is stored here, including information also found in $_FILES.

$this->params['admin']

Is set to 1 if the current action was invoked via admin routing.

$this->params['bare']

Stores 1 if the current layout is empty, 0 if not.

$this->params['isAjax']

Stores 1 if the current request is an ajax call, 0 if not. This variable is only set if the RequestHandler Component is being used in the controller.

$this->params['controller']

Stores the name of the current controller handling the request. For example, if the URL /posts/view/1 was requested, $this->params['controller'] would equal "posts".

$this->params['action']

Stores the name of the current action handling the request. For example, if the URL /posts/view/1 was requested, $this->params['action'] would equal "view".

$this->params['pass']

Returns an array (numerically indexed) of URL parameters after the Action.

// URL: /posts/view/12/print/narrow

Array
(
    [0] => 12
    [1] => print
    [2] => narrow
)

$this->params['url']

Stores the current URL requested, along with key-value pairs of get variables. For example, if the URL /posts/view/?var1=3&var2=4 was called, $this->params['url'] would contain:

[url] => Array
(
    [url] => posts/view
    [var1] => 3
    [var2] => 4
)

$this->data

Used to handle POST data sent from the FormHelper forms to the controller.

// The FormHelper is used to create a form element:
$form->text('User.first_name');

1. // The FormHelper is used to create a form element:
2. $form->text('User.first_name');

Which when rendered, looks something like:

 
<input name="data[User][first_name]" value="" type="text" />

When the form is submitted to the controller via POST, the data shows up in this->data

 
//The submitted first name can be found here:
$this->data['User']['first_name'];

2. //The submitted first name can be found here:
3. $this->data['User']['first_name'];

$this->params['prefix']

Set to the routing prefix. For example, this attribute would contain the string "admin" during a request to /admin/posts/someaction.

$this->params['named']

Stores any named parameters in the url query string in the form /key:value/. For example, if the URL /posts/view/var1:3/var2:4 was requested, $this->params['named'] would be an array containing:

[named] => Array
(
    [var1] => 3
    [var2] => 4
)

While you can check out the details for all controller attributes in the API, there are other controller attributes that merit their own sections in the manual.

The $cacheAction attribute aids in caching views, and the $paginate attribute is used to set pagination defaults for the controller. For more information on how to use these attributes, check out their respective sections later on in this manual.

Stub. Update Me!

Used to create cached instances of models a controller uses. When set to true, all models related to the controller will be cached. This can increase performance in many cases.

For a complete list of controller methods and their descriptions visit the CakePHP API. Check out http://api.cakephp.org/class/controller.

set(string $var, mixed $value)

The set() method is the main way to send data from your controller to your view. Once you've used set(), the variable can be accessed in your view.

<?php
    
//First you pass data from the controller:

$this->set('color', 'pink');

//Then, in the view, you can utilize the data:
?>

You have selected <?php echo $color; ?> icing for the cake.

1. <?php
3. //First you pass data from the controller:
4. $this->set('color', 'pink');
5. //Then, in the view, you can utilize the data:
6. ?>
7.  
8. You have selected <?php echo $color; ?> icing for the cake.

The set() method also takes an associative array as its first parameter. This can often be a quick way to assign a set of information to the view.

Array keys will be inflected before they are assigned to the view ('underscored_key' becomes 'underscoredKey', etc.):

<?php
    
$data = array(
    'color' => 'pink',
    'type' => 'sugar',
    'base_price' => 23.95
);

//make $color, $type, and $basePrice 
//available to the view:

$this->set($data);  

?>

1. <?php
3. $data = array(
4. 'color' => 'pink',
5. 'type' => 'sugar',
6. 'base_price' => 23.95
7. );
8. //make $color, $type, and $basePrice
9. //available to the view:
10. $this->set($data);
11. ?>

render(string $action, string $layout, string $file)

The render() method is automatically called at the end of each requested controller action. This method performs all the view logic (using the data you’ve given in using the set() method), places the view inside its layout and serves it back to the end user.

The default view file used by render is determined by convention. If the search() action of the RecipesController is requested, the view file in /app/views/recipes/search.ctp will be rendered.

class RecipesController extends AppController {
...
    function search() {
        // Render the view in /views/recipes/search.ctp
        $this->render();
    }
...
}

1. class RecipesController extends AppController {
2. ...
3. function search() {
4. // Render the view in /views/recipes/search.ctp
5. $this->render();
6. }
7. ...
8. }

Although CakePHP will automatically call it (unless you’ve set $this->autoRender to false) after every action’s logic, you can use it to specify an alternate view file by specifying an action name in the controller using $action.

If $action starts with '/' it is assumed to be a view or element file relative to the /app/views folder. This allows direct rendering of elements, very useful in ajax calls.

// Render the element in /views/elements/ajaxreturn.ctp
$this->render('/elements/ajaxreturn');

1. // Render the element in /views/elements/ajaxreturn.ctp
2. $this->render('/elements/ajaxreturn');

You can also specify an alternate view or element file using the third parameter, $file. When using $file, don't forget to utilize a few of CakePHP’s global constants (such as VIEWS).

The $layout parameter allows you to specify the layout the view is rendered in.

redirect(string $url, integer $status, boolean $exit)

The flow control method you’ll use most often is redirect(). This method takes its first parameter in the form of a CakePHP-relative URL. When a user has successfully placed an order, you might wish to redirect them to a receipt screen.

function placeOrder() {

    //Logic for finalizing order goes here

    if($success) {
        $this->redirect(array('controller' => 'orders', 'action' => 'thanks'));
    } else {
        $this->redirect(array('controller' => 'orders', 'action' => 'confirm'));
    }
}

1. function placeOrder() {
2. //Logic for finalizing order goes here
3. if($success) {
4. $this->redirect(array('controller' => 'orders', 'action' => 'thanks'));
5. } else {
6. $this->redirect(array('controller' => 'orders', 'action' => 'confirm'));
7. }
8. }

You can also use a relative or absolute URL as the $url argument:

$this->redirect('/orders/thanks'));
$this->redirect('http://www.example.com');

1. $this->redirect('/orders/thanks'));
2. $this->redirect('http://www.example.com');

You can also pass data to the action:

$this->redirect(array('action' => 'edit', $id));

1. $this->redirect(array('action' => 'edit', $id));

The second parameter of redirect() allows you to define an HTTP status code to accompany the redirect. You may want to use 301 (moved permanently) or 303 (see other), depending on the nature of the redirect.

The method will issue an exit() after the redirect unless you set the third parameter to false.

If you need to redirect to the referer page you can use:

$this->redirect($this->referer());

1. $this->redirect($this->referer());

flash(string $message, string $url, integer $pause)

Similarly, the flash() method is used to direct a user to a new page after an operation. The flash() method is different in that it shows a message before passing the user on to another URL.

The first parameter should hold the message to be displayed, and the second parameter is a CakePHP-relative URL. CakePHP will display the $message for $pause seconds before forwarding the user on.

For in-page flash messages, be sure to check out SessionComponent’s setFlash() method.

CakePHP controllers come fitted with callbacks you can use to insert logic just before or after controller actions are rendered.

beforeFilter()

This function is executed before every action in the controller. It's a handy place to check for an active session or inspect user permissions.

beforeRender()

Called after controller action logic, but before the view is rendered. This callback is not used often, but may be needed if you are calling render() manually before the end of a given action.

afterFilter()

Called after every controller action, and after rendering is complete. This is the last controller method to run.

CakePHP also supports callbacks related to scaffolding.

_beforeScaffold($method)

$method name of method called example index, edit, etc.

_afterScaffoldSave($method)

$method name of method called either edit or update.

_afterScaffoldSaveError($method)

$method name of method called either edit or update.

_scaffoldError($method)

$method name of method called example index, edit, etc.

This method loads the models required by the controller. This loading process is done by CakePHP normally, but this method is handy to have when accessing controllers from a different perspective. If you need CakePHP in a command-line script or some other outside use, constructClasses() may come in handy.

Returns the referring URL for the current request.

Used to tell the user’s browser not to cache the results of the current request. This is different than view caching, covered in a later chapter.

postConditions(array $data, mixed $op, string $bool, boolean $exclusive)

Use this method to turn a set of POSTed model data (from HtmlHelper-compatible inputs) into a set of find conditions for a model. This function offers a quick shortcut on building search logic. For example, an administrative user may want to be able to search orders in order to know which items need to be shipped. You can use CakePHP’s Form- and HtmlHelpers to create a quick form based on the Order model. Then a controller action can use the data posted from that form to craft find conditions:

function index() {
    $o = $this->Order->findAll($this->postConditions($this->data));
    $this->set('orders', $o);
}

1. function index() {
2. $o = $this->Order->findAll($this->postConditions($this->data));
3. $this->set('orders', $o);
4. }

If $this->data[‘Order’][‘destination’] equals “Old Towne Bakery”, postConditions converts that condition to an array compatible for use in a Model->findAll() method. In this case, array(“Order.destination” => “Old Towne Bakery”).

If you want use a different SQL operator between terms, supply them using the second parameter.

/*
Contents of $this->data
array(
    'Order' => array(
        'num_items' => '4',
        'referrer' => 'Ye Olde'
    )
)
*/

//Let’s get orders that have at least 4 items and contain ‘Ye Olde’
$o = $this->Order->findAll($this->postConditions(
    $this->data,
    array(
        'num_items' => '>=', 
        'referrer' => 'LIKE'
    )
));

1. /*
2. Contents of $this->data
3. array(
4. 'Order' => array(
5. 'num_items' => '4',
6. 'referrer' => 'Ye Olde'
7. )
8. )
9. */
10. //Let’s get orders that have at least 4 items and contain ‘Ye Olde’
11. $o = $this->Order->findAll($this->postConditions(
12. $this->data,
13. array(
14. 'num_items' => '>=',
15. 'referrer' => 'LIKE'
16. )
17. ));

The third parameter allows you to tell CakePHP what SQL boolean operator to use between the find conditions. String like ‘AND’, ‘OR’ and ‘XOR’ are all valid values.

Finally, if the last parameter is set to true, and the $op parameter is an array, fields not included in $op will not be included in the returned conditions.

This method is used for paginating results fetched by your models. You can specify page sizes, model find conditions and more. See the pagination section for more details on how to use paginate.

requestAction(string $url, array $options)

This function calls a controller's action from any location and returns data from the action. The $url passed is a CakePHP-relative URL (/controllername/actionname/params). To pass extra data to the receiving controller action add to the $options array.

You can use requestAction() to retrieve a fully rendered view by passing 'return' in the options: requestAction($url, array('return'));

If used without caching requestAction can lead to poor performance. It is rarely appropriate to use in a controller or model.

requestAction is best used in conjunction with (cached) elements – as a way to fetch data for an element before rendering. Let's use the example of putting a "latest comments" element in the layout. First we need to create a controller function that will return the data.

// controllers/comments_controller.php
class CommentsController extends AppController {
    function latest() {
        return $this->Comment->find('all', array('order' => 'Comment.created DESC', 'limit' => 10));
    }
}

1. // controllers/comments_controller.php
2. class CommentsController extends AppController {
3. function latest() {
4. return $this->Comment->find('all', array('order' => 'Comment.created DESC', 'limit' => 10));
5. }
6. }

If we now create a simple element to call that function:

// views/elements/latest_comments.ctp

$comments = $this->requestAction('/comments/latest');
foreach($comments as $comment) {
    echo $comment['Comment']['title'];
}

1. // views/elements/latest_comments.ctp
2. $comments = $this->requestAction('/comments/latest');
3. foreach($comments as $comment) {
4. echo $comment['Comment']['title'];
5. }

We can then place that element anywhere at all to get the output using:

echo $this->element('latest_comments');

1. echo $this->element('latest_comments');

Written in this way, whenever the element is rendered, a request will be made to the controller to get the data, the data will be processed, and returned. However in accordance with the warning above it's best to make use of element caching to prevent needless processing. By modifying the call to element to look like this:

echo $this->element('latest_comments', array('cache'=>'+1 hour'));

1. echo $this->element('latest_comments', array('cache'=>'+1 hour'));

The requestAction call will not be made while the cached element view file exists and is valid.

In addition, requestAction now takes array based cake style urls:

echo $this->requestAction(array('controller' => 'articles', 'action' => 'featured'), array('return'));

1. echo $this->requestAction(array('controller' => 'articles', 'action' => 'featured'), array('return'));

This allows the requestAction call to bypass the usage of Router::url which can increase performance. The url based arrays are the same as the ones that HtmlHelper::link uses with one difference - if you are using named or passed parameters, you must put them in a second array and wrap them with the correct key. This is because requestAction only merges the named args array into the Controller::params member array and does not place the named args in the key 'named'.

echo $this->requestAction('/articles/featured/limit:3');
echo $this->requestAction('/articles/view/5');

1. echo $this->requestAction('/articles/featured/limit:3');
2. echo $this->requestAction('/articles/view/5');

As an array in the requestAction would then be:

echo $this->requestAction(array('controller' => 'articles', 'action' => 'featured'), array('named' => array('limit' => 3)));

echo $this->requestAction(array('controller' => 'articles', 'action' => 'view'), array('pass' => array(5)));

1. echo $this->requestAction(array('controller' => 'articles', 'action' => 'featured'), array('named' => array('limit' => 3)));
2. echo $this->requestAction(array('controller' => 'articles', 'action' => 'view'), array('pass' => array(5)));

Unlike other places where array urls are analogous to string urls, requestAction treats them differently.

When using an array url in conjunction with requestAction() you must specify all parameters that you will need in the requested action. This includes parameters like $this->data and $this->params['form']. In addition to passing all required parameters, named and pass parameters must be done in the second array as seen above.

Components are packages of logic that are shared between controllers. If you find yourself wanting to copy and paste things between controllers, you might consider wrapping some functionality in a component.

CakePHP also comes with a fantastic set of core components you can use to aid in:

• Security
• Sessions
• Access control lists
• Emails
• Cookies
• Authentication
• Request handling

Each of these core components are detailed in their own chapters. For now, we’ll show you how to create your own components. Creating components keeps controller code clean and allows you to reuse code between projects.

Many of the core components require configuration. Some examples of components requiring configuration are Auth, Cookie and Email. Configuration for these components, and components in general is usually done in your Controller's beforeFilter() method.

function beforeFilter() {
	$this->Auth->authorize = 'controller';
	$this->Auth->loginAction = array('controller' => 'users', 'action' => 'login');
	
	$this->Cookie->name = 'CookieMonster';
}

1. function beforeFilter() {
2. $this->Auth->authorize = 'controller';
3. $this->Auth->loginAction = array('controller' => 'users', 'action' => 'login');
5. $this->Cookie->name = 'CookieMonster';
6. }

Would be an example of configuring component variables in your controller's beforeFilter()

It's possible, however, that a component requires certain configuration options to be set before the controller's beforeFilter is run. To this end, some components allow configuration options be set in the $components array.

var $components = array('DebugKit.toolbar' => array('panels' => array('history', 'session'));

1. var $components = array('DebugKit.toolbar' => array('panels' => array('history', 'session'));

Consult the relevant documentation to determine what configuration options each component provides.

Suppose our online application needs to perform a complex mathematical operation in many different parts of the application. We could create a component to house this shared logic for use in many different controllers.

The first step is to create a new component file and class. Create the file in /app/controllers/components/math.php. The basic structure for the component would look something like this:

<?php

class MathComponent extends Object {
    function doComplexOperation($amount1, $amount2) {
        return $amount1 + $amount2;
    }
}

?>

1. <?php
2. class MathComponent extends Object {
3. function doComplexOperation($amount1, $amount2) {
4. return $amount1 + $amount2;
5. }
6. }
7. ?>

Once our component is finished, we can use it in the application's controllers by placing the component's name (minus the "Component" part) in the controller's $components array. The controller will automatically be given a new attribute named after the component, through which we can access an instance of it:

/* Make the new component available at $this->Math,
as well as the standard $this->Session */
var $components = array('Math', 'Session');

1. /* Make the new component available at $this->Math,
2. as well as the standard $this->Session */
3. var $components = array('Math', 'Session');

Components declared in AppController will be merged with those in your other controllers. So there is no need to re-declare the same component twice.

When including Components in a Controller you can also declare a set of parameters that will be passed on to the Component's initialize() method. These parameters can then be handled by the Component.

var $components = array(
	'Math' => array(
		'precision' => 2,
		'randomGenerator' => 'srand'
	),
	'Session', 'Auth'
);

1. var $components = array(
2. 'Math' => array(
3. 'precision' => 2,
4. 'randomGenerator' => 'srand'
5. ),
6. 'Session', 'Auth'
7. );

The above would pass the array containing precision and randomGenerator to MathComponent's initialize() method as the second parameter.

This syntax is not implemented by any of the Core Components at this time

Components feature a number of callbacks used by the parent controller class. Judicious use of these callbacks can make creating and using components much easier..

initialize(&$controller, $settings=array())

The initialize method is called before the controller's beforeFilter method.

startup(&$controller)

The startup method is called after the controller's beforeFilter method but before the controller executes the current action handler.

beforeRender(&$controller)

The beforeRender method is called after the controller's beforeRender method but before the controller's renders views and layout.

shutdown(&$controller)

The shutdown method is called before output is sent to browser.

beforeRedirect(&$controller, $url, $status=null, $exit=true)

The beforeRedirect method is invoked when the controller's redirect method is called but before any further action. If this method returns false the controllerwill not continue on to redirect the request. The $url, $status and $exit variables have same meaning as for the controller's method.

Here is a skeleton component you can use as a template for your own custom components.

<?php
class SkeletonComponent extends Object {
	//called before Controller::beforeFilter()
	function initialize(&$controller, $settings = array()) {
		// saving the controller reference for later use
		$this->controller =& $controller;
	}

	//called after Controller::beforeFilter()
	function startup(&$controller) {
	}

	//called after Controller::beforeRender()
	function beforeRender(&$controller) {
	}

	//called after Controller::render()
	function shutdown(&$controller) {
	}

	//called before Controller::redirect()
	function beforeRedirect(&$controller, $url, $status=null, $exit=true) {
	}

	function redirectSomewhere($value) {
		// utilizing a controller method
		$this->controller->redirect($value);
	}
}
?>

1. <?php
2. class SkeletonComponent extends Object {
3. //called before Controller::beforeFilter()
4. function initialize(&$controller, $settings = array()) {
5. // saving the controller reference for later use
6. $this->controller =& $controller;
7. }
8. //called after Controller::beforeFilter()
9. function startup(&$controller) {
10. }
11. //called after Controller::beforeRender()
12. function beforeRender(&$controller) {
13. }
14. //called after Controller::render()
15. function shutdown(&$controller) {
16. }
17. //called before Controller::redirect()
18. function beforeRedirect(&$controller, $url, $status=null, $exit=true) {
19. }
20. function redirectSomewhere($value) {
21. // utilizing a controller method
22. $this->controller->redirect($value);
23. }
24. }
25. ?>

You might also want to utilize other components inside a custom component. To do so, just create a $components class variable (just like you would in a controller) as an array that holds the names of components you wish to utilize.

<?php
class MyComponent extends Object {

	// This component uses other components
	var $components = array('Session', 'Math');

	function doStuff() {
		$result = $this->Math->doComplexOperation(1, 2);
		$this->Session->write('stuff', $result);
	}

}
?>

1. <?php
2. class MyComponent extends Object {
3. // This component uses other components
4. var $components = array('Session', 'Math');
5. function doStuff() {
6. $result = $this->Math->doComplexOperation(1, 2);
7. $this->Session->write('stuff', $result);
8. }
9. }
10. ?>

To access/use a model in a component is not generally recommended; If you end up needing one, you'll need to instantiate your model class and use it manually. Here's an example:

<?php
class MathComponent extends Object {
	function doComplexOperation($amount1, $amount2) {
		return $amount1 + $amount2;
	}

	function doReallyComplexOperation ($amount1, $amount2) {
		$userInstance = ClassRegistry::init('User');
		$totalUsers = $userInstance->find('count');
		return ($amount1 + $amount2) / $totalUsers;
	}
}
?>

1. <?php
2. class MathComponent extends Object {
3. function doComplexOperation($amount1, $amount2) {
4. return $amount1 + $amount2;
5. }
6. function doReallyComplexOperation ($amount1, $amount2) {
7. $userInstance = ClassRegistry::init('User');
8. $totalUsers = $userInstance->find('count');
9. return ($amount1 + $amount2) / $totalUsers;
10. }
11. }
12. ?>

Sometimes one of your components may need to use another.

You can include other components in your component the exact same way you include them in controllers: Use the $components var.

<?php
class CustomComponent extends Object {
    var $name = "Custom"; // the name of your component
    var $components = array( "Existing" ); // the other component your component uses

    function initialize(&$controller) {
        $this->Existing->foo();
    }

    function bar() {
        // ...
    }
}
?>

1. <?php
2. class CustomComponent extends Object {
3. var $name = "Custom"; // the name of your component
4. var $components = array( "Existing" ); // the other component your component uses
5. function initialize(&$controller) {
6. $this->Existing->foo();
7. }
8. function bar() {
9. // ...
10. }
11. }
12. ?>

<?php
class ExistingComponent extends Object {
    var $name = "Existing";

    function initialize(&$controller) {
        $this->Parent->bar();
    }

    function foo() {
        // ...
    }
}
?>

1. <?php
2. class ExistingComponent extends Object {
3. var $name = "Existing";
4. function initialize(&$controller) {
5. $this->Parent->bar();
6. }
7. function foo() {
8. // ...
9. }
10. }
11. ?>

Models represent data and are used in CakePHP applications for data access. A model usually represents a database table but can be used to access anything that stores data such as files, LDAP records, iCal events, or rows in a CSV file.

A model can be associated with other models. For example, a Recipe may be associated with the Author of the recipe as well as the Ingredient in the recipe.

This section will explain what features of the model can be automated, how to override those features, and what methods and properties a model can have. It'll explain the different ways to associate your data. It'll describe how to find, save, and delete data. Finally, it'll look at Datasources.

A Model represents your data model and in object-oriented programming is an object that represents a "thing", like a car, a person, or a house. A blog, for example, may have many blog posts and each blog post may have many comments. The Blog, Post, and Comment are all examples of models, each associated with another.

Here is a simple example of a model definition in CakePHP:

<?php

class Ingredient extends AppModel {
    var $name = 'Ingredient';
}

?>

1. <?php
2. class Ingredient extends AppModel {
3. var $name = 'Ingredient';
4. }
5. ?>

With just this simple declaration, the Ingredient model is bestowed with all the functionality you need to create queries along with saving and deleting data. These magic methods come from CakePHP's Model class by the magic of inheritance. The Ingredient model extends the application model, AppModel, which extends CakePHP's internal Model class. It is this core Model class that bestows the functionality onto your Ingredient model.

This intermediate class, AppModel, is empty and if you haven't created your own is taken from within the /cake/ folder. Overriding the AppModel allows you to define functionality that should be made available to all models within your application. To do so, you need to create your own app_model.php file that resides in the root of the /app/ folder. Creating a project using Bake will automatically generate this file for you.

Create your model PHP file in the /app/models/ directory or in a subdirectory of /app/models. CakePHP will find it anywhere in the directory. By convention it should have the same name as the class; for this example ingredient.php.

CakePHP will dynamically create a model object for you if it cannot find a corresponding file in /app/models. This also means that if your model file isn't named correctly (i.e. Ingredient.php or ingredients.php) CakePHP will use a instance of AppModel rather than your awol (from CakePHP's perspective) model file. If you're trying to use a method you've defined in your model, or a behavior attached to your model and you're getting SQL errors that are the name of the method you're calling - it's a sure sign CakePHP can't find your model and you either need to check the file names, clear your tmp files, or both.

See also Behaviors for more information on how to apply similar logic to multiple models.

The $name property is necessary for PHP4 but optional for PHP5.

With your model defined, it can be accessed from within your Controller. CakePHP will automatically make the model available for access when its name matches that of the controller. For example, a controller named IngredientsController will automatically initialize the Ingredient model and attach it to the controller at $this->Ingredient.

<?php
class IngredientsController extends AppController {
    function index() {
        //grab all ingredients and pass it to the view:
        $ingredients = $this->Ingredient->find('all');
        $this->set('ingredients', $ingredients);
    }
}

?>

1. <?php
2. class IngredientsController extends AppController {
3. function index() {
4. //grab all ingredients and pass it to the view:
5. $ingredients = $this->Ingredient->find('all');
6. $this->set('ingredients', $ingredients);
7. }
8. }
9. ?>

Associated models are available through the main model. In the following example, Recipe has an association with the Ingredient model.

<?php
class RecipesController extends AppController {
    function index() {
        $ingredients = $this->Recipe->Ingredient->find('all');
        $this->set('ingredients', $ingredients);
    }
}
?>

1. <?php
2. class RecipesController extends AppController {
3. function index() {
4. $ingredients = $this->Recipe->Ingredient->find('all');
5. $this->set('ingredients', $ingredients);
6. }
7. }
8. ?>

If models have absolutely NO association between them, you can use the ClassRegistry class to get the model.

<?php
class RecipesController extends AppController {
    function index() {
       $recipes = $this->Recipe->find('all');
       
       $this->Car =& ClassRegistry::init('Car');
       $cars = $this->Car->find('all');
       
       $this->set(compact('recipes', 'cars'));
    }
}
?>

1. <?php
2. class RecipesController extends AppController {
3. function index() {
4. $recipes = $this->Recipe->find('all');
6. $this->Car =& ClassRegistry::init('Car');
7. $cars = $this->Car->find('all');
9. $this->set(compact('recipes', 'cars'));
10. }
11. }
12. ?>

While CakePHP can have datasources that aren't database driven, most of the time, they are. CakePHP is designed to be agnostic and will work with MySQL, MSSQL, Oracle, PostgreSQL and others. You can create your database tables as you normally would. When you create your Model classes, they'll automatically map to the tables that you've created.

Table names are by convention lowercase and pluralized with multi-word table names separated by underscores. For example, a Model name of Ingredient expects the table name ingredients. A Model name of EventRegistration would expect a table name of event_registrations. CakePHP will inspect your tables to determine the data type of each field and uses this information to automate various features such as outputting form fields in the view.

Field names are by convention lowercase and separated by underscores.

Model to table name associations can be overridden with the useTable attribute of the model explained later in this chapter.

In the rest of this section, you'll see how CakePHP maps database field types to PHP data types and how CakePHP can automate tasks based on how your fields are defined.

Every RDBMS defines data types in slightly different ways. Within the datasource class for each database system, CakePHP maps those types to something it recognizes and creates a unified interface, no matter which database system you need to run on.

This breakdown describes how each one is mapped.

An object, in the physical sense, often has a name or a title that refers to it. A person has a name like John or Mac or Buddy. A blog post has a title. A category has a name.

By specifying a title or name field, CakePHP will automatically use this label in various circumstances:

• Scaffolding — page titles, fieldset labels
• Lists — normally used for <select> drop-downs
• TreeBehavior — reordering, tree views

If you have a title and name field in your table, the title will be used.

By defining a created or modified field in your database table as datetime fields, CakePHP will recognize those fields and populate them automatically whenever a record is created or saved to the database (unless the data being saved already contains a value for these fields).

The created and modified fields will be set to the current date and time when the record is initially added. The modified field will be updated with the current date and time whenever the existing record is saved.

Note: A field named updated will exhibit the same behavior as modified. These fields need to be datetime fields with the default value set to NULL to be recognized by CakePHP.

Primary keys are normally defined as INT fields. The database will automatically increment the field, starting at 1, for each new record that gets added. Alternatively, if you specify your primary key as a CHAR(36) or BINARY(36), CakePHP will automatically generate UUIDs when new records are created.

A UUID is a 32 byte string separated by four hyphens, for a total of 36 characters. For example:

550e8400-e29b-41d4-a716-446655440000

UUIDs are designed to be unique, not only within a single table, but also across tables and databases. If you require a field to remain unique across systems then UUIDs are a great approach.

find($type, $params)

Find is the multifunctional workhorse of all model data-retrieval functions. $type can be either 'all', 'first', 'count', 'list', 'neighbors' or 'threaded'. The default find type is 'first'.

$params is used to pass all parameters to the various finds, and has the following possible keys by default - all of which are optional:

array(
	'conditions' => array('Model.field' => $thisValue), //array of conditions
	'recursive' => 1, //int
	'fields' => array('Model.field1', 'DISTINCT Model.field2'), //array of field names
	'order' => array('Model.created', 'Model.field3 DESC'), //string or array defining order
	'group' => array('Model.field'), //fields to GROUP BY
	'limit' => n, //int
	'page' => n, //int
	'callbacks' => true //other possible values are false, 'before', 'after'
)

1. array(
2. 'conditions' => array('Model.field' => $thisValue), //array of conditions
3. 'recursive' => 1, //int
4. 'fields' => array('Model.field1', 'DISTINCT Model.field2'), //array of field names
5. 'order' => array('Model.created', 'Model.field3 DESC'), //string or array defining order
6. 'group' => array('Model.field'), //fields to GROUP BY
7. 'limit' => n, //int
8. 'page' => n, //int
9. 'callbacks' => true //other possible values are false, 'before', 'after'
10. )

It's also possible to add and use other parameters, as is made use of by some find types, behaviors and of course possible with your own model methods

More information about model callbacks is available here

find('first', $params)

'first' is the default find type, and will return one result, you'd use this for any use where you expect only one result. Below are a couple of simple (controller code) examples:

function some_function() {
   ...
   $this->Article->order = null; // resetting if it's set
   $semiRandomArticle = $this->Article->find();
   $this->Article->order = 'Article.created DESC'; // simulating the model having a default order
   $lastCreated = $this->Article->find();
   $alsoLastCreated = $this->Article->find('first', array('order' => array('Article.created DESC')));
   $specificallyThisOne = $this->Article->find('first', array('conditions' => array('Article.id' => 1)));
   ...
}

1. function some_function() {
2. ...
3. $this->Article->order = null; // resetting if it's set
4. $semiRandomArticle = $this->Article->find();
5. $this->Article->order = 'Article.created DESC'; // simulating the model having a default order
6. $lastCreated = $this->Article->find();
7. $alsoLastCreated = $this->Article->find('first', array('order' => array('Article.created DESC')));
8. $specificallyThisOne = $this->Article->find('first', array('conditions' => array('Article.id' => 1)));
9. ...
10. }

In the first example, no parameters at all are passed to find - therefore no conditions or sort order will be used. The format returned from find('first') call is of the form:

Array
(
    [ModelName] => Array
        (
            [id] => 83
            [field1] => value1
            [field2] => value2
            [field3] => value3
        )

    [AssociatedModelName] => Array
        (
            [id] => 1
            [field1] => value1
            [field2] => value2
            [field3] => value3
        )
)

There are no additional parameters used by find('first').

find('count', $params)

find('count', $params) returns an integer value. Below are a couple of simple (controller code) examples:

function some_function() {
   ...
   $total = $this->Article->find('count');
   $pending = $this->Article->find('count', array('conditions' => array('Article.status' => 'pending')));
   $authors = $this->Article->User->find('count');
   $publishedAuthors = $this->Article->find('count', array(
      'fields' => 'DISTINCT Article.user_id',
      'conditions' => array('Article.status !=' => 'pending')
   ));
   ...
}

1. function some_function() {
2. ...
3. $total = $this->Article->find('count');
4. $pending = $this->Article->find('count', array('conditions' => array('Article.status' => 'pending')));
5. $authors = $this->Article->User->find('count');
6. $publishedAuthors = $this->Article->find('count', array(
7. 'fields' => 'DISTINCT Article.user_id',
8. 'conditions' => array('Article.status !=' => 'pending')
9. ));
10. ...
11. }

Don't pass fields as an array to find('count'). You would only need to specify fields for a DISTINCT count (since otherwise, the count is always the same - dictated by the conditions).

There are no additional parameters used by find('count').

find('all', $params)

find('all') returns an array of (potentially multiple) results. It is in fact the mechanism used by all find() variants, as well as paginate. Below are a couple of simple (controller code) examples:

function some_function() {
   ...
   $allArticles = $this->Article->find('all');
   $pending = $this->Article->find('all', array('conditions' => array('Article.status' => 'pending')));
   $allAuthors = $this->Article->User->find('all');
   $allPublishedAuthors = $this->Article->User->find('all', array('conditions' => array('Article.status !=' => 'pending')));
   ...
}

1. function some_function() {
2. ...
3. $allArticles = $this->Article->find('all');
4. $pending = $this->Article->find('all', array('conditions' => array('Article.status' => 'pending')));
5. $allAuthors = $this->Article->User->find('all');
6. $allPublishedAuthors = $this->Article->User->find('all', array('conditions' => array('Article.status !=' => 'pending')));
7. ...
8. }

In the above example $allAuthors will contain every user in the users table, there will be no condition applied to the find as none were passed.

The results of a call to find('all') will be of the following form:

Array
(
    [0] => Array
        (
            [ModelName] => Array
                (
                    [id] => 83
                    [field1] => value1
                    [field2] => value2
                    [field3] => value3
                )

            [AssociatedModelName] => Array
                (
                    [id] => 1
                    [field1] => value1
                    [field2] => value2
                    [field3] => value3
                )

        )
)

There are no additional parameters used by find('all').

find('list', $params)

find('list', $params) returns an indexed array, useful for any use where you would want a list such as for populating input select boxes. Below are a couple of simple (controller code) examples:

function some_function() {
   ...
   $allArticles = $this->Article->find('list');
   $pending = $this->Article->find('list', array('conditions' => array('Article.status' => 'pending')));
   $allAuthors = $this->Article->User->find('list');
   $allPublishedAuthors = $this->Article->User->find('list', array('conditions' => array('Article.status !=' => 'pending')));
   ...
}

1. function some_function() {
2. ...
3. $allArticles = $this->Article->find('list');
4. $pending = $this->Article->find('list', array('conditions' => array('Article.status' => 'pending')));
5. $allAuthors = $this->Article->User->find('list');
6. $allPublishedAuthors = $this->Article->User->find('list', array('conditions' => array('Article.status !=' => 'pending')));
7. ...
8. }

In the above example $allAuthors will contain every user in the users table, there will be no condition applied to the find as none were passed.

The results of a call to find('list') will be in the following form:

Array
(
    //[id] => 'displayValue',
    [1] => 'displayValue1',
    [2] => 'displayValue2',
    [4] => 'displayValue4',
    [5] => 'displayValue5',
    [6] => 'displayValue6',
    [3] => 'displayValue3',
)

When calling find('list') the fields passed are used to determine what should be used as the array key, value and optionally what to group the results by. By default the primary key for the model is used for the key, and the display field is used for the value. Some further examples to clarify:.

function some_function() {
   ...
   $justusernames = $this->Article->User->find('list', array('fields' => array('User.username'));
   $usernameMap = $this->Article->User->find('list', array('fields' => array('User.username', 'User.first_name'));
   $usernameGroups = $this->Article->User->find('list', array('fields' => array('User.username', 'User.first_name', 'User.group'));
   ...
}

1. function some_function() {
2. ...
3. $justusernames = $this->Article->User->find('list', array('fields' => array('User.username'));
4. $usernameMap = $this->Article->User->find('list', array('fields' => array('User.username', 'User.first_name'));
5. $usernameGroups = $this->Article->User->find('list', array('fields' => array('User.username', 'User.first_name', 'User.group'));
6. ...
7. }

With the above code example, the resultant vars would look something like this:

$justusernames = Array
(
    //[id] => 'username',
    [213] => 'AD7six',
    [25] => '_psychic_',
    [1] => 'PHPNut',
    [2] => 'gwoo',
    [400] => 'jperras',
)

$usernameMap = Array
(
    //[username] => 'firstname',
    ['AD7six'] => 'Andy',
    ['_psychic_'] => 'John',
    ['PHPNut'] => 'Larry',
    ['gwoo'] => 'Gwoo',
    ['jperras'] => 'Joël',
)

$usernameGroups = Array
(
    ['Uber'] => Array
        (
	    ['PHPNut'] => 'Larry',
	    ['gwoo'] => 'Gwoo',
        )

    ['Admin'] => Array
        (
	    ['_psychic_'] => 'John',
	    ['AD7six'] => 'Andy',
	    ['jperras'] => 'Joël',
        )

)

find('threaded', $params)

find('threaded', $params) returns a nested array, and is appropriate if you want to use the parent_id field of your model data to build nested results. Below are a couple of simple (controller code) examples:

function some_function() {
   ...
   $allCategories = $this->Category->find('threaded');
   $aCategory = $this->Category->find('first', array('conditions' => array('parent_id' => 42)); // not the root
   $someCategories = $this->Category->find('threaded', array(
	'conditions' => array(
		'Article.lft >=' => $aCategory['Category']['lft'], 
		'Article.rght <=' => $aCategory['Category']['rght']
	)
   ));
   ...
}

1. function some_function() {
2. ...
3. $allCategories = $this->Category->find('threaded');
4. $aCategory = $this->Category->find('first', array('conditions' => array('parent_id' => 42)); // not the root
5. $someCategories = $this->Category->find('threaded', array(
6. 'conditions' => array(
7. 'Article.lft >=' => $aCategory['Category']['lft'],
8. 'Article.rght <=' => $aCategory['Category']['rght']
9. )
10. ));
11. ...
12. }

It is not necessary to use the Tree behavior to use this method - but all desired results must be possible to be found in a single query.

In the above code example, $allCategories will contain a nested array representing the whole category structure. The second example makes use of the data structure used by the Tree behavior the return a partial, nested, result for $aCategory and everything below it. The results of a call to find('threaded') will be of the following form:

Array
(
    [0] => Array
        (
            [ModelName] => Array
                (
                    [id] => 83
                    [parent_id] => null
                    [field1] => value1
                    [field2] => value2
                    [field3] => value3
                )

            [AssociatedModelName] => Array
                (
                    [id] => 1
                    [field1] => value1
                    [field2] => value2
                    [field3] => value3
                )
            [children] => Array
                (
		    [0] => Array
			(
			    [ModelName] => Array
				(
				    [id] => 42
		                    [parent_id] => 83
				    [field1] => value1
				    [field2] => value2
				    [field3] => value3
				)

			    [AssociatedModelName] => Array
				(
				    [id] => 2
				    [field1] => value1
				    [field2] => value2
				    [field3] => value3
				)
		            [children] => Array
				(
				)
	                )
			...
                )
        )
)

The order results appear can be changed as it is influence by the order of processing. For example, if 'order' => 'name ASC' is passed in the params to find('threaded'), the results will appear in name order. Likewise any order can be used, there is no inbuilt requirement of this method for the top result to be returned first.

There are no additional parameters used by find('threaded').

find('neighbors', $params)

'neighbors' will perform a find similar to 'first', but will return the row before and after the one you request. Below is a simple (controller code) example:

function some_function() {
   $neighbors = $this->Article->find('neighbors', array('field' => 'id', 'value' => 3));
}

1. function some_function() {
2. $neighbors = $this->Article->find('neighbors', array('field' => 'id', 'value' => 3));
3. }

You can see in this example the two required elements of the $params array: field and value. Other elements are still allowed as with any other find (Ex: If your model acts as containable, then you can specify 'contain' in $params). The format returned from a find('neighbors') call is in the form:

Array
(
    [prev] => Array
        (
            [ModelName] => Array
                (
                    [id] => 2
                    [field1] => value1
                    [field2] => value2
                    ...
                )
            [AssociatedModelName] => Array
                (
                    [id] => 151
                    [field1] => value1
                    [field2] => value2
                    ...
                )
        )
    [next] => Array
        (
            [ModelName] => Array
                (
                    [id] => 4
                    [field1] => value1
                    [field2] => value2
                    ...
                )
            [AssociatedModelName] => Array
                (
                    [id] => 122
                    [field1] => value1
                    [field2] => value2
                    ...
                )
        )
)

Note how the result always contains only two root elements: prev and next.

findAll(string $conditions, array $fields, string $order, int $limit, int $page, int $recursive)

findAll has been deprecated, use find('all') instead.

Returns the specified fields up to $limit records matching $conditions (if any), start listing from page $page (default is page 1). If there are no matching fields, an empty array is returned.

The $conditions should be formed just as they would in an SQL statement: $conditions = "Pastry.type LIKE '%cake%' AND Pastry.created_on > '2007-01-01'", for example. Prefixing conditions with the model's name ('Pastry.type' rather than just 'type') is always a good practice, especially when associated data is being fetched in a query.

Setting the $recursive parameter to an integer forces findAll() to fetch data according to the behavior described in the Model Attributes $recursive section outlined earlier. Do not forget to manually add the required foreign key columns to the $fields array as described there.

Data from findAll() is returned in an array, following this basic format:

Array
(
    [0] => Array
        (
            [ModelName] => Array
                (
                    [id] => 83
                    [field1] => value1
                    [field2] => value2
                    [field3] => value3
                )

            [AssociatedModelName] => Array
                (
                    [id] => 1
                    [field1] => value1
                    [field2] => value2
                    [field3] => value3
                )
        )
    [1] => Array
        (
            [ModelName] => Array
                (
                    [id] => 85
                    [field1] => value1
                    [field2] => value2
                    [field3] => value3
                )

            [AssociatedModelName] => Array
                (
                    [id] => 2
                    [field1] => value1
                    [field2] => value2
                    [field3] => value3
                )
        )
)

findAllBy<fieldName>(string $value)

These magic functions can be used as a shortcut to search your tables by a certain field. Just add the name of the field (in CamelCase format) to the end of these functions, and supply the criteria for that field as the first parameter.

PHP4 users have to use this function a little differently due to some case-insensitivity in PHP4:

findBy() functions like find('first',...), while findAllBy() functions like find('all',...).

In either case, the returned result is an array formatted just as it would be from find() or findAll(), respectively.

findBy<fieldName>(string $value)

These magic functions can be used as a shortcut to search your tables by a certain field. Just add the name of the field (in CamelCase format) to the end of these functions, and supply the criteria for that field as the first parameter.