When you happen to write twice the same method for two classes of the Propel object model, it is time to think about symfony Behaviors. Behaviors offer a simple way to extend several model classes the same way, by altering existing methods or adding new ones. Using existing behaviors is quite simple: follow the instructions written in the README file bundled with the behavior, and you're done. But if you want to create a new behavior, you need to understand how they work.

I'm paranoid, how are you?

To illustrate the process of creating a behavior, let's start with an already extended model. For instance, let's imagine that for security reasons, the records of the article table must not be removed from the database. The $article->delete() method must still mark records so that they are not returned by a call to ArticlePeer::doSelect(), but the underlying data must not be erased. This is how you could extend the Propel model to implement this rule:

Of course, that implies adding a new timestamp field called deleted_at to the article table.

Note: The reason why we extend doSelectRS() instead of doSelect() is because the former is used not only by doSelect(), but also by doCount().

The combination of a new field and altered methods gives to the Article object a "paranoid" behavior. For now, the word "behavior" just refers to a set of methods.

Enter Mixins

Now, imagine that you need to keep also the deleted records of the comment table. Instead of copying the two methods above in the Comment and CommentPeer classes, which would not be D.R.Y., you should refactor the code used more than once in a new class, and inject it via the Mixins system. You should be familiar with the concept of Mixins and the sfMixer class to understand the following, so refer to Chapter 17 of the symfony book if you wonder what this is about.

The first step is to remove any code from the model classes, and to add hooks to allow them to be extended.

Next, you must put the behavior code in a new class, save this class in a directory where it can be autoloaded:

Finally, you must register the methods of the new ParanoidBehavior class on the hooks of the Article and Comment classes:

By the power of Mixins, the code of the behavior can be reused across several model objects.

But the task of adding hooks to the model classes and registering the methods make this process longer than a simple copy of the code... This is where the symfony Behaviors come as a great help.

Add model hooks automatically

Symfony can add hooks to the model automatically. To enable these hooks, set the AddBehaviors property to true in the propel.ini file, as follows:

You need to rebuild the model for the hooks to be inserted in the generated model classes:

The hooks are added to the Base classes, the ones under the lib/model/om/ directory. For instance, here is an extract of the generated BaseArticlePeer class with behaviors hooks enabled:

That's almost exactly the same hook as the one we added by hand to the custom ArticlePeer during step 1. The difference is that the registered hook name is BaseArticlePeer:doSelectRS:doSelectRS instead of ArticlePeer:doSelectRS:doSelectRS. So you can remove the code added to the custom classes during Step 1. This means that when Behaviors are enabled in the propel.ini, you no longer need to add hooks manually inside your model classes.

As the name of the hooks changed (they are now all prefixed by Base), we need to change the way the methods of the Paranoid behavior are registered in Step 3. But before doing so, have a look at the complete list of hooks added:

// Hooks added to the base object class
[className]:delete:pre     // before deletion
[className]:delete:post    // after deletion
[className]:save:pre       // before save
[className]:save:post      // after save
[className]:[methodName]   // inside __call() (allows for new methods)
// Hooks added to the base Peer class
[PeerClassName]:doSelectRS:doSelectRS
[PeerClassName]:doSelectJoin:doSelectJoin
[PeerClassName]:doSelectJoinAll:doSelectJoinAll
[PeerClassName]:doSelectJoinAllExcept:doSelectJoinAllExcept
[PeerClassName]:doUpdate:pre
[PeerClassName]:doUpdate:post
[PeerClassName]:doInsert:pre
[PeerClassName]:doInsert:post

Note: As of symfony 1.0, there is only one hook related to the doSelect methods, instead of the four hooks described above. This explains why some behaviors work only with symfony 1.1 and not with symfony 1.0, which has an incomplete support for behaviors.

Adding new methods

One of the hooks should get a closer look: the one allowing for new methods in the object class. When Behaviors are enables in propel.ini, all the generated base object classes contain a __call() method similar to this one:

