The next logical step on the way from the domain model to the Cake models would be to refine the domain model to a database diagram. I say “would be” as it is something I almost never do, especially not for small projects. For me it isn’t worth the additional effort as a database diagram doesn’t add much value if you know some basic rules (Cake conventions). And well, I don’t have found a free tool for this task which convinced me ;-)

So I will go on and create the tables manually. For this purpose I will create a create.sql file in app/config/sql.

The first rule is that table names are plural. So we can write the SQL statement for the table for the “User” class (I omit the other classes as it is the same for them):

CREATE TABLE users (
);

The second rule is that each table has a primary key field with the name “id”. So we can modify the script from above to:

CREATE TABLE users (
    id INT(11) NOT NULL AUTO_INCREMENT,
    PRIMARY KEY (id)
);

The third rule is optional, but you can add the fields “created” and “modified” to the table, which are later automatically populated by CakePHP:

CREATE TABLE users (
    id INT(11) NOT NULL AUTO_INCREMENT,
    created DATETIME,
    modified DATETIME,
    PRIMARY KEY (id)
);

The fourth rule affects 1:n relations: The “n” table must contain a field named “singular name of ’1′ table” + “_id”. In our domain model the relation between User and Project is such a 1:n relation: one User can have many Projects. So we have to add the field “user_id” to the “projects” table:

CREATE TABLE projects (
    id INT(11) NOT NULL AUTO_INCREMENT,
    user_id INT(11) NOT NULL,
    created DATETIME,
    modified DATETIME,
    PRIMARY KEY (id)
);

The fifth rule affects n:n relations. Such relations cannot be mapped directly to the database, we have to introduce a join table. The name of this join table is “plural name of first ‘n’ table” + “_” + “plural name of second ‘n’ table” whereby the names are sorted alphabetically. In our domain model we have only one n:n relation, between User and Project. So the table name is “projects_users”. We also have to apply the fourth rule, as the relations between “projects” and “projects_users” resp. between “users” and “projects_users” are 1:n relations. And so we get:

CREATE TABLE projects_users (
    project_id INT(11) NOT NULL,
    user_id INT(11) NOT NULL
);

Now we can add the attributes from the conceptual classes as fields to the respective tables and write the drop statements. And we get:

CREATE TABLE users (
    id INT(11) NOT NULL AUTO_INCREMENT,
    created DATETIME,
	modified DATETIME,
    PRIMARY KEY (id)
);

CREATE TABLE projects (
    id INT(11) NOT NULL AUTO_INCREMENT,
    user_id INT(11) NOT NULL,
    created DATETIME,
    modified DATETIME,
    PRIMARY KEY (id)
);

CREATE TABLE messages (
    id INT(11) NOT NULL AUTO_INCREMENT,
    project_id INT(11) NOT NULL,
    title VARCHAR(255) NOT NULL,
    content TEXT NOT NULL,
    created DATETIME,
    modified DATETIME,
    PRIMARY KEY (id)
);

CREATE TABLE feeds (
    id INT(11) NOT NULL AUTO_INCREMENT,
    user_id INT(11) NOT NULL,
    url VARCHAR(255) NOT NULL,
    created DATETIME,
    modified DATETIME,
    PRIMARY KEY (id)
);

CREATE TABLE projects_users (
    project_id INT(11) NOT NULL,
    user_id INT(11) NOT NULL
);

And in app/config/sql/drop.sql:

DROP TABLE IF EXISTS users;
DROP TABLE IF EXISTS projects;
DROP TABLE IF EXISTS messages;
DROP TABLE IF EXISTS feeds;
DROP TABLE IF EXISTS projects_users;

To execute these SQL scripts I use a simple Ant script (app/config/sql/build.xml):

<?xml version="1.0"?>
<project name="n" default="default">
    <property name="driver" value="com.mysql.jdbc.Driver"></property>
    <property name="url" value="jdbc:mysql://localhost/n?characterEncoding=UTF-8"></property>
    <property name="user" value="root"></property>
    <property name="password" value=""></property>

    <target name="default">
        <sql driver="${driver}" password="${password}" url="${url}" userid="${user}" src="drop.sql" encoding="UTF-8"></sql>
        <sql driver="${driver}" password="${password}" url="${url}" userid="${user}" src="create.sql" encoding="UTF-8"></sql>
    </target>
</project>

