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.
235 $c->execute($class, $coderef)
236 Execute a coderef in given class and catch exceptions. Errors are
237 available via $c->error.
255 An alias for finalize_body.
258 Finalize the input after reading is complete.
261 Finalize uploads. Cleans up any temporary files.
263 $c->get_action( $action, $namespace, $inherit )
264 Get an action in a given namespace.
266 handle_request( $class, @arguments )
269 $c->prepare(@arguments)
270 Turns the engine-specific request( Apache, CGI ... ) into a Catalyst
277 Prepare message body.
279 $c->prepare_body_chunk( $chunk )
280 Prepare a chunk of data before sending it to HTTP::Body.
282 $c->prepare_body_parameters
283 Prepare body parameters.
285 $c->prepare_connection
294 $c->prepare_parameters
298 Prepare path and base.
300 $c->prepare_query_parameters
301 Prepare query parameters.
304 Prepare the input for reading.
307 Prepare the engine request.
313 Prepare the output for writing.
315 $c->read( [$maxlength] )
316 Read a chunk of data from the request body. This method is designed
317 to be used in a while loop, reading $maxlength bytes on every call.
318 $maxlength defaults to the size of the request if not specified.
320 You have to set MyApp->config->{parse_on_demand} to use this
326 $c->set_action( $action, $code, $namespace, $attrs )
327 Set an action in a given namespace.
329 $c->setup_actions($component)
330 Setup actions for a component.
341 Writes $data to the output stream. When using this method directly,
342 you will need to manually set the Content-Length header to the
343 length of your output data, if known.
346 Returns the Catalyst version number. mostly useful for powered by
347 messages in template systems.
350 By default Catalyst is not case sensitive, so "MyApp::C::FOO::Bar"
353 But you can activate case sensitivity with a config parameter.
355 MyApp->config->{case_sensitive} = 1;
357 So "MyApp::C::Foo::Bar" becomes "/Foo/Bar".
360 The request body is usually parsed at the beginning of a request, but if
361 you want to handle input yourself or speed things up a bit you can
362 enable on-demand parsing with a config parameter.
364 MyApp->config->{parse_on_demand} = 1;
367 Many production servers operate using the common double-server approach,
368 with a lightweight frontend web server passing requests to a larger
369 backend server. An application running on the backend server must deal
370 with two problems: the remote user always appears to be '127.0.0.1' and
371 the server's hostname will appear to be 'localhost' regardless of the
372 virtual host the user connected through.
374 Catalyst will automatically detect this situation when you are running
375 both the frontend and backend servers on the same machine. The following
376 changes are made to the request.
378 $c->req->address is set to the user's real IP address, as read from the
379 HTTP_X_FORWARDED_FOR header.
381 The host value for $c->req->base and $c->req->uri is set to the real host,
382 as read from the HTTP_X_FORWARDED_HOST header.
384 Obviously, your web server must support these 2 headers for this to
387 In a more complex server farm environment where you may have your
388 frontend proxy server(s) on different machines, you will need to set a
389 configuration option to tell Catalyst to read the proxied data from the
392 MyApp->config->{using_frontend_proxy} = 1;
394 If you do not wish to use the proxy support at all, you may set:
396 MyApp->config->{ignore_frontend_proxy} = 1;
399 Catalyst has been tested under Apache 2's threading mpm_worker,
400 mpm_winnt, and the standalone forking HTTP server on Windows. We believe
401 the Catalyst core to be thread-safe.
403 If you plan to operate in a threaded environment, remember that all
404 other modules you are using must also be thread-safe. Some modules, most
405 notably DBD::SQLite, are not thread-safe.
410 Join #catalyst on irc.perl.org.
414 http://lists.rawmode.org/mailman/listinfo/catalyst
415 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
419 http://catalyst.perl.org
422 Catalyst::Manual - The Catalyst Manual
423 Catalyst::Engine - Core Engine
424 Catalyst::Log - The Log Class.
425 Catalyst::Request - The Request Object
426 Catalyst::Response - The Response Object
427 Catalyst::Test - The test suite.
485 Sebastian Riedel, "sri@oook.de"
488 This library is free software, you can redistribute it and/or modify it
489 under the same terms as Perl itself.