That’s when I realized it could be a usability issue. And that the “user interface” of the component is simply not understood by the users… Anyway, this post is not about possible problems of the Auth component.

What I want to talk about is, as the title says, usability-driven development. If you hear “usability”, you probably associate it with user interfaces and how people interact with them. And so usability-driven development will probably deal with making better user interfaces. That’s correct. But it is not about user interfaces like web pages, it is about “user interfaces” of code components.

I know, it sounds a bit strange. But on an abstract level you can look at the public attributes and methods plus the comments as the user interface of a code component. And the programmer, who uses the component, interacts with this user interface. You may imagine a component as a beverage vending machine: methods are buttons, method names are the button labels, and comments are descriptions of the buttons. I know, this thought model is a bit inaccurate, as parameters and attributes are missing. But it shouldn’t matter.

By doing some thought experiments with our imaginary beverage vending machine we can come up with the following conclusions:

• too many descriptions suck as nobody likes to read much before he can use something
• good button labels help to avoid unnecessary descriptions
• too many buttons suck as it makes it harder to find the desired button
• the order of buttons matters as it is faster to find the desired button when the buttons are ordered
• as it is a beverage vending machine it shouldn’t provide food

These conclusions can be easily translated back to code. By doing this we will see that a lot of code is not optimal from a usability point of view…

To get more concrete results (e.g. whether two methods without parameters are better than a single method with a parameter) we could introduce some metrics into our thought model, e.g. the time it takes to accomplish something.

Ok, what can you do to improve the usability of your code?

I think the most important point is to get a mindset that your code components are user interfaces for others and that you want to provide a good user experience to them. So you will design your components differently (compare it with the iPod vs. traditional MP3 players).

It is also a good idea to follow good coding practices like testing and refactoring.

And last, but not least, you could do usability tests. Give your component to someone else who never used it and let him accomplish a task while you watch. It may give you some good insights into what sucks with your component ;-)

Ok, I hope it was not too confusing. And maybe you will now look differently at your code ;-)

So, how to deal with such a situation?

I think the most important step is to reduce the activity which makes you unhappy as soon as possible to avoid something worse like a breakdown or a burn out. Don’t stave it off, there is never an ideal time for such things!

The next step is to define what you want to do in the future. Should you still program? And if yes, how much? And what else could you do to earn money in the future? Difficult questions. Questions to which I don’t have answers yet…

From the answers to those (and probably other) questions you can then derive goals and a strategy to achieve them. The last step is to implement this strategy.

As you see, life comes with ups and downs. Nobody likes downs, but I think they are a good opportunity to learn. And the next up comes surely ;-)

• English is the defacto standard language for code. Almost all programming languages, frameworks and libraries use English for their APIs
• Code written in one language is easier to read than code that mixes two languages (I think you wouldn’t like it if I would mix german and english words in my posts *g*)
• Code written in a non-english language excludes a lot of programmers from understanding your code, with the following consequences:
  • It is more difficult to get help in newsgroups, forums, etc.
  • It is more difficult to outsource the development of parts of your application
  • Your framework or library won’t be used

You see, there are more disadvantages than advantages when using a non-english language for your code. So there is no reason to stick to your non-english language anymore (except for maintenance purposes).

• all data are stored in one place: the database
• it is easier to test
• it is easier to develop as I do not have to keep database and file system in sync

Enough of bla-bla, let us dive in the code. First the table definition for MySQL:

CREATE TABLE my_files (
  id INT(11) NOT NULL AUTO_INCREMENT,
  name VARCHAR(75) NOT NULL,
  type VARCHAR(255) NOT NULL,
  size INT(11) NOT NULL,
  data MEDIUMBLOB NOT NULL,
  created DATETIME,
  modified DATETIME,
  PRIMARY KEY (id)
);

Note: Use MEDIUMBLOB or LONGBLOB as data type unless you know for sure that the file size of the uploaded files is never bigger than 64kB.

The model is straight-forward:

// app/models/my_file.php
class MyFile extends AppModel {
    var $name = 'MyFile';
}

We omit the controller for the moment and create directly the view:

// app/views/my_files/add.ctp  (Cake 1.2)
<?php
    echo $form->create('MyFile', array('action' => 'add', 'type' => 'file'));
    echo $form->file('File');
    echo $form->submit('Upload');
    echo $form->end();
