Welcome to The Cookbook

Just place your cake install inside your web server’s document root. For example, assuming your web server’s document root is /var/www/html, a development setup would look like this on the filesystem:

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

To see your CakePHP application, point your web browser to http://www.example.com/cake_1_2/

In order to utilize a production setup, you will need to have the rights to change the document root for your web server. Choosing the production setup means the whole domain acts as a single CakePHP application.

The production setup uses the following layout:

• /path_to_cake_install/
• /app
  • /webroot (this directory is set as the document root for the web server)
• /cake
• /docs
• /index.php
• /vendors

If this application was going to be hosted on Apache, the DocumentRoot directive for the domain would look something like:

DocumentRoot /path_to_cake_install/app/webroot

1. DocumentRoot /path_to_cake_install/app/webroot

To see your CakePHP application, point your web browser to 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 path 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'.DS.'cake');
}

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'.DS.'cake');
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();

1. $viewPaths = array();
2. $controllerPaths = array();
3. $modelPaths = array();
4. $helperPaths = array();
5. $componentPaths = array();
6. $behaviorPaths = 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:

• Make sure that an .htaccess override is allowed. In your httpd.conf, you should have a section that defines your Directory on the server. Make sure the AllowOverride is set to All for the correct DocumentRoot.
• Make sure you are editing the system httpd.conf rather than a user- or site-specific httpd.conf.
• Is CakePHP missing its needed .htaccess files? This sometimes happens during copying or moving because some operating systems treat files that start with '.' as hidden. Make sure your copy of CakePHP is from the downloads section of the site or our SVN repository, and has been unpacked correctly.
• Make sure you are loading up mod_rewrite correctly. You should see something like LoadModule rewrite_module libexec/httpd/mod_rewrite.so (Unix/Linux users should also see something like AddModule mod_rewrite.c) in your httpd.conf. Also make sure that those lines have not been commented out (by being prepended with a #). Restart Apache to make sure your conf settings are active.
• If you are installing CakePHP into a user directory (http://example.com/~username), you'll need to modify the .htaccess file in the base directory of your CakePHP installation. Just add the line "RewriteBase /~myusername/".

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.