3 Catalyst::Manual::ExtendingCatalyst - Extending The Framework
7 This document will provide you with access points, techniques and best
8 practices to extend the L<Catalyst> framework, or to find more elegant
9 ways to abstract and use your own code.
11 The design of Catalyst is such that the framework itself should not
12 get in your way. There are many entry points to alter or extend
13 Catalyst's behaviour, and this can be confusing. This document is
14 written to help you understand the possibilities, current practices
15 and their consequences.
17 Please read the L<BEST PRACTICES> section before deciding on a design,
18 especially if you plan to release your code to CPAN. The Catalyst
19 developer and user communities, which B<you are part of>, will benefit
20 most if we all work together and coordinate.
22 If you are unsure on an implementation or have an idea you would like
23 to have RFC'ed, it surely is a good idea to send your questions and
24 suggestions to the Catalyst mailing list (See L<Catalyst/SUPPORT>)
25 and/or come to the C<#catalyst> channel on the C<irc.perl.org>
26 network. You might also want to refer to those places for research to
27 see if a module doing what you're trying to implement already
28 exists. This might give you a solution to your problem or a basis for
33 During Catalyst's early days, it was common to write plugins to
34 provide functionality application wide. Since then, Catalyst has
35 become a lot more flexible and powerful. It soon became a best
36 practice to use some other form of abstraction or interface, to keep
37 the scope of its influence as close as possible to where it belongs.
39 For those in a hurry, here's a quick checklist of some fundamental
40 points. If you are going to read the whole thing anyway, you can jump
41 forward to L</Namespaces>.
43 =head2 Quick Checklist
47 =item Use the C<CatalystX::*> namespace if you can!
49 If your extension isn't a Model, View, Controller, Plugin, Engine,
50 or Log, it's best to leave it out of the C<Catalyst::> namespace.
51 Use <CatalystX::> instead.
53 =item Don't make it a plugin unless you have to!
55 A plugin should be careful since it's overriding Catalyst internals.
56 If your plugin doesn't really need to muck with the internals, make it a
57 base Controller or Model.
59 Also, if you think you really need a plugin, please instead consider
60 using a L<Moose::Role>.
62 =item There's a community. Use it!
64 There are many experienced developers in the Catalyst community,
65 there's always the IRC channel and the mailing list to discuss things.
67 =item Add tests and documentation!
69 This gives a stable basis for contribution, and even more importantly,
70 builds trust. The easiest way is a test application. See
71 L<Catalyst::Manual::Tutorial::Testing> for more information.
77 While some core extensions (engines, plugins, etc.) have to be placed
78 in the C<Catalyst::*> namespace, the Catalyst core would like to ask
79 developers to use the C<CatalystX::*> namespace if possible.
81 Please B<do not> invent components which are outside the well
82 known C<Model>, C<View>, C<Controller> or C<Plugin> namespaces!
84 When you try to put a base class for a C<Model>, C<View> or
85 C<Controller> directly under your C<MyApp> directory as, for example,
86 C<MyApp::Controller::Foo>, you will have the problem that Catalyst
87 will try to load that base class as a component of your
88 application. The solution is simple: Use another namespace. Common
89 ones are C<MyApp::Base::Controller::*> or C<MyApp::ControllerBase::*>
92 =head2 Can it be a simple module?
94 Sometimes you want to use functionality in your application that
95 doesn't require the framework at all. Remember that Catalyst is just
96 Perl and you always can just C<use> a module. If you have application
97 specific code that doesn't need the framework, there is no problem in
98 putting it in your C<MyApp::*> namespace. Just don't put it in
99 C<Model>, C<Controller> or C<View>, because that would make Catalyst
100 try to load them as components.
102 Writing a generic component that only works with Catalyst is wasteful
103 of your time. Try writing a plain perl module, and then a small bit
104 of glue that integrates it with Catalyst. See
105 L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> for a
106 module that takes the approach. The advantage here is that your
107 "Catalyst" DBIC schema works perfectly outside of Catalyst, making
108 testing (and command-line scripts) a breeze. The actual Catalyst
109 Model is just a few lines of glue that makes working with the schema
112 If you want the thinnest interface possible, take a look at
113 L<Catalyst::Model::Adaptor|Catalyst::Model::Adaptor>.
115 =head2 Using Moose roles to apply method modifiers
117 Rather than having a complex set of base classes which you have to mixin
118 via multiple inheritence, if your functionality is well structured, then
119 it's possible to use the composability of L<Moose> roles, and method modifiers
120 to hook onto to provide functionality.
122 These can be applied to your models/views/controllers, and your application
123 class. Please see the sections below for special notes and caveats, and
124 the L<Moose::Manual::Roles> for more information about roles in general.
126 =head3 In your application class
128 It should be noted that when applying roles to your application class, that
129 you should B<not> wrap methods provided by L<Catalyst> until B<after> you have
130 run C<< __PACKAGE__->setup >>, as your class does not inherit from any of your
131 plugins until the setup method is run.
133 With Catalyst 5.80004, it is possible to include Roles in the plugin list, and
134 these roles will be applied to your application class immediately after
135 'traditional' plugins have been composed into your application class'
136 inheritance hierarchy.
138 =head3 In controllers
140 Method modifiers on controller actions will work as expected (either in your
141 controllers, or when composed from roles) in Catalyst 5.80003 and above.
143 It is possible to have action methods with attributes inside Moose roles, using
144 the trait introduced in L<MooseX::MethodAttributes> version 0.12, example:
146 package MyApp::ControllerRole;
147 use Moose::Role -traits => 'MethodAttributes';
154 =head2 Inheritance and overriding methods
156 When overriding a method, keep in mind that some day additionall
157 arguments may be provided to the method, if the last parameter is not
158 a flat list. It is thus better to override a method by shifting the
159 invocant off of C<@_> and assign the rest of the used arguments, so
160 you can pass your complete arguments to the original method via C<@_>:
166 my ($bar, $baz) = @_; # ... return
167 $self->next::method(@_);
170 If you would do the common
172 my ($self, $foo, $bar) = @_;
174 you'd have to use a much uglier construct to ensure that all arguments
175 will be passed along and the method is future proof:
177 $self->next::method(@_[ 1 .. $#_ ]);
179 =head2 Tests and documentation
181 When you release your module to the CPAN, proper documentation and at
182 least a basic test suite (which means more than pod or even just
183 C<use_ok>, sorry) gives people a good base to contribute to the
184 module. It also shows that you care for your users. If you would like
185 your module to become a recommended addition, these things will prove
188 If you're just getting started, try using
189 L<CatalystX::Starter|CatalystX::Starter> to generate some example
190 tests for your module.
194 In planning to release a module to the community (Catalyst or CPAN and
195 Perl), you should consider if you have the resources to keep it up to
196 date, including fixing bugs and accepting contributions.
198 If you're not sure about this, you can always ask in the proper
199 Catalyst or Perl channels if someone else might be interested in the
200 project, and would jump in as co-maintainer.
202 A public repository can further ease interaction with the
203 community. Even read only access enables people to provide you with
204 patches to your current development version. subversion, SVN and SVK,
205 are broadly preferred in the Catalyst community.
207 If you're developing a Catalyst extension, please consider asking the
208 core team for space in Catalyst's own subversion repository. You can
209 get in touch about this via IRC or the Catalyst developers mailing
212 =head2 The context object
214 Sometimes you want to get a hold of the context object in a component
215 that was created on startup time, where no context existed yet. Often
216 this is about the model reading something out of the stash or other
217 context information (current language, for example).
219 If you use the context object in your component you have tied it to an
220 existing request. This means that you might get into problems when
221 you try to use the component (e.g. the model - the most common case)
222 outside of Catalyst, for example in cronjobs.
224 A stable solution to this problem is to design the Catalyst model
225 separately from the underlying model logic. Let's take
226 L<Catalyst::Model::DBIC::Schema> as an example. You can create a
227 schema outside of Catalyst that knows nothing about the web. This kind
228 of design ensures encapsulation and makes development and maintenance
229 a whole lot easier. The you use the aforementioned model to tie your
230 schema to your application. This gives you a C<MyApp::DBIC> (the name
231 is of course just an example) model as well as
232 C<MyApp::DBIC::TableName> models to access your result sources
235 By creating such a thin layer between the actual model and the
236 Catalyst application, the schema itself is not at all tied to any
237 application and the layer in-between can access the model's API using
238 information from the context object.
240 A Catalyst component accesses the context object at request time with
241 L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.
245 The application has to interact with the extension with some
246 configuration. There is of course again more than one way to do it.
250 You can specify any valid Perl attribute on Catalyst actions you like.
251 (See L<attributes/"Syntax of Attribute Lists"> for a description of
252 what is valid.) These will be available on the C<Catalyst::Action>
253 instance via its C<attributes> accessor. To give an example, this
256 sub foo : Local Bar('Baz') {
259 $self->action_for('foo')->attributes;
260 $c->res->body($attributes->{Bar}[0] );
263 will set the response body to C<Baz>. The values always come in an
264 array reference. As you can see, you can use attributes to configure
265 your actions. You can specify or alter these attributes via
266 L</"Component Configuration">, or even react on them as soon as
267 Catalyst encounters them by providing your own L<component base
268 class|/"Component Base Classes">.
270 =head2 Creating custom accessors
272 L<Catalyst::Component> uses L<Class::Accessor::Fast> for accessor
273 creation. Please refer to the modules documentation for usage
276 =head2 Component configuration
278 At creation time, the class configuration of your component (the one
279 available via C<$self-E<gt>config>) will be merged with possible
280 configuration settings from the applications configuration (either
281 directly or via config file). This is then stored in the controller
282 object's hash reference. So, if you read possible configurations like:
284 my $model_name = $controller->{model_name};
286 you will get the right value. The C<config> accessor always only
287 contains the original class configuration and must not be used for
288 component configuration.
290 You are advised to create accessors on your component class for your
291 configuration values. This is good practice and makes it easier to
292 capture configuration key typos. You can do this with the
293 C<mk_ro_accessors> method provided to L<Catalyst::Component> via
294 L<Class::Accessor::Fast>:
296 use base 'Catalyst::Controller';
297 __PACKAGE__->mk_ro_accessors('model_name');
299 my $model_name = $controller->model_name;
301 =head1 IMPLEMENTATION
303 This part contains the technical details of various implementation
304 methods. Please read the L</"BEST PRACTICES"> before you start your
305 implementation, if you haven't already.
307 =head2 Action classes
309 Usually, your action objects are of the class L<Catalyst::Action>.
310 You can override this with the C<ActionClass> attribute to influence
311 execution and/or dispatching of the action. A widely used example of
312 this is L<Catalyst::Action::RenderView>, which is used in every newly
313 created Catalyst application in your root controller:
315 sub end : ActionClass('RenderView') { }
317 Usually, you want to override the C<execute> and/or the C<match>
318 method. The execute method of the action will naturally call the
319 methods code. You can surround this by overriding the method in a
322 package Catalyst::Action::MyFoo;
326 use base 'Catalyst::Action';
330 my ($controller, $c, @args) = @_;
331 # put your 'before' code here
332 my $r = $self->next::method(@_);
333 # put your 'after' code here
338 We are using L<MRO::Compat> to ensure that you have the next::method
339 call, from L<Class::C3> (in older perls), or natively (if you are using
340 perl 5.10) to re-dispatch to the original C<execute> method in the
341 L<Catalyst::Action> class.
343 The Catalyst dispatcher handles an incoming request and, depending
344 upon the dispatch type, will call the appropriate target or chain.
345 From time to time it asks the actions themselves, or through the
346 controller, if they would match the current request. That's what the
347 C<match> method does. So by overriding this, you can change on what
348 the action will match and add new matching criteria.
350 For example, the action class below will make the action only match on
353 package Catalyst::Action::OnlyMondays;
357 use base 'Catalyst::Action';
361 return 0 if ( localtime(time) )[6] == 1;
362 return $self->next::method(@_);
366 And this is how we'd use it:
368 sub foo: Local ActionClass('OnlyMondays') {
370 $c->res->body('I feel motivated!');
373 If you are using action classes often or have some specific base
374 classes that you want to specify more conveniently, you can implement
375 a component base class providing an attribute handler.
377 For further information on action classes, please refer to
378 L<Catalyst::Action> and L<Catalyst::Manual::Actions>.
380 =head2 Component base classes
382 Many L<Catalyst::Plugin> that were written in Catalyst's early days
383 should really have been just controller base classes. With such a
384 class, you could provide functionality scoped to a single controller,
385 not polluting the global namespace in the context object.
387 You can provide regular Perl methods in a base class as well as
388 actions which will be inherited to the subclass. Please refer to
389 L</Controllers> for an example of this.
391 You can introduce your own attributes by specifying a handler method
392 in the controller base. For example, to use a C<FullClass> attribute
393 to specify a fully qualified action class name, you could use the
394 following implementation. Note, however, that this functionality is
395 already provided via the C<+> prefix for action classes. A simple
397 sub foo : Local ActionClass('+MyApp::Action::Bar') { ... }
399 will use C<MyApp::Action::Bar> as action class.
401 package MyApp::Base::Controller::FullClass; use strict; use base
402 'Catalyst::Controller';
404 sub _parse_FullClass_attr {
405 my ($self, $app_class, $action_name, $value, $attrs) = @_;
406 return( ActionClass => $value );
410 Note that the full line of arguments is only provided for completeness
411 sake. We could use this attribute in a subclass like any other
414 package MyApp::Controller::Foo;
416 use base 'MyApp::Base::Controller::FullClass';
418 sub foo : Local FullClass('MyApp::Action::Bar') { ... }
424 Many things can happen in controllers, and it often improves
425 maintainability to abstract some of the code out into reusable base
428 You can provide usual Perl methods that will be available via your
429 controller object, or you can even define Catalyst actions which will
430 be inherited by the subclasses. Consider this controller base class:
432 package MyApp::Base::Controller::ModelBase;
434 use base 'Catalyst::Controller';
436 sub list : Chained('base') PathPart('') Args(0) {
438 my $model = $c->model( $self->{model_name} );
439 my $condition = $self->{model_search_condition} || {};
440 my $attrs = $self->{model_search_attrs} || {};
441 $c->stash(rs => $model->search($condition, $attrs);
444 sub load : Chained('base') PathPart('') CaptureArgs(1) {
445 my ($self, $c, $id) = @_;
446 my $model = $c->model( $self->{model_name} );
447 $c->stash(row => $model->find($id));
451 This example implements two simple actions. The C<list> action chains
452 to a (currently non-existent) C<base> action and puts a result-set
453 into the stash taking a configured C<model_name> as well as a search
454 condition and attributes. This action is a
455 L<chained|Catalyst::DispatchType::Chained> endpoint. The other action,
456 called C< load > is a chain midpoint that takes one argument. It takes
457 the value as an ID and loads the row from the configured model. Please
458 not that the above code is simplified for clarity. It misses error
459 handling, input validation, and probably other things.
461 The class above is not very useful on its own, but we can combine it
462 with some custom actions by sub-classing it:
464 package MyApp::Controller::Foo;
466 use base 'MyApp::Base::Controller::ModelBase';
468 __PACKAGE__->config( model_name => 'DB::Foo',
469 model_search_condition=> { is_active => 1 },
470 model_search_attrs => { order_by => 'name' },
473 sub base : Chained PathPart('foo') CaptureArgs(0) { }
475 sub view : Chained('load') Args(0) {
477 my $row = $c->stash->{row};
478 $c->res->body(join ': ', $row->name,
479 $row->description); }
482 This class uses the formerly created controller as a base
483 class. First, we see the configurations that were used in the parent
484 class. Next comes the C<base> action, where everything chains off of.
486 Note that inherited actions act like they were declared in your
487 controller itself. You can therefor call them just by their name in
488 C<forward>s, C<detaches> and C<Chained(..)> specifications. This is an
489 important part of what makes this technique so useful.
491 The new C<view> action ties itself to the C<load> action specified in
492 the base class and outputs the loaded row's C<name> and C<description>
493 columns. The controller C<MyApp::Controller::Foo> now has these
494 publicly available paths:
500 Will call the controller's C<base>, then the base classes C<list>
505 First, the controller's C<base> will be called, then it will C<load>
506 the row with the corresponding C<$id>. After that, C<view> will
507 display some fields out of the object.
511 =head2 Models and Views
513 If the functionality you'd like to add is really a data-set that you
514 want to manipulate, for example internal document types, images,
515 files, it might be better suited as a model.
517 The same applies for views. If your code handles representation or
518 deals with the applications interface and should be universally
519 available, it could be a perfect candidate for a view.
521 Please implement a C<process> method in your views. This method will
522 be called by Catalyst if it is asked to forward to a component without
523 a specified action. Note that C<process> is B<not a Catalyst action>
524 but a simple Perl method.
526 You are also encouraged to implement a C<render> method corresponding
527 with the one in L<Catalyst::View::TT>. This has proven invaluable,
528 because people can use your view for much more fine-grained content
531 Here is some example code for a fictional view:
533 package CatalystX::View::MyView;
535 use base 'Catalyst::View';
539 my $template = $c->stash->{template};
540 my $content = $self->render($c, $template, $c->stash);
541 $c->res->body( $content );
545 my ($self, $c, $template, $args) = @_;
546 # prepare content here
553 The first thing to say about plugins is that if you're not sure if
554 your module should be a plugin, it probably shouldn't. It once was
555 common to add features to Catalyst by writing plugins that provide
556 accessors to said functionality. As Catalyst grew more popular, it
557 became obvious that this qualifies as bad practice.
559 By designing your module as a Catalyst plugin, every method you
560 implement, import or inherit will be available via your applications
561 context object. A plugin pollutes the global namespace, and you
562 should be only doing that when you really need to.
564 Often, developers design extensions as plugins because they need to
565 get hold of the context object. Either to get at the stash or
566 request/response objects are the widely spread reasons. It is,
567 however, perfectly possible to implement a regular Catalyst component
568 (read: model, view or controller) that receives the current context
569 object via L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.
571 When is a plugin suited to your task? Your code needs to be a
572 plugin to act upon or alter specific parts of Catalyst's request
573 lifecycle. If your functionality needs to change some C<prepare_*> or
574 C<finalize_*> stages, you won't get around a plugin.
576 Note, if you just want to hook into such a stage, and run code before,
577 or after it, then it is recommended that you use L<Moose>s method modifiers
580 Another valid target for a plugin architecture are things that
581 B<really> have to be globally available, like sessions or
584 B<Please do not> release Catalyst extensions as plugins only to
585 provide some functionality application wide. Design it as a controller
586 base class or another suiting technique with a smaller scope, so that
587 your code only influences those parts of the application where it is
588 needed, and namespace clashes and conflicts are ruled out.
590 The implementation is pretty easy. Your plugin will be inserted in the
591 application's inheritance list, above Catalyst itself. You can by this
592 alter Catalyst's request lifecycle behaviour. Every method you
593 declare, every import in your package will be available as method on
594 the application and the context object. As an example, let's say you
595 want Catalyst to warn you every time uri_for was called without an action
596 object as the first parameter, for example to test that all your chained
597 uris are generated from actions (a recommended best practice).
598 You could do this with this simple
599 implementation (excuse the lame class name, it's just an example):
601 package Catalyst::Plugin::UriforUndefWarning;
603 use Scalar::Util qw/blessed/;
608 my $uri = $c->next::method(@_);
609 $c->log->warn( 'uri_for with non action: ', join(', ', @_), )
610 if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action'));
616 This would override Catalyst's C<uri_for> method and emit a C<warn>
617 log entry containing the arguments to uri_for.
619 Please note this is not a practical example, as string URLs are fine for
622 A simple example like this is actually better as a L<Moose> role, for example:
624 package CatalystX::UriforUndefWarning;
626 use namespace::clean -except => 'meta';
628 after 'uri_for' => sub {
630 $c->log->warn( 'uri_for with non action: ', join(', ', @_), )
631 if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action'));
635 =head2 Factory components with COMPONENT()
637 Every component inheriting from L<Catalyst::Component> contains a
638 C<COMPONENT> method. It is used on application startup by
639 C<setup_components> to instantiate the component object for the
640 Catalyst application. By default, this will merge the components own
641 C<config>uration with the application wide overrides and call the
642 class' C<new> method to return the component object.
644 You can override this method and do and return whatever you want.
645 However, you should use L<Class::C3> (via L<MRO::Compat>) to forward
646 to the original C<COMPONENT> method to merge the configuration of
649 Here is a stub C<COMPONENT> method:
651 package CatalystX::Component::Foo;
653 use base 'Catalyst::Component';
659 # Note: $app is like $c, but since the application isn't fully
660 # initialized, we don't want to call it $c yet. $config
661 # is a hashref of config options possibly set on this component.
662 my ($app, $config) = @_;
664 # Do things here before instantiation
665 $new = $class->next::method(@_);
666 # Do things to object after instantiation
670 The arguments are the class name of the component, the class name of
671 the application instantiating the component, and a hash reference with
672 the controller's configuration.
674 You are free to re-bless the object, instantiate a whole other
675 component or really do anything compatible with Catalyst's
676 expectations on a component.
678 For more information, please see
679 L<Catalyst::Component/"COMPONENT($c,$arguments)">.
683 L<Catalyst>, L<Catalyst::Manual::Actions>, L<Catalyst::Component>
687 Robert Sedlacek C<< <rs@474.at> >>
689 Jonathan Rockway C<< <jrockway@cpan.org> >>
691 =head1 LICENSE AND COPYRIGHT
693 This document is free, you can redistribute it and/or modify it under
694 the same terms as Perl itself.