NAME Catalyst - The Elegant MVC Web Application Framework SYNOPSIS # use the helper to start a new application catalyst.pl MyApp cd MyApp # add models, views, controllers script/myapp_create.pl model Something script/myapp_create.pl view Stuff script/myapp_create.pl controller Yada # built in testserver script/myapp_server.pl # command line interface script/myapp_test.pl /yada use Catalyst; use Catalyst qw/My::Module My::OtherModule/; use Catalyst '-Debug'; use Catalyst qw/-Debug -Engine=CGI/; sub default : Private { $_[1]->res->output('Hello') } ); sub index : Path('/index.html') { my ( $self, $c ) = @_; $c->res->output('Hello'); $c->forward('foo'); } sub product : Regex('^product[_]*(\d*).html$') { my ( $self, $c ) = @_; $c->stash->{template} = 'product.tt'; $c->stash->{product} = $c->req->snippets->[0]; } See also Catalyst::Manual::Intro DESCRIPTION The key concept of Catalyst is DRY (Don't Repeat Yourself). See Catalyst::Manual for more documentation. Catalyst plugins can be loaded by naming them as arguments to the "use Catalyst" statement. Omit the "Catalyst::Plugin::" prefix from the plugin name, so "Catalyst::Plugin::My::Module" becomes "My::Module". use Catalyst 'My::Module'; Special flags like -Debug and -Engine can also be specifed as arguments when Catalyst is loaded: use Catalyst qw/-Debug My::Module/; The position of plugins and flags in the chain is important, because they are loaded in exactly the order that they appear. The following flags are supported: -Debug enables debug output, i.e.: use Catalyst '-Debug'; this is equivalent to: use Catalyst; sub debug { 1 } -Dispatcher Force Catalyst to use a specific dispatcher. -Engine Force Catalyst to use a specific engine. Omit the "Catalyst::Engine::" prefix of the engine name, i.e.: use Catalyst '-Engine=CGI'; -Home Force Catalyst to use a specific home directory. -Log Specify log level. METHODS $c->comp($name) $c->component($name) Get a component object by name. $c->comp('MyApp::Model::MyModel')->do_stuff; config Returns a hashref containing your applications settings. debug Overload to enable debug messages. $c->detach( $command [, \@arguments ] ) Like "forward" but doesn't return. $c->dispatcher Contains the dispatcher instance. Stringifies to class. $c->forward( $command [, \@arguments ] ) Forward processing to a private action or a method from a class. If you define a class without method it will default to process(). also takes an optional arrayref containing arguments to be passed to the new function. $c->req->args will be reset upon returning from the function. $c->forward('/foo'); $c->forward('index'); $c->forward(qw/MyApp::Model::CDBI::Foo do_stuff/); $c->forward('MyApp::View::TT'); $c->setup Setup. $c->setup; $c->uri_for($path) Merges path with $c->request->base for absolute uri's and with $c->request->match for relative uri's, then returns a normalized URI object. $c->error $c->error($error, ...) $c->error($arrayref) Returns an arrayref containing error messages. my @error = @{ $c->error }; Add a new error. $c->error('Something bad happened'); $c->engine Contains the engine instance. Stringifies to the class. $c->log Contains the logging object. Unless it is already set Catalyst sets this up with a "Catalyst::Log" object. To use your own log class: $c->log( MyLogger->new ); $c->log->info("now logging with my own logger!"); Your log class should implement the methods described in the "Catalyst::Log" man page. $c->plugin( $name, $class, @args ) Instant plugins for Catalyst. Classdata accessor/mutator will be created, class loaded and instantiated. MyApp->plugin( 'prototype', 'HTML::Prototype' ); $c->prototype->define_javascript_functions; $c->request $c->req Returns a "Catalyst::Request" object. my $req = $c->req; $c->response $c->res Returns a "Catalyst::Response" object. my $res = $c->res; $c->state Contains the return value of the last executed action. $c->stash Returns a hashref containing all your data. $c->stash->{foo} ||= 'yada'; print $c->stash->{foo}; INTERNAL METHODS $c->benchmark($coderef) Takes a coderef with arguments and returns elapsed time as float. my ( $elapsed, $status ) = $c->benchmark( sub { return 1 } ); $c->log->info( sprintf "Processing took %f seconds", $elapsed ); $c->components Contains the components. $c->counter Returns a hashref containing coderefs and execution counts. (Needed for deep recursion detection) $c->depth Returns the actual forward depth. $c->dispatch Dispatch request to actions. $c->execute($class, $coderef) Execute a coderef in given class and catch exceptions. Errors are available via $c->error. $c->finalize Finalize request. $c->finalize_body Finalize body. $c->finalize_cookies Finalize cookies. $c->finalize_error Finalize error. $c->finalize_headers Finalize headers. $c->finalize_output An alias for finalize_body. $c->finalize_read Finalize the input after reading is complete. $c->finalize_uploads Finalize uploads. Cleans up any temporary files. $c->get_action( $action, $namespace, $inherit ) Get an action in a given namespace. handle_request( $class, @arguments ) Handles the request. $c->prepare(@arguments) Turns the engine-specific request( Apache, CGI ... ) into a Catalyst context . $c->prepare_action Prepare action. $c->prepare_body Prepare message body. $c->prepare_body_parameters Prepare body parameters. $c->prepare_connection Prepare connection. $c->prepare_cookies Prepare cookies. $c->prepare_headers Prepare headers. $c->prepare_parameters Prepare parameters. $c->prepare_path Prepare path and base. $c->prepare_query_parameters Prepare query parameters. $c->prepare_read Prepare the input for reading. $c->prepare_request Prepare the engine request. $c->prepare_uploads Prepare uploads. $c->prepare_write Prepare the output for writing. $c->read( [$maxlength] ) Read a chunk of data from the request body. This method is designed to be used in a while loop, reading $maxlength bytes on every call. $maxlength defaults to the size of the request if not specified. You have to set MyApp->config->{parse_on_demand} to use this directly. $c->run Starts the engine. $c->set_action( $action, $code, $namespace, $attrs ) Set an action in a given namespace. $c->setup_actions($component) Setup actions for a component. $c->setup_components Setup components. $c->setup_dispatcher $c->setup_engine $c->setup_home $c->setup_log $c->setup_plugins $c->write( $data ) Writes $data to the output stream. When using this method directly, you will need to manually set the Content-Length header to the length of your output data, if known. CASE SENSITIVITY By default Catalyst is not case sensitive, so "MyApp::C::FOO::Bar" becomes "/foo/bar". But you can activate case sensitivity with a config parameter. MyApp->config->{case_sensitive} = 1; So "MyApp::C::Foo::Bar" becomes "/Foo/Bar". ON-DEMAND PARSER The request body is usually parsed at the beginning of a request, but if you want to handle input yourself or speed things up a bit you can enable on-demand parsing with a config parameter. MyApp->config->{parse_on_demand} = 1; PROXY SUPPORT Many production servers operate using the common double-server approach, with a lightweight frontend web server passing requests to a larger backend server. An application running on the backend server must deal with two problems: the remote user always appears to be '127.0.0.1' and the server's hostname will appear to be 'localhost' regardless of the virtual host the user connected through. Catalyst will automatically detect this situation when you are running both the frontend and backend servers on the same machine. The following changes are made to the request. $c->req->address is set to the user's real IP address, as read from the HTTP_X_FORWARDED_FOR header. The host value for $c->req->base and $c->req->uri is set to the real host, as read from the HTTP_X_FORWARDED_HOST header. Obviously, your web server must support these 2 headers for this to work. In a more complex server farm environment where you may have your frontend proxy server(s) on different machines, you will need to set a configuration option to tell Catalyst to read the proxied data from the headers. MyApp->config->{using_frontend_proxy} = 1; If you do not wish to use the proxy support at all, you may set: MyApp->config->{ignore_frontend_proxy} = 1; THREAD SAFETY Catalyst has been tested under Apache 2's threading mpm_worker, mpm_winnt, and the standalone forking HTTP server on Windows. We believe the Catalyst core to be thread-safe. If you plan to operate in a threaded environment, remember that all other modules you are using must also be thread-safe. Some modules, most notably DBD::SQLite, are not thread-safe. SUPPORT IRC: Join #catalyst on irc.perl.org. Mailing-Lists: http://lists.rawmode.org/mailman/listinfo/catalyst http://lists.rawmode.org/mailman/listinfo/catalyst-dev Web: http://catalyst.perl.org SEE ALSO Catalyst::Manual - The Catalyst Manual Catalyst::Engine - Core Engine Catalyst::Log - The Log Class. Catalyst::Request - The Request Object Catalyst::Response - The Response Object Catalyst::Test - The test suite. CREDITS Andy Grundman Andy Wardley Andrew Ford Andrew Ruthven Arthur Bergman Autrijus Tang Christian Hansen Christopher Hicks Dan Sully Danijel Milicevic David Naughton Gary Ashton Jones Geoff Richards Jesse Sheidlower Jesse Vincent Jody Belka Johan Lindstrom Juan Camacho Leon Brocard Marcus Ramberg Matt S Trout Robert Sedlacek Tatsuhiko Miyagawa Ulf Edvinsson AUTHOR Sebastian Riedel, "sri@oook.de" LICENSE This library is free software . You can redistribute it and/or modify it under the same terms as perl itself.