After executing the Ant script, we are ready to bake the models. I will use the bake script (available in cake/scripts) to generate the User model, as I was asked to show how bake.php is used. I think it should be self-explanatory:

This will create the following model in app/models/user.php:

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

    //The Associations below have been created with all possible keys, those that are not needed can be removed
    var $hasMany = array(
        'Feed' => array('className' => 'Feed',
            'foreignKey' => 'user_id',
            'conditions' => '',
            'fields' => '',
            'order' => '',
            'limit' => '',
            'offset' => '',
            'dependent' => '',
            'exclusive' => '',
            'finderQuery' => '',
            'counterQuery' => ''),
        'Project' => array('className' => 'Project',
            'foreignKey' => 'user_id',
            'conditions' => '',
            'fields' => '',
            'order' => '',
            'limit' => '',
            'offset' => '',
            'dependent' => '',
            'exclusive' => '',
            'finderQuery' => '',
            'counterQuery' => ''),
    );

    var $hasAndBelongsToMany = array(
        'Project' => array('className' => 'Project',
            'joinTable' => 'projects_users',
            'foreignKey' => 'user_id',
            'associationForeignKey' => 'project_id',
            'conditions' => '',
            'fields' => '',
            'order' => '',
            'limit' => '',
            'offset' => '',
            'unique' => '',
            'finderQuery' => '',
            'deleteQuery' => '',
            'insertQuery' => ''),
    );
}
?>

It generates also a test case for the model in app/tests/cases/models/user.test.php:

<?php 

loadModel('User');

class UserTestCase extends UnitTestCase {
    var $object = null;

    function setUp() {
        $this->object = new User();
    }

    function tearDown() {
        unset($this->object);
    }

    /*
    function testMe() {
        $result = $this->object->doSomething();
        $expected = 1;
        $this->assertEqual($result, $expected);
    }
    */
}
?>

As you see, when using the bake script you have to answer many questions. That’s a bit of a pain when you want to bake multiple models. And if you don’t want to write tests you have to remove them (that’s at least what I do with files which are not used). These are the reasons I prefer to write the models manually.

Here are the other models (please notice that I omit the $name variable as I am a) using PHP5 and b) lazy):

// app/models/feed.php
<?php

class Feed extends AppModel {
    var $belongsTo = array('User');
}
?>

// app/models/project.php
<?php

class Project extends AppModel {
    var $hasMany = array('Message');
    var $hasAndBelongsToMany = array('User');
}
?>

// app/models/message.php
<?php

class Message extends AppModel {
    var $belongsTo = array('Project');
}
?>

To test whether we defined the associations correctly, we can create for all models the corresponding controllers. Here the UsersController (the other controllers are similar):

// app/controllers/users_controller.php
<?php

class UsersController extends AppController {
    var $scaffold;
}
?>

With that, we have something to play, we can add, edit, and remove records. But it isn’t very useful yet ;-)

That’s it for today.

(other articles from this series)

I will describe an advanced setup (i.e the core of CakePHP will be used by multiple applications) as I think it is a common setup for developers working on different projects. Such a setup involves more steps than a default setup, so if you want to do a default setup you have to skip some steps.