?>

// app/views/my_files/add.thtml (Cake 1.1)
<form action="/my_files/add" enctype="multipart/form-data" method="post">
    <?php echo $html->file('File'); ?>
    <?php echo $html->submit('Upload'); ?>
</form>

So, now we are ready to build the controller and to implement the add() function:

// app/controllers/my_files_controller.php (Cake 1.2)
class MyFilesController extends AppController {
    function add() {
        if (!empty($this->data) &&
             is_uploaded_file($this->data['MyFile']['File']['tmp_name'])) {
            $fileData = fread(fopen($this->data['MyFile']['File']['tmp_name'], "r"),
                                     $this->data['MyFile']['File']['size']);

            $this->data['MyFile']['name'] = $this->data['MyFile']['File']['name'];
            $this->data['MyFile']['type'] = $this->data['MyFile']['File']['type'];
            $this->data['MyFile']['size'] = $this->data['MyFile']['File']['size'];
            $this->data['MyFile']['data'] = $fileData;

            $this->MyFile->save($this->data);

            $this->redirect('somecontroller/someaction');
        }
    }
}

// app/controllers/my_files_controller.php (Cake 1.1)
class MyFilesController extends AppController {
    function add() {
        if (!empty($this->params['form']) &&
             is_uploaded_file($this->params['form']['File']['tmp_name'])) {
            $fileData = fread(fopen($this->params['form']['File']['tmp_name'], "r"),
                                     $this->params['form']['File']['size']);
            $this->params['form']['File']['data'] = $fileData;

            $this->MyFile->save($this->params['form']['File']);

            $this->redirect('somecontroller/someaction');
        }
    }
}

Easy, isn’t it? Up to now we have stored the file in the database. To retrieve the file from the database, we need a download() action which we add to our controller:

function download($id) {
    Configure::write('debug', 0);
    $file = $this->MyFile->findById($id);

    header('Content-type: ' . $file['MyFile']['type']);
    header('Content-length: ' . $file['MyFile']['size']); // some people reported problems with this line (see the comments), commenting out this line helped in those cases
    header('Content-Disposition: attachment; filename="'.$file['MyFile']['name'].'"');
    echo $file['MyFile']['data'];

    exit();
}

Well, I know that this action is probably not very cake-like, the proper way would be to use a layout and a view, but this way I have less to write ;-)

So, that’s it. We have finished our very simple upload/download application.

Update (2006-08-05): Fixed a security hole in the code above, see also “Be careful with file uploads”. Thanks to Lamby.
Update (2007-06-09): Fixed a small bug in the download function. Thanks to Wilhelm Raab!
Update (2007-10-15): The name “File” led to problems with the core class with the same name, hence I renamed table name, model name, etc. Thanks to “fyi” for the hint!
Update (2007-12-11): Updated for CakePHP 1.2.
Update (2009-02-20): Adding comment to the header(‘Content-length’) statement in the download method

I have already written about defining conditions in RC6, but unfortunately, most of it is no longer valid ;-) So, in this post I will show the current way of defining conditions.

First some examples using the array syntax:

