// app/app_model.php
class AppModel extends Model {
    function save($data = null, $validate = true, $fieldList = array(), $blackList = false) {
        if (!empty($fieldList) && $blackList) {
            $fieldList = array_diff(array_keys($this->schema()), $fieldList);
        }
        return parent::save($data, $validate, $fieldList);
    }
}

Well, I’m not that happy with his solution ;-)

Sure, it works. However, it changes the meaning of the third parameter, $fieldList, of Model::save(). By design, it represents a whitelist, i.e. you specify with this parameter, which fields should be saved. With the solution shown above, $fieldList now represents either a whitelist or a blacklist, depending on the value of the new $blackList parameter. And this dependency is not visible in the code. If you see the following statement, and you are used to CakePHP, you automatically assume the third parameter is a whitelist, because that’s the way you learned it…

$this->MyModel->save($this->data, true, array('fieldA', 'fieldB'), true);

Ok, so what’s a better solution?

I think a better solution would be to leave Model::save() “untouched” (i.e. you don’t override it), and to move the blacklist-to-whitelist transformation functionality into its own method as shown below (though I’m not sure whether this should be in the AppModel, it probably belongs to a utility class):

// app/app_model.php
class AppModel extends Model {
    public function transformToWhitelist($blacklist) {
        return array_diff(array_keys($this->schema()), $blacklist);
    }
}

The advantages of such a solution are: a) it is easier to read, b) it is probably easier to test, and c) you don’t mix responsibilities (the responsibility of a save() method is to save data, and not to transform a list into another list).

Whether it makes sense to use a blacklist when saving data is a different question. See the discussion on teknoid’s article.

I disagree with him, because visibility is one of the essential concepts of OOP. Let me explain why with a short story.

Max and Moritz both own a coke machine. And both want to make a lot of money with their machines ;-)

Max has a traditional coke machine: its basic functionality is to give you a bottle of coke after you paid for it. And from time to time Max has to replenish the machine with new bottles.

Moritz’ coke machine is slightly different: it doesn’t contain a front cover (it saves him 100 dollar). You just take a bottle of coke and then you can pay for it. And of course it has to be replenished from time to time by Moritz.

After the first day Max is happy about what he earned with his machine. And what about Moritz? He is depressed. His machine is empty. And the cash box too…

If we analyze both machines, we see that Max’ machine is successful because it only gives you access to a bottle when you paid for it.

Or to say it more generally: it is often necessary to restrict the access to something.

It is a concept you find everywhere in the real world. You don’t want that everyone drives with your car, or that everyone can get money from your bank account, and so on.

And so it makes sense to use the same concept in the software engineering world. If I want to model Max’ machine in software, I need a way to show that not everyone can access the bottles. And the same applies at the implementation level. And for this purpose it is essential to be able to distinguish between public and private (plus protected, but it doesn’t fit in the machine metaphor).

At last I want to recommend the opposite to Felix’ recommendation: Make as much as possible private or protected. Not everything has to be public!

An explicit API is usually quite self-explanatory, the method name tells you what the method does (at least, if it has a good name). Some examples from the core of CakePHP:

Model::findAll($conditions = null, $fields = null, $order = null, $limit = null, $page = 1, $recursive = null)  // deprecated
Model::findCount($conditions = null, $recursive = 0)  // deprecated
FormHelper::checkbox($fieldName, $options = array())
FormHelper::submit($caption = null, $options = array())

On the other hand, an implicit API doesn’t tell you what the method does (respectively it does it on a more abstract level):

Model::find($type, $options = array())  // new syntax
FormHelper::input($fieldName, $options = array())

In the first example, the $type parameter determines what the method does, and in the second example it depends either on the data type of the respective database field or on the value of the “type” option.

For you as a developer, implementing an implicit API means a) you have to write more code and b) you have to write more documentation (because you also have to explain what the method does)… On the other hand, an implicit API allows you to provide a unified API (e.g. Model::find(‘all’), Model::find(‘count’), and Model::find(‘list’) vs. Model::findAll(), Model::findCount(), and Model::generateList()).

