In the first tutorial, I covered basic foundations of views, and set out create a simple task management application. This tutorial will focus on controllers, which interact with both views and models. The process of the MVC framework is a simple paradigm, where controllers handle requests, get data from the model as needed, and process the request by giving feedback to the user through views. Controllers play an important middle-man role in MVC applications.

To help illustrate the role controllers play, consider a bank. Customers request information from the bank through ATMs, online banking websites, and bank employees. Customers don’t have direct access to the bank’s safe, they must request this information from ATMs and bank tellers, etc. ATMs and tellers represent the controller in our analogy. They facilitate the requests of customers by accessing account information and money. This information is then processed and returned to the customer. In the same way, users of an MVC application make requests to the controller through views. These requests are received by the controller. The controller requests data from the database through models. Controllers then return data to views.

CakePHP controllers work closely with models to facilitate data from the database. This means we need to create a database and a table to get our controller working. We could bypass the model (controllers don’t technically need models in some cases) and just use our controller, but that would only be confusing to those learning the importance of controllers in working with both models and views.

Lets start by creating a database. For simplicity, lets name the database “taskmaster” (I know, totally cheezy :-/). You should have a working MySQL database server running. This tutorial will not go into the details of setting up MySQL and PHP. Fire up your favorite MySQL management tool, or use the handy terminal if that suits you. I’m going to type the following to login via the terminal:

mysql -u root -p

MySQL will prompt you for a password. Once you type in your password (default is blank, or no password) you will see the mysql prompt. Type in:

create database taskmaster;

Don’t forget the semi-colon! Verify that the database was created by typing in:

show databases

Now that we have our database created, lets create a table. Enter the following query to create your first table.

CREATE TABLE `tasks` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `description` varchar(255) NOT NULL,
  `completed` tinyint(1) DEFAULT '0',
  `created` datetime,
  `modified` datetime,
  PRIMARY KEY (`id`)
);

This might seem like a simple table, but there are a few important conventions that CakePHP will reward. The table name “tasks” will ensure that we can create a controller called “TasksController” and a model called “Task”. We don’t have to do much configuration to start working with our data if we use these naming conventions. The lowercase id field is standard on any table in CakePHP. Created and modified columns will be automatically updated by CakePHP when we save a new record or update one. We don’t even have to worry about these columns when saving data.

Lets create a few records so we have actual data to retrieve from our model via the controller. Run the following queries to get some tasks in the tasks table:

INSERT INTO tasks (description, created, modified)
    VALUES ('Take out the trash.', NOW(), NOW());
INSERT INTO tasks (description, created, modified)
    VALUES ('Wash the car.', NOW(), NOW());

Note: I added NOW() twice to simulate what CakePHP will do when we create a new task within the application.

Now that our table is created and has a few tasks entered, lets jump over to our CakePHP application. The first order of business is telling CakePHP about our database. Navigate to app/config/database.php and change the default connection to match your database information. Mine looks like the following:

var $default = array(
	'driver' => 'mysql',
	'persistent' => false,
	'host' => 'localhost',
	'login' => 'root',
	'password' => '',
	'database' => 'taskmaster',
	'prefix' => '',
);

Create a new file in app/controllers called tasks_controller.php and populate with the following code:

<?php
class TasksController extends AppController {
	public $name = ‘Tasks’;
	
	public function index() {

	}
}

I’ve added an empty function for our default action. As you will see shortly, functions in controllers are actions requested by users through a URL. Index is the default action for any controller unless you specify otherwise in app/config/routes.php. Controller class names are camel-cased, and the file names use underscores, which is why TasksController’s filename is tasks_controller.php. Controllers are generally named the same as the name of the database table.

Now we need to create a model file. Create a new file in app/models called task.php and populate with the following:

<?php
class Task extends AppModel {
	public $name = ‘Task’;
}

We now have a skeleton model and controller. Since we have data, lets write our controller code to get our tasks from the database and then display them in the view. Our controller will request tasks from the tasks table, and for now, we will request all tasks (we only have two so far after all). Your tasks controller will look like this:

<?php
public function index() {
	$tasks = $this->Task->find('all');
	$this->set('tasks', $tasks);
}

We are getting all tasks in the database, using the Task model. $this->Task represents the model we just created. Both our controllers and models inherit a bunch of built-in functionality from AppController and AppModel.
$this->Task->find() is one such method. The controller then sets a variable for the view called “tasks” and is populated with an associative array that was returned from the find method. We have everything we need to display model data in the view…let’s get going!

Create a folder in app/views called tasks. This folder name also matches the controller name, which keeps our views organized. In the newly created folder, create a file called index.ctp, which matches our index function in TasksController, and paste the following:

<h1>Tasks</h1>
<table>
	<thead>
		<tr>
			<th scope="col">Id</th>
			<th scope="col">Description</th>
			<th scope="col">Complete?</th>
			<th scope="col">Created</th>
			<th scope="col">Modified</th>
		</tr>
	</thead>
	<tbody>
	<?php foreach($tasks as $task):
		$completed = $task['Task']['completed'] == FALSE ? 'No' : 'Yes';
	?>
		<tr>
			<td><?php echo $task['Task']['id']; ?></td>
			<td><?php echo $task['Task']['description']; ?></td>
			<td><?php echo $completed; ?> </td>
			<td><?php echo $task['Task']['created']; ?></td>
			<td><?php echo $task['Task']['modified']; ?></td>
		</tr>
	<?php endforeach; ?>
	</tbody>
</table>

You can now see the index action of our controller by navigating to the url of your application. Mine is http://localhost/cakephp-designers/tasks. The url contains our controller name “tasks”. You can omit the “index” action from the url because, like I mentioned above, index is the default action.

To illustrate how URLs match functions in a controller, you can navigate to http://localhost/cakephp-designers/tasks/index and get the same page. An add action might have this URL: http://localhost/cakephp-designers/tasks/add and would call a function called “add” in the TasksController class.

Our plain vanilla table has a foreach loop that loops through the data supplied from the controller that was assigned to a variable called tasks. It is important to understand the array structure that CakePHP returns when retrieving data from models. You can view the array by adding debug($tasks); in the view. You must have debugging turned on to see the array. You will notice that each record is contained in an associative array, where the key matches the model, or “Task”.

We now have a very simple, but functional controller. Our next tutorial will focus on learning about the form helper, getting data into our database from a form, validating that data through the model, and furthering your understanding of models and controllers in general. Until next time!

CakePHP for web designers, is a series of hands-on tutorials that help new programers and those with a design background understand the basics of CakePHP. There is plenty of theory and API documentation out there on the web; I’d rather spend my time writing about hands-on examples of how you can start using CakePHP today.

CakePHP hits the sweet-spot for many of my projects. The conventions and “baked” in classes are huge productivity boosters. Even if you just intend of working with visual elements on a CakePHP project (views), this series will walk you through hands-on lessons of building a simple task management application with CakePHP.

Installing CakePHP

This series is focused on working with CakePHP, so I don’t want PHP installation interfering with the content of this series. I’ve included installation notes at the bottom of this tutorial to get Apache, PHP, MySQL going. For a full explanation of how to get CakePHP set up properly, see section 3.1, 3.2, 3.3 and 3.4 of the CakePHP book.

In a nutshell, you will download CakePHP’s latest stable version at http://cakephp.org and upload the files somewhere inside the apache document root on your development machine. I’ve installed a fresh version on http://localhost/cakephp-designers/

What you see in screenshot #1 is the default CakePHP page with info about your environment configuration. Obviously, we don’t want this to be the homepage of our website, but it’s nice to see something when we get CakePHP installed correctly. This page has useful information about your configuration, and potentially, gives you warnings of steps you missed during setup.

CakePHP applications follow the MVC software design pattern which we will tackle later in this series. Learning the MVC software paradigm is essential to using CakePHP, and the payoff is clean code that is more secure and easier to maintain. This post will be focusing on the “V” in MVC, or the View.

Navigate to your project’s app > views folder. Create a folder called “pages” and inside pages, create a file called “about.ctp”. The file extension “.ctp” is CakePHP view files and accepts HTML and PHP code. Lets add a basic placeholder for our about page in about.ctp:

<h1>About</h1>
<p>This is the about page for our application</p>

Navigate to your newly create page by navigating to your project url. Mine is http://localhost/cakephp-designers/pages/about Notice that our page is displaying much more than our simple HTML. View the source and you will see the entire HTML structure of your project. The doctype and other HTML code belong to the layout.

Your Layout

Right now our project is using the built-in CakePHP layout, but we want to work with our own layout. By default, CakePHP looks for default.ctp in app > views > layouts but if you look in your project you will not find default.ctp anywhere. Create default.ctp and throw in the following HTML:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
	<title>Tasks</title>
</head>
<body>
	<?php echo $content_for_layout; ?>
</body>
</html>

Nothing special here except $content_for_layout. This variable is the output of your view. If you browse to your about page now, you will see the new template in action, and and unstyled site.

Create two more pages, in app > views > pages called index.ctp and contact.ctp and paste in the following:

<h1>Contact Us</h1>
<p>Contact info for our application will go here.</p>

and

<h1>Welcome!</h1>
<p>Welcome to my task management site.</p>

Linking

Now we have three separate pages, but no way to navigate between each page. CakePHP has a built-in helper called the HTML Helper that makes navigation links within a CakePHP application a breeze; and you can be certain that your links will always work when you follow conventions, no matter where the application resides.

We could easily create static anchor tags and call it a day, but we would be penalized in the future when we update our routes.php file or if we moved the application to another location. With static HTML links, all links would have to be manually updated each time routes.php was modified with a custom URL pattern.