Get CakePHP: You can download a release of CakePHP from CakeForge, or you can get it directly via Subversion (https://svn.cakephp.org/repo/trunk resp. https://svn.cakephp.org/repo/branches/1.2.x.x for the development branch). For the application I will use the version from the development branch.

Extract archive file: For the advanced setup we only need the “cake” and “vendors” folder plus the two files “.htaccess” and “index.php”. Extract them from the archive file, it doesn’t matter where you place them. In my case, I have placed them in /home/dho/projects/cake_1.2.x.x

Bake the application skeleton: CakePHP comes with a command line tool called bake (it is available in cake/scripts) which allows you to create the application skeleton very easily. The screenshot should be self-explanatory:

Create the database: As database I will use MySQL (you could also use PostgreSQL, MS SQL Server, and some others, even though I don’t know how mature those drivers are). To create the database I use the command line tool which comes with MySQL as it is in my opinion the fastest way to create a database. As I will name the application “n” (short for notify), the database is also named “n”.

dho@tumulux:~$ mysql -u root
mysql> create database n;
mysql> quit
dho@tumulux:~$

Define database settings: First we have to rename app/config/database.php.default to database.php:

dho@tumulux:~/projects/n/trunk/app/config$ mv database.php.default database.php

And then we can define the database settings (you can remove the $test connection as it is not used):

class DATABASE_CONFIG
{
    var $default = array('driver' => 'mysql',
                                 'connect' => 'mysql_connect',
                                 'host' => 'localhost',
                                 'login' => 'root',
                                 'password' => '',
                                 'database' => 'n',
                                 'prefix' => '');
}

Edit app/webroot/index.php: In this step we have to specify the location of the Cake core. For this purpose we have to change the value of the constant CAKE_CORE_INCLUDE_PATH in app/webroot/index.php. In my case the statement is now:

define('CAKE_CORE_INCLUDE_PATH', '/home/dho/projects/cake_1.2.x.x');

Add hosts entry: For each project I have an entry in the form project.localhost in the file /etc/hosts. That allows me to use virtual hosts in Apache (see next step). For this application it looks like:

127.0.0.1    n.localhost    localhost

Add virtual host: The previous step is done so that I can use a virtual host for the application on my local machine. So I have to add the following to /etc/apache2/sites-available/default:

NameVirtualHost *
#
# other virtual hosts
#
<VirtualHost *>
    ServerName n.localhost:80
    DocumentRoot /home/dho/projects/n/trunk/app/webroot

    ErrorLog /var/log/apache2/n_error.log
    CustomLog /var/log/apache2/n_access.log combined
</VirtualHost>

Please note that the DocumentRoot points to app/webroot, i.e. only the webroot folder (and its subfolders) will be directly accessible with the browser, all other folders are not accessible.

After restarting Apache with

apache2 -k restart

we should now get the welcome screen when we go to http://n.localhost. And voilà, here it is:

Change value of CAKE_SESSION_STRING: Since revision 4565 you will get the following notice when you go to http://n.localhost:

Notice: Please change the value of CAKE_SESSION_STRING in app/config/core.php to a salt value specific to your
application in /home/dho/projects/cake_1.2.x.x/cake/bootstrap.php on line 54

So we have to do what is stated in the notice, we have to change the value of the constant CAKE_SESSION_STRING in app/config/core.php. After a reload the notice will disappear and we will get the screen as shown above.

So, mission accomplished for today. The next mission already waits…

Update (2007-03-04): Added last step “Change value of CAKE_SESSION_STRING”

If we look at the first use case “Creating a project”:

The user choses to create a new project, enters the project information, and the system creates the project.

we get the following nouns:

• user
• project
• project information
• system

The first two nouns are conceptual classes. The third noun sounds like it is an attribute of the “project” class, even though the term “information” is a bit too general. The last noun, “system” refers to the application we want to build and is therefore no conceptual class.

If we apply this approach to the other use cases we find two additional conceptual classes: message and feed.

The next step is to define the associations between those classes. We can do that textually or visually by drawing a UML diagram. I prefer the latter, as it is more clear. But first the textual version:

• A User has many Feeds
• A User has many Projects
• A User subscribes to many Projects
• A Feed belongs to a User
• A project belongs to a User
• A project is subscribed by many Users
• A Project has many Messages
• A Message belongs to a Project

And here the same as UML diagram (created with JUDE, but personally I prefer to use pen and paper as it is the fastest way to create an UML diagram):

Up to now it doesn’t matter which technology we will use to realize the application, as all steps were technology-neutral. But this will change next week when we will setup the database and start programming.

Entire series

[...] to build an application which allows [...] to notify the users of [...] code snippets about updates.

Now it is time to become more concrete and to define what our application is supposed to do. For this purpose I will write some stories/use cases. So here we go:

Creating a project: The user choses to create a new project, enters the project information, and the system creates the project.

Posting a message: The user selects a project and enters the message, which is then published by the system.

Subscribing to a project: The user selects a project and subscribes to it, so that he gets all future messages of the selected project.

Importing an external feed: The user enters the url of an external feed, so that he will get all messages provided by that feed.

There are more use cases like Unsubscribing from a project, but they are not that important at the moment.

So we can move on to identify the conceptual classes and draw the domain model. But that’s a task for tomorrow…

Every project starts with an idea of what should be accomplished.

In my case, I want to build an application which allows me to notify the users of my code snippets about updates.

A bit vague, isn’t it? Don’t worry, it will become more clear when we look at the requirements.