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 specified 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.
92 Accessor for the current action
96 Get a component object by name.
98 $c->comp('MyApp::Model::MyModel')->do_stuff;
101 Returns a hashref containing your applications settings.
104 Overload to enable debug messages.
106 $c->detach( $command [, \@arguments ] )
107 Like "forward" but doesn't return.
110 Contains the dispatcher instance. Stringifies to class.
112 $c->forward( $command [, \@arguments ] )
113 Forward processing to a private action or a method from a class. If
114 you define a class without method it will default to process(). also
115 takes an optional arrayref containing arguments to be passed to the
116 new function. $c->req->args will be reset upon returning from the
120 $c->forward('index');
121 $c->forward(qw/MyApp::Model::CDBI::Foo do_stuff/);
122 $c->forward('MyApp::View::TT');
125 Accessor to the namespace of the current action
128 Merges @path with $c->config->{home} and returns a Path::Class
133 $c->path_to( 'db', 'sqlite.db' );
140 $c->uri_for($path,[@args])
141 Merges path with $c->request->base for absolute uri's and with
142 $c->request->match for relative uri's, then returns a normalized URI
143 object. If any args are passed, they are added at the end of the
147 $c->error($error, ...)
149 Returns an arrayref containing error messages.
151 my @error = @{ $c->error };
155 $c->error('Something bad happened');
162 Contains the engine instance. Stringifies to the class.
165 Contains the logging object. Unless it is already set Catalyst sets
166 this up with a "Catalyst::Log" object. To use your own log class:
168 $c->log( MyLogger->new );
169 $c->log->info("now logging with my own logger!");
171 Your log class should implement the methods described in the
172 "Catalyst::Log" man page.
174 $c->plugin( $name, $class, @args )
175 Instant plugins for Catalyst. Classdata accessor/mutator will be
176 created, class loaded and instantiated.
178 MyApp->plugin( 'prototype', 'HTML::Prototype' );
180 $c->prototype->define_javascript_functions;
184 Returns a "Catalyst::Request" object.
190 Returns a "Catalyst::Response" object.
195 Contains the return value of the last executed action.
198 Returns a hashref containing all your data.
200 print $c->stash->{foo};
202 Keys may be set in the stash by assigning to the hash reference, or
203 by passing either a single hash reference or a list of key/value
208 $c->stash->{foo} ||= 'yada';
209 $c->stash( { moose => 'majestic', qux => 0 } );
210 $c->stash( bar => 1, gorch => 2 );
213 Returns the Catalyst welcome HTML page.
216 $c->benchmark($coderef)
217 Takes a coderef with arguments and returns elapsed time as float.
219 my ( $elapsed, $status ) = $c->benchmark( sub { return 1 } );
220 $c->log->info( sprintf "Processing took %f seconds", $elapsed );
223 Contains the components.
226 Returns a hashref containing coderefs and execution counts. (Needed
227 for deep recursion detection)
230 Returns the actual forward depth.
233 Dispatch request to actions.
236 Returns a list of 2-element array references (name, structure) pairs
237 that will be dumped on the error page in debug mode.
239 $c->execute($class, $coderef)
240 Execute a coderef in given class and catch exceptions. Errors are
241 available via $c->error.
259 An alias for finalize_body.
262 Finalize the input after reading is complete.
265 Finalize uploads. Cleans up any temporary files.
267 $c->get_action( $action, $namespace )
268 Get an action in a given namespace.
270 $c->get_actions( $action, $namespace )
271 Get all actions of a given name in a namespace and all base
274 handle_request( $class, @arguments )
277 $c->prepare(@arguments)
278 Turns the engine-specific request( Apache, CGI ... ) into a Catalyst
285 Prepare message body.
287 $c->prepare_body_chunk( $chunk )
288 Prepare a chunk of data before sending it to HTTP::Body.
290 $c->prepare_body_parameters
291 Prepare body parameters.
293 $c->prepare_connection
302 $c->prepare_parameters
306 Prepare path and base.
308 $c->prepare_query_parameters
309 Prepare query parameters.
312 Prepare the input for reading.
315 Prepare the engine request.
321 Prepare the output for writing.
323 $c->read( [$maxlength] )
324 Read a chunk of data from the request body. This method is designed
325 to be used in a while loop, reading $maxlength bytes on every call.
326 $maxlength defaults to the size of the request if not specified.
328 You have to set MyApp->config->{parse_on_demand} to use this
334 $c->set_action( $action, $code, $namespace, $attrs )
335 Set an action in a given namespace.
337 $c->setup_actions($component)
338 Setup actions for a component.
349 Writes $data to the output stream. When using this method directly,
350 you will need to manually set the Content-Length header to the
351 length of your output data, if known.
354 Returns the Catalyst version number. mostly useful for powered by
355 messages in template systems.
358 Catalyst uses internal actions like "_DISPATCH", "_BEGIN", "_AUTO"
359 "_ACTION" and "_END", these are by default not shown in the private
362 But you can deactivate this with a config parameter.
364 MyApp->config->{show_internal_actions} = 1;
367 By default Catalyst is not case sensitive, so "MyApp::C::FOO::Bar"
370 But you can activate case sensitivity with a config parameter.
372 MyApp->config->{case_sensitive} = 1;
374 So "MyApp::C::Foo::Bar" becomes "/Foo/Bar".
377 The request body is usually parsed at the beginning of a request, but if
378 you want to handle input yourself or speed things up a bit you can
379 enable on-demand parsing with a config parameter.
381 MyApp->config->{parse_on_demand} = 1;
384 Many production servers operate using the common double-server approach,
385 with a lightweight frontend web server passing requests to a larger
386 backend server. An application running on the backend server must deal
387 with two problems: the remote user always appears to be '127.0.0.1' and
388 the server's hostname will appear to be 'localhost' regardless of the
389 virtual host the user connected through.
391 Catalyst will automatically detect this situation when you are running
392 both the frontend and backend servers on the same machine. The following
393 changes are made to the request.
395 $c->req->address is set to the user's real IP address, as read from the
396 HTTP_X_FORWARDED_FOR header.
398 The host value for $c->req->base and $c->req->uri is set to the real host,
399 as read from the HTTP_X_FORWARDED_HOST header.
401 Obviously, your web server must support these 2 headers for this to
404 In a more complex server farm environment where you may have your
405 frontend proxy server(s) on different machines, you will need to set a
406 configuration option to tell Catalyst to read the proxied data from the
409 MyApp->config->{using_frontend_proxy} = 1;
411 If you do not wish to use the proxy support at all, you may set:
413 MyApp->config->{ignore_frontend_proxy} = 1;
416 Catalyst has been tested under Apache 2's threading mpm_worker,
417 mpm_winnt, and the standalone forking HTTP server on Windows. We believe
418 the Catalyst core to be thread-safe.
420 If you plan to operate in a threaded environment, remember that all
421 other modules you are using must also be thread-safe. Some modules, most
422 notably DBD::SQLite, are not thread-safe.
427 Join #catalyst on irc.perl.org.
431 http://lists.rawmode.org/mailman/listinfo/catalyst
432 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
436 http://catalyst.perl.org
439 Catalyst::Manual - The Catalyst Manual
440 Catalyst::Engine - Core Engine
441 Catalyst::Log - The Log Class.
442 Catalyst::Request - The Request Object
443 Catalyst::Response - The Response Object
444 Catalyst::Test - The test suite.
504 Sebastian Riedel, "sri@oook.de"
507 This library is free software, you can redistribute it and/or modify it
508 under the same terms as Perl itself.