For a user, an implicit API is probably more difficult to use than an explicit API, at least in the beginning. For example, if you want to get the number of some records, you first look for a method with “count” in its name. With an explicit API you will find the Model::findCount() method, but with an implicit API you probably won’t discover that Model::find() supports a “count” type…

Anyway, in the end it is up to you to decide which approach better fits to your specific situation. Both approaches have their advantages and disadvantages.

echo $form->submit('Save');

or with:

echo $form->end('Save');

The first snippet shows the generic solution to create a submit button, the second is a shortcut to create such a button at the end of a form (plus it closes the form).

At first glance this looks pretty nice. But if you think about it, you will see there is quite a price to pay: you have to write and maintain more code, you have more to document and to teach the users, and the users have more to learn…

Sometimes it is worth to pay this price, sometimes not. It’s your decision whether you are willing to pay the price.

This leads to the question: Where do you decide what is shown? In the controller or in the view?

One could argument that we have two different views, and so the controller has to decide which view to use. In this case the code would look like:

// posts_controller.php
function index() {
    $posts = $this->Post->findAll();

    if (!empty($posts)) {
        $this->set('posts', $posts);
    } else {
        $this->render('no_posts');
    }
}

// posts/index.ctp
foreach($posts as $post) {
    echo $post['Post']['title'];
}

// posts/no_posts.ctp
Sorry, no posts yet.

On the other hand one could argument that the view should decide itself how it will react if there is no data provided. Then the code looks like:

// posts_controller.php
function index() {
    $this->set('posts', $this->Post->findAll(););
}

// posts/index.ctp
if (!empty($posts)) {
    foreach($posts as $post) {
        echo $post['Post']['title'];
    }
} else {
    echo "Sorry, no posts yet.";
}

I don’t know which approach is “better”, personally I tend to the first approach where the logic is in the controller.

I found one such example as I used the core class ClassRegistry in a scenario which could be simplified as shown below:

class A {
    function id() {
        return 'A';
    }
}

class B {
    function id() {
        return 'B';
    }
}

$a = new A();
$b = new B();

ClassRegistry::addObject('test', $a);
ClassRegistry::addObject('test', $b);

$class = ClassRegistry::getObject('test');
echo $class->id();

What will be the output of this example? As you may guess the output is not “B” but “A”. Not really what you would expect. If we look at the code of the addObject method (rev. 5671) we see the reason for this result:

/**
 * Add $object to the registry, associating it with the name $key.
 *
 * @param string $key	Key for the object in registry
 * @param mixed $object	Object to store
 * @access public
 */
function addObject($key, &$object) {
    $_this =& ClassRegistry::getInstance();
    $key = Inflector::underscore($key);
    if (array_key_exists($key, $_this->__objects) === false) {
        $_this->__objects[$key] = &$object;
    }
}

An object gets only added to the registry if the respective key is not already used. If the key already exists, nothing happens and no error is thrown. So, to be sure your object gets added, you have to call removeObject() first… I don’t know why it was implemented in this way and at the moment I can’t imagine a reason why it was realized like that.

Ok, what could be done better?

The easiest and, in my opinion, the best solution is to implement it in the same way other structures to store key/value pairs work, i.e. an object with a certain key gets overwritten if a new object is added with the same key. To get this functionality, only the check for the key existence has to be removed.

If you want to keep the functionality as it is implemented now, then I think you have to do two changes: modify the API comment so that it describes what the method really does, and throw an error if someone tries to add an object with a key that already exists.

The main lesson for me from this example is: Don’t implement a known concept differently, unless you have a very good reason to do so.

loadController(null);

If you read that statement, it simply doesn’t make sense. To load a controller with the name set to null, huch? A look at the API doesn’t bring any clarification:

Loads a controller and its helper libraries.
Parameters:
string   $name Name of controller
Returns:
boolean Success

So we have to dive into the source code (which we fortunately have) to figure out what’s going on:

function loadController($name) {
    if (!class_exists('AppController')) {
        if (file_exists(APP . 'app_controller.php')) {
            require(APP . 'app_controller.php');
        } else {
            require(CAKE . 'app_controller.php');
        }
    }
    if ($name === null) {
        return true;
    }
    // load the controller
    ...
}

