In the evolution of symfony, plugins are an important step. But before we can think of applications made entirely with plugins - the 'Lego' dream - the framework must offer a way to customize plugin schemas.

Why plugin schemas must be configurable

More and more symfony plugins offer high-level features, even entire modules, based on a bundled schema. The sfGuardPlugin, for instance, defines several tables for user management. The sfSimpleForumPlugin defines tables for forums, topics and posts, in order to provide a complete forum packaged in one plugin.

The problem is that unlike all the other parts of a plugin, a plugin schema can't be customized. This is a very strong limitation, and it makes plugins impossible to use in many cases.

For instance, the sfGuardUser table doesn't have an email column. As its schema can't be customized, this means that if you want to use sfGuard and handle user emails (that should be about 99% of the cases), then you have to define a new table for user details with a 1:1 relationship to the sfGuardUser table. Bummer.

Worse, if you want to use a behavior, like for instance the sfPropelParanoidBehavior, on a plugin model, you simply can't. The said behavior needs an extra deleted_at column to be added to the table, and you can't add it to a plugin schema - or else it will be deleted the next time you update the plugin.

Using PHP in YAML files

But nothing is impossible with symfony. By using two powerful features of the symfony YAML parser, it is possible to make a schema more configurable.

First, you probably know that symfony sees YAML files as PHP, and therefore executes them before interpreting the YAML inside. This means that a YAML schema can include PHP code, and that gives a certain level of customization to schemas. For instance, look at how the sfSimpleBloginPlugin schema offers a way to change the connection and tables names:

To customize table names, you just need to create a config/sfBlogPlugin.yml overriding the values of the $config array, like for instance:

In a previous post, I explained how a custom config handler can make this task even easier.

This is more or less a hack, and it allows only the customization of predefined elements of the schema. Besides, PHP code makes the YAML schema less readable.

A YAML file is an array

A second property of YAML files in symfony is that, if they return a PHP array, then the YAML parser won't be invoked at all. Imagine the following YAML file:

Since the YAML file returns an array, the YAML code is ignored. Everything happens as if the file had been:

Combining this property and the power of sfToolkit::arrayDeepMerge(), it is possible to allow more configuration to plugin schemas. Look at how it is done in the sfSimpleForumPlugin:

Not only is the schema more readable (the embedded PHP statements were replaced by tokens), it is now possible to add new fields to the schema:

At last, it makes it possible to extend existing plugin schemas... That is, if the plugin planned for it.

What's next?

This feature is so crucial for plugins adoption that it should, in fact, be built-in the symfony plugin system instead of being implemented in each plugin. Users should be able to add a YAML file in the project's config/ directory for each of the schemas provided by the installed plugins, following a naming convention similar to the one I exposed in the sfSimpleForumPlugin.

Of course, this will never work for plugins that use the XML syntax for schemas. Unless we tell the propel tasks to transform every XML schema to YAML, to allow for customization, before transforming them back to XML, which is the only format Propel understands. But to me, the ability to be customized should clearly promote the YAML schema syntax as the only standard for symfony plugins. Future versions of symfony should drop support for the legacy XML schema syntax.

There is another step that could be taken towards standardization... The schema customization exposed in the sfSimpleForumPlugin example uses two different techniques to change table names and add fields. But if the YAML schema syntax was a little different, all this could be done simply through one YAML file. I'm thinking about a new syntax that would mix the current symfony schema syntax and the Doctrine schema syntax. Imagine that the topic table above is defined as follows:

If this is automatically merged with user-defined schemas, it would be very easy to change table names or add custom fields, for instance with this file:

Conclusion

The current YAML syntax for schemas (which I designed myself) was a first step, but it needs to evolve. To be able to fully replace XML schemas, and to allow compatibility between Propel and Doctrine, it is probably necessary to change it - but preserve backward compatibility, of course.

Developing an extension of the sfPropelDatabaseSchema class to implement both the new syntax and the ability to customize schemas is possible, but before getting myself into it, I wonder: Would anybody else benefit from this?

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.