2 Catalyst - The Elegant MVC Web Application Framework
5 # use the helper to start a new application
9 # add models, views, controllers
10 script/myapp_create.pl model Something
11 script/myapp_create.pl view Stuff
12 script/myapp_create.pl controller Yada
15 script/myapp_server.pl
17 # command line interface
18 script/myapp_test.pl /yada
22 use Catalyst qw/My::Module My::OtherModule/;
24 use Catalyst '-Debug';
26 use Catalyst qw/-Debug -Engine=CGI/;
28 sub default : Private { $_[1]->res->output('Hello') } );
30 sub index : Path('/index.html') {
31 my ( $self, $c ) = @_;
32 $c->res->output('Hello');
36 sub product : Regex('^product[_]*(\d*).html$') {
37 my ( $self, $c ) = @_;
38 $c->stash->{template} = 'product.tt';
39 $c->stash->{product} = $c->req->snippets->[0];
42 See also Catalyst::Manual::Intro
45 The key concept of Catalyst is DRY (Don't Repeat Yourself).
47 See Catalyst::Manual for more documentation.
49 Catalyst plugins can be loaded by naming them as arguments to the "use
50 Catalyst" statement. Omit the "Catalyst::Plugin::" prefix from the
51 plugin name, so "Catalyst::Plugin::My::Module" becomes "My::Module".
53 use Catalyst 'My::Module';
55 Special flags like -Debug and -Engine can also be specifed as arguments
56 when Catalyst is loaded:
58 use Catalyst qw/-Debug My::Module/;
60 The position of plugins and flags in the chain is important, because
61 they are loaded in exactly the order that they appear.
63 The following flags are supported:
66 enables debug output, i.e.:
68 use Catalyst '-Debug';
70 this is equivalent to:
76 Force Catalyst to use a specific dispatcher.
79 Force Catalyst to use a specific engine. Omit the
80 "Catalyst::Engine::" prefix of the engine name, i.e.:
82 use Catalyst '-Engine=CGI';
85 Force Catalyst to use a specific home directory.
93 Get a component object by name.
95 $c->comp('MyApp::Model::MyModel')->do_stuff;
98 Returns a hashref containing your applications settings.
101 Overload to enable debug messages.
103 $c->detach( $command [, \@arguments ] )
104 Like "forward" but doesn't return.
107 Contains the dispatcher instance. Stringifies to class.
109 $c->forward( $command [, \@arguments ] )
110 Forward processing to a private action or a method from a class. If
111 you define a class without method it will default to process(). also
112 takes an optional arrayref containing arguments to be passed to the
113 new function. $c->req->args will be reset upon returning from the
117 $c->forward('index');
118 $c->forward(qw/MyApp::Model::CDBI::Foo do_stuff/);
119 $c->forward('MyApp::View::TT');
127 Merges path with $c->request->base for absolute uri's and with
128 $c->request->match for relative uri's, then returns a normalized URI
132 $c->error($error, ...)
134 Returns an arrayref containing error messages.
136 my @error = @{ $c->error };
140 $c->error('Something bad happened');
143 Contains the engine instance. Stringifies to the class.
146 Contains the logging object. Unless it is already set Catalyst sets
147 this up with a "Catalyst::Log" object. To use your own log class:
149 $c->log( MyLogger->new );
150 $c->log->info("now logging with my own logger!");
152 Your log class should implement the methods described in the
153 "Catalyst::Log" man page.
155 $c->plugin( $name, $class, @args )
156 Instant plugins for Catalyst. Classdata accessor/mutator will be
157 created, class loaded and instantiated.
159 MyApp->plugin( 'prototype', 'HTML::Prototype' );
161 $c->prototype->define_javascript_functions;
165 Returns a "Catalyst::Request" object.
171 Returns a "Catalyst::Response" object.
176 Contains the return value of the last executed action.
179 Returns a hashref containing all your data.
181 $c->stash->{foo} ||= 'yada';
182 print $c->stash->{foo};
185 $c->benchmark($coderef)
186 Takes a coderef with arguments and returns elapsed time as float.
188 my ( $elapsed, $status ) = $c->benchmark( sub { return 1 } );
189 $c->log->info( sprintf "Processing took %f seconds", $elapsed );
192 Contains the components.
195 Returns a hashref containing coderefs and execution counts. (Needed
196 for deep recursion detection)
199 Returns the actual forward depth.
202 Dispatch request to actions.
204 $c->execute($class, $coderef)
205 Execute a coderef in given class and catch exceptions. Errors are
206 available via $c->error.
224 An alias for finalize_body.
227 Finalize the input after reading is complete.
230 Finalize uploads. Cleans up any temporary files.
232 $c->get_action( $action, $namespace, $inherit )
233 Get an action in a given namespace.
235 handle_request( $class, @arguments )
238 $c->prepare(@arguments)
239 Turns the engine-specific request( Apache, CGI ... ) into a Catalyst
246 Prepare message body.
248 $c->prepare_body_parameters
249 Prepare body parameters.
251 $c->prepare_connection
260 $c->prepare_parameters
264 Prepare path and base.
266 $c->prepare_query_parameters
267 Prepare query parameters.
270 Prepare the input for reading.
273 Prepare the engine request.
279 Prepare the output for writing.
281 $c->read( [$maxlength] )
282 Read a chunk of data from the request body. This method is designed
283 to be used in a while loop, reading $maxlength bytes on every call.
284 $maxlength defaults to the size of the request if not specified.
286 You have to set MyApp->config->{parse_on_demand} to use this
292 $c->set_action( $action, $code, $namespace, $attrs )
293 Set an action in a given namespace.
295 $c->setup_actions($component)
296 Setup actions for a component.
307 Writes $data to the output stream. When using this method directly,
308 you will need to manually set the Content-Length header to the
309 length of your output data, if known.
312 By default Catalyst is not case sensitive, so "MyApp::C::FOO::Bar"
315 But you can activate case sensitivity with a config parameter.
317 MyApp->config->{case_sensitive} = 1;
319 So "MyApp::C::Foo::Bar" becomes "/Foo/Bar".
322 The request body is usually parsed at the beginning of a request, but if
323 you want to handle input yourself or speed things up a bit you can
324 enable on-demand parsing with a config parameter.
326 MyApp->config->{parse_on_demand} = 1;
329 Many production servers operate using the common double-server approach,
330 with a lightweight frontend web server passing requests to a larger
331 backend server. An application running on the backend server must deal
332 with two problems: the remote user always appears to be '127.0.0.1' and
333 the server's hostname will appear to be 'localhost' regardless of the
334 virtual host the user connected through.
336 Catalyst will automatically detect this situation when you are running
337 both the frontend and backend servers on the same machine. The following
338 changes are made to the request.
340 $c->req->address is set to the user's real IP address, as read from the
341 HTTP_X_FORWARDED_FOR header.
343 The host value for $c->req->base and $c->req->uri is set to the real host,
344 as read from the HTTP_X_FORWARDED_HOST header.
346 Obviously, your web server must support these 2 headers for this to
349 In a more complex server farm environment where you may have your
350 frontend proxy server(s) on different machines, you will need to set a
351 configuration option to tell Catalyst to read the proxied data from the
354 MyApp->config->{using_frontend_proxy} = 1;
356 If you do not wish to use the proxy support at all, you may set:
358 MyApp->config->{ignore_frontend_proxy} = 1;
361 Catalyst has been tested under Apache 2's threading mpm_worker,
362 mpm_winnt, and the standalone forking HTTP server on Windows. We believe
363 the Catalyst core to be thread-safe.
365 If you plan to operate in a threaded environment, remember that all
366 other modules you are using must also be thread-safe. Some modules, most
367 notably DBD::SQLite, are not thread-safe.
372 Join #catalyst on irc.perl.org.
376 http://lists.rawmode.org/mailman/listinfo/catalyst
377 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
381 http://catalyst.perl.org
384 Catalyst::Manual - The Catalyst Manual
385 Catalyst::Engine - Core Engine
386 Catalyst::Log - The Log Class.
387 Catalyst::Request - The Request Object
388 Catalyst::Response - The Response Object
389 Catalyst::Test - The test suite.
441 Sebastian Riedel, "sri@oook.de"
444 This library is free software . You can redistribute it and/or modify it
445 under the same terms as perl itself.