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 : Chained('/') Args() { # 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 : Chained('/') PathPart('/bar/of/soap') Args() { ... }
51 # called after all actions are finished
53 sub end : Action {
54 my ( $self, $c ) = @_;
55 if ( scalar @{ $c->error } ) { ... } # handle errors
56 return if $c->res->body; # already have a response
57 $c->forward( 'MyApp::View::TT' ); # render template
58 }
59 See Catalyst::Manual::Intro for additional information.
61
63 Catalyst is a modern framework for making web applications without the
64 pain usually associated with this process. This document is a reference
65 to the main Catalyst application. If you are a new user, we suggest you
66 start with Catalyst::Manual::Tutorial or Catalyst::Manual::Intro.
67 See Catalyst::Manual for more documentation.
69 Catalyst plugins can be loaded by naming them as arguments to the "use
71 Catalyst" statement. Omit the "Catalyst::Plugin::" prefix from the
72 plugin name, i.e., "Catalyst::Plugin::My::Module" becomes "My::Module".
73 use Catalyst qw/My::Module/;
75 If your plugin starts with a name other than "Catalyst::Plugin::", you
77 can fully qualify the name by using a unary plus:
78 use Catalyst qw/
80 My::Module
81 +Fully::Qualified::Plugin::Name
82 /;
83 Special flags like "-Debug" can also be specified as arguments when
85 Catalyst is loaded:
86 use Catalyst qw/-Debug My::Module/;
88 The position of plugins and flags in the chain is important, because
90 they are loaded in the order in which they appear.
91 The following flags are supported:
93 -Debug
95 Enables debug output. You can also force this setting from the system
96 environment with CATALYST_DEBUG or <MYAPP>_DEBUG. The environment
97 settings override the application, with <MYAPP>_DEBUG having the
98 highest priority.
99 This sets the log level to 'debug' and enables full debug output on the
101 error screen. If you only want the latter, see $c->debug.
102 -Home
104 Forces Catalyst to use a specific home directory, e.g.:
105 use Catalyst qw[-Home=/usr/mst];
107 This can also be done in the shell environment by setting either the
109 "CATALYST_HOME" environment variable or "MYAPP_HOME"; where "MYAPP" is
110 replaced with the uppercased name of your application, any "::" in the
111 name will be replaced with underscores, e.g. MyApp::Web should use
112 MYAPP_WEB_HOME. If both variables are set, the MYAPP_HOME one will be
113 used.
114 If none of these are set, Catalyst will attempt to automatically detect
116 the home directory. If you are working in a development environment,
117 Catalyst will try and find the directory containing either Makefile.PL,
118 Build.PL, dist.ini, or cpanfile. If the application has been installed
119 into the system (i.e. you have done "make install"), then Catalyst will
120 use the path to your application module, without the .pm extension
121 (e.g., /foo/MyApp if your application was installed at /foo/MyApp.pm)
122 -Log
124 use Catalyst '-Log=warn,fatal,error';
125 Specifies a comma-delimited list of log levels.
127 -Stats
129 Enables statistics collection and reporting.
130 use Catalyst qw/-Stats=1/;
132 You can also force this setting from the system environment with
134 CATALYST_STATS or <MYAPP>_STATS. The environment settings override the
135 application, with <MYAPP>_STATS having the highest priority.
136 Stats are also enabled if debugging is enabled.
138
140 INFORMATION ABOUT THE CURRENT REQUEST
141 $c->action
142 Returns a Catalyst::Action object for the current action, which
143 stringifies to the action name. See Catalyst::Action.
144 $c->namespace
146 Returns the namespace of the current action, i.e., the URI prefix
147 corresponding to the controller of the current action. For example:
148 # in Controller::Foo::Bar
150 $c->namespace; # returns 'foo/bar';
151 $c->request
153 $c->req
154 Returns the current Catalyst::Request object, giving access to
155 information about the current client request (including parameters,
156 cookies, HTTP headers, etc.). See Catalyst::Request.
157 There is a predicate method "has_request" that returns true if the
159 request object has been created. This is something you might need to
160 check if you are writing plugins that run before a request is
161 finalized.
162 REQUEST FLOW HANDLING
164 $c->forward( $action [, \@arguments ] )
165 $c->forward( $class, $method, [, \@arguments ] )
166 $c->forward( $component_instance, $method, [, \@arguments ] )
167 This is one way of calling another action (method) in the same or a
168 different controller. You can also use "$self->my_method($c, @args)" in
169 the same controller or "$c->controller('MyController')->my_method($c,
170 @args)" in a different controller. The main difference is that
171 'forward' uses some of the Catalyst request cycle overhead, including
172 debugging, which may be useful to you. On the other hand, there are
173 some complications to using 'forward', restrictions on values returned
174 from 'forward', and it may not handle errors as you prefer. Whether
175 you use 'forward' or not is up to you; it is not considered superior to
176 the other ways to call a method.
177 'forward' calls another action, by its private name. If you give a
179 class name but no method, process() is called. You may also optionally
180 pass arguments in an arrayref. The action will receive the arguments in
181 @_ and "$c->req->args". Upon returning from the function,
182 "$c->req->args" will be restored to the previous values.
183 Any data "return"ed from the action forwarded to, will be returned by
185 the call to forward.
186 my $foodata = $c->forward('/foo');
188 $c->forward('index');
189 $c->forward(qw/Model::DBIC::Foo do_stuff/);
190 $c->forward('View::TT');
191 Note that forward implies an "eval { }" around the call (actually
193 execute does), thus rendering all exceptions thrown by the called
194 action non-fatal and pushing them onto $c->error instead. If you want
195 "die" to propagate you need to do something like:
196 $c->forward('foo');
198 die join "\n", @{ $c->error } if @{ $c->error };
199 Or make sure to always return true values from your actions and write
201 your code like this:
202 $c->forward('foo') || return;
204 Another note is that "$c->forward" always returns a scalar because it
206 actually returns $c->state which operates in a scalar context. Thus,
207 something like:
208 return @array;
210 in an action that is forwarded to is going to return a scalar, i.e. how
212 many items are in that array, which is probably not what you want. If
213 you need to return an array then return a reference to it, or stash it
214 like so:
215 $c->stash->{array} = \@array;
217 and access it from the stash.
219 Keep in mind that the "end" method used is that of the caller action.
221 So a "$c->detach" inside a forwarded action would run the "end" method
222 from the original action requested.
223 If you call c<forward> with the name of a component class or instance,
225 rather than an action name or instance, we invoke the "process" action
226 on that class or instance, or whatever action you specific via the
227 second argument $method.
228 $c->detach( $action [, \@arguments ] )
230 $c->detach( $class, $method, [, \@arguments ] )
231 $c->detach()
232 The same as forward, but doesn't return to the previous action when
233 processing is finished.
234 When called with no arguments it escapes the processing chain entirely.
236 $c->visit( $action [, \@arguments ] )
238 $c->visit( $action [, \@captures, \@arguments ] )
239 $c->visit( $class, $method, [, \@arguments ] )
240 $c->visit( $class, $method, [, \@captures, \@arguments ] )
241 Almost the same as forward, but does a full dispatch, instead of just
242 calling the new $action / "$class->$method". This means that "begin",
243 "auto" and the method you go to are called, just like a new request.
244 In addition both "$c->action" and "$c->namespace" are localized. This
246 means, for example, that "$c->action" methods such as name, class and
247 reverse return information for the visited action when they are invoked
248 within the visited action. This is different from the behavior of
249 forward, which continues to use the $c->action object from the caller
250 action even when invoked from the called action.
251 "$c->stash" is kept unchanged.
253 In effect, visit allows you to "wrap" another action, just as it would
255 have been called by dispatching from a URL, while the analogous go
256 allows you to transfer control to another action as if it had been
257 reached directly from a URL.
258 $c->go( $action [, \@arguments ] )
260 $c->go( $action [, \@captures, \@arguments ] )
261 $c->go( $class, $method, [, \@arguments ] )
262 $c->go( $class, $method, [, \@captures, \@arguments ] )
263 The relationship between "go" and visit is the same as the relationship
264 between forward and detach. Like "$c->visit", "$c->go" will perform a
265 full dispatch on the specified action or method, with localized
266 "$c->action" and "$c->namespace". Like "detach", "go" escapes the
267 processing of the current request chain on completion, and does not
268 return to its caller.
269 @arguments are arguments to the final destination of $action. @captures
271 are arguments to the intermediate steps, if any, on the way to the
272 final sub of $action.
273 $c->response
275 $c->res
276 Returns the current Catalyst::Response object, see there for details.
277 There is a predicate method "has_response" that returns true if the
279 request object has been created. This is something you might need to
280 check if you are writing plugins that run before a request is
281 finalized.
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 The stash hash is currently stored in the PSGI $env and is managed by
300 Catalyst::Middleware::Stash. Since it's part of the $env items in the
301 stash can be accessed in sub applications mounted under your main
302 Catalyst application. For example if you delegate the response of an
303 action to another Catalyst application, that sub application will have
304 access to all the stash keys of the main one, and if can of course add
305 more keys of its own. However those new keys will not 'bubble' back up
306 to the main application.
307 For more information the best thing to do is to review the test case:
309 t/middleware-stash.t in the distribution /t directory.
310 $c->error
312 $c->error($error, ...)
313 $c->error($arrayref)
314 Returns an arrayref containing error messages. If Catalyst encounters
315 an error while processing a request, it stores the error in $c->error.
316 This method should only be used to store fatal error messages.
317 my @error = @{ $c->error };
319 Add a new error.
321 $c->error('Something bad happened');
323 Calling this will always return an arrayref (if there are no errors it
325 will be an empty arrayref.
326 $c->state
328 Contains the return value of the last executed action. Note that <<
329 $c->state >> operates in a scalar context which means that all values
330 it returns are scalar.
331 Please note that if an action throws an exception, the value of state
333 should no longer be considered the return if the last action. It is
334 generally going to be 0, which indicates an error state. Examine
335 $c->error for error details.
336 $c->clear_errors
338 Clear errors. You probably don't want to clear the errors unless you
339 are implementing a custom error screen.
340 This is equivalent to running
342 $c->error(0);
344 $c->has_errors
346 Returns true if you have errors
347 $c->last_error
349 Returns the most recent error in the stack (the one most recently
350 added...) or nothing if there are no errors. This does not modify the
351 contents of the error stack.
352 shift_errors
354 shifts the most recently added error off the error stack and returns
355 it. Returns nothing if there are no more errors.
356 pop_errors
358 pops the most recently added error off the error stack and returns it.
359 Returns nothing if there are no more errors.
360 COMPONENT ACCESSORS
362 $c->controller($name)
363 Gets a Catalyst::Controller instance by name.
364 $c->controller('Foo')->do_stuff;
366 If the name is omitted, will return the controller for the dispatched
368 action.
369 If you want to search for controllers, pass in a regexp as the
371 argument.
372 # find all controllers that start with Foo
374 my @foo_controllers = $c->controller(qr{^Foo});
375 $c->model($name)
377 Gets a Catalyst::Model instance by name.
378 $c->model('Foo')->do_stuff;
380 Any extra arguments are directly passed to ACCEPT_CONTEXT, if the model
382 defines ACCEPT_CONTEXT. If it does not, the args are discarded.
383 If the name is omitted, it will look for
385 - a model object in $c->stash->{current_model_instance}, then
386 - a model name in $c->stash->{current_model}, then
387 - a config setting 'default_model', or
388 - check if there is only one model, and return it if that's the case.
389 If you want to search for models, pass in a regexp as the argument.
391 # find all models that start with Foo
393 my @foo_models = $c->model(qr{^Foo});
394 $c->view($name)
396 Gets a Catalyst::View instance by name.
397 $c->view('Foo')->do_stuff;
399 Any extra arguments are directly passed to ACCEPT_CONTEXT.
401 If the name is omitted, it will look for
403 - a view object in $c->stash->{current_view_instance}, then
404 - a view name in $c->stash->{current_view}, then
405 - a config setting 'default_view', or
406 - check if there is only one view, and return it if that's the case.
407 If you want to search for views, pass in a regexp as the argument.
409 # find all views that start with Foo
411 my @foo_views = $c->view(qr{^Foo});
412 $c->controllers
414 Returns the available names which can be passed to $c->controller
415 $c->models
417 Returns the available names which can be passed to $c->model
418 $c->views
420 Returns the available names which can be passed to $c->view
421 $c->comp($name)
423 $c->component($name)
424 Gets a component object by name. This method is not recommended, unless
425 you want to get a specific component by full class. "$c->controller",
426 "$c->model", and "$c->view" should be used instead.
427 If $name is a regexp, a list of components matched against the full
429 component name will be returned.
430 If Catalyst can't find a component by name, it will fallback to regex
432 matching by default. To disable this behaviour set
433 disable_component_resolution_regex_fallback to a true value.
434 __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );
436 CLASS DATA AND HELPER CLASSES
438 $c->config
439 Returns or takes a hashref containing the application's configuration.
440 __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
442 You can also use a "YAML", "XML" or Config::General config file like
444 "myapp.conf" in your applications home directory. See
445 Catalyst::Plugin::ConfigLoader.
446 Cascading configuration
448 The config method is present on all Catalyst components, and
450 configuration will be merged when an application is started.
451 Configuration loaded with Catalyst::Plugin::ConfigLoader takes
452 precedence over other configuration, followed by configuration in your
453 top level "MyApp" class. These two configurations are merged, and then
454 configuration data whose hash key matches a component name is merged
455 with configuration for that component.
456 The configuration for a component is then passed to the "new" method
458 when a component is constructed.
459 For example:
461 MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
463 MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });
464 will mean that "MyApp::Model::Foo" receives the following data when
466 constructed:
467 MyApp::Model::Foo->new({
469 bar => 'baz',
470 quux => 'frob',
471 overrides => 'me',
472 });
473 It's common practice to use a Moose attribute on the receiving
475 component to access the config value.
476 package MyApp::Model::Foo;
478 use Moose;
480 # this attr will receive 'baz' at construction time
482 has 'bar' => (
483 is => 'rw',
484 isa => 'Str',
485 );
486 You can then get the value 'baz' by calling $c->model('Foo')->bar (or
488 $self->bar inside code in the model).
489 NOTE: you MUST NOT call "$self->config" or "__PACKAGE__->config" as a
491 way of reading config within your code, as this will not give you the
492 correctly merged config back. You MUST take the config values supplied
493 to the constructor and use those instead.
494 $c->log
496 Returns the logging object instance. Unless it is already set, Catalyst
497 sets this up with a Catalyst::Log object. To use your own log class,
498 set the logger with the "__PACKAGE__->log" method prior to calling
499 "__PACKAGE__->setup".
500 __PACKAGE__->log( MyLogger->new );
502 __PACKAGE__->setup;
503 And later:
505 $c->log->info( 'Now logging with my own logger!' );
507 Your log class should implement the methods described in Catalyst::Log.
509 has_encoding
511 Returned True if there's a valid encoding
512 clear_encoding
514 Clears the encoding for the current context
515 encoding
517 Sets or gets the application encoding. Setting encoding takes either
518 an Encoding object or a string that we try to resolve via
519 Encode::find_encoding.
520 You would expect to get the encoding object back if you attempt to set
522 it. If there is a failure you will get undef returned and an error
523 message in the log.
524 $c->debug
526 Returns 1 if debug mode is enabled, 0 otherwise.
527 You can enable debug mode in several ways:
529 By calling myapp_server.pl with the -d flag
531 With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG
532 The -Debug option in your MyApp.pm
533 By declaring "sub debug { 1 }" in your MyApp.pm.
534 The first three also set the log level to 'debug'.
536 Calling "$c->debug(1)" has no effect.
538 $c->dispatcher
540 Returns the dispatcher instance. See Catalyst::Dispatcher.
541 $c->engine
543 Returns the engine instance. See Catalyst::Engine.
544 UTILITY METHODS
546 $c->path_to(@path)
547 Merges @path with "$c->config->{home}" and returns a Path::Class::Dir
548 object. Note you can usually use this object as a filename, but
549 sometimes you will have to explicitly stringify it yourself by calling
550 the "->stringify" method.
551 For example:
553 $c->path_to( 'db', 'sqlite.db' );
555 MyApp->setup
557 Initializes the dispatcher and engine, loads any plugins, and loads the
558 model, view, and controller components. You may also specify an array
559 of plugins to load here, if you choose to not load them in the "use
560 Catalyst" line.
561 MyApp->setup;
563 MyApp->setup( qw/-Debug/ );
564 Note: You should not wrap this method with method modifiers or bad
566 things will happen - wrap the "setup_finalize" method instead.
567 Note: You can create a custom setup stage that will execute when the
569 application is starting. Use this to customize setup.
570 MyApp->setup(-Custom=value);
572 sub setup_custom {
574 my ($class, $value) = @_;
575 }
576 Can be handy if you want to hook into the setup phase.
578 $app->setup_finalize
580 A hook to attach modifiers to. This method does not do anything except
581 set the "setup_finished" accessor.
582 Applying method modifiers to the "setup" method doesn't work, because
584 of quirky things done for plugin setup.
585 Example:
587 after setup_finalize => sub {
589 my $app = shift;
590 ## do stuff here..
592 };
593 $c->uri_for( $path?, @args?, \%query_values?, \$fragment? )
595 $c->uri_for( $action, \@captures?, @args?, \%query_values?, \$fragment? )
596 $c->uri_for( $action, [@captures, @args], \%query_values?, \$fragment? )
597 Constructs an absolute URI object based on the application root, the
598 provided path, and the additional arguments and query parameters
599 provided. When used as a string, provides a textual URI. If you need
600 more flexibility than this (i.e. the option to provide relative URIs
601 etc.) see Catalyst::Plugin::SmartURI.
602 If no arguments are provided, the URI for the current action is
604 returned. To return the current action and also provide @args, use
605 "$c->uri_for( $c->action, @args )".
606 If the first argument is a string, it is taken as a public URI path
608 relative to "$c->namespace" (if it doesn't begin with a forward slash)
609 or relative to the application root (if it does). It is then merged
610 with "$c->request->base"; any @args are appended as additional path
611 components; and any %query_values are appended as "?foo=bar"
612 parameters.
613 NOTE If you are using this 'stringy' first argument, we skip encoding
615 and allow you to declare something like:
616 $c->uri_for('/foo/bar#baz')
618 Where 'baz' is a URI fragment. We consider this first argument string
620 to be 'expert' mode where you are expected to create a valid URL and we
621 for the most part just pass it through without a lot of internal effort
622 to escape and encode.
623 If the first argument is a Catalyst::Action it represents an action
625 which will have its path resolved using
626 "$c->dispatcher->uri_for_action". The optional "\@captures" argument
627 (an arrayref) allows passing the captured variables that are needed to
628 fill in the paths of Chained and Regex actions; once the path is
629 resolved, "uri_for" continues as though a path was provided, appending
630 any arguments or parameters and creating an absolute URI.
631 The captures for the current request can be found in
633 "$c->request->captures", and actions can be resolved using
634 "Catalyst::Controller->action_for($name)". If you have a private action
635 path, use "$c->uri_for_action" instead.
636 # Equivalent to $c->req->uri
638 $c->uri_for($c->action, $c->req->captures,
639 @{ $c->req->args }, $c->req->params);
640 # For the Foo action in the Bar controller
642 $c->uri_for($c->controller('Bar')->action_for('Foo'));
643 # Path to a static resource
645 $c->uri_for('/static/images/logo.png');
646 In general the scheme of the generated URI object will follow the
648 incoming request however if your targeted action or action chain has
649 the Scheme attribute it will use that instead.
650 Also, if the targeted Action or Action chain declares Args/CaptureArgs
652 that have type constraints, we will require that your proposed URL
653 verify on those declared constraints.
654 $c->uri_for_action( $path, \@captures_and_args?, @args?, \%query_values? )
656 $c->uri_for_action( $action, \@captures_and_args?, @args?, \%query_values?
657 )
658 $path
659 A private path to the Catalyst action you want to create a URI for.
660 This is a shortcut for calling
662 "$c->dispatcher->get_action_by_path($path)" and passing the
663 resulting $action and the remaining arguments to "$c->uri_for".
664 You can also pass in a Catalyst::Action object, in which case it is
666 passed to "$c->uri_for".
667 Note that although the path looks like a URI that dispatches to the
669 wanted action, it is not a URI, but an internal path to that
670 action.
671 For example, if the action looks like:
673 package MyApp::Controller::Users;
675 sub lst : Path('the-list') {}
677 You can use:
679 $c->uri_for_action('/users/lst')
681 and it will create the URI /users/the-list.
683 \@captures_and_args?
685 Optional array reference of Captures (i.e. "CaptureArgs" or
686 "$c->req->captures") and arguments to the request. Usually used
687 with Catalyst::DispatchType::Chained to interpolate all the
688 parameters in the URI.
689 @args?
691 Optional list of extra arguments - can be supplied in the
692 "\@captures_and_args?" array ref, or here - whichever is easier for
693 your code.
694 Your action can have zero, a fixed or a variable number of args
696 (e.g. Args(1) for a fixed number or Args() for a variable
697 number)..
698 \%query_values?
700 Optional array reference of query parameters to append. E.g.
701 { foo => 'bar' }
703 will generate
705 /rest/of/your/uri?foo=bar
707 $c->welcome_message
709 Returns the Catalyst welcome HTML page.
710 run_options
712 Contains a hash of options passed from the application script,
713 including the original ARGV the script received, the processed values
714 from that ARGV and any extra arguments to the script which were not
715 processed.
716 This can be used to add custom options to your application's scripts
718 and setup your application differently depending on the values of these
719 options.
720
722 These methods are not meant to be used by end users.
723 $c->components
725 Returns a hash of components.
726 $c->context_class
728 Returns or sets the context class.
729 $c->counter
731 Returns a hashref containing coderefs and execution counts (needed for
732 deep recursion detection).
733 $c->depth
735 Returns the number of actions on the current internal execution stack.
736 $c->dispatch
738 Dispatches a request to actions.
739 $c->dispatcher_class
741 Returns or sets the dispatcher class.
742 $c->dump_these
744 Returns a list of 2-element array references (name, structure) pairs
745 that will be dumped on the error page in debug mode.
746 $c->engine_class
748 Returns or sets the engine class.
749 $c->execute( $class, $coderef )
751 Execute a coderef in given class and catch exceptions. Errors are
752 available via $c->error.
753 $c->finalize
755 Finalizes the request.
756 $c->log_stats
758 Logs statistics.
759 $c->finalize_body
761 Finalizes body.
762 $c->finalize_cookies
764 Finalizes cookies.
765 $c->finalize_error
767 Finalizes error. If there is only one error in "error" and it is an
768 object that does "as_psgi" or "code" we rethrow the error and presume
769 it caught by middleware up the ladder. Otherwise we return the
770 debugging error page (in debug mode) or we return the default error
771 page (production mode).
772 $c->finalize_headers
774 Finalizes headers.
775 $c->finalize_encoding
777 Make sure your body is encoded properly IF you set an encoding. By
778 default the encoding is UTF-8 but you can disable it by explicitly
779 setting the encoding configuration value to undef.
780 We can only encode when the body is a scalar. Methods for encoding via
782 the streaming interfaces (such as "write" and "write_fh" on
783 Catalyst::Response are available).
784 See "ENCODING".
786 $c->finalize_output
788 An alias for finalize_body.
789 $c->finalize_read
791 Finalizes the input after reading is complete.
792 $c->finalize_uploads
794 Finalizes uploads. Cleans up any temporary files.
795 $c->get_action( $action, $namespace )
797 Gets an action in a given namespace.
798 $c->get_actions( $action, $namespace )
800 Gets all actions of a given name in a namespace and all parent
801 namespaces.
802 $app->handle_request( @arguments )
804 Called to handle each HTTP request.
805 $class->prepare( @arguments )
807 Creates a Catalyst context from an engine-specific request (Apache,
808 CGI, etc.).
809 $c->prepare_action
811 Prepares action. See Catalyst::Dispatcher.
812 $c->prepare_body
814 Prepares message body.
815 $c->prepare_body_chunk( $chunk )
817 Prepares a chunk of data before sending it to HTTP::Body.
818 See Catalyst::Engine.
820 $c->prepare_body_parameters
822 Prepares body parameters.
823 $c->prepare_connection
825 Prepares connection.
826 $c->prepare_cookies
828 Prepares cookies by ensuring that the attribute on the request object
829 has been built.
830 $c->prepare_headers
832 Prepares request headers by ensuring that the attribute on the request
833 object has been built.
834 $c->prepare_parameters
836 Prepares parameters.
837 $c->prepare_path
839 Prepares path and base.
840 $c->prepare_query_parameters
842 Prepares query parameters.
843 $c->log_request
845 Writes information about the request to the debug logs. This includes:
846 • Request method, path, and remote IP address
848 • Query keywords (see "query_keywords" in Catalyst::Request)
850 • Request parameters
852 • File uploads
854 $c->log_response
856 Writes information about the response to the debug logs by calling
857 "$c->log_response_status_line" and "$c->log_response_headers".
858 $c->log_response_status_line($response)
860 Writes one line of information about the response to the debug logs.
861 This includes:
862 • Response status code
864 • Content-Type header (if present)
866 • Content-Length header (if present)
868 $c->log_response_headers($headers);
870 Hook method which can be wrapped by plugins to log the response
871 headers. No-op in the default implementation.
872 $c->log_request_parameters( query => {}, body => {} )
874 Logs request parameters to debug logs
875 $c->log_request_uploads
877 Logs file uploads included in the request to the debug logs. The
878 parameter name, filename, file type, and file size are all included in
879 the debug logs.
880 $c->log_request_headers($headers);
882 Hook method which can be wrapped by plugins to log the request headers.
883 No-op in the default implementation.
884 $c->log_headers($type => $headers)
886 Logs HTTP::Headers (either request or response) to the debug logs.
887 $c->prepare_read
889 Prepares the input for reading.
890 $c->prepare_request
892 Prepares the engine request.
893 $c->prepare_uploads
895 Prepares uploads.
896 $c->prepare_write
898 Prepares the output for writing.
899 $c->request_class
901 Returns or sets the request class. Defaults to Catalyst::Request.
902 $app->request_class_traits
904 An arrayref of Moose::Roles which are applied to the request class.
905 You can name the full namespace of the role, or a namespace suffix,
906 which will then be tried against the following standard namespace
907 prefixes.
908 $MyApp::TraitFor::Request::$trait_suffix
910 Catalyst::TraitFor::Request::$trait_suffix
911 So for example if you set:
913 MyApp->request_class_traits(['Foo']);
915 We try each possible role in turn (and throw an error if none load)
917 Foo
919 MyApp::TraitFor::Request::Foo
920 Catalyst::TraitFor::Request::Foo
921 The namespace part 'TraitFor::Request' was chosen to assist in
923 backwards compatibility with CatalystX::RoleApplicator which previously
924 provided these features in a stand alone package.
925 $app->composed_request_class
927 This is the request class which has been composed with any
928 request_class_traits.
929 $c->response_class
931 Returns or sets the response class. Defaults to Catalyst::Response.
932 $app->response_class_traits
934 An arrayref of Moose::Roles which are applied to the response class.
935 You can name the full namespace of the role, or a namespace suffix,
936 which will then be tried against the following standard namespace
937 prefixes.
938 $MyApp::TraitFor::Response::$trait_suffix
940 Catalyst::TraitFor::Response::$trait_suffix
941 So for example if you set:
943 MyApp->response_class_traits(['Foo']);
945 We try each possible role in turn (and throw an error if none load)
947 Foo
949 MyApp::TraitFor::Response::Foo
950 Catalyst::TraitFor::Responset::Foo
951 The namespace part 'TraitFor::Response' was chosen to assist in
953 backwards compatibility with CatalystX::RoleApplicator which previously
954 provided these features in a stand alone package.
955 $app->composed_response_class
957 This is the request class which has been composed with any
958 response_class_traits.
959 $c->read( [$maxlength] )
961 Reads a chunk of data from the request body. This method is designed to
962 be used in a while loop, reading $maxlength bytes on every call.
963 $maxlength defaults to the size of the request if not specified.
964 You have to set "MyApp->config(parse_on_demand => 1)" to use this
966 directly.
967 Warning: If you use read(), Catalyst will not process the body, so you
969 will not be able to access POST parameters or file uploads via
970 $c->request. You must handle all body parsing yourself.
971 $c->run
973 Starts the engine.
974 $c->set_action( $action, $code, $namespace, $attrs )
976 Sets an action in a given namespace.
977 $c->setup_actions($component)
979 Sets up actions for a component.
980 $c->setup_components
982 This method is called internally to set up the application's
983 components.
984 It finds modules by calling the locate_components method, expands them
986 to package names with the expand_component_module method, and then
987 installs each component into the application.
988 The "setup_components" config option is passed to both of the above
990 methods.
991 Installation of each component is performed by the setup_component
993 method, below.
994 $app->setup_injected_components
996 Called by setup_compoents to setup components that are injected.
997 $app->setup_injected_component( $injected_component_name, $config )
999 Setup a given injected component.
1000 $app->inject_component($MyApp_Component_name => \%args);
1002 Add a component that is injected at setup:
1003 MyApp->inject_component( 'Model::Foo' => { from_component => 'Common::Foo' } );
1005 Must be called before ->setup. Expects a component name for your
1007 current application and \%args where
1008 from_component
1010 The target component being injected into your application
1011 roles
1013 An arrayref of Moose::Roles that are applied to your component.
1014 Example
1016 MyApp->inject_component(
1018 'Model::Foo' => {
1019 from_component => 'Common::Model::Foo',
1020 roles => ['Role1', 'Role2'],
1021 });
1022 $app->inject_components
1024 Inject a list of components:
1025 MyApp->inject_components(
1027 'Model::FooOne' => {
1028 from_component => 'Common::Model::Foo',
1029 roles => ['Role1', 'Role2'],
1030 },
1031 'Model::FooTwo' => {
1032 from_component => 'Common::Model::Foo',
1033 roles => ['Role1', 'Role2'],
1034 });
1035 $c->locate_components( $setup_component_config )
1037 This method is meant to provide a list of component modules that should
1038 be setup for the application. By default, it will use
1039 Module::Pluggable.
1040 Specify a "setup_components" config option to pass additional options
1042 directly to Module::Pluggable. To add additional search paths, specify
1043 a key named "search_extra" as an array reference. Items in the array
1044 beginning with "::" will have the application class name prepended to
1045 them.
1046 $c->expand_component_module( $component, $setup_component_config )
1048 Components found by "locate_components" will be passed to this method,
1049 which is expected to return a list of component (package) names to be
1050 set up.
1051 $app->delayed_setup_component
1053 Returns a coderef that points to a setup_component instance. Used
1054 internally for when you want to delay setup until the first time the
1055 component is called.
1056 $c->setup_component
1058 $app->config_for( $component_name )
1059 Return the application level configuration (which is not yet merged
1060 with any local component configuration, via $component_class->config)
1061 for the named component or component object. Example:
1062 MyApp->config(
1064 'Model::Foo' => { a => 1, b => 2},
1065 );
1066 my $config = MyApp->config_for('MyApp::Model::Foo');
1068 In this case $config is the hashref "{a=>1, b=>2}".
1070 This is also handy for looking up configuration for a plugin, to make
1072 sure you follow existing Catalyst standards for where a plugin should
1073 put its configuration.
1074 $c->setup_dispatcher
1076 Sets up dispatcher.
1077 $c->setup_engine
1079 Sets up engine.
1080 $c->apply_default_middlewares
1082 Adds the following Plack middlewares to your application, since they
1083 are useful and commonly needed:
1084 Plack::Middleware::LighttpdScriptNameFix (if you are using Lighttpd),
1086 Plack::Middleware::IIS6ScriptNameFix (always applied since this
1087 middleware is smart enough to conditionally apply itself).
1088 We will also automatically add Plack::Middleware::ReverseProxy if we
1090 notice that your HTTP $env variable "REMOTE_ADDR" is '127.0.0.1'. This
1091 is usually an indication that your server is running behind a proxy
1092 frontend. However in 2014 this is often not the case. We preserve
1093 this code for backwards compatibility however I highly recommend that
1094 if you are running the server behind a front end proxy that you clearly
1095 indicate so with the "using_frontend_proxy" configuration setting to
1096 true for your environment configurations that run behind a proxy. This
1097 way if you change your front end proxy address someday your code would
1098 inexplicably stop working as expected.
1099 Additionally if we detect we are using Nginx, we add a bit of custom
1101 middleware to solve some problems with the way that server handles
1102 $ENV{PATH_INFO} and $ENV{SCRIPT_NAME}.
1103 Please NOTE that if you do use "using_frontend_proxy" the middleware is
1105 now adding via "registered_middleware" rather than this method.
1106 If you are using Lighttpd or IIS6 you may wish to apply these
1108 middlewares. In general this is no longer a common case but we have
1109 this here for backward compatibility.
1110 App->psgi_app
1112 App->to_app
1113 Returns a PSGI application code reference for the catalyst application
1114 $c. This is the bare application created without the
1115 "apply_default_middlewares" method called. We do however apply
1116 "registered_middleware" since those are integral to how Catalyst
1117 functions. Also, unlike starting your application with a generated
1118 server script (via Catalyst::Devel and "catalyst.pl") we do not attempt
1119 to return a valid PSGI application using any existing "${myapp}.psgi"
1120 scripts in your $HOME directory.
1121 NOTE "apply_default_middlewares" was originally created when the first
1123 PSGI port was done for v5.90000. These are middlewares that are added
1124 to achieve backward compatibility with older applications. If you
1125 start your application using one of the supplied server scripts
1126 (generated with Catalyst::Devel and the project skeleton script
1127 "catalyst.pl") we apply "apply_default_middlewares" automatically.
1128 This was done so that pre and post PSGI port applications would work
1129 the same way.
1130 This is what you want to be using to retrieve the PSGI application code
1132 reference of your Catalyst application for use in a custom .psgi or in
1133 your own created server modules.
1134 $c->setup_home
1136 Sets up the home directory.
1137 $c->setup_encoding
1139 Sets up the input/output encoding. See ENCODING
1140 handle_unicode_encoding_exception
1142 Hook to let you customize how encoding errors are handled. By default
1143 we just throw an exception and the default error page will pick it up.
1144 Receives a hashref of debug information. Example of call (from the
1145 Catalyst internals):
1146 my $decoded_after_fail = $c->handle_unicode_encoding_exception({
1148 param_value => $value,
1149 error_msg => $_,
1150 encoding_step => 'params',
1151 });
1152 The calling code expects to receive a decoded string or an exception.
1154 You can override this for custom handling of unicode errors. By default
1156 we just die. If you want a custom response here, one approach is to
1157 throw an HTTP style exception, instead of returning a decoded string or
1158 throwing a generic exception.
1159 sub handle_unicode_encoding_exception {
1161 my ($c, $params) = @_;
1162 HTTP::Exception::BAD_REQUEST->throw(status_message=>$params->{error_msg});
1163 }
1164 Alternatively you can 'catch' the error, stash it and write handling
1166 code later in your application:
1167 sub handle_unicode_encoding_exception {
1169 my ($c, $params) = @_;
1170 $c->stash(BAD_UNICODE_DATA=>$params);
1171 # return a dummy string.
1172 return 1;
1173 }
1174 <B>NOTE:</b> Please keep in mind that once an error like this occurs,
1176 the request setup is still ongoing, which means the state of $c and
1177 related context parts like the request and response may not be setup up
1178 correctly (since we haven't finished the setup yet). If you throw an
1179 exception the setup is aborted.
1180 $c->setup_log
1182 Sets up log by instantiating a Catalyst::Log object and passing it to
1183 log(). Pass in a comma-delimited list of levels to set the log to.
1184 This method also installs a "debug" method that returns a true value
1186 into the catalyst subclass if the "debug" level is passed in the comma-
1187 delimited list, or if the $CATALYST_DEBUG environment variable is set
1188 to a true value.
1189 Note that if the log has already been setup, by either a previous call
1191 to "setup_log" or by a call such as "__PACKAGE__->log( MyLogger->new
1192 )", that this method won't actually set up the log object.
1193 $c->setup_plugins
1195 Sets up plugins.
1196 $c->setup_stats
1198 Sets up timing statistics class.
1199 $c->registered_plugins
1201 Returns a sorted list of the plugins which have either been stated in
1202 the import list.
1203 If passed a given plugin name, it will report a boolean value
1205 indicating whether or not that plugin is loaded. A fully qualified
1206 name is required if the plugin name does not begin with
1207 "Catalyst::Plugin::".
1208 if ($c->registered_plugins('Some::Plugin')) {
1210 ...
1211 }
1212 default_middleware
1214 Returns a list of instantiated PSGI middleware objects which is the
1215 default middleware that is active for this application (taking any
1216 configuration options into account, excluding your custom added
1217 middleware via the "psgi_middleware" configuration option). You can
1218 override this method if you wish to change the default middleware
1219 (although do so at risk since some middleware is vital to application
1220 function.)
1221 The current default middleware list is:
1223 Catalyst::Middleware::Stash
1225 Plack::Middleware::HTTPExceptions
1226 Plack::Middleware::RemoveRedundantBody
1227 Plack::Middleware::FixMissingBodyInRedirect
1228 Plack::Middleware::ContentLength
1229 Plack::Middleware::MethodOverride
1230 Plack::Middleware::Head
1231 If the configuration setting "using_frontend_proxy" is true we add:
1233 Plack::Middleware::ReverseProxy
1235 If the configuration setting "using_frontend_proxy_path" is true we
1237 add:
1238 Plack::Middleware::ReverseProxyPath
1240 But NOTE that Plack::Middleware::ReverseProxyPath is not a dependency
1242 of the Catalyst distribution so if you want to use this option you
1243 should add it to your project distribution file.
1244 These middlewares will be added at "setup_middleware" during the
1246 "setup" phase of application startup.
1247 registered_middlewares
1249 Read only accessor that returns an array of all the middleware in the
1250 order that they were added (which is the REVERSE of the order they will
1251 be applied).
1252 The values returned will be either instances of Plack::Middleware or of
1254 a compatible interface, or a coderef, which is assumed to be inlined
1255 middleware
1256 setup_middleware (?@middleware)
1258 Read configuration information stored in configuration key
1259 "psgi_middleware" or from passed @args.
1260 See under "CONFIGURATION" information regarding "psgi_middleware" and
1262 how to use it to enable Plack::Middleware
1263 This method is automatically called during 'setup' of your application,
1265 so you really don't need to invoke it. However you may do so if you
1266 find the idea of loading middleware via configuration weird :). For
1267 example:
1268 package MyApp;
1270 use Catalyst;
1272 __PACKAGE__->setup_middleware('Head');
1274 __PACKAGE__->setup;
1275 When we read middleware definitions from configuration, we reverse the
1277 list which sounds odd but is likely how you expect it to work if you
1278 have prior experience with Plack::Builder or if you previously used the
1279 plugin Catalyst::Plugin::EnableMiddleware (which is now considered
1280 deprecated)
1281 So basically your middleware handles an incoming request from the first
1283 registered middleware, down and handles the response from the last
1284 middleware up.
1285 registered_data_handlers
1287 A read only copy of registered Data Handlers returned as a Hash, where
1288 each key is a content type and each value is a subref that attempts to
1289 decode that content type.
1290 setup_data_handlers (?@data_handler)
1292 Read configuration information stored in configuration key
1293 "data_handlers" or from passed @args.
1294 See under "CONFIGURATION" information regarding "data_handlers".
1296 This method is automatically called during 'setup' of your application,
1298 so you really don't need to invoke it.
1299 default_data_handlers
1301 Default Data Handlers that come bundled with Catalyst. Currently there
1302 are only two default data handlers, for 'application/json' and an
1303 alternative to 'application/x-www-form-urlencoded' which supposed
1304 nested form parameters via CGI::Struct or via CGI::Struct::XS IF you've
1305 installed it.
1306 The 'application/json' data handler is used to parse incoming JSON into
1308 a Perl data structure. It uses JSON::MaybeXS. This allows you to fail
1309 back to JSON::PP, which is a Pure Perl JSON decoder, and has the
1310 smallest dependency impact.
1311 Because we don't wish to add more dependencies to Catalyst, if you wish
1313 to use this new feature we recommend installing Cpanel::JSON::XS in
1314 order to get the best performance. You should add either to your
1315 dependency list (Makefile.PL, dist.ini, cpanfile, etc.)
1316 $c->stack
1318 Returns an arrayref of the internal execution stack (actions that are
1319 currently executing).
1320 $c->stats
1322 Returns the current timing statistics object. By default Catalyst uses
1323 Catalyst::Stats, but can be set otherwise with stats_class.
1324 Even if -Stats is not enabled, the stats object is still available. By
1326 enabling it with "$c->stats->enabled(1)", it can be used to profile
1327 explicitly, although MyApp.pm still won't profile nor output anything
1328 by itself.
1329 $c->stats_class
1331 Returns or sets the stats (timing statistics) class. Catalyst::Stats is
1332 used by default.
1333 $app->stats_class_traits
1335 A arrayref of Moose::Roles that are applied to the stats_class before
1336 creating it.
1337 $app->composed_stats_class
1339 this is the stats_class composed with any 'stats_class_traits'. You
1340 can name the full namespace of the role, or a namespace suffix, which
1341 will then be tried against the following standard namespace prefixes.
1342 $MyApp::TraitFor::Stats::$trait_suffix
1344 Catalyst::TraitFor::Stats::$trait_suffix
1345 So for example if you set:
1347 MyApp->stats_class_traits(['Foo']);
1349 We try each possible role in turn (and throw an error if none load)
1351 Foo
1353 MyApp::TraitFor::Stats::Foo
1354 Catalyst::TraitFor::Stats::Foo
1355 The namespace part 'TraitFor::Stats' was chosen to assist in backwards
1357 compatibility with CatalystX::RoleApplicator which previously provided
1358 these features in a stand alone package.
1359 $c->use_stats
1361 Returns 1 when stats collection is enabled.
1362 Note that this is a static method, not an accessor and should be
1364 overridden by declaring "sub use_stats { 1 }" in your MyApp.pm, not by
1365 calling "$c->use_stats(1)".
1366 $c->write( $data )
1368 Writes $data to the output stream. When using this method directly, you
1369 will need to manually set the "Content-Length" header to the length of
1370 your output data, if known.
1371 version
1373 Returns the Catalyst version number. Mostly useful for "powered by"
1374 messages in template systems.
1375
1377 There are a number of 'base' config variables which can be set:
1378 • "always_catch_http_exceptions" - As of version 5.90060 Catalyst
1380 rethrows errors conforming to the interface described by
1381 Plack::Middleware::HTTPExceptions and lets the middleware deal with
1382 it. Set true to get the deprecated behaviour and have Catalyst
1383 catch HTTP exceptions.
1384 • "default_model" - The default model picked if you say "$c->model".
1386 See "$c->model($name)".
1387 • "default_view" - The default view to be rendered or returned when
1389 "$c->view" is called. See "$c->view($name)".
1390 • "disable_component_resolution_regex_fallback" - Turns off the
1392 deprecated component resolution functionality so that if any of the
1393 component methods (e.g. "$c->controller('Foo')") are called then
1394 regex search will not be attempted on string values and instead
1395 "undef" will be returned.
1396 • "home" - The application home directory. In an uninstalled
1398 application, this is the top level application directory. In an
1399 installed application, this will be the directory containing
1400 "MyApp.pm".
1401 • "ignore_frontend_proxy" - See "PROXY SUPPORT"
1403 • "name" - The name of the application in debug messages and the
1405 debug and welcome screens
1406 • "parse_on_demand" - The request body (for example file uploads)
1408 will not be parsed until it is accessed. This allows you to (for
1409 example) check authentication (and reject the upload) before
1410 actually receiving all the data. See "ON-DEMAND PARSER"
1411 • "root" - The root directory for templates. Usually this is just a
1413 subdirectory of the home directory, but you can set it to change
1414 the templates to a different directory.
1415 • "search_extra" - Array reference passed to Module::Pluggable to for
1417 additional namespaces from which components will be loaded (and
1418 constructed and stored in "$c->components").
1419 • "show_internal_actions" - If true, causes internal actions such as
1421 "_DISPATCH" to be shown in hit debug tables in the test server.
1422 • "use_request_uri_for_path" - Controls if the "REQUEST_URI" or
1424 "PATH_INFO" environment variable should be used for determining the
1425 request path.
1426 Most web server environments pass the requested path to the
1428 application using environment variables, from which Catalyst has to
1429 reconstruct the request base (i.e. the top level path to / in the
1430 application, exposed as "$c->request->base") and the request path
1431 below that base.
1432 There are two methods of doing this, both of which have advantages
1434 and disadvantages. Which method is used is determined by the
1435 "$c->config(use_request_uri_for_path)" setting (which can either be
1436 true or false).
1437 use_request_uri_for_path => 0
1439 This is the default (and the) traditional method that Catalyst
1440 has used for determining the path information. The path is
1441 generated from a combination of the "PATH_INFO" and
1442 "SCRIPT_NAME" environment variables. The allows the
1443 application to behave correctly when "mod_rewrite" is being
1444 used to redirect requests into the application, as these
1445 variables are adjusted by mod_rewrite to take account for the
1446 redirect.
1447 However this method has the major disadvantage that it is
1449 impossible to correctly decode some elements of the path, as
1450 RFC 3875 says: ""Unlike a URI path, the PATH_INFO is not
1451 URL-encoded, and cannot contain path-segment parameters."" This
1452 means PATH_INFO is always decoded, and therefore Catalyst can't
1453 distinguish / vs %2F in paths (in addition to other encoded
1454 values).
1455 use_request_uri_for_path => 1
1457 This method uses the "REQUEST_URI" and "SCRIPT_NAME"
1458 environment variables. As "REQUEST_URI" is never decoded, this
1459 means that applications using this mode can correctly handle
1460 URIs including the %2F character (i.e. with
1461 "AllowEncodedSlashes" set to "On" in Apache).
1462 Given that this method of path resolution is provably more
1464 correct, it is recommended that you use this unless you have a
1465 specific need to deploy your application in a non-standard
1466 environment, and you are aware of the implications of not being
1467 able to handle encoded URI paths correctly.
1468 However it also means that in a number of cases when the app
1470 isn't installed directly at a path, but instead is having paths
1471 rewritten into it (e.g. as a .cgi/fcgi in a public_html
1472 directory, with mod_rewrite in a .htaccess file, or when SSI is
1473 used to rewrite pages into the app, or when sub-paths of the
1474 app are exposed at other URIs than that which the app is
1475 'normally' based at with "mod_rewrite"), the resolution of
1476 "$c->request->base" will be incorrect.
1477 • "using_frontend_proxy" - See "PROXY SUPPORT".
1479 • "using_frontend_proxy_path" - Enabled
1481 Plack::Middleware::ReverseProxyPath on your application (if
1482 installed, otherwise log an error). This is useful if your
1483 application is not running on the 'root' (or /) of your host
1484 server. NOTE if you use this feature you should add the required
1485 middleware to your project dependency list since its not
1486 automatically a dependency of Catalyst. This has been done since
1487 not all people need this feature and we wish to restrict the growth
1488 of Catalyst dependencies.
1489 • "encoding" - See "ENCODING"
1491 This now defaults to 'UTF-8'. You my turn it off by setting this
1493 configuration value to undef.
1494 • "abort_chain_on_error_fix"
1496 Defaults to true.
1498 When there is an error in an action chain, the default behavior is
1500 to abort the processing of the remaining actions to avoid running
1501 them when the application is in an unexpected state.
1502 Before version 5.90070, the default used to be false. To keep the
1504 old behaviour, you can explicitly set the value to false. E.g.
1505 __PACKAGE__->config(abort_chain_on_error_fix => 0);
1507 If this setting is set to false, then the remaining actions are
1509 performed and the error is caught at the end of the chain.
1510 • "use_hash_multivalue_in_request"
1512 In Catalyst::Request the methods "query_parameters",
1514 "body_parametes" and "parameters" return a hashref where values
1515 might be scalar or an arrayref depending on the incoming data. In
1516 many cases this can be undesirable as it leads one to writing
1517 defensive code like the following:
1518 my ($val) = ref($c->req->parameters->{a}) ?
1520 @{$c->req->parameters->{a}} :
1521 $c->req->parameters->{a};
1522 Setting this configuration item to true will make Catalyst populate
1524 the attributes underlying these methods with an instance of
1525 Hash::MultiValue which is used by Plack::Request and others to
1526 solve this very issue. You may prefer this behavior to the
1527 default, if so enable this option (be warned if you enable it in a
1528 legacy application we are not sure if it is completely backwardly
1529 compatible).
1530 • "skip_complex_post_part_handling"
1532 When creating body parameters from a POST, if we run into a
1534 multipart POST that does not contain uploads, but instead contains
1535 inlined complex data (very uncommon) we cannot reliably convert
1536 that into field => value pairs. So instead we create an instance
1537 of Catalyst::Request::PartData. If this causes issue for you, you
1538 can disable this by setting "skip_complex_post_part_handling" to
1539 true (default is false).
1540 • "skip_body_param_unicode_decoding"
1542 Generally we decode incoming POST params based on your declared
1544 encoding (the default for this is to decode UTF-8). If this is
1545 causing you trouble and you do not wish to turn all encoding
1546 support off (with the "encoding" configuration parameter) you may
1547 disable this step atomically by setting this configuration
1548 parameter to true.
1549 • "do_not_decode_query"
1551 If true, then do not try to character decode any wide characters in
1553 your request URL query or keywords. Most readings of the relevant
1554 specifications suggest these should be UTF-* encoded, which is the
1555 default that Catalyst will use, however if you are creating a lot
1556 of URLs manually or have external evil clients, this might cause
1557 you trouble. If you find the changes introduced in Catalyst
1558 version 5.90080+ break some of your query code, you may disable the
1559 UTF-8 decoding globally using this configuration.
1560 This setting takes precedence over "default_query_encoding"
1562 • "do_not_check_query_encoding"
1564 Catalyst versions 5.90080 - 5.90106 would decode query parts of an
1566 incoming request but would not raise an exception when the decoding
1567 failed due to incorrect unicode. It now does, but if this change
1568 is giving you trouble you may disable it by setting this
1569 configuration to true.
1570 • "default_query_encoding"
1572 By default we decode query and keywords in your request URL using
1574 UTF-8, which is our reading of the relevant specifications. This
1575 setting allows one to specify a fixed value for how to decode your
1576 query. You might need this if you are doing a lot of custom
1577 encoding of your URLs and not using UTF-8.
1578 • "use_chained_args_0_special_case"
1580 In older versions of Catalyst, when more than one action matched
1582 the same path AND all those matching actions declared Args(0), we'd
1583 break the tie by choosing the first action defined. We now
1584 normalized how Args(0) works so that it follows the same rule as
1585 Args(N), which is to say when we need to break a tie we choose the
1586 LAST action defined. If this breaks your code and you don't have
1587 time to update to follow the new normalized approach, you may set
1588 this value to true and it will globally revert to the original
1589 chaining behavior.
1590 • "psgi_middleware" - See "PSGI MIDDLEWARE".
1592 • "data_handlers" - See "DATA HANDLERS".
1594 • "stats_class_traits"
1596 An arrayref of Moose::Roles that get composed into your stats
1598 class.
1599 • "request_class_traits"
1601 An arrayref of Moose::Roles that get composed into your request
1603 class.
1604 • "response_class_traits"
1606 An arrayref of Moose::Roles that get composed into your response
1608 class.
1609 • "inject_components"
1611 A Hashref of Catalyst::Component subclasses that are 'injected'
1613 into configuration. For example:
1614 MyApp->config({
1616 inject_components => {
1617 'Controller::Err' => { from_component => 'Local::Controller::Errors' },
1618 'Model::Zoo' => { from_component => 'Local::Model::Foo' },
1619 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] },
1620 },
1621 'Controller::Err' => { a => 100, b=>200, namespace=>'error' },
1622 'Model::Zoo' => { a => 2 },
1623 'Model::Foo' => { a => 100 },
1624 });
1625 Generally Catalyst looks for components in your Model/View or
1627 Controller directories. However for cases when you which to use an
1628 existing component and you don't need any customization (where for
1629 when you can apply a role to customize it) you may inject those
1630 components into your application. Please note any configuration
1631 should be done 'in the normal way', with a key under configuration
1632 named after the component affix, as in the above example.
1633 Using this type of injection allows you to construct significant
1635 amounts of your application with only configuration!. This may or
1636 may not lead to increased code understanding.
1637 Please not you may also call the ->inject_components application
1639 method as well, although you must do so BEFORE setup.
1640
1642 Generally when you throw an exception inside an Action (or somewhere in
1643 your stack, such as in a model that an Action is calling) that
1644 exception is caught by Catalyst and unless you either catch it yourself
1645 (via eval or something like Try::Tiny or by reviewing the "error"
1646 stack, it will eventually reach "finalize_errors" and return either the
1647 debugging error stack page, or the default error page. However, if
1648 your exception can be caught by Plack::Middleware::HTTPExceptions,
1649 Catalyst will instead rethrow it so that it can be handled by that
1650 middleware (which is part of the default middleware). For example this
1651 would allow
1652 use HTTP::Throwable::Factory 'http_throw';
1654 sub throws_exception :Local {
1656 my ($self, $c) = @_;
1657 http_throw(SeeOther => { location =>
1659 $c->uri_for($self->action_for('redirect')) });
1660 }
1662
1664 Catalyst uses internal actions like "_DISPATCH", "_BEGIN", "_AUTO",
1665 "_ACTION", and "_END". These are by default not shown in the private
1666 action table, but you can make them visible with a config parameter.
1667 MyApp->config(show_internal_actions => 1);
1669
1671 The request body is usually parsed at the beginning of a request, but
1672 if you want to handle input yourself, you can enable on-demand parsing
1673 with a config parameter.
1674 MyApp->config(parse_on_demand => 1);
1676
1678 Many production servers operate using the common double-server
1679 approach, with a lightweight frontend web server passing requests to a
1680 larger backend server. An application running on the backend server
1681 must deal with two problems: the remote user always appears to be
1682 127.0.0.1 and the server's hostname will appear to be "localhost"
1683 regardless of the virtual host that the user connected through.
1684 Catalyst will automatically detect this situation when you are running
1686 the frontend and backend servers on the same machine. The following
1687 changes are made to the request.
1688 $c->req->address is set to the user's real IP address, as read from
1690 the HTTP X-Forwarded-For header.
1691 The host value for $c->req->base and $c->req->uri is set to the real
1693 host, as read from the HTTP X-Forwarded-Host header.
1694 Additionally, you may be running your backend application on an
1696 insecure connection (port 80) while your frontend proxy is running
1697 under SSL. If there is a discrepancy in the ports, use the HTTP header
1698 "X-Forwarded-Port" to tell Catalyst what port the frontend listens on.
1699 This will allow all URIs to be created properly.
1700 In the case of passing in:
1702 X-Forwarded-Port: 443
1704 All calls to "uri_for" will result in an https link, as is expected.
1706 Obviously, your web server must support these headers for this to work.
1708 In a more complex server farm environment where you may have your
1710 frontend proxy server(s) on different machines, you will need to set a
1711 configuration option to tell Catalyst to read the proxied data from the
1712 headers.
1713 MyApp->config(using_frontend_proxy => 1);
1715 If you do not wish to use the proxy support at all, you may set:
1717 MyApp->config(ignore_frontend_proxy => 0);
1719 Note about psgi files
1721 Note that if you supply your own .psgi file, calling
1722 "MyApp->psgi_app(@_);", then this will not happen automatically.
1723 You either need to apply Plack::Middleware::ReverseProxy yourself in
1725 your psgi, for example:
1726 builder {
1728 enable "Plack::Middleware::ReverseProxy";
1729 MyApp->psgi_app
1730 };
1731 This will unconditionally add the ReverseProxy support, or you need to
1733 call "$app = MyApp->apply_default_middlewares($app)" (to conditionally
1734 apply the support depending upon your config).
1735 See Catalyst::PSGI for more information.
1737
1739 Catalyst has been tested under Apache 2's threading "mpm_worker",
1740 "mpm_winnt", and the standalone forking HTTP server on Windows. We
1741 believe the Catalyst core to be thread-safe.
1742 If you plan to operate in a threaded environment, remember that all
1744 other modules you are using must also be thread-safe. Some modules,
1745 most notably DBD::SQLite, are not thread-safe.
1746
1748 The Catalyst::Request object uses HTTP::Body to populate 'classic' HTML
1749 form parameters and URL search query fields. However it has become
1750 common for various alternative content types to be PUT or POSTed to
1751 your controllers and actions. People working on RESTful APIs, or using
1752 AJAX often use JSON, XML and other content types when communicating
1753 with an application server. In order to better support this use case,
1754 Catalyst defines a global configuration option, "data_handlers", which
1755 lets you associate a content type with a coderef that parses that
1756 content type into something Perl can readily access.
1757 package MyApp::Web;
1759 use Catalyst;
1761 use JSON::MaybeXS;
1762 __PACKAGE__->config(
1764 data_handlers => {
1765 'application/json' => sub { local $/; decode_json $_->getline },
1766 },
1767 ## Any other configuration.
1768 );
1769 __PACKAGE__->setup;
1771 By default Catalyst comes with a generic JSON data handler similar to
1773 the example given above, which uses JSON::MaybeXS to provide either
1774 JSON::PP (a pure Perl, dependency free JSON parser) or Cpanel::JSON::XS
1775 if you have it installed (if you want the faster XS parser, add it to
1776 you project Makefile.PL or dist.ini, cpanfile, etc.)
1777 The "data_handlers" configuration is a hashref whose keys are HTTP
1779 Content-Types (matched against the incoming request type using a regexp
1780 such as to be case insensitive) and whose values are coderefs that
1781 receive a localized version of $_ which is a filehandle object pointing
1782 to received body.
1783 This feature is considered an early access release and we reserve the
1785 right to alter the interface in order to provide a performant and
1786 secure solution to alternative request body content. Your reports
1787 welcomed!
1788
1790 You can define middleware, defined as Plack::Middleware or a compatible
1791 interface in configuration. Your middleware definitions are in the
1792 form of an arrayref under the configuration key "psgi_middleware".
1793 Here's an example with details to follow:
1794 package MyApp::Web;
1796 use Catalyst;
1798 use Plack::Middleware::StackTrace;
1799 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1801 __PACKAGE__->config(
1803 'psgi_middleware', [
1804 'Debug',
1805 '+MyApp::Custom',
1806 $stacktrace_middleware,
1807 'Session' => {store => 'File'},
1808 sub {
1809 my $app = shift;
1810 return sub {
1811 my $env = shift;
1812 $env->{myapp.customkey} = 'helloworld';
1813 $app->($env);
1814 },
1815 },
1816 ],
1817 );
1818 __PACKAGE__->setup;
1820 So the general form is:
1822 __PACKAGE__->config(psgi_middleware => \@middleware_definitions);
1824 Where @middleware is one or more of the following, applied in the
1826 REVERSE of the order listed (to make it function similarly to
1827 Plack::Builder:
1828 Alternatively, you may also define middleware by calling the
1830 "setup_middleware" package method:
1831 package MyApp::Web;
1833 use Catalyst;
1835 __PACKAGE__->setup_middleware( \@middleware_definitions);
1837 __PACKAGE__->setup;
1838 In the case where you do both (use 'setup_middleware' and
1840 configuration) the package call to setup_middleware will be applied
1841 earlier (in other words its middleware will wrap closer to the
1842 application). Keep this in mind since in some cases the order of
1843 middleware is important.
1844 The two approaches are not exclusive.
1846 Middleware Object
1848 An already initialized object that conforms to the
1849 Plack::Middleware specification:
1850 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1852 __PACKAGE__->config(
1854 'psgi_middleware', [
1855 $stacktrace_middleware,
1856 ]);
1857 coderef
1859 A coderef that is an inlined middleware:
1860 __PACKAGE__->config(
1862 'psgi_middleware', [
1863 sub {
1864 my $app = shift;
1865 return sub {
1866 my $env = shift;
1867 if($env->{PATH_INFO} =~m/forced/) {
1868 Plack::App::File
1869 ->new(file=>TestApp->path_to(qw/share static forced.txt/))
1870 ->call($env);
1871 } else {
1872 return $app->($env);
1873 }
1874 },
1875 },
1876 ]);
1877 a scalar
1879 We assume the scalar refers to a namespace after normalizing it
1880 using the following rules:
1881 (1) If the scalar is prefixed with a "+" (as in "+MyApp::Foo") then
1883 the full string is assumed to be 'as is', and we just install and
1884 use the middleware.
1885 (2) If the scalar begins with "Plack::Middleware" or your
1887 application namespace (the package name of your Catalyst
1888 application subclass), we also assume then that it is a full
1889 namespace, and use it.
1890 (3) Lastly, we then assume that the scalar is a partial namespace,
1892 and attempt to resolve it first by looking for it under your
1893 application namespace (for example if you application is
1894 "MyApp::Web" and the scalar is "MyMiddleware", we'd look under
1895 "MyApp::Web::Middleware::MyMiddleware") and if we don't find it
1896 there, we will then look under the regular Plack::Middleware
1897 namespace (i.e. for the previous we'd try
1898 "Plack::Middleware::MyMiddleware"). We look under your application
1899 namespace first to let you 'override' common Plack::Middleware
1900 locally, should you find that a good idea.
1901 Examples:
1903 package MyApp::Web;
1905 __PACKAGE__->config(
1907 'psgi_middleware', [
1908 'Debug', ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap
1909 'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap
1910 '+MyApp::Custom', ## MyApp::Custom->wrap
1911 ],
1912 );
1913 a scalar followed by a hashref
1915 Just like the previous, except the following "HashRef" is used as
1916 arguments to initialize the middleware object.
1917 __PACKAGE__->config(
1919 'psgi_middleware', [
1920 'Session' => {store => 'File'},
1921 ]);
1922 Please see PSGI for more on middleware.
1924
1926 Starting in Catalyst version 5.90080 encoding is automatically enabled
1927 and set to encode all body responses to UTF8 when possible and
1928 applicable. Following is documentation on this process. If you are
1929 using an older version of Catalyst you should review documentation for
1930 that version since a lot has changed.
1931 By default encoding is now 'UTF-8'. You may turn it off by setting the
1933 encoding configuration to undef.
1934 MyApp->config(encoding => undef);
1936 This is recommended for temporary backwards compatibility only.
1938 To turn it off for a single request use the clear_encoding method to
1940 turn off encoding for this request. This can be useful when you are
1941 setting the body to be an arbitrary block of bytes, especially if that
1942 block happens to be a block of UTF8 text.
1943 Encoding is automatically applied when the content-type is set to a
1945 type that can be encoded. Currently we encode when the content type
1946 matches the following regular expression:
1947 $content_type =~ /^text|xml$|javascript$/
1949 Encoding is set on the application, but it is copied to the context
1951 object so that you can override it on a request basis.
1952 Be default we don't automatically encode 'application/json' since the
1954 most common approaches to generating this type of response (Either via
1955 Catalyst::View::JSON or Catalyst::Action::REST) will do so already and
1956 we want to avoid double encoding issues.
1957 If you are producing JSON response in an unconventional manner (such as
1959 via a template or manual strings) you should perform the UTF8 encoding
1960 manually as well such as to conform to the JSON specification.
1961 NOTE: We also examine the value of $c->response->content_encoding. If
1963 you set this (like for example 'gzip', and manually gzipping the body)
1964 we assume that you have done all the necessary encoding yourself, since
1965 we cannot encode the gzipped contents. If you use a plugin like
1966 Catalyst::Plugin::Compress you need to update to a modern version in
1967 order to have this function correctly with the new UTF8 encoding code,
1968 or you can use Plack::Middleware::Deflater or (probably best) do your
1969 compression on a front end proxy.
1970 Methods
1972 encoding
1973 Returns an instance of an "Encode" encoding
1974 print $c->encoding->name
1976 handle_unicode_encoding_exception ($exception_context)
1978 Method called when decoding process for a request fails.
1979 An $exception_context hashref is provided to allow you to override
1981 the behaviour of your application when given data with incorrect
1982 encodings.
1983 The default method throws exceptions in the case of invalid request
1985 parameters (resulting in a 500 error), but ignores errors in upload
1986 filenames.
1987 The keys passed in the $exception_context hash are:
1989 param_value
1991 The value which was not able to be decoded.
1992 error_msg
1994 The exception received from Encode.
1995 encoding_step
1997 What type of data was being decoded. Valid values are
1998 (currently) "params" - for request parameters / arguments /
1999 captures and "uploads" - for request upload filenames.
2000
2002 IRC:
2003 Join #catalyst on irc.perl.org.
2005 Mailing Lists:
2007 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
2009 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
2010 Web:
2012 http://catalyst.perl.org
2014 Wiki:
2016 http://dev.catalyst.perl.org
2018
2020 Task::Catalyst - All you need to start with Catalyst
2021 Catalyst::Manual - The Catalyst Manual
2022 Catalyst::Component, Catalyst::Controller - Base classes for components
2023 Catalyst::Engine - Core engine
2024 Catalyst::Log - Log class.
2025 Catalyst::Request - Request object
2026 Catalyst::Response - Response object
2027 Catalyst::Test - The test suite.
2029 sri: Sebastian Riedel <sri@cpan.org>
2030
2032 abw: Andy Wardley
2033 acme: Leon Brocard <leon@astray.com>
2035 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
2037 andrewalker: André Walker <andre@cpan.org>
2039 Andrew Bramble
2041 Andrew Ford <A.Ford@ford-mason.co.uk>
2043 Andrew Ruthven
2045 andyg: Andy Grundman <andy@hybridized.org>
2047 audreyt: Audrey Tang
2049 bricas: Brian Cassidy <bricas@cpan.org>
2051 Caelum: Rafael Kitover <rkitover@io.com>
2053 chansen: Christian Hansen
2055 Chase Venters <chase.venters@gmail.com>
2057 chicks: Christopher Hicks
2059 Chisel Wright <pause@herlpacker.co.uk>
2061 Danijel Milicevic <me@danijel.de>
2063 davewood: David Schmidt <davewood@cpan.org>
2065 David Kamholz <dkamholz@cpan.org>
2067 David Naughton <naughton@umn.edu>
2069 David E. Wheeler
2071 dhoss: Devin Austin <dhoss@cpan.org>
2073 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
2075 Drew Taylor
2077 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
2079 esskar: Sascha Kiefer
2081 fireartist: Carl Franks <cfranks@cpan.org>
2083 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
2085 gabb: Danijel Milicevic
2087 Gary Ashton Jones
2089 Gavin Henry <ghenry@perl.me.uk>
2091 Geoff Richards
2093 groditi: Guillermo Roditi <groditi@gmail.com>
2095 hobbs: Andrew Rodland <andrew@cleverdomain.org>
2097 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
2099 jcamacho: Juan Camacho
2101 jester: Jesse Sheidlower <jester@panix.com>
2103 jhannah: Jay Hannah <jay@jays.net>
2105 Jody Belka
2107 Johan Lindstrom
2109 jon: Jon Schutz <jjschutz@cpan.org>
2111 Jonathan Rockway <jrockway@cpan.org>
2113 Kieren Diment <kd@totaldatasolution.com>
2115 konobi: Scott McWhirter <konobi@cpan.org>
2117 marcus: Marcus Ramberg <mramberg@cpan.org>
2119 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
2121 mgrimes: Mark Grimes <mgrimes@cpan.org>
2123 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
2125 mugwump: Sam Vilain
2127 naughton: David Naughton
2129 ningu: David Kamholz <dkamholz@cpan.org>
2131 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
2133 numa: Dan Sully <daniel@cpan.org>
2135 obra: Jesse Vincent
2137 Octavian Rasnita
2139 omega: Andreas Marienborg
2141 Oleg Kostyuk <cub.uanic@gmail.com>
2143 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
2145 rafl: Florian Ragwitz <rafl@debian.org>
2147 random: Roland Lammel <lammel@cpan.org>
2149 revmischa: Mischa Spiegelmock <revmischa@cpan.org>
2151 Robert Sedlacek <rs@474.at>
2153 rrwo: Robert Rothenberg <rrwo@cpan.org>
2155 SpiceMan: Marcel Montes
2157 sky: Arthur Bergman
2159 szbalint: Balint Szilakszi <szbalint@cpan.org>
2161 t0m: Tomas Doran <bobtfish@bobtfish.net>
2163 Ulf Edvinsson
2165 vanstyn: Henry Van Styn <vanstyn@cpan.org>
2167 Viljo Marrandi <vilts@yahoo.com>
2169 Will Hawes <info@whawes.co.uk>
2171 willert: Sebastian Willert <willert@cpan.org>
2173 wreis: Wallace Reis <wreis@cpan.org>
2175 Yuval Kogman <nothingmuch@woobling.org>
2177 rainboxx: Matthias Dietrich <perl@rainboxx.de>
2179 dd070: Dhaval Dhanani <dhaval070@gmail.com>
2181 Upasana <me@upasana.me>
2183 John Napiorkowski (jnap) <jjnapiork@cpan.org>
2185
2187 Copyright (c) 2005-2015, the above named PROJECT FOUNDER and
2188 CONTRIBUTORS.
2189
2191 This library is free software. You can redistribute it and/or modify it
2192 under the same terms as Perl itself.
2193perl v5.36.0 2023-01-20 Catalyst(3)