1Catalyst(3) User Contributed Perl Documentation Catalyst(3)
2
6 Catalyst - The Elegant MVC Web Application Framework
7
9 See the Catalyst::Manual distribution for comprehensive documentation
10 and tutorials.
11 # Install Catalyst::Devel for helpers and other development tools
13 # use the helper to create a new application
14 catalyst.pl MyApp
15 # add models, views, controllers
17 script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
18 script/myapp_create.pl view MyTemplate TT
19 script/myapp_create.pl controller Search
20 # built in testserver -- use -r to restart automatically on changes
22 # --help to see all available options
23 script/myapp_server.pl
24 # command line testing interface
26 script/myapp_test.pl /yada
27 ### in lib/MyApp.pm
29 use Catalyst qw/-Debug/; # include plugins here as well
30 ### In lib/MyApp/Controller/Root.pm (autocreated)
32 sub foo : Global { # called for /foo, /foo/1, /foo/1/2, etc.
33 my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
34 $c->stash->{template} = 'foo.tt'; # set the template
35 # lookup something from db -- stash vars are passed to TT
36 $c->stash->{data} =
37 $c->model('Database::Foo')->search( { country => $args[0] } );
38 if ( $c->req->params->{bar} ) { # access GET or POST parameters
39 $c->forward( 'bar' ); # process another action
40 # do something else after forward returns
41 }
42 }
43 # The foo.tt TT template can use the stash data from the database
45 [% WHILE (item = data.next) %]
46 [% item.foo %]
47 [% END %]
48 # called for /bar/of/soap, /bar/of/soap/10, etc.
50 sub bar : Path('/bar/of/soap') { ... }
51 # called for all actions, from the top-most controller downwards
53 sub auto : Private {
54 my ( $self, $c ) = @_;
55 if ( !$c->user_exists ) { # Catalyst::Plugin::Authentication
56 $c->res->redirect( '/login' ); # require login
57 return 0; # abort request and go immediately to end()
58 }
59 return 1; # success; carry on to next action
60 }
61 # called after all actions are finished
63 sub end : Private {
64 my ( $self, $c ) = @_;
65 if ( scalar @{ $c->error } ) { ... } # handle errors
66 return if $c->res->body; # already have a response
67 $c->forward( 'MyApp::View::TT' ); # render template
68 }
69 ### in MyApp/Controller/Foo.pm
71 # called for /foo/bar
72 sub bar : Local { ... }
73 # called for /blargle
75 sub blargle : Global { ... }
76 # an index action matches /foo, but not /foo/1, etc.
78 sub index : Private { ... }
79 ### in MyApp/Controller/Foo/Bar.pm
81 # called for /foo/bar/baz
82 sub baz : Local { ... }
83 # first Root auto is called, then Foo auto, then this
85 sub auto : Private { ... }
86 # powerful regular expression paths are also possible
88 sub details : Regex('^product/(\w+)/details$') {
89 my ( $self, $c ) = @_;
90 # extract the (\w+) from the URI
91 my $product = $c->req->captures->[0];
92 }
93 See Catalyst::Manual::Intro for additional information.
95
97 Catalyst is a modern framework for making web applications without the
98 pain usually associated with this process. This document is a reference
99 to the main Catalyst application. If you are a new user, we suggest you
100 start with Catalyst::Manual::Tutorial or Catalyst::Manual::Intro.
101 See Catalyst::Manual for more documentation.
103 Catalyst plugins can be loaded by naming them as arguments to the "use
105 Catalyst" statement. Omit the "Catalyst::Plugin::" prefix from the
106 plugin name, i.e., "Catalyst::Plugin::My::Module" becomes "My::Module".
107 use Catalyst qw/My::Module/;
109 If your plugin starts with a name other than "Catalyst::Plugin::", you
111 can fully qualify the name by using a unary plus:
112 use Catalyst qw/
114 My::Module
115 +Fully::Qualified::Plugin::Name
116 /;
117 Special flags like "-Debug" and "-Engine" can also be specified as
119 arguments when Catalyst is loaded:
120 use Catalyst qw/-Debug My::Module/;
122 The position of plugins and flags in the chain is important, because
124 they are loaded in the order in which they appear.
125 The following flags are supported:
127 -Debug
129 Enables debug output. You can also force this setting from the system
130 environment with CATALYST_DEBUG or <MYAPP>_DEBUG. The environment
131 settings override the application, with <MYAPP>_DEBUG having the
132 highest priority.
133 This sets the log level to 'debug' and enables full debug output on the
135 error screen. If you only want the latter, see $c->debug.
136 -Engine
138 Forces Catalyst to use a specific engine. Omit the "Catalyst::Engine::"
139 prefix of the engine name, i.e.:
140 use Catalyst qw/-Engine=CGI/;
142 -Home
144 Forces Catalyst to use a specific home directory, e.g.:
145 use Catalyst qw[-Home=/usr/mst];
147 This can also be done in the shell environment by setting either the
149 "CATALYST_HOME" environment variable or "MYAPP_HOME"; where "MYAPP" is
150 replaced with the uppercased name of your application, any "::" in the
151 name will be replaced with underscores, e.g. MyApp::Web should use
152 MYAPP_WEB_HOME. If both variables are set, the MYAPP_HOME one will be
153 used.
154 If none of these are set, Catalyst will attempt to automatically detect
156 the home directory. If you are working in a development envirnoment,
157 Catalyst will try and find the directory containing either Makefile.PL,
158 Build.PL or dist.ini. If the application has been installed into the
159 system (i.e. you have done "make install"), then Catalyst will use the
160 path to your application module, without the .pm extension (ie,
161 /foo/MyApp if your application was installed at /foo/MyApp.pm)
162 -Log
164 use Catalyst '-Log=warn,fatal,error';
165 Specifies a comma-delimited list of log levels.
167 -Stats
169 Enables statistics collection and reporting.
170 use Catalyst qw/-Stats=1/;
172 You can also force this setting from the system environment with
174 CATALYST_STATS or <MYAPP>_STATS. The environment settings override the
175 application, with <MYAPP>_STATS having the highest priority.
176 Stats are also enabled if debugging is enabled.
178
180 INFORMATION ABOUT THE CURRENT REQUEST
181 $c->action
182 Returns a Catalyst::Action object for the current action, which
183 stringifies to the action name. See Catalyst::Action.
184 $c->namespace
186 Returns the namespace of the current action, i.e., the URI prefix
187 corresponding to the controller of the current action. For example:
188 # in Controller::Foo::Bar
190 $c->namespace; # returns 'foo/bar';
191 $c->request
193 $c->req
194 Returns the current Catalyst::Request object, giving access to
195 information about the current client request (including parameters,
196 cookies, HTTP headers, etc.). See Catalyst::Request.
197 REQUEST FLOW HANDLING
199 $c->forward( $action [, \@arguments ] )
200 $c->forward( $class, $method, [, \@arguments ] )
201 Forwards processing to another action, by its private name. If you give
202 a class name but no method, "process()" is called. You may also
203 optionally pass arguments in an arrayref. The action will receive the
204 arguments in @_ and "$c->req->args". Upon returning from the function,
205 "$c->req->args" will be restored to the previous values.
206 Any data "return"ed from the action forwarded to, will be returned by
208 the call to forward.
209 my $foodata = $c->forward('/foo');
211 $c->forward('index');
212 $c->forward(qw/Model::DBIC::Foo do_stuff/);
213 $c->forward('View::TT');
214 Note that forward implies an "eval { }" around the call (actually
216 execute does), thus de-fatalizing all 'dies' within the called action.
217 If you want "die" to propagate you need to do something like:
218 $c->forward('foo');
220 die join "\n", @{ $c->error } if @{ $c->error };
221 Or make sure to always return true values from your actions and write
223 your code like this:
224 $c->forward('foo') || return;
226 Another note is that "$c->forward" always returns a scalar because it
228 actually returns $c->state which operates in a scalar context. Thus,
229 something like:
230 return @array;
232 in an action that is forwarded to is going to return a scalar, i.e. how
234 many items are in that array, which is probably not what you want. If
235 you need to return an array then return a reference to it, or stash it
236 like so:
237 $c->stash->{array} = \@array;
239 and access it from the stash.
241 $c->detach( $action [, \@arguments ] )
243 $c->detach( $class, $method, [, \@arguments ] )
244 $c->detach()
245 The same as forward, but doesn't return to the previous action when
246 processing is finished.
247 When called with no arguments it escapes the processing chain entirely.
249 $c->visit( $action [, \@captures, \@arguments ] )
251 $c->visit( $class, $method, [, \@captures, \@arguments ] )
252 Almost the same as forward, but does a full dispatch, instead of just
253 calling the new $action / "$class->$method". This means that "begin",
254 "auto" and the method you go to are called, just like a new request.
255 In addition both "$c->action" and "$c->namespace" are localized. This
257 means, for example, that "$c->action" methods such as name, class and
258 reverse return information for the visited action when they are invoked
259 within the visited action. This is different from the behavior of
260 forward, which continues to use the $c->action object from the caller
261 action even when invoked from the callee.
262 "$c->stash" is kept unchanged.
264 In effect, visit allows you to "wrap" another action, just as it would
266 have been called by dispatching from a URL, while the analogous go
267 allows you to transfer control to another action as if it had been
268 reached directly from a URL.
269 $c->go( $action [, \@captures, \@arguments ] )
271 $c->go( $class, $method, [, \@captures, \@arguments ] )
272 The relationship between "go" and visit is the same as the relationship
273 between forward and detach. Like "$c->visit", "$c->go" will perform a
274 full dispatch on the specified action or method, with localized
275 "$c->action" and "$c->namespace". Like "detach", "go" escapes the
276 processing of the current request chain on completion, and does not
277 return to its caller.
278 $c->response
280 $c->res
281 Returns the current Catalyst::Response object, see there for details.
282 $c->stash
284 Returns a hashref to the stash, which may be used to store data and
285 pass it between components during a request. You can also set hash keys
286 by passing arguments. The stash is automatically sent to the view. The
287 stash is cleared at the end of a request; it cannot be used for
288 persistent storage (for this you must use a session; see
289 Catalyst::Plugin::Session for a complete system integrated with
290 Catalyst).
291 $c->stash->{foo} = $bar;
293 $c->stash( { moose => 'majestic', qux => 0 } );
294 $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
295 # stash is automatically passed to the view for use in a template
297 $c->forward( 'MyApp::View::TT' );
298 $c->error
300 $c->error($error, ...)
301 $c->error($arrayref)
302 Returns an arrayref containing error messages. If Catalyst encounters
303 an error while processing a request, it stores the error in $c->error.
304 This method should only be used to store fatal error messages.
305 my @error = @{ $c->error };
307 Add a new error.
309 $c->error('Something bad happened');
311 $c->state
313 Contains the return value of the last executed action. Note that <<
314 $c->state >> operates in a scalar context which means that all values
315 it returns are scalar.
316 $c->clear_errors
318 Clear errors. You probably don't want to clear the errors unless you
319 are implementing a custom error screen.
320 This is equivalent to running
322 $c->error(0);
324 COMPONENT ACCESSORS
326 $c->controller($name)
327 Gets a Catalyst::Controller instance by name.
328 $c->controller('Foo')->do_stuff;
330 If the name is omitted, will return the controller for the dispatched
332 action.
333 If you want to search for controllers, pass in a regexp as the
335 argument.
336 # find all controllers that start with Foo
338 my @foo_controllers = $c->controller(qr{^Foo});
339 $c->model($name)
341 Gets a Catalyst::Model instance by name.
342 $c->model('Foo')->do_stuff;
344 Any extra arguments are directly passed to ACCEPT_CONTEXT.
346 If the name is omitted, it will look for
348 - a model object in $c->stash->{current_model_instance}, then
349 - a model name in $c->stash->{current_model}, then
350 - a config setting 'default_model', or
351 - check if there is only one model, and return it if that's the case.
352 If you want to search for models, pass in a regexp as the argument.
354 # find all models that start with Foo
356 my @foo_models = $c->model(qr{^Foo});
357 $c->view($name)
359 Gets a Catalyst::View instance by name.
360 $c->view('Foo')->do_stuff;
362 Any extra arguments are directly passed to ACCEPT_CONTEXT.
364 If the name is omitted, it will look for
366 - a view object in $c->stash->{current_view_instance}, then
367 - a view name in $c->stash->{current_view}, then
368 - a config setting 'default_view', or
369 - check if there is only one view, and return it if that's the case.
370 If you want to search for views, pass in a regexp as the argument.
372 # find all views that start with Foo
374 my @foo_views = $c->view(qr{^Foo});
375 $c->controllers
377 Returns the available names which can be passed to $c->controller
378 $c->models
380 Returns the available names which can be passed to $c->model
381 $c->views
383 Returns the available names which can be passed to $c->view
384 $c->comp($name)
386 $c->component($name)
387 Gets a component object by name. This method is not recommended, unless
388 you want to get a specific component by full class. "$c->controller",
389 "$c->model", and "$c->view" should be used instead.
390 If $name is a regexp, a list of components matched against the full
392 component name will be returned.
393 If Catalyst can't find a component by name, it will fallback to regex
395 matching by default. To disable this behaviour set
396 disable_component_resolution_regex_fallback to a true value.
397 __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );
399 CLASS DATA AND HELPER CLASSES
401 $c->config
402 Returns or takes a hashref containing the application's configuration.
403 __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
405 You can also use a "YAML", "XML" or Config::General config file like
407 "myapp.conf" in your applications home directory. See
408 Catalyst::Plugin::ConfigLoader.
409 Cascading configuration
411 The config method is present on all Catalyst components, and
413 configuration will be merged when an application is started.
414 Configuration loaded with Catalyst::Plugin::ConfigLoader takes
415 precedence over other configuration, followed by configuration in your
416 top level "MyApp" class. These two configurations are merged, and then
417 configuration data whose hash key matches a component name is merged
418 with configuration for that component.
419 The configuration for a component is then passed to the "new" method
421 when a component is constructed.
422 For example:
424 MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
426 MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });
427 will mean that "MyApp::Model::Foo" receives the following data when
429 constructed:
430 MyApp::Model::Foo->new({
432 bar => 'baz',
433 quux => 'frob',
434 overrides => 'me',
435 });
436 It's common practice to use a Moose attribute on the receiving
438 component to access the config value.
439 package MyApp::Model::Foo;
441 use Moose;
443 # this attr will receive 'baz' at construction time
445 has 'bar' => (
446 is => 'rw',
447 isa => 'Str',
448 );
449 You can then get the value 'baz' by calling $c->model('Foo')->bar
451 $c->log
453 Returns the logging object instance. Unless it is already set, Catalyst
454 sets this up with a Catalyst::Log object. To use your own log class,
455 set the logger with the "__PACKAGE__->log" method prior to calling
456 "__PACKAGE__->setup".
457 __PACKAGE__->log( MyLogger->new );
459 __PACKAGE__->setup;
460 And later:
462 $c->log->info( 'Now logging with my own logger!' );
464 Your log class should implement the methods described in Catalyst::Log.
466 $c->debug
468 Returns 1 if debug mode is enabled, 0 otherwise.
469 You can enable debug mode in several ways:
471 By calling myapp_server.pl with the -d flag
473 With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG
474 The -Debug option in your MyApp.pm
475 By declaring "sub debug { 1 }" in your MyApp.pm.
476 The first three also set the log level to 'debug'.
478 Calling "$c->debug(1)" has no effect.
480 $c->dispatcher
482 Returns the dispatcher instance. See Catalyst::Dispatcher.
483 $c->engine
485 Returns the engine instance. See Catalyst::Engine.
486 UTILITY METHODS
488 $c->path_to(@path)
489 Merges @path with "$c->config->{home}" and returns a Path::Class::Dir
490 object. Note you can usually use this object as a filename, but
491 sometimes you will have to explicitly stringify it yourself by calling
492 the "->stringify" method.
493 For example:
495 $c->path_to( 'db', 'sqlite.db' );
497 $c->plugin( $name, $class, @args )
499 Helper method for plugins. It creates a class data accessor/mutator and
500 loads and instantiates the given class.
501 MyApp->plugin( 'prototype', 'HTML::Prototype' );
503 $c->prototype->define_javascript_functions;
505 Note: This method of adding plugins is deprecated. The ability to add
507 plugins like this will be removed in a Catalyst 5.81. Please do not
508 use this functionality in new code.
509 MyApp->setup
511 Initializes the dispatcher and engine, loads any plugins, and loads the
512 model, view, and controller components. You may also specify an array
513 of plugins to load here, if you choose to not load them in the "use
514 Catalyst" line.
515 MyApp->setup;
517 MyApp->setup( qw/-Debug/ );
518 $app->setup_finalize
520 A hook to attach modifiers to. This method does not do anything except
521 set the "setup_finished" accessor.
522 Applying method modifiers to the "setup" method doesn't work, because
524 of quirky thingsdone for plugin setup.
525 Example:
527 after setup_finalize => sub {
529 my $app = shift;
530 ## do stuff here..
532 };
533 $c->uri_for( $path?, @args?, \%query_values? )
535 $c->uri_for( $action, \@captures?, @args?, \%query_values? )
536 Constructs an absolute URI object based on the application root, the
537 provided path, and the additional arguments and query parameters
538 provided. When used as a string, provides a textual URI.
539 If no arguments are provided, the URI for the current action is
541 returned. To return the current action and also provide @args, use
542 "$c->uri_for( $c->action, @args )".
543 If the first argument is a string, it is taken as a public URI path
545 relative to "$c->namespace" (if it doesn't begin with a forward slash)
546 or relative to the application root (if it does). It is then merged
547 with "$c->request->base"; any @args are appended as additional path
548 components; and any %query_values are appended as "?foo=bar"
549 parameters.
550 If the first argument is a Catalyst::Action it represents an action
552 which will have its path resolved using
553 "$c->dispatcher->uri_for_action". The optional "\@captures" argument
554 (an arrayref) allows passing the captured variables that are needed to
555 fill in the paths of Chained and Regex actions; once the path is
556 resolved, "uri_for" continues as though a path was provided, appending
557 any arguments or parameters and creating an absolute URI.
558 The captures for the current request can be found in
560 "$c->request->captures", and actions can be resolved using
561 "Catalyst::Controller->action_for($name)". If you have a private action
562 path, use "$c->uri_for_action" instead.
563 # Equivalent to $c->req->uri
565 $c->uri_for($c->action, $c->req->captures,
566 @{ $c->req->args }, $c->req->params);
567 # For the Foo action in the Bar controller
569 $c->uri_for($c->controller('Bar')->action_for('Foo'));
570 # Path to a static resource
572 $c->uri_for('/static/images/logo.png');
573 $c->uri_for_action( $path, \@captures?, @args?, \%query_values? )
575 $c->uri_for_action( $action, \@captures?, @args?, \%query_values? )
576 $path
577 A private path to the Catalyst action you want to create a URI for.
578 This is a shortcut for calling
580 "$c->dispatcher->get_action_by_path($path)" and passing the
581 resulting $action and the remaining arguments to "$c->uri_for".
582 You can also pass in a Catalyst::Action object, in which case it is
584 passed to "$c->uri_for".
585 Note that although the path looks like a URI that dispatches to the
587 wanted action, it is not a URI, but an internal path to that
588 action.
589 For example, if the action looks like:
591 package MyApp::Controller::Users;
593 sub lst : Path('the-list') {}
595 You can use:
597 $c->uri_for_action('/users/lst')
599 and it will create the URI /users/the-list.
601 $c->welcome_message
603 Returns the Catalyst welcome HTML page.
604
606 These methods are not meant to be used by end users.
607 $c->components
609 Returns a hash of components.
610 $c->context_class
612 Returns or sets the context class.
613 $c->counter
615 Returns a hashref containing coderefs and execution counts (needed for
616 deep recursion detection).
617 $c->depth
619 Returns the number of actions on the current internal execution stack.
620 $c->dispatch
622 Dispatches a request to actions.
623 $c->dispatcher_class
625 Returns or sets the dispatcher class.
626 $c->dump_these
628 Returns a list of 2-element array references (name, structure) pairs
629 that will be dumped on the error page in debug mode.
630 $c->engine_class
632 Returns or sets the engine class.
633 $c->execute( $class, $coderef )
635 Execute a coderef in given class and catch exceptions. Errors are
636 available via $c->error.
637 $c->finalize
639 Finalizes the request.
640 $c->finalize_body
642 Finalizes body.
643 $c->finalize_cookies
645 Finalizes cookies.
646 $c->finalize_error
648 Finalizes error.
649 $c->finalize_headers
651 Finalizes headers.
652 $c->finalize_output
654 An alias for finalize_body.
655 $c->finalize_read
657 Finalizes the input after reading is complete.
658 $c->finalize_uploads
660 Finalizes uploads. Cleans up any temporary files.
661 $c->get_action( $action, $namespace )
663 Gets an action in a given namespace.
664 $c->get_actions( $action, $namespace )
666 Gets all actions of a given name in a namespace and all parent
667 namespaces.
668 $app->handle_request( @arguments )
670 Called to handle each HTTP request.
671 $c->prepare( @arguments )
673 Creates a Catalyst context from an engine-specific request (Apache,
674 CGI, etc.).
675 $c->prepare_action
677 Prepares action. See Catalyst::Dispatcher.
678 $c->prepare_body
680 Prepares message body.
681 $c->prepare_body_chunk( $chunk )
683 Prepares a chunk of data before sending it to HTTP::Body.
684 See Catalyst::Engine.
686 $c->prepare_body_parameters
688 Prepares body parameters.
689 $c->prepare_connection
691 Prepares connection.
692 $c->prepare_cookies
694 Prepares cookies.
695 $c->prepare_headers
697 Prepares headers.
698 $c->prepare_parameters
700 Prepares parameters.
701 $c->prepare_path
703 Prepares path and base.
704 $c->prepare_query_parameters
706 Prepares query parameters.
707 $c->log_request
709 Writes information about the request to the debug logs. This includes:
710 · Request method, path, and remote IP address
712 · Query keywords (see "query_keywords" in Catalyst::Request)
714 · Request parameters
716 · File uploads
718 $c->log_response
720 Writes information about the response to the debug logs by calling
721 "$c->log_response_status_line" and "$c->log_response_headers".
722 $c->log_response_status_line($response)
724 Writes one line of information about the response to the debug logs.
725 This includes:
726 · Response status code
728 · Content-Type header (if present)
730 · Content-Length header (if present)
732 $c->log_response_headers($headers);
734 Hook method which can be wrapped by plugins to log the responseheaders.
735 No-op in the default implementation.
736 $c->log_request_parameters( query => {}, body => {} )
738 Logs request parameters to debug logs
739 $c->log_request_uploads
741 Logs file uploads included in the request to the debug logs. The
742 parameter name, filename, file type, and file size are all included in
743 the debug logs.
744 $c->log_request_headers($headers);
746 Hook method which can be wrapped by plugins to log the request headers.
747 No-op in the default implementation.
748 $c->log_headers($type => $headers)
750 Logs HTTP::Headers (either request or response) to the debug logs.
751 $c->prepare_read
753 Prepares the input for reading.
754 $c->prepare_request
756 Prepares the engine request.
757 $c->prepare_uploads
759 Prepares uploads.
760 $c->prepare_write
762 Prepares the output for writing.
763 $c->request_class
765 Returns or sets the request class.
766 $c->response_class
768 Returns or sets the response class.
769 $c->read( [$maxlength] )
771 Reads a chunk of data from the request body. This method is designed to
772 be used in a while loop, reading $maxlength bytes on every call.
773 $maxlength defaults to the size of the request if not specified.
774 You have to set "MyApp->config(parse_on_demand => 1)" to use this
776 directly.
777 Warning: If you use read(), Catalyst will not process the body, so you
779 will not be able to access POST parameters or file uploads via
780 $c->request. You must handle all body parsing yourself.
781 $c->run
783 Starts the engine.
784 $c->set_action( $action, $code, $namespace, $attrs )
786 Sets an action in a given namespace.
787 $c->setup_actions($component)
789 Sets up actions for a component.
790 $c->setup_components
792 This method is called internally to set up the application's
793 components.
794 It finds modules by calling the locate_components method, expands them
796 to package names with the expand_component_module method, and then
797 installs each component into the application.
798 The "setup_components" config option is passed to both of the above
800 methods.
801 Installation of each component is performed by the setup_component
803 method, below.
804 $c->locate_components( $setup_component_config )
806 This method is meant to provide a list of component modules that should
807 be setup for the application. By default, it will use
808 Module::Pluggable.
809 Specify a "setup_components" config option to pass additional options
811 directly to Module::Pluggable. To add additional search paths, specify
812 a key named "search_extra" as an array reference. Items in the array
813 beginning with "::" will have the application class name prepended to
814 them.
815 $c->expand_component_module( $component, $setup_component_config )
817 Components found by "locate_components" will be passed to this method,
818 which is expected to return a list of component (package) names to be
819 set up.
820 $c->setup_component
822 $c->setup_dispatcher
823 Sets up dispatcher.
824 $c->setup_engine
826 Sets up engine.
827 $c->setup_home
829 Sets up the home directory.
830 $c->setup_log
832 Sets up log by instantiating a Catalyst::Log object and passing it to
833 "log()". Pass in a comma-delimited list of levels to set the log to.
834 This method also installs a "debug" method that returns a true value
836 into the catalyst subclass if the "debug" level is passed in the comma-
837 delimited list, or if the $CATALYST_DEBUG environment variable is set
838 to a true value.
839 Note that if the log has already been setup, by either a previous call
841 to "setup_log" or by a call such as "__PACKAGE__->log( MyLogger->new
842 )", that this method won't actually set up the log object.
843 $c->setup_plugins
845 Sets up plugins.
846 $c->setup_stats
848 Sets up timing statistics class.
849 $c->registered_plugins
851 Returns a sorted list of the plugins which have either been stated in
852 the import list or which have been added via "MyApp->plugin(@args);".
853 If passed a given plugin name, it will report a boolean value
855 indicating whether or not that plugin is loaded. A fully qualified
856 name is required if the plugin name does not begin with
857 "Catalyst::Plugin::".
858 if ($c->registered_plugins('Some::Plugin')) {
860 ...
861 }
862 $c->stack
864 Returns an arrayref of the internal execution stack (actions that are
865 currently executing).
866 $c->stats
868 Returns the current timing statistics object. By default Catalyst uses
869 Catalyst::Stats, but can be set otherwise with stats_class.
870 Even if -Stats is not enabled, the stats object is still available. By
872 enabling it with " $c-"stats->enabled(1) >, it can be used to profile
873 explicitly, although MyApp.pm still won't profile nor output anything
874 by itself.
875 $c->stats_class
877 Returns or sets the stats (timing statistics) class. Catalyst::Stats is
878 used by default.
879 $c->use_stats
881 Returns 1 when stats collection is enabled.
882 Note that this is a static method, not an accessor and should be
884 overridden by declaring "sub use_stats { 1 }" in your MyApp.pm, not by
885 calling "$c->use_stats(1)".
886 $c->write( $data )
888 Writes $data to the output stream. When using this method directly, you
889 will need to manually set the "Content-Length" header to the length of
890 your output data, if known.
891 version
893 Returns the Catalyst version number. Mostly useful for "powered by"
894 messages in template systems.
895
897 There are a number of 'base' config variables which can be set:
898 · "default_model" - The default model picked if you say "$c->model".
900 See "$c->model($name)".
901 · "default_view" - The default view to be rendered or returned when
903 "$c->view" is called. See "$c->view($name)".
904 · "disable_component_resolution_regex_fallback" - Turns off the
906 deprecated component resolution functionality so that if any of the
907 component methods (e.g. "$c->controller('Foo')") are called then
908 regex search will not be attempted on string values and instead
909 "undef" will be returned.
910 · "home" - The application home directory. In an uninstalled
912 application, this is the top level application directory. In an
913 installed application, this will be the directory containing
914 "MyApp.pm".
915 · "ignore_frontend_proxy" - See "PROXY SUPPORT"
917 · "name" - The name of the application in debug messages and the
919 debug and welcome screens
920 · "parse_on_demand" - The request body (for example file uploads)
922 will not be parsed until it is accessed. This allows you to (for
923 example) check authentication (and reject the upload) before
924 actually recieving all the data. See "ON-DEMAND PARSER"
925 · "root" - The root directory for templates. Usually this is just a
927 subdirectory of the home directory, but you can set it to change
928 the templates to a different directory.
929 · "search_extra" - Array reference passed to Module::Pluggable to for
931 additional namespaces from which components will be loaded (and
932 constructed and stored in "$c->components").
933 · "show_internal_actions" - If true, causes internal actions such as
935 "_DISPATCH" to be shown in hit debug tables in the test server.
936 · "use_request_uri_for_path" - Controlls if the "REQUEST_URI" or
938 "PATH_INFO" environment variable should be used for determining the
939 request path. See "PATH DECODING" in Catalyst::Engine::CGI for more
940 information.
941 · "using_frontend_proxy" - See "PROXY SUPPORT".
943
945 Catalyst uses internal actions like "_DISPATCH", "_BEGIN", "_AUTO",
946 "_ACTION", and "_END". These are by default not shown in the private
947 action table, but you can make them visible with a config parameter.
948 MyApp->config(show_internal_actions => 1);
950
952 The request body is usually parsed at the beginning of a request, but
953 if you want to handle input yourself, you can enable on-demand parsing
954 with a config parameter.
955 MyApp->config(parse_on_demand => 1);
957
959 Many production servers operate using the common double-server
960 approach, with a lightweight frontend web server passing requests to a
961 larger backend server. An application running on the backend server
962 must deal with two problems: the remote user always appears to be
963 127.0.0.1 and the server's hostname will appear to be "localhost"
964 regardless of the virtual host that the user connected through.
965 Catalyst will automatically detect this situation when you are running
967 the frontend and backend servers on the same machine. The following
968 changes are made to the request.
969 $c->req->address is set to the user's real IP address, as read from
971 the HTTP X-Forwarded-For header.
972 The host value for $c->req->base and $c->req->uri is set to the real
974 host, as read from the HTTP X-Forwarded-Host header.
975 Additionally, you may be running your backend application on an
977 insecure connection (port 80) while your frontend proxy is running
978 under SSL. If there is a discrepancy in the ports, use the HTTP header
979 "X-Forwarded-Port" to tell Catalyst what port the frontend listens on.
980 This will allow all URIs to be created properly.
981 In the case of passing in:
983 X-Forwarded-Port: 443
985 All calls to "uri_for" will result in an https link, as is expected.
987 Obviously, your web server must support these headers for this to work.
989 In a more complex server farm environment where you may have your
991 frontend proxy server(s) on different machines, you will need to set a
992 configuration option to tell Catalyst to read the proxied data from the
993 headers.
994 MyApp->config(using_frontend_proxy => 1);
996 If you do not wish to use the proxy support at all, you may set:
998 MyApp->config(ignore_frontend_proxy => 1);
1000
1002 Catalyst has been tested under Apache 2's threading "mpm_worker",
1003 "mpm_winnt", and the standalone forking HTTP server on Windows. We
1004 believe the Catalyst core to be thread-safe.
1005 If you plan to operate in a threaded environment, remember that all
1007 other modules you are using must also be thread-safe. Some modules,
1008 most notably DBD::SQLite, are not thread-safe.
1009
1011 IRC:
1012 Join #catalyst on irc.perl.org.
1014 Mailing Lists:
1016 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
1018 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
1019 Web:
1021 http://catalyst.perl.org
1023 Wiki:
1025 http://dev.catalyst.perl.org
1027
1029 Task::Catalyst - All you need to start with Catalyst
1030 Catalyst::Manual - The Catalyst Manual
1031 Catalyst::Component, Catalyst::Controller - Base classes for components
1032 Catalyst::Engine - Core engine
1033 Catalyst::Log - Log class.
1034 Catalyst::Request - Request object
1035 Catalyst::Response - Response object
1036 Catalyst::Test - The test suite.
1038 sri: Sebastian Riedel <sri@cpan.org>
1039
1041 abw: Andy Wardley
1042 acme: Leon Brocard <leon@astray.com>
1044 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
1046 Andrew Bramble
1048 Andrew Ford <A.Ford@ford-mason.co.uk>
1050 Andrew Ruthven
1052 andyg: Andy Grundman <andy@hybridized.org>
1054 audreyt: Audrey Tang
1056 bricas: Brian Cassidy <bricas@cpan.org>
1058 Caelum: Rafael Kitover <rkitover@io.com>
1060 chansen: Christian Hansen
1062 chicks: Christopher Hicks
1064 Chisel Wright "pause@herlpacker.co.uk"
1066 Danijel Milicevic "me@danijel.de"
1068 David Kamholz <dkamholz@cpan.org>
1070 David Naughton, "naughton@umn.edu"
1072 David E. Wheeler
1074 dhoss: Devin Austin <dhoss@cpan.org>
1076 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
1078 Drew Taylor
1080 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
1082 esskar: Sascha Kiefer
1084 fireartist: Carl Franks <cfranks@cpan.org>
1086 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
1088 gabb: Danijel Milicevic
1090 Gary Ashton Jones
1092 Gavin Henry "ghenry@perl.me.uk"
1094 Geoff Richards
1096 groditi: Guillermo Roditi <groditi@gmail.com>
1098 hobbs: Andrew Rodland <andrew@cleverdomain.org>
1100 ilmari: Dagfinn Ilmari MannsA~Xker <ilmari@ilmari.org>
1102 jcamacho: Juan Camacho
1104 jester: Jesse Sheidlower "jester@panix.com"
1106 jhannah: Jay Hannah <jay@jays.net>
1108 Jody Belka
1110 Johan Lindstrom
1112 jon: Jon Schutz <jjschutz@cpan.org>
1114 Jonathan Rockway "<jrockway@cpan.org>"
1116 Kieren Diment "kd@totaldatasolution.com"
1118 konobi: Scott McWhirter <konobi@cpan.org>
1120 marcus: Marcus Ramberg <mramberg@cpan.org>
1122 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
1124 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
1126 mugwump: Sam Vilain
1128 naughton: David Naughton
1130 ningu: David Kamholz <dkamholz@cpan.org>
1132 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
1134 numa: Dan Sully <daniel@cpan.org>
1136 obra: Jesse Vincent
1138 Octavian Rasnita
1140 omega: Andreas Marienborg
1142 Oleg Kostyuk <cub.uanic@gmail.com>
1144 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
1146 rafl: Florian Ragwitz <rafl@debian.org>
1148 random: Roland Lammel <lammel@cpan.org>
1150 Robert Sedlacek "<rs@474.at>"
1152 SpiceMan: Marcel Montes
1154 sky: Arthur Bergman
1156 szbalint: Balint Szilakszi <szbalint@cpan.org>
1158 t0m: Tomas Doran <bobtfish@bobtfish.net>
1160 Ulf Edvinsson
1162 Viljo Marrandi "vilts@yahoo.com"
1164 Will Hawes "info@whawes.co.uk"
1166 willert: Sebastian Willert <willert@cpan.org>
1168 wreis: Wallace Reis <wallace@reis.org.br>
1170 Yuval Kogman, "nothingmuch@woobling.org"
1172 rainboxx: Matthias Dietrich, "perl@rainboxx.de"
1174
1176 This library is free software. You can redistribute it and/or modify it
1177 under the same terms as Perl itself.
1178perl v5.12.1 2010-07-28 Catalyst(3)