How to work with plugins in symfony 1.2

For symfony 1.1, the complete plugin system has been rewritten from scratch. This has been done to allow some serious improvements in the way plugins work, and to make it even simpler to work with plugins in your symfony project.

Installing a plugin

Installing a plugin has become much easier since symfony 1.1. The whole plugin system is now based on a full implementation of PEAR channels, which enables us to use all the advantages of this, such as the easy management (and even installation) of dependencies, or even the installation of plugins from different PEAR channels than the default symfony channel. You could even set up your own plugin channel to easily install the plugins you've written yourself!

To install plugins from the default channel (the official symfony channel), it is no longer necessary to use the full URL to the packages to install them. A simple command is now enough:

$ ./symfony plugin:install sfGuardPlugin

This will immediately install the sfGuardPlugin for you. However, there are more options available to control what gets installed into your project:

$ ./symfony plugin:install --stability=beta sfGuardPlugin

This will install a non-stable plugin into your project, which is useful if you either want to try out the beta of an already stable plugin, or if you want to try out this new plugin that does not have a stable release yet.

You can also control which specific version of a plugin you want to install:

$ ./symfony plugin:install --release=1.0.0 sfGuardPlugin

This will install version 1.0.0 of the sfGuardPlugin into your project.

Various plugins are depending on other plugins to be installed before they can work. In symfony 1.0, this meant the install instructions contained a list of plugins to install before you could install the plugin of your choice. Since symfony 1.1, the installation experience of plugins has been enhanced by the dependency features inherited from using a full PEAR channel implementation. To install a plugin and all it's dependencies, symfony issue the command:

$ ./symfony plugin-install --install_deps sfGuardPlugin

No more browsing through various wiki pages to find all the install instructions and get everything working, symfony will now take care of the installation of those plugins for you.

Another improvement thanks to using PEAR channels is the ability to use several different channels. By default, symfony uses the official symfony PEAR channel (plugins.symfony-project.org), which goes by the name symfony-plugins (no need to specify this with the default installation). To use other channels, you will first need to add a new channel:

$ ./symfony plugin:add-channel custom-channel.example.com

Now you can install plugins from this channel by specifying the channel in the install command:

$ ./symfony plugin:install --channel=custom-channel.example.com sfGuardPlugin

The above extra parameters all also have a shorthand notation, which can be found by using the help:

$ ./symfony help plugin:install

And last but not least, it is also possible to directly reference the PEAR package of the plugin you want to install, either using a full URL or a local path:

$ ./symfony plugin:install http://www.example.com/sfGuardPlugin-1.0.0.tgz

or $ ./symfony plugin:install /home/stefan/plugins/sfGuardPlugin-1.0.0.tgz

Uninstalling a plugin

The task of uninstalling a plugin to remove it from your project is still very easy. One simple command will do the trick:

$ ./symfony plugin:uninstall sfGuardPlugin

One thing to take note of though is if you use multiple channels, and you want to uninstall a plugin that comes from another channel than the default symfony-plugins channel, you need to specify the channel:

$ .symfony plugin:install --channel=custom-channel.example.com sfGuardPlugin

To find out which channel a plugin is installed from, you can use the ./symfony plugin:list task

Upgrading a plugin

If you want to upgrade a plugin, this is very simple. Just issue a single command and your plugin is up-to-date with the latest version:

$ ./symfony plugin:upgrade sfGuardPlugin

The arguments --stability, --release and --channel, including their shorthand notations, are also available for this task and apply in the same way.

Listing the installed plugins

The simplest of all tasks is the listing of the installed plugins, which again only needs a single command:

$ ./symfony plugin:list

This command has no arguments.

As you can see, the rewritten plugin management system is more powerful and allows for much easier management of plugins. Especially if you develop your own plugins, it now allows you to centralize your plugins in your own PEAR channel and easily install them into any of your projects.