The Manual¶

Activating the cache¶

By default, view caching is disabled. To activate it, you first need to change the value of CACHE_CHECK in /app/config/core.php from false to true:

<?php
define ('CACHE_CHECK', true);

<?php
var $helpers = array('Cache');

<?php
var $cacheAction = array(
    'view/23/'  => 21600,
    'view/48/'  => 21600
);

<?php
var $cacheAction = array('recalled/' => 86400);

<?php
var $cacheAction = "1 hour";

<h1> New Products! </h1>
<cake:nocache>
<ul>
<?php foreach($newProducts as $product): ?>
<li>$product['name']</li>
<?endforeach;?>
</ul>
</cake:nocache>

<?php
//Remove all cached pages that have the controller name.
clearCache('controller');

//Remove all cached pages that have the controller_action name.
clearCache('controller_action/');

//Remove all cached pages that have the controller_action_params name.
//Note: you can have multiple params
clearCache('controller_action_params');

//You can also use an array to clear muliple caches at once.
clearCache(array('controller_action_params','controller2_action_params));

Things To Remember¶

Below are a few things to remember about View Caching:

1. To enable cache you set CACHE_CHECK to true in/app/config/core.php .

2. In the controller for the views you want to cache you have to add the Cache helper to the helpers array.

3. To cache certain URLs, use $cacheAction in the controller.

4. To stop certain parts of a view from being cached, wrap them with <cake:nocache> </cake:nocache>

5. Cake automatically clears specific cache copies when changes are made to the database

6. To manually clear parts of the cache, use clearCache().

Getting Cake¶

First, let’s get a copy of fresh Cake code.

To get a fresh download, visit the CakePHP project at Cakeforge: and download the stable release.

You can also checkout/export a fresh copy of our trunk code at: https://svn.cakephp.org/repo/trunk/cake/1.x.x.x/

Regardless of how you downloaded it, place the code inside of your DocumentRoot. Once finished, your directory setup should look something like the following:

/path_to_document_root
    /app
    /cake
    /vendors
    .htaccess
    index.php
    VERSION.txt

Now might be a good time to learn a bit about how Cake’s directory structure works: check out Basic Concepts, Section

Creating the Blog Database¶

Next, lets set up the underlying database for our blog. Right now, we’ll just create a single table to store our posts. We’ll also throw in a few posts right now to use for testing purposes. Execute the following SQL statements into your database:

/* First, create our posts table: */
CREATE TABLE posts (
    id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    title VARCHAR(50),
    body TEXT,
    created DATETIME DEFAULT NOT NULL,
    modified DATETIME DEFAULT NOT NULL
);

/* Then insert some posts for testing: */
INSERT INTO posts (title,body,created)
    VALUES ('The title', 'This is the post body.', NOW());
INSERT INTO posts (title,body,created)
    VALUES ('A title once again', 'And the post body follows.', NOW());
INSERT INTO posts (title,body,created)
    VALUES ('Title strikes back', 'This is really exciting! Not.', NOW());

The choices on table and column names are not arbitrary. If you follow Cake’s database naming conventions, and Cake’s class naming conventions (both outlined in Appendix “Cake Conventions”), you’ll be able to take advantage of a lot of free functionality and avoid configuration. Cake is flexible enough to accomodate even the worst legacy database schema, but adhering to convention will save you time.

Check out Appendix “Cake Conventions” for more information, but suffice it to say that naming our table ‘posts’ automatically hooks it to our Post model, and having fields called ‘modified’ and ‘created’ will be automagically managed by Cake.

Cake Database Configuration¶

Onward and upward: let’s tell Cake where our database is and how to connect to it. This will be the first and last time you configure anything.

A copy of Cake’s database configuration file is found in /app/config/database.php.default. Make a copy of this file in the same directory, but name it database.php.

The config file should be pretty straightforward: just replace the values in the $default array with those that apply to your setup. A sample completed configuration array might look something like the following:

<?php
var $default = array('driver'   => 'mysql',
                     'connect'  => 'mysql_pconnect',
                     'host'     => 'localhost',
                     'login'    => 'cakeBlog',
                     'password' => 'c4k3-rUl3Z',
                     'database' => 'cake_blog_tutorial' );

Once you’ve saved your new database.php file, you should be able to open your browser and see the Cake welcome page. It should also tell you that your database connection file was found, and that Cake can successfully connect to the database.

A Note On mod_rewrite¶

Occasionally a new user will run in to mod_rewrite issues, so I’ll mention them marginally here. If the Cake welcome page looks a little funny (no images or css styles), it probably means mod_rewrite isn’t functioning on your system. Here are some tips to help get you up and running:

1. Make sure that an .htaccess override is allowed: in your httpd.conf, you should have a section that defines a section for each Directory on your server. Make sure the AllowOverride is set to All for the correct Directory.

2. Make sure you are editing the system httpd.conf rather than a user- or site-specific httpd.conf.

3. For some reason or another, you might have obtained a copy of CakePHP without the needed .htaccess files. This sometimes happens because some operating systems treat files that start with ‘.’ as hidden, and don’t copy them. Make sure your copy of CakePHP is from the downloads section of the site or our SVN repository.

4. Make sure you are loading up mod_rewrite correctly! You should see something like LoadModule rewrite_module libexec/httpd/mod_rewrite.so and AddModule mod_rewrite.c in your httpd.conf.

If you don’t want or can’t get mod_rewrite (or some other compatible module) up and running on your server, you’ll need to use Cake’s built in pretty URLs. In /app/config/core.php, uncomment the line that looks like:

<?php
define ('BASE_URL', env('SCRIPT_NAME'));

This will make your URLs look like www.example.com/index.php/controllername/actionname/param rather than www.example.com/controllername/actionname/param.

Create a Post Model¶

The model class is the bread and butter of CakePHP applications. By creating a Cake model that will interact with our database, we’ll have the foundation in place needed to do our view, add, edit, and delete operations later.

Cake’s model class files go in /app/models, and the file we will be creating will be saved to /app/models/post.php. The completed file should look like this:

<?php

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

?>

Create a Posts Controller¶

Next we’ll create a controller for our posts. The controller is where all the logic for post interaction will happen, and its also where all the actions for this model will be found. You should place this new controller in a file called posts_controller.php inside your /app/controllers directory. Here’s what the basic controller should look like:

<?php

class PostsController extends AppController
{
    var $name = 'Posts';
}

?>

<?php

class PostsController extends AppController
{
    var $name = 'Posts';

    function index()
    {
        $this->set('posts', $this->Post->findAll());
    }
}

?>

Creating Post Views¶

Now that we have our database connected using our model, and our application logic and flow defined by our controller, let’s create a view for the index action we defined above.

Cake views are just HTML and PHP flavored fragments that fit inside an application’s layout. Layouts can be defined and switched between, but for now, let’s just use the default.

Remember in the last section how we assigned the ‘posts’ variable to the view using the set() method? That would hand down data to the view that would look something like this:

// print_r($posts) output:

Array
(
    [0] => Array
        (
            [Post] => Array
                (
                    [id] => 1
                    [title] => The title
                    [body] => This is the post body.
                    [created] => 2006-03-08 14:42:22
                    [modified] =>
                )
         )
    [1] => Array
        (
            [Post] => Array
                (
                    [id] => 2
                    [title] => A title once again
                    [body] => And the post body follows.
                    [created] => 2006-03-08 14:42:23
                    [modified] =>
                )
        )
    [2] => Array
        (
            [Post] => Array
                (
                    [id] => 3
                    [title] => Title strikes back
                    [body] => This is really exciting! Not.
                    [created] => 2006-03-08 14:42:24
                    [modified] =>
                )
         )
)

Cake’s view files are stored in /app/views inside a folder named after the controller they correspond to (we’ll have to create a folder named ‘posts’ in this case). To format this post data in a nice table, our view code might look something like this:

<h1>Blog posts</h1>
<table>
    <tr>
        <th>Id</th>
        <th>Title</th>
        <th>Created</th>
    </tr>

   <!-- Here's where we loop through our $posts array, printing out post info -->

    <?php foreach ($posts as $post): ?>
    <tr>
        <td><?php echo $post['Post']['id']; ?></td>
        <td>
            <?php echo $html->link($post['Post']['title'], "/posts/view/".$post['Post']['id']); ?>
        </td>
        <td><?php echo $post['Post']['created']; ?></td>
    </tr>
    <?php endforeach; ?>

</table>

<?php

class PostsController extends AppController
{

    var $name = 'Posts';

    function index()
    {
          $this->set('posts', $this->Post->findAll());
    }

    function view($id = null)
    {
        $this->Post->id = $id;
        $this->set('post', $this->Post->read());
    }
}

?>

<h1><?php echo $post['Post']['title']?></h1>

<p><small>Created: <?php echo $post['Post']['created']?></small></p>

<p><?php echo $post['Post']['body']?></p>

Adding Posts¶

reading from the database and showing us the posts is fine and dandy, but let’s allow for the adding of new posts.

First, start with the add() action in the PostsController:

<?php

class PostsController extends AppController
{
    var $name = 'Posts';

    function index()
    {
         $this->set('posts', $this->Post->findAll());
    }

    function view($id)
    {
        $this->Post->id = $id;
        $this->set('post', $this->Post->read());

    }

    function add()
    {
        if (!empty($this->data))
        {
            if ($this->Post->save($this->data))
            {
                $this->flash('Your post has been saved.','/posts');
            }
        }
    }
}

?>

Data Validation¶

Cake goes a long way in taking the monotony out of form input validation. Everyone hates coding up endless forms and their validation routines, and Cake makes it easier and faster.

To take advantage of the validation features, you’ll need to use Cake’s HtmlHelper in your views. The HtmlHelper is available by default to all views at $html.

Here’s our add view:

<h1>Add Post</h1>
<form method="post" action="<?php echo $html->url('/posts/add')?>">
    <p>
        Title:
        <?php echo $html->input('Post/title', array('size' => '40'))?>
        <?php echo $html->tagErrorMsg('Post/title', 'Title is required.') ?>
    </p>
    <p>
        Body:
        <?php echo $html->textarea('Post/body', array('rows'=>'10')) ?>
        <?php echo $html->tagErrorMsg('Post/body', 'Body is required.') ?>
    </p>
    <p>
        <?php echo $html->submit('Save') ?>
    </p>
</form>

<?php

class Post extends AppModel
{
    var $name = 'Post';

    var $validate = array(

        'title'  => VALID_NOT_EMPTY,
        'body'   => VALID_NOT_EMPTY

    );
}

?>

Deleting Posts¶

Next, let’s make a way for users to delete posts. Start with a delete() action in the PostsController:

function delete($id)
{
    $this->Post->del($id);
    $this->flash('The post with id: '.$id.' has been deleted.', '/posts');
}

<h1>Blog posts</h1>
<p><?php echo $html->link('Add Post', '/posts/add'); ?></p>
<table>
    <tr>
        <th>Id</th>
        <th>Title</th>
        <th>Created</th>
    </tr>

   <!-- Here's where we loop through our $posts array, printing out post info -->

    <?php foreach ($posts as $post): ?>
    <tr>
        <td><?php echo $post['Post']['id']; ?></td>
        <td>
            <?php echo $html->link($post['Post']['title'], '/posts/view/'.$post['Post']['id']);?>
            <?php echo $html->link(
                'Delete',
                "/posts/delete/{$post['Post']['id']}",
                null,
                'Are you sure?'
            )?>
        </td>
        <td><?php echo $post['Post']['created']; ?></td>
    </tr>
    <?php endforeach; ?>

</table>

Editing Posts¶

So… post editing: here we go. You’re a Cake pro by now, so you should have picked up a pattern. Make the action, then the view. Here’s what the edit action of the Posts Controller would look like:

function edit($id = null)
{
    if (empty($this->data))
    {
        $this->Post->id = $id;
        $this->data = $this->Post->read();
    }
    else
    {
        if ($this->Post->save($this->data['Post']))
        {
            $this->flash('Your post has been updated.','/posts');
        }
    }
}

<h1>Edit Post</h1>
<form method="post" action="<?php echo $html->url('/posts/edit')?>">
    <?php echo $html->hidden('Post/id'); ?>
    <p>
        Title:
        <?php echo $html->input('Post/title', array('size' => '40'))?>
        <?php echo $html->tagErrorMsg('Post/title', 'Title is required.') ?>
    </p>
    <p>
        Body:
        <?php echo $html->textarea('Post/body', array('rows'=>'10')) ?>
        <?php echo $html->tagErrorMsg('Post/body', 'Body is required.') ?>
    </p>
    <p>
        <?php echo $html->submit('Save') ?>
    </p>
</form>

<h1>Blog posts</h1>
<p><?php echo $html->link("Add Post", "/posts/add"); ?>
<table>
    <tr>
        <th>Id</th>
        <th>Title</th>
        <th>Created</th>
    </tr>

   <!-- Here's where we loop through our $posts array, printing out post info -->

    <?php foreach ($posts as $post): ?>
    <tr>
        <td><?php echo $post['Post']['id']; ?></td>
        <td>
            <?php echo $html->link($post['Post']['title'], '/posts/view/'.$post['Post']['id']);?>
            <?php echo $html->link(
                'Delete',
                "/posts/delete/{$post['Post']['id']}",
                null,
                'Are you sure?'
            )?>
            <?php echo $html->link('Edit', '/posts/edit/'.$post['Post']['id']);?>
        </td>
        <td><?php echo $post['Post']['created']; ?></td>
    </tr>
    <?php endforeach; ?>

</table>

Routes Configuration¶

Cake’s default route will take a person visiting the root of your site (i.e. http://www.example.com) to the PagesController, and render a view called home. Rather than do that, we’ll want users of our blog application to go to our soon-to-be-created PostsController.

Cake’s routing is found in /app/config/routes.php. You’ll want to comment out or remove the line that looks like this:

<?php
$Route->connect ('/', array('controller'=>'pages', 'action'=>'display', 'home'));

This line connects the URL / with the default Cake home page. We want it to connect with our own controller, so add a line that looks like this:

<?php
$Route->connect ('/', array('controller'=>'posts', 'action'=>'index'));

This should connect users requesting ‘/’ to the index() action of our soon-to-be-created PostsController.

Conclusion¶

Keep in mind that this tutorial was very basic. Cake has many more features to offer, and is flexible in ways we didn’t wish to cover here. Use the rest of this manual as a guide for building more feature-rich applications.

Now that you’ve created a basic Cake application you’re ready for the real thing. Start your own project, read the rest of the Manual and API.

If you need help, come see us in #cakephp. Welcome to Cake!

The Big Picture¶

If you’re new to CakePHP, you’ll be strongly tempted to copy and paste this code for use in your mission critical, sensitive-data-handling production application. Resist ye: this chapter is a discussion on Cake internals, not application security. While I doubt we’ll provide for any extremely obvious security pitfalls, the point of this example is to show you how Cake’s internals work, and allow you to create a bulletproof brute of an application on your own.

Cake has access control via its built-in ACL engine, but what about user authentication and persistence? What about that?

Well, for now, we’ve found that user authentication systems vary from application to application. Some like hashed passwords, others, LDAP authentication - and almost every app will have User models that are slightly different. For now, we’re leaving it up to you. Will this change? We’re not sure yet. For now, we think that the extra overhead of building this into the framework isn’t worth it, because creating your own user authentication setup is easy with Cake.

You need just three things:

• A way to authenticate users (usually done by verifying a user’s identity with a username/password combination)

• A way to persistently track that user as they navigate your application (usually done with sessions)

• A way to check if a user has been authenticated (also often done by interacting with sessions)

In this example, we’ll create a simple user authentication system for a client management system. This fictional application would probably be used by an office to track contact information and related notes about clients. All of the system functionality will be placed behind our user authentication system except for few bare-bones, public-safe views that shows only the names and titles of clients stored in the system.

We’ll start out by showing you how to verify users that try to access the system. Authenticated user info will be stored in a PHP session using Cake’s Session Component. Once we’ve got user info in the session, we’ll place checks in the application to make sure application users aren’t entering places they shouldn’t be.

One thing to note - authentication is not the same as access control. All we’re after in this example is how to see if people are who they say they are, and allow them basic access to parts of the application. If you want to fine tune this access, check out the chapter on Cake’s Access Control Lists. We’ll make notes as to where ACLs might fit in, but for now, let’s focus on simple user authentication.

I should also say that this isn’t meant to serve as some sort of primer in application security. We just want to give you enough to work with so you can build bulletproof apps of your own.

CREATE TABLE `users` (
  `id` int(11) NOT NULL auto_increment,
  `username` varchar(255) NOT NULL,
  `password` varchar(32) NOT NULL,
  `first_name` varchar(255) NOT NULL,
  `last_name` varchar(255) NOT NULL,
  PRIMARY KEY  (`id`)
)

<?php
class User extends AppModel
{
    var $name = 'User';
}
?>

<?php if ($error): ?>
<p>The login credentials you supplied could not be recognized. Please try again.</p>
<?php endif; ?>

<form action="<?php echo $html->url('/users/login'); ?>" method="post">
<div>
    <label for="username">Username:</label>
    <?php echo $html->input('User/username', array('size' => 20)); ?>
</div>
<div>
    <label for="password">Password:</label>
    <?php echo $html->password('User/password', array('size' => 20)); ?>
</div>
<div>
    <?php echo $html->submit('Login'); ?>
</div>
</form>

<?php
class UsersController extends AppController
{
    function login()
    {
        //Don't show the error message if no data has been submitted.
        $this->set('error', false);

        // If a user has submitted form data:
        if (!empty($this->data))
        {
            // First, let's see if there are any users in the database
            // with the username supplied by the user using the form:

            $someone = $this->User->findByUsername($this->data['User']['username']);

            // At this point, $someone is full of user data, or its empty.
            // Let's compare the form-submitted password with the one in
            // the database.

            if(!empty($someone['User']['password']) && $someone['User']['password'] == $this->data['User']['password'])
            {
                // Note: hopefully your password in the DB is hashed,
                // so your comparison might look more like:
                // md5($this->data['User']['password']) == ...

                // This means they were the same. We can now build some basic
                // session information to remember this user as 'logged-in'.

                $this->Session->write('User', $someone['User']);

                // Now that we have them stored in a session, forward them on
                // to a landing page for the application.

                $this->redirect('/clients');
            }
            // Else, they supplied incorrect data:
            else
            {
                // Remember the $error var in the view? Let's set that to true:
                $this->set('error', true);
            }
        }
    }

    function logout()
    {
        // Redirect users to this action if they click on a Logout button.
        // All we need to do here is trash the session information:

        $this->Session->delete('User');

        // And we should probably forward them somewhere, too...

        $this->redirect('/');
    }
}
?>

<?php
class AppController extends Controller
{
    function checkSession()
    {
        // If the session info hasn't been set...
        if (!$this->Session->check('User'))
        {
            // Force the user to login
            $this->redirect('/users/login');
            exit();
        }
    }
}
?>

<?php
class NotesController extends AppController
{
    // Don't want non-authenticated users looking at any of the actions
    // in this controller? Use a beforeFilter to have Cake run checkSession
    // before any action logic.

    function beforeFilter()
    {
        $this->checkSession();
    }
}
?>

<?php
class NotesController extends AppController
{
    function publicNotes($clientID)
    {
        // Public access to this action is okay...
    }

    function edit($noteId)
    {
        // But you only want authenticated users to access this action.
        $this->checkSession();
    }
}
?>

Conventions, eh ?¶

Yes, conventions. According to thefreedictionary:

• General agreement on or acceptance of certain practices or attitudes: By convention, north is at the top of most maps.

• A practice or procedure widely observed in a group, especially to facilitate social interaction; a custom: the convention of shaking hands.

• A widely used and accepted device or technique, as in drama, literature, or painting: the theatrical convention of the aside.

Conventions in cake are what make the magic happen, read it automagic. Needless to say by favorizing convention over configuration, Cake makes your productivity increase to a scary level without any loss to flexibility. Conventions in cake are really simple and intuitive. They were extracted from the best practices good web developers have used throughout the years in the field of web developement.

Filenames¶

Filenames are underscore. As a general rule, if you have a class MyNiftyClass, then in Cake, its file should be named my_nifty_class.php.

So if you find a snippet you automatically know that:

• If it’s a Controller named KissesAndHugsController, then its filename must be kisses_and_hugs_controller.php (notice _controller in the filename)

• If it’s a Model named OptionValue, then its filename must be option_value.php

• If it’s a Component named MyHandyComponent, then its filename must be my_handy.php(no need for _component in the filename)

• If it’s a Helper named BestHelperEver, then its filename must be best_helper_ever.php

Models¶

• Model class names are singular.

• Model class names are Capitalized for single-word models, and UpperCamelCased for multi-word models.

  • Examples: Person, Monkey, GlassDoor, LineItem, ReallyNiftyThing

• many-to-many join tables should be named: alphabetically_first_table_plural_alphabetically_second_table_plural ie: tags_users

• Model filenames use a lower-case underscored syntax.

  • Examples: person.php, monkey.php, glass_door.php, line_item.php, really_nifty_thing.php

• Database tables related to models also use a lower-case underscored syntax - but they are plural.

  • Examples: people, monkeys, glass_doors, line_items, really_nifty_things

CakePHP naming conventions are meant to streamline code creation and make code more readable. If you find it getting in your way, you can override it.

• Model name: Set var $name in your model definition.

• Model-related database tables: Set var $useTable in your model definition.

Controllers¶

• Controller class names are plural.

• Controller class names are Capitalized for single-word controllers, and UpperCamelCased for multi-word controllers. Controller class names also end with ‘Controller’.

  • Examples: PeopleController, MonkeysController, GlassDoorsController, LineItemsController, ReallyNiftyThingsController

• Controller file names use a lower-case underscored syntax. Controller file names also end with ‘_controller’. So if you have a controller class called PostsController, the controller file name should be posts_controller.php

  • Examples: people_controller.php, monkeys_controller.php, glass_doors_controller.php, line_items_controller.php, really_nifty_things_controller.php

• For protected member visibility, controller action names should be prepended with ‘-‘.

• For private member visibility, controller action names should be prepended with ‘__’.

Views¶

• Views are named after actions they display.

• Name the view file after action name, in lowercase.

  • Examples: PeopleController::worldPeace() expects a view in /app/views/people/world_peace.thtml; MonkeysController::banana() expects a view in /app/views/monkeys/banana.thtml.

You can force an action to render a specific view by calling $this->render(‘name_of_view_file_without_dot_thtml’); at the end of your action.

Helpers¶

• Helper classname is CamelCased and ends in “Helper”, the filename is underscored.

  • Example: class MyHelperHelper extends Helper is in /app/views/helpers/my_helper.php.

Include in the controller with var $helpers = array(‘Html’,’MyHelper’); in the view you can access with $myHelper->method().

Components¶

• Component classname is CamelCased and ends in “Component”, the filename is underscored.

  • Example: class MyComponentComponent extends Object is in /app/controllers/components/my_component.php.

Include in the controller with var $components = array(‘MyComponent’); in the controller you can access with $this->MyComponent->method().

Vendors¶

Vendors don’t follow any convention for obvious reasons: they are third-party pieces of code, Cake has no control over them.