3 Catalyst::Manual::WritingPlugins - An introduction to writing plugins
8 Writing an integrated plugin for L<Catalyst> using L<NEXT>.
12 A Catalyst plugin is an integrated part of your application. By writing
13 plugins you can, for example, perform processing actions automatically,
14 instead of having to C<forward> to a processing method every time you
19 L<NEXT> is used to re-dispatch a method call as if the calling method
20 doesn't exist at all. In other words: If the class you're inheriting
21 from defines a method, and you're overloading that method in your own
22 class, NEXT gives you the possibility to call that overloaded method.
24 This technique is the usual way to plug a module into Catalyst.
26 =head1 INTEGRATING YOUR PLUGIN
28 You can use L<NEXT> for your plugin by overloading certain methods which
29 are called by Catalyst during a request.
31 =head2 The request life-cycle
33 Catalyst creates a context object (C<$context> or, more usually, its
34 alias C<$c>) on every request, which is passed to all the handlers that
35 are called from preparation to finalization.
37 For a complete list of the methods called during a request, see
38 L<Catalyst::Manual::Internals>. The request can be split up in three
45 When the C<prepare> handler is called, it initializes the request
46 object, connections, headers, and everything else that needs to be
47 prepared. C<prepare> itself calls other methods to delegate these tasks.
48 After this method has run, everything concerning the request is in
53 The dispatching phase is where the black magic happens. The C<dispatch>
54 handler decides which actions have to be called for this request.
58 Catalyst uses the C<finalize> method to prepare the response to give to
59 the client. It makes decisions according to your C<response> (e.g. where
60 you want to redirect the user to). After this method, the response is
61 ready and waiting for you to do something with it--usually, hand it off
66 =head2 What Plugins look like
68 There's nothing special about a plugin except its name. A module named
69 C<Catalyst::Plugin::MyPlugin> will be loaded by Catalyst if you specify it
70 in your application class, e.g.:
73 package Catalyst::Plugin::MyPlugin;
78 # MyApp.pm, your application class
79 use Catalyst qw/-Debug MyPlugin/;
81 This does nothing but load your module. We'll now see how to overload stages of the request cycle, and provide accessors.
83 =head2 Calling methods from your Plugin
85 Methods that do not overload a handler are available directly in the
86 C<$c> context object; they don't need to be qualified with namespaces,
87 and you don't need to C<use> them.
89 package Catalyst::Plugin::Foobar;
91 sub foo { return 'bar'; }
93 # anywhere else in your Catalyst application:
95 $c->foo(); # will return 'bar'
99 =head2 Overloading - Plugging into Catalyst
101 If you don't just want to provide methods, but want to actually plug
102 your module into the request cycle, you have to overload the handler
103 that suits your needs.
105 Every handler gets the context object passed as its first argument. Pass
106 the rest of the arguments to the next handler in row by calling it via
108 $c->NEXT::handler-name( @_ );
110 if you already C<shift>ed it out of C<@_>. Remember to C<use> C<NEXT>.
112 =head2 Storage and Configuration
114 Some Plugins use their accessor names as a storage point, e.g.
118 $c->{my_accessor} = ..
120 but it is more safe and clear to put your data in your configuration
123 $c->config->{my_plugin}{ name } = $value;
125 If you need to maintain data for more than one request, you should
126 store it in a session.
130 Here's a simple example Plugin that shows how to overload C<prepare>
131 to add a unique ID to every request:
133 package Catalyst::Plugin::RequestUUID;
138 use Catalyst::Request;
144 { # create a uuid accessor
145 package Catalyst::Request;
146 __PACKAGE__->mk_accessors('uuid');
152 # Turns the engine-specific request into a Catalyst context .
153 my $c = $class->NEXT::prepare( @_ );
155 $c->request->uuid( Data::UUID->new->create_str );
156 $c->log->debug( 'Request UUID "'. $c->request->uuid .'"' );
163 Let's just break it down into pieces:
165 package Catalyst::Plugin::RequestUUID;
167 The package name has to start with C<Catalyst::Plugin::> to make sure you
168 can load your plugin by simply specifying
170 use Catalyst qw/RequestUUID/;
172 in the application class. L<warnings> and L<strict> are recommended for
173 all Perl applications.
179 NEXT must be explicitly C<use>d. L<Data::UUID> generates our unique
180 ID. The C<$VERSION> gets set because it's a) a good habit and b)
181 L<ExtUtils::ModuleMaker> likes it.
185 These methods are called without attributes (Private, Local, etc.).
189 We get the context object for this request as the first argument.
191 B<Hint!>:Be sure you shift the context object out of C<@_> in this. If
196 it remains there, and you may run into problems if you're not aware of
197 what you pass to the handler you've overloaded. If you take a look at
199 $c = $c->NEXT::prepare( @_ );
201 you see you would pass the context twice here if you don't shift it out
202 of your parameter list.
204 This line is the main part of the plugin procedure. We call the
205 overloaded C<prepare> method and pass along the parameters we got. We
206 also overwrite the context object C<$c> with the one returned by the
207 called method returns. We'll return our modified context object at the
210 Note that that if we modify C<$c> before this line, we also modify it
211 before the original (overloaded) C<prepare> is run. If we modify it
212 after, we modify an already prepared context. And, of course, it's no
213 problem to do both, if you need to. Another example of working on the
214 context before calling the actual handler would be setting header
215 information before C<finalize> does its job.
217 $c->req->{req_uuid} = Data::UUID->new->create_str;
219 This line creates a new L<Data::UUID> object and calls the C<create_str>
220 method. The value is saved in our request, under the key C<req_uuid>. We
221 can use that to access it in future in our application.
223 $c->log->debug( 'Request UUID "'. $c->req->{req_uuid} .'"' );
225 This sends our UUID to the C<debug> log.
231 passes our modified context object back to whoever has called us. This
232 could be Catalyst itself, or the overloaded handler of another plugin.
236 L<Catalyst>, L<NEXT>, L<ExtUtils::ModuleMaker>, L<Catalyst::Manual::Plugins>,
237 L<Catalyst::Manual::Internals>.
241 Sebastian Riedel and his team of Catalyst developers as well as all the
242 helpful people in #catalyst.
246 This program is free software, you can redistribute it and/or modify it
247 under the same terms as Perl itself.
251 S<Robert Sedlacek, C<phaylon@dunkelheit.at>> with a lot of help from the