CakePHP 3: Bake by example

This article is aimed at newbies to the CakePHP 3 framework.

I'm a fan of CakePHP, and was completely new to it about 9 months ago. Any framework takes some getting used to, but my biggest issue with Cake 3 is the manual. I feel it is written very much with a feeling of "you're familiar with Cake 2, so we don't need explain as much with this one".

Once you get used to using the framework however, it is a very rewarding framework, and luckily the IRC channel and cakephp-3.x tag on stack overflow is actively maintained, so you can work it out or get an answer pretty quickly.

Rather than moan about the manual, I thought I would post an example-based guide to the code generation feature, to help any other new-to-cake devs out there.

These examples are deliberately simple, they're just to get you started with the code generator, rather than just the basic list of commands currently available in the docs.

Before you use the bake command

1. Create some tables, following CakePHP conventions
2. Check you are in the root directory of your project, if you do a directory listing ls you should see folders "bin", "config", "src", "webroot"

Create a controller for a table called users

bin/cake bake controller Users

creates src/Controller/UsersController.php

Create a model (and entity) for a table called users

bin/cake bake model Users

creates src/Model/Table/UsersTable.php
creates src/Model/Entities/User.php

Create the default template files for a table (add/edit/view/index)

bin/cake bake template Users

creates src/Template/Users/index.ctp add.ctp edit.ctp view.ctp

Bake all of the above in 1 command

bin/cake bake all Users

Bake just the index template file

bin/cake bake template Users index

creates src/Template/Users/index.ctp

Baking for prefix folders (e.g. admin)

If you are baking for an admin section of your site, you will be using separate controller and template files

bin/cake bake controller Users --prefix admin

creates src/Controller/Admin/UsersController.php

bin/cake bake template Users --prefix admin

creates src/Template/Admin/Users/index.ctp edit.ctp add.ctp view.ctp

Bake from a different database

The previous examples all use the db connection defined in app.php as 'default'. If you have a legacy database for handling client records, e.g. db_records, your config file might look like this

// in config/app.php
'Datasources' => [
        'default' => [
            'host' => 'localhost',
            'username' => 'db_user',
            'password' => 'pass123',
            'database' => 'db_application',
        ],
        'records' => [
            'host' => 'localhost',
            'username' => 'db_records_user',
            'password' => 'pass123',
            'database' => 'db_records',
        ],
]

Create a model for a table called user_records in the records database

bin/cake bake model UserRecords -c records

creates /src/Model/Table/UserRecordsTable.php
creates /src/Model/Entities/UserRecord.php

This will include in your UserRecordsTable.php file

public static function defaultConnectionName()
{
    return 'records';
}

Create a model from this database for a table not following cake convention, e.g. tbl_records_user

bin/cake bake model UserRecords -c records --table tbl_records_user

creates /src/Model/Table/UserRecordsTable.php
creates /src/Model/Entities/UserRecord.php

This will add the defaultConnectionName() and also set

$this->setTable('tbl_records_user');

There are other options you can set here, but some are easier to set by editing the file afterwards. But for example, you can also set the display field to be something other than the default, e.g. email

bin/cake bake model UserRecords -c records --table tbl_records_user --display-field email

This will modify the display field

$this->setDisplayField('email');

Associations

By default the bake command will look for associations. If you are using a legacy table, or a different datasource, any field headings that end in _id might cause a 'base table or view not found' error.

To avoid this you can bake without associations

bin/cake bake model UserRecords -c records --table tbl_records_user --no-associations

Baking with a plugin

Assume you have installed a plugin such as friendsofcake/BootstrapUI so that your template files are using Bootstrap styles by default
You can now add -t BootstrapUI to any of the above commands

Create the template files using the plugin

creates /src/Template/Users/index.ctp add.ctp edit.ctp view.ctp

bin/cake bake template Users -t BootstrapUI

Create the whole MVC skeleton (controller, table, entity, templates) using the legacy database

bin/cake bake all UserRecords -c records --table tbl_records_user -t BootstrapUI

Useful Features

Bake relies on the database connection, so to save you loading up and remembering all the tables in the system, you can call a command without specifying the table name to see a list of available tables. Let's say your database has 3 tables:
users
articles
activity_logs

Using the command bin/cake bake model will produce a list of available tables

bin/cake bake model
Choose a model to bake from the following:
Users
Articles
ActivityLogs

The same goes for:

bin/cake bake controller
bin/cake bake template

Hopefully if you're using CakePHP for the first time this is a useful reference for the bake console.