$this->User->find('all', array('conditions' => array('User.firstname' => 'Daniel')));
$this->User->find('all', array('conditions' => array('User.firstname LIKE' => '%an%'));
$this->User->find('all', array('conditions' => array('User.age >' => 18));

When using several conditions in the array, they are combined with an “AND”.

[removed old stuff which no longer works]

The most flexible way is to use a simple string with your condition(s). In this case you have to single quote the values, as shown in the example:

$this->User->find('all' => array('conditions' => array("User.firstname = 'Daniel' OR User.firstname = 'Hugo'")));

Let us write a model for a contact form, where the user must enter an email address and a text. This is our model for the moment:

<?php
    class Contactrequest extends AppModel
    {
    }
?>

What could go wrong with our model? Theoretically nothing, as we have not written anything. But in reality, we do not know if the framework works as expected, as there are almost no test cases for the framework available. So let us test if we can save our model.

<?php
class ContactrequestTest extends UnitTestCase
{
	var $model;
	var $validEmail = 'dho@xy.com';
	var $validComment = 'hello';

	function setUp()
	{
		$this->model =& new Contactrequest();
		$this->model->query('DELETE FROM contactrequests');
	}

	function testSave()
	{
		$this->model->data = array('Contactrequest' => array('email' =>
                                        $this->validEmail, 'comment' => $this->validComment));

		$this->assertTrue($this->model->save());
		$id = $this->model->getLastInsertId();
		$modelData = $this->model->find(array('id' => $id));
		$this->assertEqual($modelData['Contactrequest']['email'],
                                               $this->validEmail);
		$this->assertEqual($modelData['Contactrequest']['comment'],
                                               $this->validComment);
	}
}
?>

If we run this test case, we get a green bar. Cool! So we go on and write tests to ensure that contact requests with an invalid email address or an empty comment cause a validation error.

function testSaveWithEmptyComment()
{
    $this->model->data = array('Contactrequest' => array('email' =>
                                                    $this->validEmail, 'comment' => ''));

    $this->assertFalse($this->model->save());
    $this->assertFalse(isset($this->model->validationErrors['email']));
    $this->assertEqual($this->model->validationErrors['comment'], '1');
}

function testSaveWithInvalidEmail()
{
    $this->model->data = array('Contactrequest' => array('email' =>
                                                   'dho@xy', 'comment' => $this->validComment));

    $this->assertFalse($this->model->save());
    $this->assertFalse(isset($this->model->validationErrors['comment']));
    $this->assertEqual($this->model->validationErrors['email'], '1');
}

Ok, we can run our test case. We get, as expected, a red bar (because we have not defined any validation rules in our model). So we add the validation rules to our model:

<?php
    class Contactrequest extends AppModel
    {
        var $validate = array('email' => array(array(VALID_EMAIL)),
                                            'comment' => array(array(VALID_NOT_EMPTY)));
    }
?>

(Notice: The definition of the validation rules is slightly different from the standard way as I use the validation approach I described in an earlier post)

And now we run our testcase again: a green bar! With that we have finished our first tested model.

$this->User->findAll(array('User.firstname' => '= Daniel'));
$this->User->findAll(array('User.firstname' => 'LIKE %an%'));
$this->User->findAll(array('User.age' => '> 18'));

To make them work again, we have to add a space to the values:

$this->User->findAll(array('User.firstname' => ' = Daniel'));
$this->User->findAll(array('User.firstname' => ' LIKE %an%'));
$this->User->findAll(array('User.age' => ' > 18'));

There are also some new features. By default, all conditions are concatenated with “AND”. If you want to use an “OR”, you have to do it in the following way:

$this->User->findAll(array('User.firstname' => ' = Daniel',
                                               ' OR User.firstname' => ' = Hugo'));

It is now also possible to use “–return” for a value, i.e. your value will not be quoted by CakePHP. Example:

$this->User->findAll(array('User.firstname' => "--return = 'Daniel'"));

Update (2006-02-28): The examples in this post are no longer valid!

$this->User->findAll('--return User.company_id = 1');

That generates something like

... WHERE User.company_id = 1 ...

That feature is useful if you have complex conditions you cannot express in another way with CakePHP. But be careful using it if your application should work with different databases.

The more important change is the way you can specify the conditions. Some examples:

$this->User->findAll(array('User.firstname' => '= Daniel'));
$this->User->findAll(array('User.firstname' => 'LIKE %an%'));
$this->User->findAll(array('User.age' => '> 18'));

That also works for the following operators: <>, >=, <=, and <.

Update (2006-02-21): The examples about specifying the conditions are no longer valid, see New syntax for conditions II.

Update (2006-02-22): All examples in this post are no longer valid!

Update (2006-02-28): The last three examples are valid again in RC6 ;-)

<input name="data[Price][price][]" value= "" />
<input name="data[Price][price][]" value= "" />

The obvious approach with

$html->inputTag('Price/price[]');

does not work, as it creates a wrong name:

<input  name="data[Price][price[]]" value="" />

If we look at this output, we can see, how CakePHP works: it splits “Price/size[]” on the “/” character and adds square brackets. That leads us to the following workaround:

$html->inputTag('Price/price][');

Sure, it is a little bit counterintuitive, but it does the job ;-)