2 Catalyst - The Elegant MVC Web Application Framework
5 # use the helper to start a new application
8 # add models, views, controllers
9 script/myapp_create.pl model Database DBIC dbi:SQLite:/path/to/db
10 script/myapp_create.pl view TT TT
11 script/myapp_create.pl controller Search
13 # built in testserver -- use -r to restart automatically on changes
14 script/myapp_server.pl
16 # command line testing interface
17 script/myapp_test.pl /yada
20 use Catalyst qw/-Debug/; # include plugins here as well
22 sub foo : Global { # called for /foo, /foo/1, /foo/1/2, etc.
23 my ( $self, $c, @args ) = @_; # args are qw/on you/ for /foo/on/you
24 $c->stash->{template} = 'foo.tt';
25 # lookup something from db -- stash vars are passed to TT
26 $c->stash->{data} = MyApp::Model::Database::Foo->search;
27 if ( $c->req->params->{bar} ) { # access GET or POST parameters
28 $c->forward( 'bar' ); # process another action
29 # do something else after forward returns
33 # The foo.tt TT template can easily use the stash data from the database
34 [% WHILE (item = data.next) %]
38 # called for /bar/of/soap, /bar/of/soap/10, etc.
39 sub bar : Path('/bar/of/soap') { ... }
41 # called for all actions, from the top-most controller inwards
43 my ( $self, $c ) = @_;
45 $c->res->redirect( '/login' ); # require login
46 return 0; # abort request and go immediately to end()
51 # called after the main action is finished
53 my ( $self, $c ) = @_;
54 if ( scalar @{ $c->error } ) { ... } # handle errors
55 return if $c->res->body; # already have a response
56 $c->forward( 'MyApp::View::TT' ); # render template
59 ### in MyApp/Controller/Foo.pm
61 sub bar : Local { ... }
64 sub blargle : Global { ... }
66 # an index action matches /foo, but not /foo/1, etc.
67 sub index : Private { ... }
69 ### in MyApp/Controller/Foo/Bar.pm
70 # called for /foo/bar/baz
71 sub baz : Local { ... }
73 # first MyApp auto is called, then Foo auto, then this
74 sub auto : Private { ... }
76 # powerful regular expression paths are also possible
77 sub details : Regex('^product/(\w+)/details$') {
78 my ( $self, $c ) = @_;
79 # extract the (\w+) from the URI
80 my $product = $c->req->snippets->[0];
83 See Catalyst::Manual::Intro for additional information.
86 The key concept of Catalyst is DRY (Don't Repeat Yourself).
88 See Catalyst::Manual for more documentation.
90 Catalyst plugins can be loaded by naming them as arguments to the "use
91 Catalyst" statement. Omit the "Catalyst::Plugin::" prefix from the
92 plugin name, i.e., "Catalyst::Plugin::My::Module" becomes "My::Module".
94 use Catalyst qw/My::Module/;
96 Special flags like -Debug and -Engine can also be specified as arguments
97 when Catalyst is loaded:
99 use Catalyst qw/-Debug My::Module/;
101 The position of plugins and flags in the chain is important, because
102 they are loaded in exactly the order that they appear.
104 The following flags are supported:
107 Enables debug output.
110 Forces Catalyst to use a specific engine. Omit the
111 "Catalyst::Engine::" prefix of the engine name, i.e.:
113 use Catalyst qw/-Engine=CGI/;
116 Forces Catalyst to use a specific home directory.
122 Information about the current request
124 Returns a Catalyst::Action object for the current action, which
125 stringifies to the action name.
128 Returns the namespace of the current action, i.e., the uri prefix
129 corresponding to the controller of the current action.
133 Returns the current Catalyst::Request object.
135 Processing and response to the current request
136 $c->forward( $action [, \@arguments ] )
137 $c->forward( $class, $method, [, \@arguments ] )
138 Forwards processing to a private action. If you give a class name
139 but no method, process() is called. You may also optionally pass
140 arguments in an arrayref. The action will receive the arguments in
141 @_ and $c->req->args. Upon returning from the function,
142 $c->req->args will be restored to the previous values.
145 $c->forward('index');
146 $c->forward(qw/MyApp::Model::CDBI::Foo do_stuff/);
147 $c->forward('MyApp::View::TT');
149 $c->detach( $action [, \@arguments ] )
150 $c->detach( $class, $method, [, \@arguments ] )
151 The same as "forward", but doesn't return.
154 $c->error($error, ...)
156 Returns an arrayref containing error messages.
158 my @error = @{ $c->error };
162 $c->error('Something bad happened');
170 Returns the current Catalyst::Response object.
173 Returns a hashref to the stash, which may be used to store data and
174 pass it between components. You can also set hash keys by passing
175 arguments. The stash is automatically sent to the view.
177 $c->stash->{foo} = $bar;
178 $c->stash( { moose => 'majestic', qux => 0 } );
179 $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
181 # stash is automatically passed to the view for use in a template
182 $c->forward( 'MyApp::V::TT' );
185 Contains the return value of the last executed action.
190 Gets a component object by name. This method is no longer
191 recommended. $c->controller, $c->model, and $c->view should be used
194 $c->controller($name)
195 Gets a Catalyst::Controller instance by name.
197 $c->controller('Foo')->do_stuff;
200 Gets a Catalyst::Model instance by name.
202 $c->model('Foo')->do_stuff;
205 Gets a Catalyst::View instance by name.
207 $c->view('Foo')->do_stuff;
209 Class data and helper classes
211 Returns or takes a hashref containing the application's
214 __PACKAGE__->config({ db => 'dsn:SQLite:foo.db' });
217 Overload to enable debug messages (same as -Debug option).
220 Returns the dispatcher instance. Stringifies to class name.
223 Returns the engine instance. Stringifies to the class name.
226 Returns the logging object instance. Unless it is already set,
227 Catalyst sets this up with a Catalyst::Log object. To use your own
230 $c->log( MyLogger->new );
231 $c->log->info( 'now logging with my own logger!' );
233 Your log class should implement the methods described in the
234 Catalyst::Log man page.
238 Merges @path with $c->config->{home} and returns a Path::Class
243 $c->path_to( 'db', 'sqlite.db' );
245 $c->plugin( $name, $class, @args )
246 Helper method for plugins. It creates a classdata accessor/mutator
247 and loads and instantiates the given class.
249 MyApp->plugin( 'prototype', 'HTML::Prototype' );
251 $c->prototype->define_javascript_functions;
254 Initializes the dispatcher and engine, loads any plugins, and loads
255 the model, view, and controller components. You may also specify an
256 array of plugins to load here, if you choose to not load them in the
260 MyApp->setup( qw/-Debug/ );
262 $c->uri_for( $path, [ @args ] )
263 Merges path with $c->request->base for absolute uri's and with
264 $c->request->match for relative uri's, then returns a normalized URI
265 object. If any args are passed, they are added at the end of the
269 Returns the Catalyst welcome HTML page.
272 $c->benchmark( $coderef )
273 Takes a coderef with arguments and returns elapsed time as float.
275 my ( $elapsed, $status ) = $c->benchmark( sub { return 1 } );
276 $c->log->info( sprintf "Processing took %f seconds", $elapsed );
279 Returns a hash of components.
282 Returns or sets the context class.
285 Returns a hashref containing coderefs and execution counts (needed
286 for deep recursion detection).
289 Returns the number of actions on the current internal execution
293 Dispatches a request to actions.
296 Returns or sets the dispatcher class.
299 Returns a list of 2-element array references (name, structure) pairs
300 that will be dumped on the error page in debug mode.
303 Returns or sets the engine class.
305 $c->execute( $class, $coderef )
306 Execute a coderef in given class and catch exceptions. Errors are
307 available via $c->error.
310 Finalizes the request.
325 An alias for finalize_body.
328 Finalizes the input after reading is complete.
331 Finalizes uploads. Cleans up any temporary files.
333 $c->get_action( $action, $namespace )
334 Gets an action in a given namespace.
336 $c->get_actions( $action, $namespace )
337 Gets all actions of a given name in a namespace and all parent
340 handle_request( $class, @arguments )
341 Called to handle each HTTP request.
343 $c->prepare( @arguments )
344 Creates a Catalyst context from an engine-specific request (Apache,
351 Prepares message body.
353 $c->prepare_body_chunk( $chunk )
354 Prepares a chunk of data before sending it to HTTP::Body.
356 $c->prepare_body_parameters
357 Prepares body parameters.
359 $c->prepare_connection
368 $c->prepare_parameters
372 Prepares path and base.
374 $c->prepare_query_parameters
375 Prepares query parameters.
378 Prepares the input for reading.
381 Prepares the engine request.
387 Prepares the output for writing.
390 Returns or sets the request class.
393 Returns or sets the response class.
395 $c->read( [$maxlength] )
396 Reads a chunk of data from the request body. This method is designed
397 to be used in a while loop, reading $maxlength bytes on every call.
398 $maxlength defaults to the size of the request if not specified.
400 You have to set MyApp->config->{parse_on_demand} to use this
406 $c->set_action( $action, $code, $namespace, $attrs )
407 Sets an action in a given namespace.
409 $c->setup_actions($component)
410 Sets up actions for a component.
424 Writes $data to the output stream. When using this method directly,
425 you will need to manually set the Content-Length header to the
426 length of your output data, if known.
429 Returns the Catalyst version number. Mostly useful for "powered by"
430 messages in template systems.
433 Catalyst uses internal actions like "_DISPATCH", "_BEGIN", "_AUTO"
434 "_ACTION" and "_END". These are by default not shown in the private
435 action table, but you can make them visible with a config parameter.
437 MyApp->config->{show_internal_actions} = 1;
440 By default Catalyst is not case sensitive, so "MyApp::C::FOO::Bar" is
441 mapped to "/foo/bar". You can activate case sensitivity with a config
444 MyApp->config->{case_sensitive} = 1;
446 This causes "MyApp::C::Foo::Bar" to map to "/Foo/Bar".
449 The request body is usually parsed at the beginning of a request, but if
450 you want to handle input yourself or speed things up a bit, you can
451 enable on-demand parsing with a config parameter.
453 MyApp->config->{parse_on_demand} = 1;
456 Many production servers operate using the common double-server approach,
457 with a lightweight frontend web server passing requests to a larger
458 backend server. An application running on the backend server must deal
459 with two problems: the remote user always appears to be 127.0.0.1 and
460 the server's hostname will appear to be "localhost" regardless of the
461 virtual host that the user connected through.
463 Catalyst will automatically detect this situation when you are running
464 the frontend and backend servers on the same machine. The following
465 changes are made to the request.
467 $c->req->address is set to the user's real IP address, as read from the
468 HTTP X-Forwarded-For header.
470 The host value for $c->req->base and $c->req->uri is set to the real host,
471 as read from the HTTP X-Forwarded-Host header.
473 Obviously, your web server must support these headers for this to work.
475 In a more complex server farm environment where you may have your
476 frontend proxy server(s) on different machines, you will need to set a
477 configuration option to tell Catalyst to read the proxied data from the
480 MyApp->config->{using_frontend_proxy} = 1;
482 If you do not wish to use the proxy support at all, you may set:
484 MyApp->config->{ignore_frontend_proxy} = 1;
487 Catalyst has been tested under Apache 2's threading mpm_worker,
488 mpm_winnt, and the standalone forking HTTP server on Windows. We believe
489 the Catalyst core to be thread-safe.
491 If you plan to operate in a threaded environment, remember that all
492 other modules you are using must also be thread-safe. Some modules, most
493 notably DBD::SQLite, are not thread-safe.
498 Join #catalyst on irc.perl.org.
502 http://lists.rawmode.org/mailman/listinfo/catalyst
503 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
507 http://catalyst.perl.org
511 http://dev.catalyst.perl.org
514 Catalyst::Manual - The Catalyst Manual
515 Catalyst::Component, Catalyst::Base - Base classes for components
516 Catalyst::Engine - Core Engine
517 Catalyst::Log - The Log Class.
518 Catalyst::Request - The Request Object
519 Catalyst::Response - The Response Object
520 Catalyst::Test - The test suite.
586 Sebastian Riedel, "sri@oook.de"
589 This library is free software, you can redistribute it and/or modify it
590 under the same terms as Perl itself.