And we see that the AppController is loaded.

Why do I show this example here? Not to blame the developer, but because this example teaches us some lessons:

Listen to what your code tells you: By using (and allowing) “null” as parameter for the loadController function our code no longer tells us what it does. It doesn’t say “I load the AppController”, it says “I load the controller with null as name”, which is of course nonsense.

DRY (don’t repeat yourself) applies to API docs, too: If we compare the API docs for the loadController function with the function signature, we see that the function signature tells us the same as the doc comment, and is therefore redundant.

Mention unobvious stuff in the API docs: As we have seen, the obvious (and redundant) stuff is in the API docs, whereas the unobvious stuff (= loading the AppController when passing “null” as parameter) is not mentioned. So by looking at the API we can’t figure out the full functionality of the function…

Don’t do too much (in a single function): If we look at the source code of the loadController function we see that it does two different things: loading the AppController, and loading the specified controller. But as the function is about loading controllers (and not about loading the AppController), it should delegate the loading of the AppController to a loadAppController function.

$this->redirect('/users/add');

or

$this->redirect(array('controller' => 'Users', 'action' => 'add'));

As usual in software engineering, using such a pattern comes with trade-offs. On the one hand you get a flexible interface you can extend very easily by adding new keywords, and which is handy for the user as in the usual case he can simply pass a string whereas in other cases he can pass an array. On the other hand you have to write more code and it becomes more difficult to override a method using this pattern.

I don’t use that pattern often in my own stuff, but maybe it will be helpful to you.

Ok, let’s dive into the code. First a bit of context:

// snippet from View::_render()
$loadedHelpers = $this->_loadHelpers($loadedHelpers, $this->helpers);

foreach(array_keys($loadedHelpers) as $helper) {

As we move to the View::_loadHelpers() function, we detect the following statement:

return $this->cakeError('missingHelperFile', array(array(
    'helper' => $helper,
    'file' => Inflector::underscore($helper) . '.php',
    'base' => $this->base
)));

That is a bit weird, as the statement returns an error, but there was no error handling in the previous code snippet. But maybe the cakeError function just returns an empty array, who knows. So let’s have a look at the cakeError function defined in the Object class:

function cakeError($method, $messages) {
    ...
    if (class_exists('AppError')) {
        $error = new AppError($method, $messages);
    } else {
        $error = new ErrorHandler($method, $messages);
    }
    return $error;
}

No, the function doesn’t return an array. Hm. As this function returns an object, and the first snippet expects an array, then there should be some PHP errors when displaying a “missing helper file” error. But there are no PHP errors. We find the answer in the ErrorHandler class: it just shows the error message and calls “exit” to stop the script execution. And so the returns are never called…

Well, this solution would work fine as long as it is only used internally (even though it is not very elegant). But the framework allows you to write a custom error handler, and so if you want to handle a “missing helper file” error yourself, you get PHP errors when you don’t use an exit.

That’s it. I hope you learned something from this example :)

Let us imagine we want to build a simple blog application (highly imaginative, I know *g*). But what does that mean? As there is no client we can ask, we have to imagine how the application will be used:

“The user logs into the application and writes a blog post. When he finishes the post, he adds tags to the post to categorize it. Then he publishes the post.”
“The (web) surfer reads the post. and because he wants to add additional information, he writes a comment.”

As it is a simple blog application, that is everything that can be done with it ;-)

From these requirements we can extract the core objects of our application, which are:

• User
• Post
• Tag
• Comment

Those objects usually have associations among each other, which we can visualize in a domain model (I recommend to use pen and paper to draw the domain model as you will be much faster than using a software tool):

With the domain model we have an image of the part of the real world that is relevant to our application (the problem domain). Things like foreign keys, id attributes, methods, and other details are not relevant at this level.

The next step is to develop the design based on the domain model. In the CakePHP world this usually means the creation of the database design. But that is outside the scope of this article, and left as an exercise for you ;-)