For the impatient: download the bundle. You should go through this post and make sure you set up shell variables properly. They are useful and worth understanding.

Most of my PHP development is done using the CakePHP framework, and I prefer to create my own files rather than using the Bake console. Just a personal preference. My templates are already proving to save time I would spend copying/pasting code.

Automating the creation of templates will save you time. Expensive time that you don’t need to waste on repetitive stuff. You can even modify the existing templates provided in the bundle editor. I know virtually every HTML document I create will need at least one stylesheet, meta data, and scripts.

The Bundle Editor

The bundle editor provides amazing functionality to TextMate. I’m convinced that the reason I work on a Mac is TextMate and the many customizable, automated features like bundles .

To get our bundle started, fire up the bundle editor in Bundles > Bundle Editor > Show Bundle Editor. You could also use the shortcut, Control + Option + Command + B (the bottom three modifier keys + B). The bundle editor allows you to create snippets, macros, drag commands, templates, etc.

Creating the Bundle and Template

Templates require a few things to work. Firstly, a script that actually processes the template, allowing you to generate dynamic template elements on the fly—you’ll see how cool this feature is in a minute. Secondly, the actual template file that we will populate with our code.

1. Create a new bundle by clicking the “+” icon on the bottom left of the TextMate bundle editor window and select “New Bundle”. Type in the name of the bundle; mine is called “CakePHP.”
2. Now that the bundle is created, highlight it, click the “+” icon again, and select “New Template.” Enter the name of your template; mine is “Controller.”
3. Highlight the template you just created and click the “+” icon one last time. Select “New template file”. It will be highlighted, name it something that matches the template and has the extension you want (in my case “.php”)

Your bundle should look similar to mine. Now that the template script and template file are created, highlight the template file (mine is controller.php). Paste in the following code, I’ll explain it afterwards:

<?php
/**
 * Description
 *
 * Copyright ${TM_YEAR}, ${TM_ORGANIZATION_NAME}. All Rights Reserved.
 *
 * @author ${TM_FULLNAME} <${AUTHOR_EMAIL}>
 * @created ${TM_DATE_FULL}
 */
class ${TM_CLASSNAME} extends AppController {
	/**
	 *
	 */
	public $name = '${TM_NAME_PARAM}';
	/**
	 *
	 */
	public $helpers = array();
	/**
	 *
	 */
	public $components = array();

	## Public Actions

	/**
	 *
	 */
	public function index() {}

	/**
	 *
	 */
	public function view($id=null){}

	## Admin Actions

	/**
	 *
	 */
	public function admin_index() {}

	/**
	 *
	 */
	public function admin_edit($id=null){}

	/**
	 *
	 */
	public function admin_delete($id=null){}

}

In my controller template, you will notice some dynamic elements and various actions/params that I use frequently in almost every controller.

The actual class name is generated by the file’s basename (the files name minus the extension) and is called ${TM_CLASSNAME} in the template. The basename variable is automatically available to templates. Those of you familiar with CakePHP will know that controller filenames use underscores. So the “UsersController” class file would be “users_controller.php” and the basename would be “users_controller”.

The template contains a variable called ${TM_FULLNAME} which is generated by the full name of your TextMate licence. You can see this name by clicking TextMate > Registration from the menu. The field is called “Owner”.

The other variables will be created in the template script and through shell variables (Section 9.2). Shell variables are reusable variables assigned in the preferences. These are really cool, because you can use them throughout the TextMate application. You can also create project-specific shell variables in your TextMate projects. Don’t think that they merely apply for this template only!

Let’s go ahead and create/update the shell variables this template will use:

1. Navigate to TextMate > Preferences > Advanced and select Shell Variables.
2. You should see a built-in shell variable called TM_ORGANIZATION_NAME with a made-up name. Edit the value of this field with the organization you want to appear in the block comment.
3. Create a new shell variable called “AUTHOR_EMAIL” and put in your email.

You can now use ${TM_ORGANIZATION_NAME} and ${AUTHOR_EMAIL} in your templates.

Template Script

The template script is where the real magic happens in our template. Select the template script of your bundle, and you will see a few fields. Update the fields with the following (see source code below image to copy):

Here is the source for the Command(s) field:

#!/usr/bin/env ruby -wKU

# METHODS
def camelize(lower_case_and_underscored_word, first_letter_in_uppercase = true)
	if first_letter_in_uppercase
         lower_case_and_underscored_word.to_s.gsub(/\/(.?)/)
             { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
    else
    	lower_case_and_underscored_word.first.downcase +
            camelize(lower_case_and_underscored_word)[1..-1]
    end
end

f = open(ENV["TM_NEW_FILE"], 'w')
template = open("controller.php").read

ENV["TM_YEAR"] = `date +%Y`.chomp
ENV["TM_DATE"] = `date +%Y-%m-%d`.chomp
ENV["TM_DATE_FULL"] = Time.now.strftime("%m-%d-%Y %I:%M %p")
basename = ENV['TM_NEW_FILE_BASENAME']

ENV["TM_CLASSNAME"] = camelize(basename)
ENV["TM_NAME_PARAM"] = camelize(basename.split('_controller').join)

if ENV["TM_SOFT_TABS"] == "YES"
	tab_size = ENV["TM_TAB_SIZE"].to_i
	tab_size = tab_size ? tab_size : 4
	template = template.gsub(/\t/, " "*tab_size)
end

template = template.gsub(/[$]\{([^}]+)\}/){|match| "#{ENV[$1]}" }
f.write template
f.close

Note that I’m borrowing the camelize method from the Rails API

You don’t have to fully understand the ruby script I’m using, but there are a few things I’ll touch on to help you understand what is going on.

1. I wanted to customize the date to include the exact time the file was created, so I used Ruby’s Time class to create ENV["TM_DATE_FULL"] with the strftime method. I can now use it in my template as ${TM_DATE_FULL}.
2. To follow CakePHP’s convention of camel-case class names, I use the camelize method to camelize the basename of the file and assign to ENV["TM_CLASSNAME"].
3. The $name param of a CakePHP controller is the same as the class name, but omits “controller”, so I am splitting the file basename at ‘_controller’ and joining the first part back to a string; this string is also camel-cased using the camelize method.

The names match the custom fields in the template file—remember that they are case-sensitive.

Now when you create a new controller in a CakePHP project you can take advantage of your new template. Make sure all your template settings match my code above. You can test a template by clicking the “Test” button in the bundle editor template script.

We’re done. Create a new file in your TextMate project (Shift + Command + N in a project), select the template we just created from the dropdown, and click “create”.

I hope this is useful for others, it really improved my workflow. My bundle download also contains a model template too, so be sure to check out the bundle code in your new friend, the bundle editor.

Other Great Textmate Bundles

Some other textmate bundles I really cannot live without:

• Ack in Project
• Zen Coding
• TextMate Email Bundle

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 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.