NAME

Catalyst::Manual::ExtendingCatalyst - Extending The Framework

DESCRIPTION

This document will provide you with access points, techniques and best practices to extend the Catalyst framework, or to find more elegant ways to abstract and use your own code.

The design of Catalyst is such that the framework itself should not get in your way. There are many entry points to alter or extend Catalyst's behaviour, and this can be confusing. This document is written to help you understand the possibilities, current practices and their consequences.

Please read the BEST PRACTICES section before deciding on a design, especially if you plan to release your code to CPAN. The Catalyst developer and user communities, which you are part of, will benefit most if we all work together and coordinate.

If you are unsure on an implementation or have an idea you would like to have RFC'ed, it surely is a good idea to send your questions and suggestions to the Catalyst mailing list (See SUPPORT in the Catalyst manpage) and/or come to the #catalyst channel on the irc.perl.org network. You might also want to refer to those places for research to see if a module doing what you're trying to implement already exists. This might give you a solution to your problem or a basis for starting.

BEST PRACTICES

During Catalyst's early days, it was common to write plugins to provide functionality application wide. Since then, Catalyst has become a lot more flexible and powerful. It soon became a best practice to use some other form of abstraction or interface, to keep the scope of its influence as close as possible to where it belongs.

For those in a hurry, here's a quick checklist of some fundamental points. If you are going to read the whole thing anyway, you can jump forward to Namespaces.

Quick Checklist

Use the CatalystX::* namespace if you can!

Excluding plugins and of course your MyApp code. Mind the X!

Don't make it a plugin unless you have to!

A plugin should be careful as it declares in global namespace.

There's a community. Use it!

There are many experienced developers in the Catalyst community, there's always the IRC channel and the mailing list to discuss things.

Add tests and documentation!

This gives a stable basis for contribution, and even more importantly, builds trust. The easiest way is a test application. See the Catalyst::Manual::Tutorial::Testing manpage for more information.

Namespaces

While some core extensions (engines, plugins, etc.) have to be placed in the Catalyst::* namespace, the Catalyst core would like to ask developers to use the CatalystX::* namespace if possible.

When you try to put a base class for a Model, View or Controller directly under your MyApp directory as, for example, MyApp::Controller::Foo, you will have the problem that Catalyst will try to load that base class as a component of your application. The solution is simple: Use another namespace. Common ones are MyApp::Base::Controller::* or MyApp::ControllerBase::* as examples.

Can it be a simple module?

Sometimes you want to use functionality in your application that doesn't require the framework at all. Remember that Catalyst is just Perl and you always can just use a module. If you have application specific code that doesn't need the framework, there is no problem in putting it in your MyApp::* namespace. Just don't put it in Model, Controller or View, because that would make Catalyst try to load them as components.

Inheritance and overriding methods

While Catalyst itself is still based on the NEXT manpage (for multiple inheritance), extension developers are encouraged to use the Class::C3 manpage, which is what Catalyst will be switching to in some point in the future.

When overriding a method, keep in mind that some day additionally arguments may be provided to the method, if the last parameter is not a flat list. It is thus better to override a method by shifting the invocant off of @_ and assign the rest of the used arguments, so you can pass your complete arguments to the original method via @_:

  use Class::C3; ...

  sub foo { my $self = shift;
            my ($bar, $baz) = @_; # ...  return
            $self->next::method(@_); }

If you would do the common

  my ($self, $foo, $bar) = @_;

