Writing Plugins

This page contains some tips on writing plugins that play nicely with Catalyst, and other plugins.

But First

The Catalyst Manual has this to say on the matter of writing plugins:

A plugin should be careful since it's overriding Catalyst internals.
If your plugin doesn't really need to muck with the internals, make it a base Controller or Model.

In other words, most plugins don't really need to be a plugin - they are simply hooks to other systems such as Template or Form builders, Databases, and so on. For those, you can write Controller and Model base classes which will be much more useful. Check out the Extending Catalyst manual page for more details.

A Catalyst Plugin is something which really needs to inspect data as it's passing through the Catalyst internals, and perhaps alter it somehow.

Back to the story

Most good practice is now in the main Catalyst Manual, including use of modules such as MRO::Compat which will play nicely with Perl 5.8 through 5.10+.

Subclassing parts of Catalyst

To extend the functionality of the Catalyst Request or Response handler, you need to subclass it. This is made easy by there being a (e.g.) request_class accessor to set. Its default value is Catalyst::Request. Your users can create a new class which isa Catalyst::Request but also isa plugin class. They then set their request_class to be this.

In the simplest case, your plugin might be the only one running, in which case you can fix things at run-time whilst you are already inside setup():

if ($self->request_class eq 'Catalyst::Request') {
else {
    die 'Please make a Request subclass for your application which '.
        'isa Catalyst::Request::MyFunkyPlugin';

In the above example, we fixed the simple case, and threw an error in the case that another plugin (or the user themselves) has already fixed request_class but not included your plugin.

Where does Catalyst::Request::MyFunkyPlugin come from?

This is the part of your Plugin where you jump into Catalyst-space and add features, if you need to. The rest of your plugin will be wrappers around parts of the Catalyst cycle such as setup() or finalize_cookies().

You can add something like the following inside your Plugin package to add features to Catalyst, but remember, you are swimming in someone else's pool so be kind, and obvious, with your naming conventions, so as to avoid clashes and confusion:

    package Catalyst::Request::MyFunkyPlugin;
    use base 'Catalyst::Request';
    __PACKAGE__->mk_accessors(qw/something somethingelse/);
    sub new_feature {
        my $self = shift;
        # etc...
 # (p.s. sorry about the # chars above, it's to help the wiki rendering)

The above example adds two accessors and one method to $c->request, which could be used as in $c->request->new_feature.

My tags:
Popular tags:
Powered by Catalyst
Powered by MojoMojo Hosted by Shadowcat - Managed by Nordaaker