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 Excluding plugins and of course your C<MyApp> code. B<Mind the X!>
51 =item Don't make it a plugin unless you have to!
53 A plugin should be careful as it declares in global namespace.
55 =item There's a community. Use it!
57 There are many experienced developers in the Catalyst community,
58 there's always the IRC channel and the mailing list to discuss things.
60 =item Add tests and documentation!
62 This gives a stable basis for contribution, and even more importantly,
63 builds trust. The easiest way is a test application. See
64 L<Catalyst::Manual::Tutorial::Testing> for more information.
70 While some core extensions (engines, plugins, etc.) have to be placed
71 in the C<Catalyst::*> namespace, the Catalyst core would like to ask
72 developers to use the C<CatalystX::*> namespace if possible.
74 When you try to put a base class for a C<Model>, C<View> or
75 C<Controller> directly under your C<MyApp> directory as, for example,
76 C<MyApp::Controller::Foo>, you will have the problem that Catalyst
77 will try to load that base class as a component of your
78 application. The solution is simple: Use another namespace. Common
79 ones are C<MyApp::Base::Controller::*> or C<MyApp::ControllerBase::*>
82 =head2 Can it be a simple module?
84 Sometimes you want to use functionality in your application that
85 doesn't require the framework at all. Remember that Catalyst is just
86 Perl and you always can just C<use> a module. If you have application
87 specific code that doesn't need the framework, there is no problem in
88 putting it in your C<MyApp::*> namespace. Just don't put it in
89 C<Model>, C<Controller> or C<View>, because that would make Catalyst
90 try to load them as components.
92 =head2 Inheritance and overriding methods
94 While Catalyst itself is still based on L<NEXT> (for multiple
95 inheritance), extension developers are encouraged to use L<Class::C3>,
96 which is what Catalyst will be switching to in some point in the
99 When overriding a method, keep in mind that some day additionally
100 arguments may be provided to the method, if the last parameter is not
101 a flat list. It is thus better to override a method by shifting the
102 invocant off of C<@_> and assign the rest of the used arguments, so
103 you can pass your complete arguments to the original method via C<@_>:
107 sub foo { my $self = shift;
108 my ($bar, $baz) = @_; # ... return
109 $self->next::method(@_); }
111 If you would do the common
113 my ($self, $foo, $bar) = @_;
115 you'd have to use a much uglier construct to ensure that all arguments
116 will be passed along and the method is future proof:
118 $self->next::method(@_[ 1 .. $#_ ]);
120 =head2 Tests and documentation
122 When you release your module to the CPAN, proper documentation and at
123 least a basic test suite (which means more than pod or even just
124 C<use_ok>, sorry) gives people a good base to contribute to the
125 module. It also shows that you care for your users. If you would like
126 your module to become a recommended addition, these things will prove
131 In planning to release a module to the community (Catalyst or CPAN and
132 Perl), you should consider if you have the resources to keep it up to
133 date, including fixing bugs and accepting contributions.
135 If you're not sure about this, you can always ask in the proper
136 Catalyst or Perl channels if someone else might be interested in the
137 project, and would jump in as co-maintainer.
139 A public repository can further ease interaction with the
140 community. Even read only access enables people to provide you with
141 patches to your current development version. subversion, SVN and SVK,
142 are broadly preferred in the Catalyst community.
144 If you're developing a Catalyst extension, please consider asking the
145 core team for space in Catalyst's own subversion repository. You can
146 get in touch about this via IRC or the Catalyst developers mailing
149 =head2 The context object
151 Sometimes you want to get a hold of the context object in a component
152 that was created on startup time, where no context existed yet. Often
153 this is about the model reading something out of the stash or other
154 context information (current language, for example).
156 If you use the context object in your component you have tied it to an
157 existing request. This means that you might get into problems when
158 you try to use the component (e.g. the model - the most common case)
159 outside of Catalyst, for example in cronjobs.
161 A stable solution to this problem is to design the Catalyst model
162 separately from the underlying model logic. Let's take
163 L<Catalyst::Model::DBIC::Schema> as an example. You can create a
164 schema outside of Catalyst that knows nothing about the web. This kind
165 of design ensures encapsulation and makes development and maintenance
166 a whole lot easier. The you use the aforementioned model to tie your
167 schema to your application. This gives you a C<MyApp::DBIC> (the name
168 is of course just an example) model as well as
169 C<MyApp::DBIC::TableName> models to access your result sources
172 By creating such a thin layer between the actual model and the
173 Catalyst application, the schema itself is not at all tied to any
174 application and the layer in-between can access the model's API using
175 information from the context object.
177 A Catalyst component accesses the context object at request time with
178 L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.
182 The application has to interact with the extension with some
183 configuration. There is of course again more than one way to do it.
187 You can specify any valid Perl attribute on Catalyst actions you like.
188 (See L<attributes/"Syntax of Attribute Lists"> for a description of
189 what is valid.) These will be available on the C<Catalyst::Action>
190 instance via its C<attributes> accessor. To give an example, this
193 sub foo : Local Bar('Baz') {
196 $self->action_for('foo')->attributes;
197 $c->res->body($attributes->{Bar}[0] );
200 will set the response body to C<Baz>. The values always come in an
201 array reference. As you can see, you can use attributes to configure
202 your actions. You can specify or alter these attributes via
203 L</"Component Configuration">, or even react on them as soon as
204 Catalyst encounters them by providing your own L<component base
205 class|/"Component Base Classes">.
207 =head2 Creating custom accessors
209 L<Catalyst::Component> uses L<Class::Accessor::Fast> for accessor
210 creation. Please refer to the modules documentation for usage
213 =head2 Component configuration
215 At creation time, the class configuration of your component (the one
216 available via C<$self-E<gt>config>) will be merged with possible
217 configuration settings from the applications configuration (either
218 directly or via config file). This is then stored in the controller
219 object's hash reference. So, if you read possible configurations like:
221 my $model_name = $controller->{model_name};
223 you will get the right value. The C<config> accessor always only
224 contains the original class configuration and must not be used for
225 component configuration.
227 You are advised to create accessors on your component class for your
228 configuration values. This is good practice and makes it easier to
229 capture configuration key typos. You can do this with the
230 C<mk_ro_accessors> method provided to L<Catalyst::Component> via
231 L<Class::Accessor::Fast>:
233 use base 'Catalyst::Controller';
234 __PACKAGE__->mk_ro_accessors('model_name');
236 my $model_name = $controller->model_name;
238 =head1 IMPLEMENTATION
240 This part contains the technical details of various implementation
241 methods. Please read the L</"BEST PRACTICES"> before you start your
242 implementation, if you haven't already.
244 =head2 Action classes
246 Usually, your action objects are of the class L<Catalyst::Action>.
247 You can override this with the C<ActionClass> attribute to influence
248 execution and/or dispatching of the action. A widely used example of
249 this is L<Catalyst::Action::RenderView>, which is used in every newly
250 created Catalyst application in your root controller:
252 sub end : ActionClass('RenderView') { }
254 Usually, you want to override the C<execute> and/or the C<match>
255 method. The execute method of the action will naturally call the
256 methods code. You can surround this by overriding the method in a
259 package Catalyst::Action::MyFoo; use strict;
261 use Class::C3; use base 'Catalyst::Action';
265 my ($controller, $c, @args) = @_;
266 # put your 'before' code here
267 my $r = $self->next::method(@_);
268 # put your 'after' code here
273 We are using L<Class::C3> to re-dispatch to the original C<execute> method
274 in the L<Catalyst::Action> class.
276 The Catalyst dispatcher handles an incoming request and, depending
277 upon the dispatch type, will call the appropriate target or chain.
278 From time to time it asks the actions themselves, or through the
279 controller, if they would match the current request. That's what the
280 C<match> method does. So by overriding this, you can change on what
281 the action will match and add new matching criteria.
283 For example, the action class below will make the action only match on
286 package Catalyst::Action::OnlyMondays; use strict;
289 use base 'Catalyst::Action';
293 return 0 if ( localtime(time) )[6] == 1;
294 return $self->next::method(@_);
298 And this is how we'd use it:
300 sub foo: Local ActionClass('OnlyMondays') {
302 $c->res->body('I feel motivated!');
305 If you are using action classes often or have some specific base
306 classes that you want to specify more conveniently, you can implement
307 a component base class providing an attribute handler.
309 For further information on action classes, please refer to
310 L<Catalyst::Action> and L<Catalyst::Manual::Actions>.
312 =head2 Component base classes
314 Many L<Catalyst::Plugin> that were written in Catalyst's early days
315 should really have been just controller base classes. With such a
316 class, you could provide functionality scoped to a single controller,
317 not polluting the global namespace in the context object.
319 You can provide regular Perl methods in a base class as well as
320 actions which will be inherited to the subclass. Please refer to
321 L</Controllers> for an example of this.
323 You can introduce your own attributes by specifying a handler method
324 in the controller base. For example, to use a C<FullClass> attribute
325 to specify a fully qualified action class name, you could use the
326 following implementation. Note, however, that this functionality is
327 already provided via the C<+> prefix for action classes. A simple
329 sub foo : Local ActionClass('+MyApp::Action::Bar') { ... }
331 will use C<MyApp::Action::Bar> as action class.
333 package MyApp::Base::Controller::FullClass; use strict; use base
334 'Catalyst::Controller';
336 sub _parse_FullClass_attr {
337 my ($self, $app_class, $action_name, $value, $attrs) = @_;
338 return( ActionClass => $value );
342 Note that the full line of arguments is only provided for completeness
343 sake. We could use this attribute in a subclass like any other
346 package MyApp::Controller::Foo;
348 use base 'MyApp::Base::Controller::FullClass';
350 sub foo : Local FullClass('MyApp::Action::Bar') { ... }
356 Many things can happen in controllers, and it often improves
357 maintainability to abstract some of the code out into reusable base
360 You can provide usual Perl methods that will be available via your
361 controller object, or you can even define Catalyst actions which will
362 be inherited by the subclasses. Consider this controller base class:
364 package MyApp::Base::Controller::ModelBase;
366 use base 'Catalyst::Controller';
368 sub list : Chained('base') PathPart('') Args(0) {
370 my $model = $c->model( $self->{model_name} );
371 my $condition = $self->{model_search_condition} || {};
372 my $attrs = $self->{model_search_attrs} || {};
373 $c->stash(rs => $model->search($condition, $attrs);
376 sub load : Chained('base') PathPart('') CaptureArgs(1) {
377 my ($self, $c, $id) = @_;
378 my $model = $c->model( $self->{model_name} );
379 $c->stash(row => $model->find($id));
383 This example implements two simple actions. The C<list> action chains
384 to a (currently non-existent) C<base> action and puts a result-set
385 into the stash taking a configured C<model_name> as well as a search
386 condition and attributes. This action is a
387 L<chained|Catalyst::DispatchType::Chained> endpoint. The other action,
388 called C< load > is a chain midpoint that takes one argument. It takes
389 the value as an ID and loads the row from the configured model. Please
390 not that the above code is simplified for clarity. It misses error
391 handling, input validation, and probably other things.
393 The class above is not very useful on its own, but we can combine it
394 with some custom actions by sub-classing it:
396 package MyApp::Controller::Foo;
398 use base 'MyApp::Base::Controller::ModelBase';
400 __PACKAGE__->config( model_name => 'DB::Foo',
401 model_search_condition=> { is_active => 1 },
402 model_search_attrs => { order_by => 'name' },
405 sub base : Chained PathPart('foo') CaptureArgs(0) { }
407 sub view : Chained('load') Args(0) {
409 my $row = $c->stash->{row};
410 $c->res->body(join ': ', $row->name,
411 $row->description); }
414 This class uses the formerly created controller as a base
415 class. First, we see the configurations that were used in the parent
416 class. Next comes the C<base> action, where everything chains off of.
418 Note that inherited actions act like they were declared in your
419 controller itself. You can therefor call them just by their name in
420 C<forward>s, C<detaches> and C<Chained(..)> specifications. This is an
421 important part of what makes this technique so useful.
423 The new C<view> action ties itself to the C<load> action specified in
424 the base class and outputs the loaded row's C<name> and C<description>
425 columns. The controller C<MyApp::Controller::Foo> now has these
426 publicly available paths:
432 Will call the controller's C<base>, then the base classes C<list>
437 First, the controller's C<base> will be called, then it will C<load>
438 the row with the corresponding C<$id>. After that, C<view> will
439 display some fields out of the object.
443 =head2 Models and Views
445 If the functionality you'd like to add is really a data-set that you
446 want to manipulate, for example internal document types, images,
447 files, it might be better suited as a model.
449 The same applies for views. If your code handles representation or
450 deals with the applications interface and should be universally
451 available, it could be a perfect candidate for a view.
453 Please implement a C<process> method in your views. This method will
454 be called by Catalyst if it is asked to forward to a component without
455 a specified action. Note that C<process> is B<not a Catalyst action>
456 but a simple Perl method.
458 You are also encouraged to implement a C<render> method corresponding
459 with the one in L<Catalyst::View::TT>. This has proven invaluable,
460 because people can use your view for much more fine-grained content
463 Here is some example code for a fictional view:
465 package CatalystX::View::MyView;
467 use base 'Catalyst::View';
471 my $template = $c->stash->{template};
472 my $content = $self->render($c, $template, $c->stash);
473 $c->res->body( $content );
477 my ($self, $c, $template, $args) = @_;
478 # prepare content here
485 The first thing to say about plugins is that if you're not sure if
486 your module should be a plugin, it probably shouldn't. It once was
487 common to add features to Catalyst by writing plugins that provide
488 accessors to said functionality. As Catalyst grew more popular, it
489 became obvious that this qualifies as bad practice.
491 By designing your module as a Catalyst plugin, every method you
492 implement, import or inherit will be available via your applications
493 context object. A plugin pollutes the global namespace, and you
494 should be only doing that when you really need to.
496 Often, developers design extensions as plugins because they need to
497 get hold of the context object. Either to get at the stash or
498 request/response objects are the widely spread reasons. It is,
499 however, perfectly possible to implement a regular Catalyst component
500 (read: model, view or controller) that receives the current context
501 object via L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.
503 When is a plugin suited to your task? Your code needs to be a
504 plugin to act upon or alter specific parts of Catalyst's request
505 lifecycle. If your functionality needs to wrap some C<prepare_*> or
506 C<finalize_*> stages, you won't get around a plugin.
508 Another valid target for a plugin architecture are things that
509 B<really> have to be globally available, like sessions or
512 B<Please do not> release Catalyst extensions as plugins only to
513 provide some functionality application wide. Design it as a controller
514 base class or another suiting technique with a smaller scope, so that
515 your code only influences those parts of the application where it is
516 needed, and namespace clashes and conflicts are ruled out.
518 The implementation is pretty easy. Your plugin will be inserted in the
519 application's inheritance list, above Catalyst itself. You can by this
520 alter Catalyst's request lifecycle behaviour. Every method you
521 declare, every import in your package will be available as method on
522 the application and the context object. As an example, let's say you
523 want Catalyst to warn you every time uri_for returned an undefined
524 value, for example because you specified the wrong number of captures
525 for the targeted action chain. You could do this with this simple
526 implementation (excuse the lame class name, it's just an example):
528 package Catalyst::Plugin::UriforUndefWarning;
534 my $uri = $c->next::method(@_);
535 $c->log->warn( 'uri_for returned undef for:', join(', ', @_), );
541 This would override Catalyst's C<uri_for> method and emit a C<warn>
542 log entry containing the arguments that led to the undefined return
545 =head2 Factory components with COMPONENT()
547 Every component inheriting from L<Catalyst::Component> contains a
548 C<COMPONENT> method. It is used on application startup by
549 C<setup_components> to instantiate the component object for the
550 Catalyst application. By default, this will merge the components own
551 C<config>uration with the application wide overrides and call the
552 class' C<new> method to return the component object.
554 You can override this method and do and return whatever you want.
555 However, you should use L<Class::C3> to forward to the original
556 C<COMPONENT> method to merge the configuration of your component.
558 Here is a stub C<COMPONENT> method:
560 package CatalystX::Component::Foo;
562 use base 'Catalyst::Component';
568 my ($app_class, $config) = @_;
570 # do things here before instantiation my
571 $obj = $self->next::method(@_);
572 # do things to object after instantiation
576 The arguments are the class name of the component, the class name of
577 the application instantiating the component, and a hash reference with
578 the controller's configuration.
580 You are free to re-bless the object, instantiate a whole other
581 component or really do anything compatible with Catalyst's
582 expectations on a component.
584 For more information, please see L<Catalyst::Component/"COMPONENT($c,$arguments)">.
588 L<Catalyst>, L<Catalyst::Manual::Actions>, L<Catalyst::Component>
592 Robert Sedlacek C<rs@474.at>
594 =head1 LICENSE AND COPYRIGHT
596 This document is free, you can redistribute it and/or modify it under
597 the same terms as Perl itself.