you'd have to use a much uglier construct to ensure that all arguments will be passed along and the method is future proof:

  $self->next::method(@_[ 1 .. $#_ ]);

Tests and documentation

When you release your module to the CPAN, proper documentation and at least a basic test suite (which means more than pod or even just use_ok, sorry) gives people a good base to contribute to the module. It also shows that you care for your users. If you would like your module to become a recommended addition, these things will prove invaluable.

Maintenance

In planning to release a module to the community (Catalyst or CPAN and Perl), you should consider if you have the resources to keep it up to date, including fixing bugs and accepting contributions.

If you're not sure about this, you can always ask in the proper Catalyst or Perl channels if someone else might be interested in the project, and would jump in as co-maintainer.

A public repository can further ease interaction with the community. Even read only access enables people to provide you with patches to your current development version. subversion, SVN and SVK, are broadly preferred in the Catalyst community.

If you're developing a Catalyst extension, please consider asking the core team for space in Catalyst's own subversion repository. You can get in touch about this via IRC or the Catalyst developers mailing list.

The context object

Sometimes you want to get a hold of the context object in a component that was created on startup time, where no context existed yet. Often this is about the model reading something out of the stash or other context information (current language, for example).

If you use the context object in your component you have tied it to an existing request. This means that you might get into problems when you try to use the component (e.g. the model - the most common case) outside of Catalyst, for example in cronjobs.

A stable solution to this problem is to design the Catalyst model separately from the underlying model logic. Let's take the Catalyst::Model::DBIC::Schema manpage as an example. You can create a schema outside of Catalyst that knows nothing about the web. This kind of design ensures encapsulation and makes development and maintenance a whole lot easier. The you use the aforementioned model to tie your schema to your application. This gives you a MyApp::DBIC (the name is of course just an example) model as well as MyApp::DBIC::TableName models to access your result sources directly.

By creating such a thin layer between the actual model and the Catalyst application, the schema itself is not at all tied to any application and the layer in-between can access the model's API using information from the context object.

A Catalyst component accesses the context object at request time with ACCEPT_CONTEXT($c, @args) in the Catalyst::Component manpage.

CONFIGURATION

The application has to interact with the extension with some configuration. There is of course again more than one way to do it.

Attributes

You can specify any valid Perl attribute on Catalyst actions you like. (See Syntax of Attribute Lists in the attributes manpage for a description of what is valid.) These will be available on the Catalyst::Action instance via its attributes accessor. To give an example, this action:

  sub foo : Local Bar('Baz') {
      my ($self, $c) = @_;
      my $attributes =
      $self->action_for('foo')->attributes;
      $c->res->body($attributes->{Bar}[0] );
  }

will set the response body to Baz. The values always come in an array reference. As you can see, you can use attributes to configure your actions. You can specify or alter these attributes via Component Configuration, or even react on them as soon as Catalyst encounters them by providing your own component base class.

Creating custom accessors

the Catalyst::Component manpage uses the Class::Accessor::Fast manpage for accessor creation. Please refer to the modules documentation for usage information.

Component configuration

At creation time, the class configuration of your component (the one available via $self->config) will be merged with possible configuration settings from the applications configuration (either directly or via config file). This is then stored in the controller object's hash reference. So, if you read possible configurations like:

  my $model_name = $controller->{model_name};

you will get the right value. The config accessor always only contains the original class configuration and must not be used for component configuration.

You are advised to create accessors on your component class for your configuration values. This is good practice and makes it easier to capture configuration key typos. You can do this with the mk_ro_accessors method provided to the Catalyst::Component manpage via the Class::Accessor::Fast manpage:

  use base 'Catalyst::Controller';
  __PACKAGE__->mk_ro_accessors('model_name');
  ...
  my $model_name = $controller->model_name;

IMPLEMENTATION

This part contains the technical details of various implementation methods. Please read the BEST PRACTICES before you start your implementation, if you haven't already.

Action classes

Usually, your action objects are of the class the Catalyst::Action manpage. You can override this with the ActionClass attribute to influence execution and/or dispatching of the action. A widely used example of this is the Catalyst::Action::RenderView manpage, which is used in every newly created Catalyst application in your root controller:

  sub end : ActionClass('RenderView') { }

Usually, you want to override the execute and/or the match method. The execute method of the action will naturally call the methods code. You can surround this by overriding the method in a subclass:

  package Catalyst::Action::MyFoo; use strict;

  use Class::C3; use base 'Catalyst::Action';

  sub execute {
      my $self = shift;
      my ($controller, $c, @args) = @_;
      # put your 'before' code here
      my $r = $self->next::method(@_);
      # put your 'after' code here
      return $r;
  }
  1;

We are using the Class::C3 manpage to re-dispatch to the original execute method in the the Catalyst::Action manpage class.

The Catalyst dispatcher handles an incoming request and, depending upon the dispatch type, will call the appropriate target or chain. From time to time it asks the actions themselves, or through the controller, if they would match the current request. That's what the match method does. So by overriding this, you can change on what the action will match and add new matching criteria.

For example, the action class below will make the action only match on Mondays:

  package Catalyst::Action::OnlyMondays; use strict;

  use Class::C3;
  use base 'Catalyst::Action';

  sub match {
      my $self = shift;
      return 0 if ( localtime(time) )[6] == 1;
      return $self->next::method(@_);
   }
  1;

And this is how we'd use it:

  sub foo: Local ActionClass('OnlyMondays') {
      my ($self, $c) = @_;
      $c->res->body('I feel motivated!');
  }

If you are using action classes often or have some specific base classes that you want to specify more conveniently, you can implement a component base class providing an attribute handler.

For further information on action classes, please refer to the Catalyst::Action manpage and the Catalyst::Manual::Actions manpage.

Component base classes

Many the Catalyst::Plugin manpage that were written in Catalyst's early days should really have been just controller base classes. With such a class, you could provide functionality scoped to a single controller, not polluting the global namespace in the context object.

You can provide regular Perl methods in a base class as well as actions which will be inherited to the subclass. Please refer to Controllers for an example of this.

You can introduce your own attributes by specifying a handler method in the controller base. For example, to use a FullClass attribute to specify a fully qualified action class name, you could use the following implementation. Note, however, that this functionality is already provided via the + prefix for action classes. A simple

  sub foo : Local ActionClass('+MyApp::Action::Bar') { ... }

will use MyApp::Action::Bar as action class.

  package MyApp::Base::Controller::FullClass; use strict; use base
  'Catalyst::Controller';

  sub _parse_FullClass_attr {
      my ($self, $app_class, $action_name, $value, $attrs) = @_;
      return( ActionClass => $value );
  }
  1;

Note that the full line of arguments is only provided for completeness sake. We could use this attribute in a subclass like any other Catalyst attribute:

  package MyApp::Controller::Foo;
  use strict;
  use base 'MyApp::Base::Controller::FullClass';

  sub foo : Local FullClass('MyApp::Action::Bar') { ... }

  1;

Controllers

Many things can happen in controllers, and it often improves maintainability to abstract some of the code out into reusable base classes.

You can provide usual Perl methods that will be available via your controller object, or you can even define Catalyst actions which will be inherited by the subclasses. Consider this controller base class:

  package MyApp::Base::Controller::ModelBase;
  use strict;
  use base 'Catalyst::Controller';

  sub list : Chained('base') PathPart('') Args(0) {
      my ($self, $c) = @_;
      my $model = $c->model( $self->{model_name} );
      my $condition = $self->{model_search_condition} || {};
      my $attrs = $self->{model_search_attrs} || {};
      $c->stash(rs => $model->search($condition, $attrs);
      }

  sub load : Chained('base') PathPart('') CaptureArgs(1) {
      my ($self, $c, $id) = @_;
      my $model = $c->model( $self->{model_name} );
      $c->stash(row => $model->find($id));
      }
  1;

This example implements two simple actions. The list action chains to a (currently non-existent) base action and puts a result-set into the stash taking a configured model_name as well as a search condition and attributes. This action is a chained endpoint. The other action, called load is a chain midpoint that takes one argument. It takes the value as an ID and loads the row from the configured model. Please not that the above code is simplified for clarity. It misses error handling, input validation, and probably other things.

The class above is not very useful on its own, but we can combine it with some custom actions by sub-classing it:

  package MyApp::Controller::Foo;
  use strict;
  use base 'MyApp::Base::Controller::ModelBase';

  __PACKAGE__->config( model_name => 'DB::Foo',
                       model_search_condition=> { is_active => 1 },
                       model_search_attrs => { order_by => 'name' },
                   );

  sub base : Chained PathPart('foo') CaptureArgs(0) { }

  sub view : Chained('load') Args(0) {
      my ($self, $c) = @_;
      my $row = $c->stash->{row};
      $c->res->body(join ': ', $row->name,
      $row->description); }
  1;

This class uses the formerly created controller as a base class. First, we see the configurations that were used in the parent class. Next comes the base action, where everything chains off of.

Note that inherited actions act like they were declared in your controller itself. You can therefor call them just by their name in forwards, detaches and Chained(..) specifications. This is an important part of what makes this technique so useful.

The new view action ties itself to the load action specified in the base class and outputs the loaded row's name and description columns. The controller MyApp::Controller::Foo now has these publicly available paths:

/foo

Will call the controller's base, then the base classes list action.

/foo/$id/view

First, the controller's base will be called, then it will load the row with the corresponding $id. After that, view will display some fields out of the object.

Models and Views

If the functionality you'd like to add is really a data-set that you want to manipulate, for example internal document types, images, files, it might be better suited as a model.

The same applies for views. If your code handles representation or deals with the applications interface and should be universally available, it could be a perfect candidate for a view.

Please implement a process method in your views. This method will be called by Catalyst if it is asked to forward to a component without a specified action. Note that process is not a Catalyst action but a simple Perl method.

You are also encouraged to implement a render method corresponding with the one in the Catalyst::View::TT manpage. This has proven invaluable, because people can use your view for much more fine-grained content generation.

Here is some example code for a fictional view:

  package CatalystX::View::MyView;
  use strict;
  use base 'Catalyst::View';

  sub process {
      my ($self, $c) = @_;
      my $template = $c->stash->{template};
      my $content = $self->render($c, $template, $c->stash);
      $c->res->body( $content );
  }

  sub render {
      my ($self, $c, $template, $args) = @_;
      # prepare content here
      return $content;
  }
  1;

Plugins

The first thing to say about plugins is that if you're not sure if your module should be a plugin, it probably shouldn't. It once was common to add features to Catalyst by writing plugins that provide accessors to said functionality. As Catalyst grew more popular, it became obvious that this qualifies as bad practice.

By designing your module as a Catalyst plugin, every method you implement, import or inherit will be available via your applications context object. A plugin pollutes the global namespace, and you should be only doing that when you really need to.

Often, developers design extensions as plugins because they need to get hold of the context object. Either to get at the stash or request/response objects are the widely spread reasons. It is, however, perfectly possible to implement a regular Catalyst component (read: model, view or controller) that receives the current context object via ACCEPT_CONTEXT($c, @args) in the Catalyst::Component manpage.

When is a plugin suited to your task? Your code needs to be a plugin to act upon or alter specific parts of Catalyst's request lifecycle. If your functionality needs to wrap some prepare_* or finalize_* stages, you won't get around a plugin.

Another valid target for a plugin architecture are things that really have to be globally available, like sessions or authentication.

Please do not release Catalyst extensions as plugins only to provide some functionality application wide. Design it as a controller base class or another suiting technique with a smaller scope, so that your code only influences those parts of the application where it is needed, and namespace clashes and conflicts are ruled out.

The implementation is pretty easy. Your plugin will be inserted in the application's inheritance list, above Catalyst itself. You can by this alter Catalyst's request lifecycle behaviour. Every method you declare, every import in your package will be available as method on the application and the context object. As an example, let's say you want Catalyst to warn you every time uri_for returned an undefined value, for example because you specified the wrong number of captures for the targeted action chain. You could do this with this simple implementation (excuse the lame class name, it's just an example):

  package Catalyst::Plugin::UriforUndefWarning;
  use strict;
  use Class::C3;

  sub uri_for {
      my $c = shift;
      my $uri = $c->next::method(@_);
      $c->log->warn( 'uri_for returned undef for:', join(', ', @_), );
      return $uri;
  }

  1;

This would override Catalyst's uri_for method and emit a warn log entry containing the arguments that led to the undefined return value.

Factory components with COMPONENT()

Every component inheriting from the Catalyst::Component manpage contains a COMPONENT method. It is used on application startup by setup_components to instantiate the component object for the Catalyst application. By default, this will merge the components own configuration with the application wide overrides and call the class' new method to return the component object.

You can override this method and do and return whatever you want. However, you should use the Class::C3 manpage to forward to the original COMPONENT method to merge the configuration of your component.

Here is a stub COMPONENT method:

  package CatalystX::Component::Foo;
  use strict;
  use base 'Catalyst::Component';

  use Class::C3;

  sub COMPONENT {
      my $class = shift;
      my ($app_class, $config) = @_;

      # do things here before instantiation my
      $obj = $self->next::method(@_);
      # do things to object after instantiation
      return $object;
        }

The arguments are the class name of the component, the class name of the application instantiating the component, and a hash reference with the controller's configuration.

You are free to re-bless the object, instantiate a whole other component or really do anything compatible with Catalyst's expectations on a component.

For more information, please see COMPONENT($c,$arguments) in the Catalyst::Component manpage.

SEE ALSO

Catalyst, the Catalyst::Manual::Actions manpage, the Catalyst::Component manpage

AUTHOR

Robert Sedlacek rs@474.at

LICENSE AND COPYRIGHT

This document is free, you can redistribute it and/or modify it under the same terms as Perl itself.