Design by Contract in PHP with Assertions

Recently I wrote about meta programming in php because my recent project involves quite a bit of it. I will probably write about it at some other point but it’s still in sort of early development stage. However while these techniques produce very compact and flexible code, they can also be hard to debug. Since code gets modified at runtime you can often run into situations where something gets passed to the wrong method and you don’t really know why and where. Each time I called some method, I was making certain assumptions as to the state of the program. For example, whether or not I am accessing the right type of class, or whether or not the method is called properly and etc. Here is a sample comment block from a function I wrote recently:

/**
 *  Returns an array built by querying another table. The name of the table is based on the
 *  foreign key passed in as an argument(param $name) which is expected to be in the form
 *  tablename_id. The method will import tablenameModel and tablenameView  classes, initializes
 *  them and run listRecords() method on the tableModel instance.
 *
 *  Note that tablenameModel and tablenameView classes must exist and be defined in files
 *  models/tablenameModel.php and views/tablenameView.php. The classes should be derived
 *  from DefaultModel and DefaultView respectively.
 *
 * @param string $name The name of the foreign key form tablename_id
 * @return array
 */

I’m assuming tons of things here. I’m expecting classes to be defined in certain files, I expecting them to be descendants of certain other classes, and I need the argument to be passed to me in a specific format. During normal execution all of these conditions should be met automatically. The correct files should be in the right place, because of the way the whole system is set up. The classes in question should extend the correct parents because that is the convention I’m using. Similarly, I’m also enforcing a convention that all foreign keys are ought to be named in the form tablename_id. So if someone passes me a parameter that is in the wrong form, or that does not have correctly defined Model and View classes associated with it, this is a big issue. This should never, ever happen at runtime.

How do I enforce these things though? I opted to take my comments and turn them into assertion statements. At some point this almost turned into sort of a Design by Contract methodology. Ensure preconditions, guarantee postconditions and etc.. Here is the method body itself:

function getComboBoxArrayFromOtherTable($name)
{
   assert('is_string($name)');
   assert('Util::EndsWith($name, \'_id\');');
            
   $tablename = substr($name, 0, strrpos($name, '_'));
   $modelname = $tablename."Model";
   $viewname = $tablename."View";
            
   assert('file_exists(\'models/\'.$modelname.\'.php\')');
   assert('file_exists(\'views/\'.$viewname.\'.php\')');
            
   include "models/$modelname.php";    
   $othermodel = new $modelname();

   include "views/$viewname.php";      
   $otherview = new $viewname();
            
   assert('is_a($othermodel, \'DefaultModel\');');
   assert('is_a($otherview, \'DefaultView\');');
                    
   $othermodel->listRecords();
   return $othermodel->getComboArray();
}

I could of course throw exceptions, or make my script die() if these conditions were not meant. But as I said before, failure to meet the asserted conditions were was not really something that could be introduced by a user stumbling to a wrong URL or entering malformed data at runtime. Failing these assertions would be primarily caused by someone calling my methods improperly, or passing wrong arguments. In other words – programmer errors. And so, we spank the programmer rather than the user by using assertions which can be disabled in production code.

They are sort of sanity checks that make sure I’m using my own methods the way I originally intended them, and that I’m not really building system around some curious side effect happening deep inside my code that I never really intended for, but over a period of time grown to really on. Not to mention that they really help you write a self documenting code.

I often forget to spell out all my assumptions like in my code block above. This one is a nicely fleshed out because but not all of my comment blocks are this informative. In fact when I’m in a hurry I will sometimes write a single sentence or two just to have something show up in the doc file. Assertions however must be explicit, and really flesh out my pre-conditions and post conditions. So even if I didn’t write any documentation for a given method, someone could pick it up and work out at least partial (bare bones) documentation just by looking at some of these statements.

I haven’t really used assertions that much in my PHP code before. But with this project I’m totally sold on them.

[tags]php, assertions, design by contract, meta programming[/tags]