As explained in Chapter 17 of the symfony book, a hook placed in a __call() makes the addition of new methods at runtime possible. For instance, if you want to add an undelete() method to the Article class to allow to reset the deleted_at flag, start by adding it to the Behavior class:

Then, register the new method as follows:

Now, every call to $article->undelete() will make a call to ParanoidBehavior::undelete($article).

Note: Unfortunately, as of PHP 5, static method calls cannot be caught by a __call(). This means that symfony behaviors are not able to add new methods to the Peer classes.

Register hooks in a single step

You still need to rewrite the other hook registrations to use the Base hook names, both for the Article and Comment classes. That would give something like:

But this code is not very D.R.Y., since you need to repeat the whole list of methods for each class. Imagine the pain if the behavior provided several dozens methods! It would be much more efficient if you could separate the registration process in two phases:

1. Register methods of the behavior into a list of class-agnostic hooks.
2. For each class, transform the class-agnostic hooks into real hooks and register them using the mixins system.

Symfony provides a utility class, called sfPropelBehavior, which does this job for you. Here is how the Step 3 can be rewritten to take advantage of this class:

Both the registerMethods and registerHooks methods expect a hook list name as first parameter. This name is then used as a shortcut when the behavior methods are added to the model classes. Notice how the hook names used when calling registerHooks don't contain any reference to a specific model class (the BaseArticle part of the hook name was removed).

Also, you don't need to specify a method name for the methods added by way of registerMethods. The name of the method in the behavior class is used by default.

It's only when the sfPropelBehavior::add() statement is executed that hooks are really registered against the sfMixer class... with a real hook name. As the first parameter of this call is a model class name, the sfPropelBehavior has all the elements to recreate the complete hook names (in this case, by concatenating the string Base with the model class name and the behavior hook name).

Packaging a behavior into a plug-in

To package the behavior into a truly reusable piece of code, the best is to create a plugin.

There is a non-written convention about behavior plugin names. They must be prefixed with 'Propel' since they work only for this ORM, and they must end with 'BehaviorPlugin'. So a good name for our Paranoid behavior could be 'myPropelParanoidBehaviorPlugin'.

As of now, there are only two files to put in the plugin: the ParanoidBehavior class, and the code written in config/config.php to register the behavior methods and hooks. Chapter 17 explains how to organize these files in a plugin tree structure:

plugins/
  myPropelParanoidBehaviorPlugin/
    lib/
      ParanoidBehavior.php    // the class containing methods to be mixed in
    config/
      config.php              // the registration of the behavior methods

The config.php file of every plugin installed in a project is executed at each request, so this is the perfect place to register behavior methods.

To complete the plugin, you must add a README file at the root of the plugin's directory, with installation and usage instructions. The best behaviors also bundle unit tests.

Eventually, add a package.xml (either manually or by way of sfPackageMakerPlugin), package the plugin with PEAR, and you are ready to reuse it. You can also post it in the symfony website.

Passing a parameter to a behavior

A well-designed behavior doesn't rely on hard coded values. In the example of the Paranoid behavior above, the deleted_at column name is hard coded and should be transformed into a parameter.

To pass a parameter to a behavior, use an associative array as the second parameter of the call to sfPropelBehavior::add() instead of a regular array, as follows:

So you are now ready to rewrite the ParanoidBehavior class to take the column parameter into account:

Conclusion

Propel Behaviors are nothing more than a set of predefined hooks, and a helper class designed to facilitate the registration of several hooks in a single statement. If you understand Mixins, it shouldn't be too hard to author your own behaviors. Make sure you check the existing behavior plugins before starting your own: they are practical examples of the behaviors syntax.

Possibly related posts (automatically generated):

• Eating My Own Dog Food
• sfPropelFinder: Now With I18n, Pagination and Update Queries
• Application Lego: Build a Wiki with Symfony in 20 Minutes
• Is symfony 1.1 too verbose?