In the meantime there is also a migrations-like feature in the Cake core, even though it seems to be a bit half-baked (or maybe I’m too stupid to understand it *g*).

Anyway, let’s have a look at it by using the traditional blog example.

First, we create a file which will contain the definitions for our schema. We name the file blog.php and place it in app/config/sql. In this file we create a class BlogSchema:

class BlogSchema extends CakeSchema {
}

Each property of a schema class represents a table, i.e. the property name is the table name, and the property value contains the table definition as an array. The definition for our posts table looks like:

class BlogSchema extends CakeSchema {
    public $posts = array(
        'id' => array('type' => 'integer', 'null' => false, 'default' => NULL, 'key' => 'primary'),
        'title' => array('type' => 'string', 'null' => false, 'length' => 100),
        'content' => array('type' => 'text', 'null' => false),
        'indexes' => array('PRIMARY' => array('column' => 'id', 'unique' => 1))
    );
}

Now, we can switch to the command line and make a test run to verify the schema script will execute the correct SQL statements:

cd cake/console
./cake schema run create blog -dry

---------------------------------------------------------------
Cake Schema Shell
---------------------------------------------------------------
Performing a dry run.

The following tables will drop.
posts

Are you sure you want to drop the tables? (y/n)
[n] > y
Dropping tables.
Dry run for posts :
DROP TABLE IF EXISTS `posts`;

The following tables will create.
posts

Are you sure you want to create the tables? (y/n)
[y] > y
Creating tables.
Dry run for posts :
CREATE TABLE `posts` (
        `id` int(11) NOT NULL AUTO_INCREMENT,
        `title` varchar(100) NOT NULL,
        `content` text NOT NULL,
        PRIMARY KEY  (`id`)
);

End create.

Everything looks fine, so we can run the same command again, this time without the -dry parameter, and it should create the posts table.

Ok, now let’s add a new column “created” to our schema:

class BlogSchema extends CakeSchema {
    public $posts = array(
        'id' => array('type' => 'integer', 'null' => false, 'default' => NULL, 'key' => 'primary'),
        'title' => array('type' => 'string', 'null' => false, 'length' => 100),
        'content' => array('type' => 'text', 'null' => false),
        'created' => array('type' => 'datetime'),
        'indexes' => array('PRIMARY' => array('column' => 'id', 'unique' => 1))
    );
}

To introduce the new column we could use the command from above, which drops the table and recreates it. Or we could use the update command, which performs an “ALTER TABLE” statement to synchronize the posts table in the database with the posts table from the schema file:

./cake schema run update blog

---------------------------------------------------------------
Cake Schema Shell
---------------------------------------------------------------
Comparing Database to Schema...

The following statements will run.
ALTER TABLE `posts`
        ADD `created` datetime DEFAULT NULL;

Are you sure you want to alter the tables? (y/n)
[n] > y

Updating Database...
posts updated.
End update.

With that, our blog database is up-to-date.

Unfortunately, the update command doesn’t work if you add a new table to the schema file, it doesn’t create this new table in the database. And so I think the migration process is currently not that useful in practice…

I used a question mark in the title of this article, as I am not sure if what I described here is really the correct way to use the schema feature. Please correct me, if I am wrong :)

The usage of the script is simple (even though I have to admit I understood it only after Mariano Iglesias‘ explanations *g*):

cake api [<path>] <classname>

<path> is optional, but if it is used it has to be one of the following values: “behavior”, “cache”, “controller”, “component”, “helper”, “model”, or “view”. So if you want to show the method signatures of the FormHelper, you would use this command:

cake api helper FormHelper

If no <path> is specified, the script looks in the cake/libs folder for the specified class.

Personally, I think it won’t be very useful for me, because I can request the more detailed online API documentation of a class with a simple url:

http://api.cakephp.org/1.2/class_<underscored_class_name>.html

Btw: On the @TheKeyboard blog the grumpy guy (aka Chris Hartjes) has published a short screencast to introduce another core shell script: the console.

With the recent changes a new concept has been introduced: Tasks. Well, tasks are not entirely new as tasks were already used by bake2 (which no longer exists). But now tasks are for shells what components are for controllers.

Tasks are placed in app/vendors/shells/tasks if they are application-specific resp. in vendors/shells/tasks if they are general-purpose tasks. Like shell scripts, task classes have to extend the “Shell” class, but the class name has to end with “Task”. Here a simple example of a task:

// vendors/shells/tasks/test.php
class TestTask extends Shell {

    function execute() {
        // do something
    }
}

In the core tasks (and in this test task) the main function is called “execute”, but you are free to use any name you want.

The test task can now be used in the shell script in the following way:

// vendors/shells/demo.php
class DemoShell extends Shell {
    var $tasks = array('Test');

    function initialize() {
        // empty
    }

    function main() {
        $this->Test->execute();
    }
}

Happy baking :)