Lets build the navigation using CakePHP conventions. Open default.ctp and add the navigation to this file so it will always appear in any view using default.ctp:

<div id="navigation">
	<?php echo $html->link('Home', 
            array('controller' => 'pages', 'action' => 'index')); ?> |
	<?php echo $html->link('About', 
            array('controller' => 'pages', 'action' => 'about')); ?> |
	<?php echo $html->link('Contact Us',
            array('controller' => 'pages', 'action' => 'contact')); ?>
</div>

If you view your project in a web browser, you will notice the magic that CakePHP performed. All the links were generated with the correct url. Unfortunately, if you click on the home link, it goes to the default CakePHP screen. We can fix that with routes.php.

Routes

Routes are an advanced topic, so we will only lightly touch on their power. Routes enable you to do magical things with your URLs and how those URLs relate to your application logic. For now, we only want our index.ctp file to be the homepage our our application. Open routes.php in app > config folder. Around line 34, you should see the default route for the homepage. Lets modify it from this:

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

to this:

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

Save and close routes.php. Make sure you only modify the above code–this file is critical to CakePHP. The routes.php file now considers index.ctp the homepage of the application, and you will now see your homepage in your web browser.

Styling Your Application

To conclude this tutorial, lets add some basic styles to our application. Your website assets are all located in app > webroot in their respective folders. The Webroot folder is the webroot of your application, so http://localhost/cakephp-designers/css in our project points to app > webroot > css.

Browse to app > webroot > css and create a file called style.css. You will also notice cake.generic.css which is the default css file used on the default homepage.

Add the following CSS rules to style.css:

body {
	background: #ddd;
	font: 12px "Lucida Grande", "Trebuchet Ms", sans-serif;
}
#wrap {
	margin: 20px auto;
	background: #fff;
	width: 800px;
}
#navigation, #footer {
	background: #333;
	padding: 8px 10px;
	color: #fff;
}
#navigation a {
	color: #fff;
	text-decoration: none;
	font-size: 14px;
	margin: 0 15px;
}
#content {
	padding: 5px 20px;
}
#content h2 {
	margin: 0;
}
#footer {
	font-size: 11px;
}

Update default.ctp to match the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
	<title>Tasks</title>
	<?php echo $html->css(array('style.css')); ?>
</head>
<body>
	<div id="wrap">
		<div id="navigation">
			<?php echo $html->link('Home', 
                            array('controller' => 'pages',
                            'action' => 'index')); ?> |
			<?php echo $html->link('About',
                            array('controller' => 'pages',
                            'action' => 'about')); ?> |
			<?php echo $html->link('Contact Us',
                            array('controller' => 'pages',
                            'action' => 'contact')); ?>
		</div>
		<div id="content"><?php echo $content_for_layout; ?></div>
		<div id="footer">
                    Copyright © <?php echo date("Y"); ?>. All Rights Reserved.
                </div>
	</div>
</body>
</html>

There are some new things in default.ctp that you might have noticed. In the of the document, I used another HTML helper method called “css” which generates a link tag to each css file listed in the array. This method automatically links to our css files in the webroot folder. This requires no additional configuration in the future, and is an important convention in CakePHP. I also threw in a date() function to show off vanilla PHP in our templates =).

Now our application is beginning to look alive, but in a boring, static way. Our next tutorial in this series will fix that, as we cover models and controllers. We must cover both simultaneously as models and controllers work closely together to deliver dynamic data in view files.

Conclusion

We just tapped the surface of the powerful features of CakePHP views. CakePHP has made it easier to create a consistent workflow for designers and developers. As you will begin to understand, following CakePHP and MVC conventions make life easier for future developers working on your applications.

We’ve covered a vast amount in a short span, but most of the learning will come from experimenting and diving into the code. Please feel free to ask questions in the comments or email me directly.

Notes:
CakePHP has a few requirements (http://book.cakephp.org/view/28/Requirements), which will work with pretty much any machine. In a nutshell, you need to configure Apache (enable mod_rewrite), PHP 5, and MySQL to get CakePHP going. CakePHP is flexible and compatible with both PHP 4 and PHP 5. Please use PHP 5. Please? Thank you.

My favorite guide for installing Apache, PHP, and MySQL is contained in PHP Solutions by David Powers. I recommend purchasing this book if you are just learning how to program PHP. David Powers is a wonderful instructor, and the book does a marvelous job of teaching new programmers PHP. Other more simple solutions include MAMP (mac) and PHP on Windows for Windows users. I am assuming Linux users can get LAMP going and don’t need advice

Depending on your configuration, you might need to add RewriteBase /path/to/your/cake/files/ to each of your .htaccess files to get CakePHP url rewriting to work properly. If you give up on getting this working, you can open app > config > core.php and uncomment line #57 //Configure::write(‘App.baseUrl’, env(‘SCRIPT_NAME’));. You must also delete all .htaccess files to not use mod_rewrite.