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, or Engine,
50 it's best to leave it out of the C<Catalyst::> namespace. Use
51 <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 =item There's a community. Use it!
61 There are many experienced developers in the Catalyst community,
62 there's always the IRC channel and the mailing list to discuss things.
64 =item Add tests and documentation!
66 This gives a stable basis for contribution, and even more importantly,
67 builds trust. The easiest way is a test application. See
68 L<Catalyst::Manual::Tutorial::Testing> for more information.
74 While some core extensions (engines, plugins, etc.) have to be placed
75 in the C<Catalyst::*> namespace, the Catalyst core would like to ask
76 developers to use the C<CatalystX::*> namespace if possible.
78 When you try to put a base class for a C<Model>, C<View> or
79 C<Controller> directly under your C<MyApp> directory as, for example,
80 C<MyApp::Controller::Foo>, you will have the problem that Catalyst
81 will try to load that base class as a component of your
82 application. The solution is simple: Use another namespace. Common
83 ones are C<MyApp::Base::Controller::*> or C<MyApp::ControllerBase::*>
86 =head2 Can it be a simple module?
88 Sometimes you want to use functionality in your application that
89 doesn't require the framework at all. Remember that Catalyst is just
90 Perl and you always can just C<use> a module. If you have application
91 specific code that doesn't need the framework, there is no problem in
92 putting it in your C<MyApp::*> namespace. Just don't put it in
93 C<Model>, C<Controller> or C<View>, because that would make Catalyst
94 try to load them as components.
96 Writing a generic component that only works with Catalyst is wasteful
97 of your time. Try writing a plain perl module, and then a small bit
98 of glue that integrates it with Catalyst. See
99 L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> for a
100 module that takes the approach. The advantage here is that your
101 "Catalyst" DBIC schema works perfectly outside of Catalyst, making
102 testing (and command-line scripts) a breeze. The actual Catalyst
103 Model is just a few lines of glue that makes working with the schema
106 If you want the thinnest interface possible, take a look at
107 L<Catalyst::Model::Adaptor|Catalyst::Model::Adaptor>.
109 =head2 Inheritance and overriding methods
111 While Catalyst itself is still based on L<NEXT> (for multiple
112 inheritance), extension developers are encouraged to use L<Class::C3>,
113 which is what Catalyst will be switching to in some point in the
116 When overriding a method, keep in mind that some day additionally
117 arguments may be provided to the method, if the last parameter is not
118 a flat list. It is thus better to override a method by shifting the
119 invocant off of C<@_> and assign the rest of the used arguments, so
120 you can pass your complete arguments to the original method via C<@_>:
124 sub foo { my $self = shift;
125 my ($bar, $baz) = @_; # ... return
126 $self->next::method(@_); }
128 If you would do the common
130 my ($self, $foo, $bar) = @_;
132 you'd have to use a much uglier construct to ensure that all arguments
133 will be passed along and the method is future proof:
135 $self->next::method(@_[ 1 .. $#_ ]);
137 =head2 Tests and documentation
139 When you release your module to the CPAN, proper documentation and at
140 least a basic test suite (which means more than pod or even just
141 C<use_ok>, sorry) gives people a good base to contribute to the
142 module. It also shows that you care for your users. If you would like
143 your module to become a recommended addition, these things will prove
146 If you're just getting started, try using
147 L<CatalystX::Starter|CatalystX::Starter> to generate some example
148 tests for your module.
152 In planning to release a module to the community (Catalyst or CPAN and
153 Perl), you should consider if you have the resources to keep it up to
154 date, including fixing bugs and accepting contributions.
156 If you're not sure about this, you can always ask in the proper
157 Catalyst or Perl channels if someone else might be interested in the
158 project, and would jump in as co-maintainer.
160 A public repository can further ease interaction with the
161 community. Even read only access enables people to provide you with
162 patches to your current development version. subversion, SVN and SVK,
163 are broadly preferred in the Catalyst community.
165 If you're developing a Catalyst extension, please consider asking the
166 core team for space in Catalyst's own subversion repository. You can
167 get in touch about this via IRC or the Catalyst developers mailing
170 =head2 The context object
172 Sometimes you want to get a hold of the context object in a component
173 that was created on startup time, where no context existed yet. Often
174 this is about the model reading something out of the stash or other
175 context information (current language, for example).
177 If you use the context object in your component you have tied it to an
178 existing request. This means that you might get into problems when
179 you try to use the component (e.g. the model - the most common case)
180 outside of Catalyst, for example in cronjobs.
182 A stable solution to this problem is to design the Catalyst model
183 separately from the underlying model logic. Let's take
184 L<Catalyst::Model::DBIC::Schema> as an example. You can create a
185 schema outside of Catalyst that knows nothing about the web. This kind
186 of design ensures encapsulation and makes development and maintenance
187 a whole lot easier. The you use the aforementioned model to tie your
188 schema to your application. This gives you a C<MyApp::DBIC> (the name
189 is of course just an example) model as well as
190 C<MyApp::DBIC::TableName> models to access your result sources
193 By creating such a thin layer between the actual model and the
194 Catalyst application, the schema itself is not at all tied to any
195 application and the layer in-between can access the model's API using
196 information from the context object.
198 A Catalyst component accesses the context object at request time with
199 L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.
203 The application has to interact with the extension with some
204 configuration. There is of course again more than one way to do it.
208 You can specify any valid Perl attribute on Catalyst actions you like.
209 (See L<attributes/"Syntax of Attribute Lists"> for a description of
210 what is valid.) These will be available on the C<Catalyst::Action>
211 instance via its C<attributes> accessor. To give an example, this
214 sub foo : Local Bar('Baz') {
217 $self->action_for('foo')->attributes;
218 $c->res->body($attributes->{Bar}[0] );
221 will set the response body to C<Baz>. The values always come in an
222 array reference. As you can see, you can use attributes to configure
223 your actions. You can specify or alter these attributes via
224 L</"Component Configuration">, or even react on them as soon as
225 Catalyst encounters them by providing your own L<component base
226 class|/"Component Base Classes">.
228 =head2 Creating custom accessors
230 L<Catalyst::Component> uses L<Class::Accessor::Fast> for accessor
231 creation. Please refer to the modules documentation for usage
234 =head2 Component configuration
236 At creation time, the class configuration of your component (the one
237 available via C<$self-E<gt>config>) will be merged with possible
238 configuration settings from the applications configuration (either
239 directly or via config file). This is then stored in the controller
240 object's hash reference. So, if you read possible configurations like:
242 my $model_name = $controller->{model_name};
244 you will get the right value. The C<config> accessor always only
245 contains the original class configuration and must not be used for
246 component configuration.
248 You are advised to create accessors on your component class for your
249 configuration values. This is good practice and makes it easier to
250 capture configuration key typos. You can do this with the
251 C<mk_ro_accessors> method provided to L<Catalyst::Component> via
252 L<Class::Accessor::Fast>:
254 use base 'Catalyst::Controller';
255 __PACKAGE__->mk_ro_accessors('model_name');
257 my $model_name = $controller->model_name;
259 =head1 IMPLEMENTATION
261 This part contains the technical details of various implementation
262 methods. Please read the L</"BEST PRACTICES"> before you start your
263 implementation, if you haven't already.
265 =head2 Action classes
267 Usually, your action objects are of the class L<Catalyst::Action>.
268 You can override this with the C<ActionClass> attribute to influence
269 execution and/or dispatching of the action. A widely used example of
270 this is L<Catalyst::Action::RenderView>, which is used in every newly
271 created Catalyst application in your root controller:
273 sub end : ActionClass('RenderView') { }
275 Usually, you want to override the C<execute> and/or the C<match>
276 method. The execute method of the action will naturally call the
277 methods code. You can surround this by overriding the method in a
280 package Catalyst::Action::MyFoo; use strict;
282 use Class::C3; use base 'Catalyst::Action';
286 my ($controller, $c, @args) = @_;
287 # put your 'before' code here
288 my $r = $self->next::method(@_);
289 # put your 'after' code here
294 We are using L<Class::C3> to re-dispatch to the original C<execute> method
295 in the L<Catalyst::Action> class.
297 The Catalyst dispatcher handles an incoming request and, depending
298 upon the dispatch type, will call the appropriate target or chain.
299 From time to time it asks the actions themselves, or through the
300 controller, if they would match the current request. That's what the
301 C<match> method does. So by overriding this, you can change on what
302 the action will match and add new matching criteria.
304 For example, the action class below will make the action only match on
307 package Catalyst::Action::OnlyMondays; use strict;
310 use base 'Catalyst::Action';
314 return 0 if ( localtime(time) )[6] == 1;
315 return $self->next::method(@_);
319 And this is how we'd use it:
321 sub foo: Local ActionClass('OnlyMondays') {
323 $c->res->body('I feel motivated!');
326 If you are using action classes often or have some specific base
327 classes that you want to specify more conveniently, you can implement
328 a component base class providing an attribute handler.
330 For further information on action classes, please refer to
331 L<Catalyst::Action> and L<Catalyst::Manual::Actions>.
333 =head2 Component base classes
335 Many L<Catalyst::Plugin> that were written in Catalyst's early days
336 should really have been just controller base classes. With such a
337 class, you could provide functionality scoped to a single controller,
338 not polluting the global namespace in the context object.
340 You can provide regular Perl methods in a base class as well as
341 actions which will be inherited to the subclass. Please refer to
342 L</Controllers> for an example of this.
344 You can introduce your own attributes by specifying a handler method
345 in the controller base. For example, to use a C<FullClass> attribute
346 to specify a fully qualified action class name, you could use the
347 following implementation. Note, however, that this functionality is
348 already provided via the C<+> prefix for action classes. A simple
350 sub foo : Local ActionClass('+MyApp::Action::Bar') { ... }
352 will use C<MyApp::Action::Bar> as action class.
354 package MyApp::Base::Controller::FullClass; use strict; use base
355 'Catalyst::Controller';
357 sub _parse_FullClass_attr {
358 my ($self, $app_class, $action_name, $value, $attrs) = @_;
359 return( ActionClass => $value );
363 Note that the full line of arguments is only provided for completeness
364 sake. We could use this attribute in a subclass like any other
367 package MyApp::Controller::Foo;
369 use base 'MyApp::Base::Controller::FullClass';
371 sub foo : Local FullClass('MyApp::Action::Bar') { ... }
377 Many things can happen in controllers, and it often improves
378 maintainability to abstract some of the code out into reusable base
381 You can provide usual Perl methods that will be available via your
382 controller object, or you can even define Catalyst actions which will
383 be inherited by the subclasses. Consider this controller base class:
385 package MyApp::Base::Controller::ModelBase;
387 use base 'Catalyst::Controller';
389 sub list : Chained('base') PathPart('') Args(0) {
391 my $model = $c->model( $self->{model_name} );
392 my $condition = $self->{model_search_condition} || {};
393 my $attrs = $self->{model_search_attrs} || {};
394 $c->stash(rs => $model->search($condition, $attrs);
397 sub load : Chained('base') PathPart('') CaptureArgs(1) {
398 my ($self, $c, $id) = @_;
399 my $model = $c->model( $self->{model_name} );
400 $c->stash(row => $model->find($id));
404 This example implements two simple actions. The C<list> action chains
405 to a (currently non-existent) C<base> action and puts a result-set
406 into the stash taking a configured C<model_name> as well as a search
407 condition and attributes. This action is a
408 L<chained|Catalyst::DispatchType::Chained> endpoint. The other action,
409 called C< load > is a chain midpoint that takes one argument. It takes
410 the value as an ID and loads the row from the configured model. Please
411 not that the above code is simplified for clarity. It misses error
412 handling, input validation, and probably other things.
414 The class above is not very useful on its own, but we can combine it
415 with some custom actions by sub-classing it:
417 package MyApp::Controller::Foo;
419 use base 'MyApp::Base::Controller::ModelBase';
421 __PACKAGE__->config( model_name => 'DB::Foo',
422 model_search_condition=> { is_active => 1 },
423 model_search_attrs => { order_by => 'name' },
426 sub base : Chained PathPart('foo') CaptureArgs(0) { }
428 sub view : Chained('load') Args(0) {
430 my $row = $c->stash->{row};
431 $c->res->body(join ': ', $row->name,
432 $row->description); }
435 This class uses the formerly created controller as a base
436 class. First, we see the configurations that were used in the parent
437 class. Next comes the C<base> action, where everything chains off of.
439 Note that inherited actions act like they were declared in your
440 controller itself. You can therefor call them just by their name in
441 C<forward>s, C<detaches> and C<Chained(..)> specifications. This is an
442 important part of what makes this technique so useful.
444 The new C<view> action ties itself to the C<load> action specified in
445 the base class and outputs the loaded row's C<name> and C<description>
446 columns. The controller C<MyApp::Controller::Foo> now has these
447 publicly available paths:
453 Will call the controller's C<base>, then the base classes C<list>
458 First, the controller's C<base> will be called, then it will C<load>
459 the row with the corresponding C<$id>. After that, C<view> will
460 display some fields out of the object.
464 =head2 Models and Views
466 If the functionality you'd like to add is really a data-set that you
467 want to manipulate, for example internal document types, images,
468 files, it might be better suited as a model.
470 The same applies for views. If your code handles representation or
471 deals with the applications interface and should be universally
472 available, it could be a perfect candidate for a view.
474 Please implement a C<process> method in your views. This method will
475 be called by Catalyst if it is asked to forward to a component without
476 a specified action. Note that C<process> is B<not a Catalyst action>
477 but a simple Perl method.
479 You are also encouraged to implement a C<render> method corresponding
480 with the one in L<Catalyst::View::TT>. This has proven invaluable,
481 because people can use your view for much more fine-grained content
484 Here is some example code for a fictional view:
486 package CatalystX::View::MyView;
488 use base 'Catalyst::View';
492 my $template = $c->stash->{template};
493 my $content = $self->render($c, $template, $c->stash);
494 $c->res->body( $content );
498 my ($self, $c, $template, $args) = @_;
499 # prepare content here
506 The first thing to say about plugins is that if you're not sure if
507 your module should be a plugin, it probably shouldn't. It once was
508 common to add features to Catalyst by writing plugins that provide
509 accessors to said functionality. As Catalyst grew more popular, it
510 became obvious that this qualifies as bad practice.
512 By designing your module as a Catalyst plugin, every method you
513 implement, import or inherit will be available via your applications
514 context object. A plugin pollutes the global namespace, and you
515 should be only doing that when you really need to.
517 Often, developers design extensions as plugins because they need to
518 get hold of the context object. Either to get at the stash or
519 request/response objects are the widely spread reasons. It is,
520 however, perfectly possible to implement a regular Catalyst component
521 (read: model, view or controller) that receives the current context
522 object via L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.
524 When is a plugin suited to your task? Your code needs to be a
525 plugin to act upon or alter specific parts of Catalyst's request
526 lifecycle. If your functionality needs to wrap some C<prepare_*> or
527 C<finalize_*> stages, you won't get around a plugin.
529 Another valid target for a plugin architecture are things that
530 B<really> have to be globally available, like sessions or
533 B<Please do not> release Catalyst extensions as plugins only to
534 provide some functionality application wide. Design it as a controller
535 base class or another suiting technique with a smaller scope, so that
536 your code only influences those parts of the application where it is
537 needed, and namespace clashes and conflicts are ruled out.
539 The implementation is pretty easy. Your plugin will be inserted in the
540 application's inheritance list, above Catalyst itself. You can by this
541 alter Catalyst's request lifecycle behaviour. Every method you
542 declare, every import in your package will be available as method on
543 the application and the context object. As an example, let's say you
544 want Catalyst to warn you every time uri_for returned an undefined
545 value, for example because you specified the wrong number of captures
546 for the targeted action chain. You could do this with this simple
547 implementation (excuse the lame class name, it's just an example):
549 package Catalyst::Plugin::UriforUndefWarning;
555 my $uri = $c->next::method(@_);
556 $c->log->warn( 'uri_for returned undef for:', join(', ', @_), );
562 This would override Catalyst's C<uri_for> method and emit a C<warn>
563 log entry containing the arguments that led to the undefined return
566 =head2 Factory components with COMPONENT()
568 Every component inheriting from L<Catalyst::Component> contains a
569 C<COMPONENT> method. It is used on application startup by
570 C<setup_components> to instantiate the component object for the
571 Catalyst application. By default, this will merge the components own
572 C<config>uration with the application wide overrides and call the
573 class' C<new> method to return the component object.
575 You can override this method and do and return whatever you want.
576 However, you should use L<Class::C3> to forward to the original
577 C<COMPONENT> method to merge the configuration of your component.
579 Here is a stub C<COMPONENT> method:
581 package CatalystX::Component::Foo;
583 use base 'Catalyst::Component';
589 my ($app_class, $config) = @_;
591 # do things here before instantiation my
592 $obj = $self->next::method(@_);
593 # do things to object after instantiation
597 The arguments are the class name of the component, the class name of
598 the application instantiating the component, and a hash reference with
599 the controller's configuration.
601 You are free to re-bless the object, instantiate a whole other
602 component or really do anything compatible with Catalyst's
603 expectations on a component.
605 For more information, please see L<Catalyst::Component/"COMPONENT($c,$arguments)">.
609 L<Catalyst>, L<Catalyst::Manual::Actions>, L<Catalyst::Component>
613 Robert Sedlacek C<< <rs@474.at> >>
615 Jonathan Rockway C<< <jrockway@cpan.org> >>
617 =head1 LICENSE AND COPYRIGHT
619 This document is free, you can redistribute it and/or modify it under
620 the same terms as Perl itself.