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.
103 $c->controller($name)
104 Get a Catalyst::Controller instance by name.
106 $c->controller('Foo')->do_stuff;
109 Overload to enable debug messages.
111 $c->detach( $command [, \@arguments ] )
112 Like "forward" but doesn't return.
115 Contains the dispatcher instance. Stringifies to class.
117 $c->forward( $command [, \@arguments ] )
118 Forward processing to a private action or a method from a class. If
119 you define a class without method it will default to process(). also
120 takes an optional arrayref containing arguments to be passed to the
121 new function. $c->req->args will be reset upon returning from the
125 $c->forward('index');
126 $c->forward(qw/MyApp::Model::CDBI::Foo do_stuff/);
127 $c->forward('MyApp::View::TT');
130 Get a Catalyst::Model instance by name.
132 $c->model('Foo')->do_stuff;
135 Accessor to the namespace of the current action
138 Merges @path with $c->config->{home} and returns a Path::Class
143 $c->path_to( 'db', 'sqlite.db' );
150 $c->uri_for($path,[@args])
151 Merges path with $c->request->base for absolute uri's and with
152 $c->request->match for relative uri's, then returns a normalized URI
153 object. If any args are passed, they are added at the end of the
157 $c->error($error, ...)
159 Returns an arrayref containing error messages.
161 my @error = @{ $c->error };
165 $c->error('Something bad happened');
172 Contains the engine instance. Stringifies to the class.
175 Contains the logging object. Unless it is already set Catalyst sets
176 this up with a "Catalyst::Log" object. To use your own log class:
178 $c->log( MyLogger->new );
179 $c->log->info("now logging with my own logger!");
181 Your log class should implement the methods described in the
182 "Catalyst::Log" man page.
184 $c->plugin( $name, $class, @args )
185 Instant plugins for Catalyst. Classdata accessor/mutator will be
186 created, class loaded and instantiated.
188 MyApp->plugin( 'prototype', 'HTML::Prototype' );
190 $c->prototype->define_javascript_functions;
194 Returns a "Catalyst::Request" object.
200 Returns a "Catalyst::Response" object.
205 Contains the return value of the last executed action.
208 Returns a hashref containing all your data.
210 print $c->stash->{foo};
212 Keys may be set in the stash by assigning to the hash reference, or
213 by passing either a single hash reference or a list of key/value
218 $c->stash->{foo} ||= 'yada';
219 $c->stash( { moose => 'majestic', qux => 0 } );
220 $c->stash( bar => 1, gorch => 2 );
223 Get a Catalyst::View instance by name.
225 $c->view('Foo')->do_stuff;
228 Returns the Catalyst welcome HTML page.
231 $c->benchmark($coderef)
232 Takes a coderef with arguments and returns elapsed time as float.
234 my ( $elapsed, $status ) = $c->benchmark( sub { return 1 } );
235 $c->log->info( sprintf "Processing took %f seconds", $elapsed );
238 Contains the components.
240 $c->context_class($class)
241 Contains the context class.
244 Returns a hashref containing coderefs and execution counts. (Needed
245 for deep recursion detection)
248 Returns the actual forward depth.
251 Dispatch request to actions.
253 $c->dispatcher_class($class)
254 Contains the dispatcher class.
257 Returns a list of 2-element array references (name, structure) pairs
258 that will be dumped on the error page in debug mode.
260 $c->engine_class($class)
261 Contains the engine class.
263 $c->execute($class, $coderef)
264 Execute a coderef in given class and catch exceptions. Errors are
265 available via $c->error.
283 An alias for finalize_body.
286 Finalize the input after reading is complete.
289 Finalize uploads. Cleans up any temporary files.
291 $c->get_action( $action, $namespace )
292 Get an action in a given namespace.
294 $c->get_actions( $action, $namespace )
295 Get all actions of a given name in a namespace and all base
298 handle_request( $class, @arguments )
301 $c->prepare(@arguments)
302 Turns the engine-specific request( Apache, CGI ... ) into a Catalyst
309 Prepare message body.
311 $c->prepare_body_chunk( $chunk )
312 Prepare a chunk of data before sending it to HTTP::Body.
314 $c->prepare_body_parameters
315 Prepare body parameters.
317 $c->prepare_connection
326 $c->prepare_parameters
330 Prepare path and base.
332 $c->prepare_query_parameters
333 Prepare query parameters.
336 Prepare the input for reading.
339 Prepare the engine request.
345 Prepare the output for writing.
347 $c->request_class($class)
348 Contains the request class.
350 $c->response_class($class)
351 Contains the response class.
353 $c->read( [$maxlength] )
354 Read a chunk of data from the request body. This method is designed
355 to be used in a while loop, reading $maxlength bytes on every call.
356 $maxlength defaults to the size of the request if not specified.
358 You have to set MyApp->config->{parse_on_demand} to use this
364 $c->set_action( $action, $code, $namespace, $attrs )
365 Set an action in a given namespace.
367 $c->setup_actions($component)
368 Setup actions for a component.
382 Writes $data to the output stream. When using this method directly,
383 you will need to manually set the Content-Length header to the
384 length of your output data, if known.
387 Returns the Catalyst version number. mostly useful for powered by
388 messages in template systems.
391 Catalyst uses internal actions like "_DISPATCH", "_BEGIN", "_AUTO"
392 "_ACTION" and "_END", these are by default not shown in the private
395 But you can deactivate this with a config parameter.
397 MyApp->config->{show_internal_actions} = 1;
400 By default Catalyst is not case sensitive, so "MyApp::C::FOO::Bar"
403 But you can activate case sensitivity with a config parameter.
405 MyApp->config->{case_sensitive} = 1;
407 So "MyApp::C::Foo::Bar" becomes "/Foo/Bar".
410 The request body is usually parsed at the beginning of a request, but if
411 you want to handle input yourself or speed things up a bit you can
412 enable on-demand parsing with a config parameter.
414 MyApp->config->{parse_on_demand} = 1;
417 Many production servers operate using the common double-server approach,
418 with a lightweight frontend web server passing requests to a larger
419 backend server. An application running on the backend server must deal
420 with two problems: the remote user always appears to be '127.0.0.1' and
421 the server's hostname will appear to be 'localhost' regardless of the
422 virtual host the user connected through.
424 Catalyst will automatically detect this situation when you are running
425 both the frontend and backend servers on the same machine. The following
426 changes are made to the request.
428 $c->req->address is set to the user's real IP address, as read from the
429 HTTP_X_FORWARDED_FOR header.
431 The host value for $c->req->base and $c->req->uri is set to the real host,
432 as read from the HTTP_X_FORWARDED_HOST header.
434 Obviously, your web server must support these 2 headers for this to
437 In a more complex server farm environment where you may have your
438 frontend proxy server(s) on different machines, you will need to set a
439 configuration option to tell Catalyst to read the proxied data from the
442 MyApp->config->{using_frontend_proxy} = 1;
444 If you do not wish to use the proxy support at all, you may set:
446 MyApp->config->{ignore_frontend_proxy} = 1;
449 Catalyst has been tested under Apache 2's threading mpm_worker,
450 mpm_winnt, and the standalone forking HTTP server on Windows. We believe
451 the Catalyst core to be thread-safe.
453 If you plan to operate in a threaded environment, remember that all
454 other modules you are using must also be thread-safe. Some modules, most
455 notably DBD::SQLite, are not thread-safe.
460 Join #catalyst on irc.perl.org.
464 http://lists.rawmode.org/mailman/listinfo/catalyst
465 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
469 http://catalyst.perl.org
472 Catalyst::Manual - The Catalyst Manual
473 Catalyst::Engine - Core Engine
474 Catalyst::Log - The Log Class.
475 Catalyst::Request - The Request Object
476 Catalyst::Response - The Response Object
477 Catalyst::Test - The test suite.
541 Sebastian Riedel, "sri@oook.de"
544 This library is free software, you can redistribute it and/or modify it
545 under the same terms as Perl itself.