Some Kind of Asshole Fish

Symfony Plugins - A five minute primer

Symfony's plugin system is very versatile - from simple internal components to integrated and publicly deployable Pear packages, it's all at your fingertips.

Why use plugins?

They make a heap of sense when considering modules which might be used in many projects. Take for instance a custom blogging mechanism you always seem to be adding to your Symfony projects. By separating its code into a plugin, you elegantly maintain a level of separation. This will make you very happy when you realize you can then maintain your blogging code in its own repository area, only adding it into individual projects as a svn:externals.

So What Can Plugins Do?

Well pretty much anything. Commonly you will find people turning libraries, modules and behaviors into plugins since they usually fit nicely within the context of "reusable".

How Symfony sees plugins

Well lets see how Symfony interacts with plugins by creating one to test with.

Please Note: This example is light on details, you should probably feel comfortable with general Symfony coding to fill in the gaps.

Create the plugin

$ cd yourSymfonyProject
$ mkdir plugins/myFirstPlugin
$ symfony cc

And your done! Well sort of, the new plugin is a little... useless to start with.

Adding a library

To add a library, simple create the lib directory in the plugin and add your files:

$ mkdir plugins/myFirstPlugin/lib
$ touch plugins/myFirstPlugin/myToolsLibrary.php
$ symfony cc

And viola! the my myToolsLibrary.php will available to Symfony.

Adding a module

If you take a look in one of your applications modules, that structure is applicable in exactly the same format inside a plugin.

So by creating something like:

$ mkdir plugins/myFirstPlugin/modules
$ mkdir plugins/myFirstPlugin/modules/myModule
$ mkdir plugins/myFirstPlugin/modules/myModule/actions
$ touch plugins/myFirstPlugin/modules/myModule/actions/actions.class.php
$ symfony cc

Would give you the required structure for a module. For security reasons, Symfony won't automatically provide access to the plugin, so you will need to authorize it inside an application by editing settings.yml:

all:
  .settings:
    enabled_modules:  [default, myModule]
 

Another:

$ symfony cc

And you now have your new module activated.

What about css, images, javascript etc?

Well, these are a little different. Since they are files to be directly accessed by Apache, they will need to be within the web directory. While you could just copy and paste them out, it's probably better to link them.

Something like:

$ mkdir plugins/myFirstPlugin/web
$ mkdir plugins/myFirstPlugin/web/css
$ touch plugins/myFirstPlugin/web/css/myStyleIsHotRightNow.css
$ ln plugins/myFirstPlugin/web/css/myStyleIsHotRightNow.css web/css/myStyleIsHotRightNow.css

Summary

So this was really just a quick preview, but the patterns and structures shown above basically set the rules on how plugins work across the board. If you want to move beyond this, perhaps give back some code to the community, Pear packaging is a great way to formalize the plugin and its contents. I won't go into details on that since I need to go and get a coffee.

Another thing to remember, as always, learning by example can really fast-track getting up to speed - Symfony plugins included. Some links can be found below.

Linkage

Examples:

• sfSimpleBlogPlugin plugin
• sfPropelActAsNestedSetBehaviorPlugin plugin

Documentation:

• The Definitive Guide to symfony :: Chapter 17 - Extending Symfony (plugins)

About Me | Copyright © 2007-2008, Piers Warmers - Powered by Steer CMS