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 This is one way of calling another action (method) in the same or a
167 different controller. You can also use "$self->my_method($c, @args)" in
168 the same controller or "$c->controller('MyController')->my_method($c,
169 @args)" in a different controller. The main difference is that
170 'forward' uses some of the Catalyst request cycle overhead, including
171 debugging, which may be useful to you. On the other hand, there are
172 some complications to using 'forward', restrictions on values returned
173 from 'forward', and it may not handle errors as you prefer. Whether
174 you use 'forward' or not is up to you; it is not considered superior to
175 the other ways to call a method.
176 'forward' calls another action, by its private name. If you give a
178 class name but no method, "process()" is called. You may also
179 optionally pass arguments in an arrayref. The action will receive the
180 arguments in @_ and "$c->req->args". Upon returning from the function,
181 "$c->req->args" will be restored to the previous values.
182 Any data "return"ed from the action forwarded to, will be returned by
184 the call to forward.
185 my $foodata = $c->forward('/foo');
187 $c->forward('index');
188 $c->forward(qw/Model::DBIC::Foo do_stuff/);
189 $c->forward('View::TT');
190 Note that forward implies an "eval { }" around the call (actually
192 execute does), thus rendering all exceptions thrown by the called
193 action non-fatal and pushing them onto $c->error instead. If you want
194 "die" to propagate you need to do something like:
195 $c->forward('foo');
197 die join "\n", @{ $c->error } if @{ $c->error };
198 Or make sure to always return true values from your actions and write
200 your code like this:
201 $c->forward('foo') || return;
203 Another note is that "$c->forward" always returns a scalar because it
205 actually returns $c->state which operates in a scalar context. Thus,
206 something like:
207 return @array;
209 in an action that is forwarded to is going to return a scalar, i.e. how
211 many items are in that array, which is probably not what you want. If
212 you need to return an array then return a reference to it, or stash it
213 like so:
214 $c->stash->{array} = \@array;
216 and access it from the stash.
218 Keep in mind that the "end" method used is that of the caller action.
220 So a "$c->detach" inside a forwarded action would run the "end" method
221 from the original action requested.
222 $c->detach( $action [, \@arguments ] )
224 $c->detach( $class, $method, [, \@arguments ] )
225 $c->detach()
226 The same as forward, but doesn't return to the previous action when
227 processing is finished.
228 When called with no arguments it escapes the processing chain entirely.
230 $c->visit( $action [, \@arguments ] )
232 $c->visit( $action [, \@captures, \@arguments ] )
233 $c->visit( $class, $method, [, \@arguments ] )
234 $c->visit( $class, $method, [, \@captures, \@arguments ] )
235 Almost the same as forward, but does a full dispatch, instead of just
236 calling the new $action / "$class->$method". This means that "begin",
237 "auto" and the method you go to are called, just like a new request.
238 In addition both "$c->action" and "$c->namespace" are localized. This
240 means, for example, that "$c->action" methods such as name, class and
241 reverse return information for the visited action when they are invoked
242 within the visited action. This is different from the behavior of
243 forward, which continues to use the $c->action object from the caller
244 action even when invoked from the called action.
245 "$c->stash" is kept unchanged.
247 In effect, visit allows you to "wrap" another action, just as it would
249 have been called by dispatching from a URL, while the analogous go
250 allows you to transfer control to another action as if it had been
251 reached directly from a URL.
252 $c->go( $action [, \@arguments ] )
254 $c->go( $action [, \@captures, \@arguments ] )
255 $c->go( $class, $method, [, \@arguments ] )
256 $c->go( $class, $method, [, \@captures, \@arguments ] )
257 The relationship between "go" and visit is the same as the relationship
258 between forward and detach. Like "$c->visit", "$c->go" will perform a
259 full dispatch on the specified action or method, with localized
260 "$c->action" and "$c->namespace". Like "detach", "go" escapes the
261 processing of the current request chain on completion, and does not
262 return to its caller.
263 @arguments are arguments to the final destination of $action. @captures
265 are arguments to the intermediate steps, if any, on the way to the
266 final sub of $action.
267 $c->response
269 $c->res
270 Returns the current Catalyst::Response object, see there for details.
271 There is a predicate method "has_response" that returns true if the
273 request object has been created. This is something you might need to
274 check if you are writing plugins that run before a request is
275 finalized.
276 $c->stash
278 Returns a hashref to the stash, which may be used to store data and
279 pass it between components during a request. You can also set hash keys
280 by passing arguments. The stash is automatically sent to the view. The
281 stash is cleared at the end of a request; it cannot be used for
282 persistent storage (for this you must use a session; see
283 Catalyst::Plugin::Session for a complete system integrated with
284 Catalyst).
285 $c->stash->{foo} = $bar;
287 $c->stash( { moose => 'majestic', qux => 0 } );
288 $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
289 # stash is automatically passed to the view for use in a template
291 $c->forward( 'MyApp::View::TT' );
292 The stash hash is currently stored in the PSGI $env and is managed by
294 Catalyst::Middleware::Stash. Since it's part of the $env items in the
295 stash can be accessed in sub applications mounted under your main
296 Catalyst application. For example if you delegate the response of an
297 action to another Catalyst application, that sub application will have
298 access to all the stash keys of the main one, and if can of course add
299 more keys of its own. However those new keys will not 'bubble' back up
300 to the main application.
301 For more information the best thing to do is to review the test case:
303 t/middleware-stash.t in the distribution /t directory.
304 $c->error
306 $c->error($error, ...)
307 $c->error($arrayref)
308 Returns an arrayref containing error messages. If Catalyst encounters
309 an error while processing a request, it stores the error in $c->error.
310 This method should only be used to store fatal error messages.
311 my @error = @{ $c->error };
313 Add a new error.
315 $c->error('Something bad happened');
317 Calling this will always return an arrayref (if there are no errors it
319 will be an empty arrayref.
320 $c->state
322 Contains the return value of the last executed action. Note that <<
323 $c->state >> operates in a scalar context which means that all values
324 it returns are scalar.
325 Please note that if an action throws an exception, the value of state
327 should no longer be considered the return if the last action. It is
328 generally going to be 0, which indicates an error state. Examine
329 $c->error for error details.
330 $c->clear_errors
332 Clear errors. You probably don't want to clear the errors unless you
333 are implementing a custom error screen.
334 This is equivalent to running
336 $c->error(0);
338 $c->has_errors
340 Returns true if you have errors
341 $c->last_error
343 Returns the most recent error in the stack (the one most recently
344 added...) or nothing if there are no errors. This does not modify the
345 contents of the error stack.
346 shift_errors
348 shifts the most recently added error off the error stack and returns
349 it. Returns nothing if there are no more errors.
350 pop_errors
352 pops the most recently added error off the error stack and returns it.
353 Returns nothing if there are no more errors.
354 COMPONENT ACCESSORS
356 $c->controller($name)
357 Gets a Catalyst::Controller instance by name.
358 $c->controller('Foo')->do_stuff;
360 If the name is omitted, will return the controller for the dispatched
362 action.
363 If you want to search for controllers, pass in a regexp as the
365 argument.
366 # find all controllers that start with Foo
368 my @foo_controllers = $c->controller(qr{^Foo});
369 $c->model($name)
371 Gets a Catalyst::Model instance by name.
372 $c->model('Foo')->do_stuff;
374 Any extra arguments are directly passed to ACCEPT_CONTEXT, if the model
376 defines ACCEPT_CONTEXT. If it does not, the args are discarded.
377 If the name is omitted, it will look for
379 - a model object in $c->stash->{current_model_instance}, then
380 - a model name in $c->stash->{current_model}, then
381 - a config setting 'default_model', or
382 - check if there is only one model, and return it if that's the case.
383 If you want to search for models, pass in a regexp as the argument.
385 # find all models that start with Foo
387 my @foo_models = $c->model(qr{^Foo});
388 $c->view($name)
390 Gets a Catalyst::View instance by name.
391 $c->view('Foo')->do_stuff;
393 Any extra arguments are directly passed to ACCEPT_CONTEXT.
395 If the name is omitted, it will look for
397 - a view object in $c->stash->{current_view_instance}, then
398 - a view name in $c->stash->{current_view}, then
399 - a config setting 'default_view', or
400 - check if there is only one view, and return it if that's the case.
401 If you want to search for views, pass in a regexp as the argument.
403 # find all views that start with Foo
405 my @foo_views = $c->view(qr{^Foo});
406 $c->controllers
408 Returns the available names which can be passed to $c->controller
409 $c->models
411 Returns the available names which can be passed to $c->model
412 $c->views
414 Returns the available names which can be passed to $c->view
415 $c->comp($name)
417 $c->component($name)
418 Gets a component object by name. This method is not recommended, unless
419 you want to get a specific component by full class. "$c->controller",
420 "$c->model", and "$c->view" should be used instead.
421 If $name is a regexp, a list of components matched against the full
423 component name will be returned.
424 If Catalyst can't find a component by name, it will fallback to regex
426 matching by default. To disable this behaviour set
427 disable_component_resolution_regex_fallback to a true value.
428 __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );
430 CLASS DATA AND HELPER CLASSES
432 $c->config
433 Returns or takes a hashref containing the application's configuration.
434 __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
436 You can also use a "YAML", "XML" or Config::General config file like
438 "myapp.conf" in your applications home directory. See
439 Catalyst::Plugin::ConfigLoader.
440 Cascading configuration
442 The config method is present on all Catalyst components, and
444 configuration will be merged when an application is started.
445 Configuration loaded with Catalyst::Plugin::ConfigLoader takes
446 precedence over other configuration, followed by configuration in your
447 top level "MyApp" class. These two configurations are merged, and then
448 configuration data whose hash key matches a component name is merged
449 with configuration for that component.
450 The configuration for a component is then passed to the "new" method
452 when a component is constructed.
453 For example:
455 MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
457 MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });
458 will mean that "MyApp::Model::Foo" receives the following data when
460 constructed:
461 MyApp::Model::Foo->new({
463 bar => 'baz',
464 quux => 'frob',
465 overrides => 'me',
466 });
467 It's common practice to use a Moose attribute on the receiving
469 component to access the config value.
470 package MyApp::Model::Foo;
472 use Moose;
474 # this attr will receive 'baz' at construction time
476 has 'bar' => (
477 is => 'rw',
478 isa => 'Str',
479 );
480 You can then get the value 'baz' by calling $c->model('Foo')->bar (or
482 $self->bar inside code in the model).
483 NOTE: you MUST NOT call "$self->config" or "__PACKAGE__->config" as a
485 way of reading config within your code, as this will not give you the
486 correctly merged config back. You MUST take the config values supplied
487 to the constructor and use those instead.
488 $c->log
490 Returns the logging object instance. Unless it is already set, Catalyst
491 sets this up with a Catalyst::Log object. To use your own log class,
492 set the logger with the "__PACKAGE__->log" method prior to calling
493 "__PACKAGE__->setup".
494 __PACKAGE__->log( MyLogger->new );
496 __PACKAGE__->setup;
497 And later:
499 $c->log->info( 'Now logging with my own logger!' );
501 Your log class should implement the methods described in Catalyst::Log.
503 has_encoding
505 Returned True if there's a valid encoding
506 clear_encoding
508 Clears the encoding for the current context
509 encoding
511 Sets or gets the application encoding. Setting encoding takes either
512 an Encoding object or a string that we try to resolve via
513 Encode::find_encoding.
514 You would expect to get the encoding object back if you attempt to set
516 it. If there is a failure you will get undef returned and an error
517 message in the log.
518 $c->debug
520 Returns 1 if debug mode is enabled, 0 otherwise.
521 You can enable debug mode in several ways:
523 By calling myapp_server.pl with the -d flag
525 With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG
526 The -Debug option in your MyApp.pm
527 By declaring "sub debug { 1 }" in your MyApp.pm.
528 The first three also set the log level to 'debug'.
530 Calling "$c->debug(1)" has no effect.
532 $c->dispatcher
534 Returns the dispatcher instance. See Catalyst::Dispatcher.
535 $c->engine
537 Returns the engine instance. See Catalyst::Engine.
538 UTILITY METHODS
540 $c->path_to(@path)
541 Merges @path with "$c->config->{home}" and returns a Path::Class::Dir
542 object. Note you can usually use this object as a filename, but
543 sometimes you will have to explicitly stringify it yourself by calling
544 the "->stringify" method.
545 For example:
547 $c->path_to( 'db', 'sqlite.db' );
549 MyApp->setup
551 Initializes the dispatcher and engine, loads any plugins, and loads the
552 model, view, and controller components. You may also specify an array
553 of plugins to load here, if you choose to not load them in the "use
554 Catalyst" line.
555 MyApp->setup;
557 MyApp->setup( qw/-Debug/ );
558 Note: You should not wrap this method with method modifiers or bad
560 things will happen - wrap the "setup_finalize" method instead.
561 Note: You can create a custom setup stage that will execute when the
563 application is starting. Use this to customize setup.
564 MyApp->setup(-Custom=value);
566 sub setup_custom {
568 my ($class, $value) = @_;
569 }
570 Can be handy if you want to hook into the setup phase.
572 $app->setup_finalize
574 A hook to attach modifiers to. This method does not do anything except
575 set the "setup_finished" accessor.
576 Applying method modifiers to the "setup" method doesn't work, because
578 of quirky things done for plugin setup.
579 Example:
581 after setup_finalize => sub {
583 my $app = shift;
584 ## do stuff here..
586 };
587 $c->uri_for( $path?, @args?, \%query_values?, \$fragment? )
589 $c->uri_for( $action, \@captures?, @args?, \%query_values?, \$fragment? )
590 $c->uri_for( $action, [@captures, @args], \%query_values?, \$fragment? )
591 Constructs an absolute URI object based on the application root, the
592 provided path, and the additional arguments and query parameters
593 provided. When used as a string, provides a textual URI. If you need
594 more flexibility than this (i.e. the option to provide relative URIs
595 etc.) see Catalyst::Plugin::SmartURI.
596 If no arguments are provided, the URI for the current action is
598 returned. To return the current action and also provide @args, use
599 "$c->uri_for( $c->action, @args )".
600 If the first argument is a string, it is taken as a public URI path
602 relative to "$c->namespace" (if it doesn't begin with a forward slash)
603 or relative to the application root (if it does). It is then merged
604 with "$c->request->base"; any @args are appended as additional path
605 components; and any %query_values are appended as "?foo=bar"
606 parameters.
607 NOTE If you are using this 'stringy' first argument, we skip encoding
609 and allow you to declare something like:
610 $c->uri_for('/foo/bar#baz')
612 Where 'baz' is a URI fragment. We consider this first argument string
614 to be 'expert' mode where you are expected to create a valid URL and we
615 for the most part just pass it through without a lot of internal effort
616 to escape and encode.
617 If the first argument is a Catalyst::Action it represents an action
619 which will have its path resolved using
620 "$c->dispatcher->uri_for_action". The optional "\@captures" argument
621 (an arrayref) allows passing the captured variables that are needed to
622 fill in the paths of Chained and Regex actions; once the path is
623 resolved, "uri_for" continues as though a path was provided, appending
624 any arguments or parameters and creating an absolute URI.
625 The captures for the current request can be found in
627 "$c->request->captures", and actions can be resolved using
628 "Catalyst::Controller->action_for($name)". If you have a private action
629 path, use "$c->uri_for_action" instead.
630 # Equivalent to $c->req->uri
632 $c->uri_for($c->action, $c->req->captures,
633 @{ $c->req->args }, $c->req->params);
634 # For the Foo action in the Bar controller
636 $c->uri_for($c->controller('Bar')->action_for('Foo'));
637 # Path to a static resource
639 $c->uri_for('/static/images/logo.png');
640 In general the scheme of the generated URI object will follow the
642 incoming request however if your targeted action or action chain has
643 the Scheme attribute it will use that instead.
644 Also, if the targeted Action or Action chain declares Args/CaptureArgs
646 that have type constraints, we will require that your proposed URL
647 verify on those declared constraints.
648 $c->uri_for_action( $path, \@captures_and_args?, @args?, \%query_values? )
650 $c->uri_for_action( $action, \@captures_and_args?, @args?, \%query_values?
651 )
652 $path
653 A private path to the Catalyst action you want to create a URI for.
654 This is a shortcut for calling
656 "$c->dispatcher->get_action_by_path($path)" and passing the
657 resulting $action and the remaining arguments to "$c->uri_for".
658 You can also pass in a Catalyst::Action object, in which case it is
660 passed to "$c->uri_for".
661 Note that although the path looks like a URI that dispatches to the
663 wanted action, it is not a URI, but an internal path to that
664 action.
665 For example, if the action looks like:
667 package MyApp::Controller::Users;
669 sub lst : Path('the-list') {}
671 You can use:
673 $c->uri_for_action('/users/lst')
675 and it will create the URI /users/the-list.
677 \@captures_and_args?
679 Optional array reference of Captures (i.e. "CaptureArgs" or
680 "$c->req->captures") and arguments to the request. Usually used
681 with Catalyst::DispatchType::Chained to interpolate all the
682 parameters in the URI.
683 @args?
685 Optional list of extra arguments - can be supplied in the
686 "\@captures_and_args?" array ref, or here - whichever is easier for
687 your code.
688 Your action can have zero, a fixed or a variable number of args
690 (e.g. Args(1) for a fixed number or "Args()" for a variable
691 number)..
692 \%query_values?
694 Optional array reference of query parameters to append. E.g.
695 { foo => 'bar' }
697 will generate
699 /rest/of/your/uri?foo=bar
701 $c->welcome_message
703 Returns the Catalyst welcome HTML page.
704 run_options
706 Contains a hash of options passed from the application script,
707 including the original ARGV the script received, the processed values
708 from that ARGV and any extra arguments to the script which were not
709 processed.
710 This can be used to add custom options to your application's scripts
712 and setup your application differently depending on the values of these
713 options.
714
716 These methods are not meant to be used by end users.
717 $c->components
719 Returns a hash of components.
720 $c->context_class
722 Returns or sets the context class.
723 $c->counter
725 Returns a hashref containing coderefs and execution counts (needed for
726 deep recursion detection).
727 $c->depth
729 Returns the number of actions on the current internal execution stack.
730 $c->dispatch
732 Dispatches a request to actions.
733 $c->dispatcher_class
735 Returns or sets the dispatcher class.
736 $c->dump_these
738 Returns a list of 2-element array references (name, structure) pairs
739 that will be dumped on the error page in debug mode.
740 $c->engine_class
742 Returns or sets the engine class.
743 $c->execute( $class, $coderef )
745 Execute a coderef in given class and catch exceptions. Errors are
746 available via $c->error.
747 $c->finalize
749 Finalizes the request.
750 $c->log_stats
752 Logs statistics.
753 $c->finalize_body
755 Finalizes body.
756 $c->finalize_cookies
758 Finalizes cookies.
759 $c->finalize_error
761 Finalizes error. If there is only one error in "error" and it is an
762 object that does "as_psgi" or "code" we rethrow the error and presume
763 it caught by middleware up the ladder. Otherwise we return the
764 debugging error page (in debug mode) or we return the default error
765 page (production mode).
766 $c->finalize_headers
768 Finalizes headers.
769 $c->finalize_encoding
771 Make sure your body is encoded properly IF you set an encoding. By
772 default the encoding is UTF-8 but you can disable it by explicitly
773 setting the encoding configuration value to undef.
774 We can only encode when the body is a scalar. Methods for encoding via
776 the streaming interfaces (such as "write" and "write_fh" on
777 Catalyst::Response are available).
778 See "ENCODING".
780 $c->finalize_output
782 An alias for finalize_body.
783 $c->finalize_read
785 Finalizes the input after reading is complete.
786 $c->finalize_uploads
788 Finalizes uploads. Cleans up any temporary files.
789 $c->get_action( $action, $namespace )
791 Gets an action in a given namespace.
792 $c->get_actions( $action, $namespace )
794 Gets all actions of a given name in a namespace and all parent
795 namespaces.
796 $app->handle_request( @arguments )
798 Called to handle each HTTP request.
799 $class->prepare( @arguments )
801 Creates a Catalyst context from an engine-specific request (Apache,
802 CGI, etc.).
803 $c->prepare_action
805 Prepares action. See Catalyst::Dispatcher.
806 $c->prepare_body
808 Prepares message body.
809 $c->prepare_body_chunk( $chunk )
811 Prepares a chunk of data before sending it to HTTP::Body.
812 See Catalyst::Engine.
814 $c->prepare_body_parameters
816 Prepares body parameters.
817 $c->prepare_connection
819 Prepares connection.
820 $c->prepare_cookies
822 Prepares cookies by ensuring that the attribute on the request object
823 has been built.
824 $c->prepare_headers
826 Prepares request headers by ensuring that the attribute on the request
827 object has been built.
828 $c->prepare_parameters
830 Prepares parameters.
831 $c->prepare_path
833 Prepares path and base.
834 $c->prepare_query_parameters
836 Prepares query parameters.
837 $c->log_request
839 Writes information about the request to the debug logs. This includes:
840 • Request method, path, and remote IP address
842 • Query keywords (see "query_keywords" in Catalyst::Request)
844 • Request parameters
846 • File uploads
848 $c->log_response
850 Writes information about the response to the debug logs by calling
851 "$c->log_response_status_line" and "$c->log_response_headers".
852 $c->log_response_status_line($response)
854 Writes one line of information about the response to the debug logs.
855 This includes:
856 • Response status code
858 • Content-Type header (if present)
860 • Content-Length header (if present)
862 $c->log_response_headers($headers);
864 Hook method which can be wrapped by plugins to log the response
865 headers. No-op in the default implementation.
866 $c->log_request_parameters( query => {}, body => {} )
868 Logs request parameters to debug logs
869 $c->log_request_uploads
871 Logs file uploads included in the request to the debug logs. The
872 parameter name, filename, file type, and file size are all included in
873 the debug logs.
874 $c->log_request_headers($headers);
876 Hook method which can be wrapped by plugins to log the request headers.
877 No-op in the default implementation.
878 $c->log_headers($type => $headers)
880 Logs HTTP::Headers (either request or response) to the debug logs.
881 $c->prepare_read
883 Prepares the input for reading.
884 $c->prepare_request
886 Prepares the engine request.
887 $c->prepare_uploads
889 Prepares uploads.
890 $c->prepare_write
892 Prepares the output for writing.
893 $c->request_class
895 Returns or sets the request class. Defaults to Catalyst::Request.
896 $app->request_class_traits
898 An arrayref of Moose::Roles which are applied to the request class.
899 You can name the full namespace of the role, or a namespace suffix,
900 which will then be tried against the following standard namespace
901 prefixes.
902 $MyApp::TraitFor::Request::$trait_suffix
904 Catalyst::TraitFor::Request::$trait_suffix
905 So for example if you set:
907 MyApp->request_class_traits(['Foo']);
909 We try each possible role in turn (and throw an error if none load)
911 Foo
913 MyApp::TraitFor::Request::Foo
914 Catalyst::TraitFor::Request::Foo
915 The namespace part 'TraitFor::Request' was chosen to assist in
917 backwards compatibility with CatalystX::RoleApplicator which previously
918 provided these features in a stand alone package.
919 $app->composed_request_class
921 This is the request class which has been composed with any
922 request_class_traits.
923 $c->response_class
925 Returns or sets the response class. Defaults to Catalyst::Response.
926 $app->response_class_traits
928 An arrayref of Moose::Roles which are applied to the response class.
929 You can name the full namespace of the role, or a namespace suffix,
930 which will then be tried against the following standard namespace
931 prefixes.
932 $MyApp::TraitFor::Response::$trait_suffix
934 Catalyst::TraitFor::Response::$trait_suffix
935 So for example if you set:
937 MyApp->response_class_traits(['Foo']);
939 We try each possible role in turn (and throw an error if none load)
941 Foo
943 MyApp::TraitFor::Response::Foo
944 Catalyst::TraitFor::Responset::Foo
945 The namespace part 'TraitFor::Response' was chosen to assist in
947 backwards compatibility with CatalystX::RoleApplicator which previously
948 provided these features in a stand alone package.
949 $app->composed_response_class
951 This is the request class which has been composed with any
952 response_class_traits.
953 $c->read( [$maxlength] )
955 Reads a chunk of data from the request body. This method is designed to
956 be used in a while loop, reading $maxlength bytes on every call.
957 $maxlength defaults to the size of the request if not specified.
958 You have to set "MyApp->config(parse_on_demand => 1)" to use this
960 directly.
961 Warning: If you use read(), Catalyst will not process the body, so you
963 will not be able to access POST parameters or file uploads via
964 $c->request. You must handle all body parsing yourself.
965 $c->run
967 Starts the engine.
968 $c->set_action( $action, $code, $namespace, $attrs )
970 Sets an action in a given namespace.
971 $c->setup_actions($component)
973 Sets up actions for a component.
974 $c->setup_components
976 This method is called internally to set up the application's
977 components.
978 It finds modules by calling the locate_components method, expands them
980 to package names with the expand_component_module method, and then
981 installs each component into the application.
982 The "setup_components" config option is passed to both of the above
984 methods.
985 Installation of each component is performed by the setup_component
987 method, below.
988 $app->setup_injected_components
990 Called by setup_compoents to setup components that are injected.
991 $app->setup_injected_component( $injected_component_name, $config )
993 Setup a given injected component.
994 $app->inject_component($MyApp_Component_name => \%args);
996 Add a component that is injected at setup:
997 MyApp->inject_component( 'Model::Foo' => { from_component => 'Common::Foo' } );
999 Must be called before ->setup. Expects a component name for your
1001 current application and \%args where
1002 from_component
1004 The target component being injected into your application
1005 roles
1007 An arrayref of Moose::Roles that are applied to your component.
1008 Example
1010 MyApp->inject_component(
1012 'Model::Foo' => {
1013 from_component => 'Common::Model::Foo',
1014 roles => ['Role1', 'Role2'],
1015 });
1016 $app->inject_components
1018 Inject a list of components:
1019 MyApp->inject_components(
1021 'Model::FooOne' => {
1022 from_component => 'Common::Model::Foo',
1023 roles => ['Role1', 'Role2'],
1024 },
1025 'Model::FooTwo' => {
1026 from_component => 'Common::Model::Foo',
1027 roles => ['Role1', 'Role2'],
1028 });
1029 $c->locate_components( $setup_component_config )
1031 This method is meant to provide a list of component modules that should
1032 be setup for the application. By default, it will use
1033 Module::Pluggable.
1034 Specify a "setup_components" config option to pass additional options
1036 directly to Module::Pluggable. To add additional search paths, specify
1037 a key named "search_extra" as an array reference. Items in the array
1038 beginning with "::" will have the application class name prepended to
1039 them.
1040 $c->expand_component_module( $component, $setup_component_config )
1042 Components found by "locate_components" will be passed to this method,
1043 which is expected to return a list of component (package) names to be
1044 set up.
1045 $app->delayed_setup_component
1047 Returns a coderef that points to a setup_component instance. Used
1048 internally for when you want to delay setup until the first time the
1049 component is called.
1050 $c->setup_component
1052 $app->config_for( $component_name )
1053 Return the application level configuration (which is not yet merged
1054 with any local component configuration, via $component_class->config)
1055 for the named component or component object. Example:
1056 MyApp->config(
1058 'Model::Foo' => { a => 1, b => 2},
1059 );
1060 my $config = MyApp->config_for('MyApp::Model::Foo');
1062 In this case $config is the hashref "{a=>1, b=>2}".
1064 This is also handy for looking up configuration for a plugin, to make
1066 sure you follow existing Catalyst standards for where a plugin should
1067 put its configuration.
1068 $c->setup_dispatcher
1070 Sets up dispatcher.
1071 $c->setup_engine
1073 Sets up engine.
1074 $c->apply_default_middlewares
1076 Adds the following Plack middlewares to your application, since they
1077 are useful and commonly needed:
1078 Plack::Middleware::LighttpdScriptNameFix (if you are using Lighttpd),
1080 Plack::Middleware::IIS6ScriptNameFix (always applied since this
1081 middleware is smart enough to conditionally apply itself).
1082 We will also automatically add Plack::Middleware::ReverseProxy if we
1084 notice that your HTTP $env variable "REMOTE_ADDR" is '127.0.0.1'. This
1085 is usually an indication that your server is running behind a proxy
1086 frontend. However in 2014 this is often not the case. We preserve
1087 this code for backwards compatibility however I highly recommend that
1088 if you are running the server behind a front end proxy that you clearly
1089 indicate so with the "using_frontend_proxy" configuration setting to
1090 true for your environment configurations that run behind a proxy. This
1091 way if you change your front end proxy address someday your code would
1092 inexplicably stop working as expected.
1093 Additionally if we detect we are using Nginx, we add a bit of custom
1095 middleware to solve some problems with the way that server handles
1096 $ENV{PATH_INFO} and $ENV{SCRIPT_NAME}.
1097 Please NOTE that if you do use "using_frontend_proxy" the middleware is
1099 now adding via "registered_middleware" rather than this method.
1100 If you are using Lighttpd or IIS6 you may wish to apply these
1102 middlewares. In general this is no longer a common case but we have
1103 this here for backward compatibility.
1104 App->psgi_app
1106 App->to_app
1107 Returns a PSGI application code reference for the catalyst application
1108 $c. This is the bare application created without the
1109 "apply_default_middlewares" method called. We do however apply
1110 "registered_middleware" since those are integral to how Catalyst
1111 functions. Also, unlike starting your application with a generated
1112 server script (via Catalyst::Devel and "catalyst.pl") we do not attempt
1113 to return a valid PSGI application using any existing "${myapp}.psgi"
1114 scripts in your $HOME directory.
1115 NOTE "apply_default_middlewares" was originally created when the first
1117 PSGI port was done for v5.90000. These are middlewares that are added
1118 to achieve backward compatibility with older applications. If you
1119 start your application using one of the supplied server scripts
1120 (generated with Catalyst::Devel and the project skeleton script
1121 "catalyst.pl") we apply "apply_default_middlewares" automatically.
1122 This was done so that pre and post PSGI port applications would work
1123 the same way.
1124 This is what you want to be using to retrieve the PSGI application code
1126 reference of your Catalyst application for use in a custom .psgi or in
1127 your own created server modules.
1128 $c->setup_home
1130 Sets up the home directory.
1131 $c->setup_encoding
1133 Sets up the input/output encoding. See ENCODING
1134 handle_unicode_encoding_exception
1136 Hook to let you customize how encoding errors are handled. By default
1137 we just throw an exception and the default error page will pick it up.
1138 Receives a hashref of debug information. Example of call (from the
1139 Catalyst internals):
1140 my $decoded_after_fail = $c->handle_unicode_encoding_exception({
1142 param_value => $value,
1143 error_msg => $_,
1144 encoding_step => 'params',
1145 });
1146 The calling code expects to receive a decoded string or an exception.
1148 You can override this for custom handling of unicode errors. By default
1150 we just die. If you want a custom response here, one approach is to
1151 throw an HTTP style exception, instead of returning a decoded string or
1152 throwing a generic exception.
1153 sub handle_unicode_encoding_exception {
1155 my ($c, $params) = @_;
1156 HTTP::Exception::BAD_REQUEST->throw(status_message=>$params->{error_msg});
1157 }
1158 Alternatively you can 'catch' the error, stash it and write handling
1160 code later in your application:
1161 sub handle_unicode_encoding_exception {
1163 my ($c, $params) = @_;
1164 $c->stash(BAD_UNICODE_DATA=>$params);
1165 # return a dummy string.
1166 return 1;
1167 }
1168 <B>NOTE:</b> Please keep in mind that once an error like this occurs,
1170 the request setup is still ongoing, which means the state of $c and
1171 related context parts like the request and response may not be setup up
1172 correctly (since we haven't finished the setup yet). If you throw an
1173 exception the setup is aborted.
1174 $c->setup_log
1176 Sets up log by instantiating a Catalyst::Log object and passing it to
1177 "log()". Pass in a comma-delimited list of levels to set the log to.
1178 This method also installs a "debug" method that returns a true value
1180 into the catalyst subclass if the "debug" level is passed in the comma-
1181 delimited list, or if the $CATALYST_DEBUG environment variable is set
1182 to a true value.
1183 Note that if the log has already been setup, by either a previous call
1185 to "setup_log" or by a call such as "__PACKAGE__->log( MyLogger->new
1186 )", that this method won't actually set up the log object.
1187 $c->setup_plugins
1189 Sets up plugins.
1190 $c->setup_stats
1192 Sets up timing statistics class.
1193 $c->registered_plugins
1195 Returns a sorted list of the plugins which have either been stated in
1196 the import list.
1197 If passed a given plugin name, it will report a boolean value
1199 indicating whether or not that plugin is loaded. A fully qualified
1200 name is required if the plugin name does not begin with
1201 "Catalyst::Plugin::".
1202 if ($c->registered_plugins('Some::Plugin')) {
1204 ...
1205 }
1206 default_middleware
1208 Returns a list of instantiated PSGI middleware objects which is the
1209 default middleware that is active for this application (taking any
1210 configuration options into account, excluding your custom added
1211 middleware via the "psgi_middleware" configuration option). You can
1212 override this method if you wish to change the default middleware
1213 (although do so at risk since some middleware is vital to application
1214 function.)
1215 The current default middleware list is:
1217 Catalyst::Middleware::Stash
1219 Plack::Middleware::HTTPExceptions
1220 Plack::Middleware::RemoveRedundantBody
1221 Plack::Middleware::FixMissingBodyInRedirect
1222 Plack::Middleware::ContentLength
1223 Plack::Middleware::MethodOverride
1224 Plack::Middleware::Head
1225 If the configuration setting "using_frontend_proxy" is true we add:
1227 Plack::Middleware::ReverseProxy
1229 If the configuration setting "using_frontend_proxy_path" is true we
1231 add:
1232 Plack::Middleware::ReverseProxyPath
1234 But NOTE that Plack::Middleware::ReverseProxyPath is not a dependency
1236 of the Catalyst distribution so if you want to use this option you
1237 should add it to your project distribution file.
1238 These middlewares will be added at "setup_middleware" during the
1240 "setup" phase of application startup.
1241 registered_middlewares
1243 Read only accessor that returns an array of all the middleware in the
1244 order that they were added (which is the REVERSE of the order they will
1245 be applied).
1246 The values returned will be either instances of Plack::Middleware or of
1248 a compatible interface, or a coderef, which is assumed to be inlined
1249 middleware
1250 setup_middleware (?@middleware)
1252 Read configuration information stored in configuration key
1253 "psgi_middleware" or from passed @args.
1254 See under "CONFIGURATION" information regarding "psgi_middleware" and
1256 how to use it to enable Plack::Middleware
1257 This method is automatically called during 'setup' of your application,
1259 so you really don't need to invoke it. However you may do so if you
1260 find the idea of loading middleware via configuration weird :). For
1261 example:
1262 package MyApp;
1264 use Catalyst;
1266 __PACKAGE__->setup_middleware('Head');
1268 __PACKAGE__->setup;
1269 When we read middleware definitions from configuration, we reverse the
1271 list which sounds odd but is likely how you expect it to work if you
1272 have prior experience with Plack::Builder or if you previously used the
1273 plugin Catalyst::Plugin::EnableMiddleware (which is now considered
1274 deprecated)
1275 So basically your middleware handles an incoming request from the first
1277 registered middleware, down and handles the response from the last
1278 middleware up.
1279 registered_data_handlers
1281 A read only copy of registered Data Handlers returned as a Hash, where
1282 each key is a content type and each value is a subref that attempts to
1283 decode that content type.
1284 setup_data_handlers (?@data_handler)
1286 Read configuration information stored in configuration key
1287 "data_handlers" or from passed @args.
1288 See under "CONFIGURATION" information regarding "data_handlers".
1290 This method is automatically called during 'setup' of your application,
1292 so you really don't need to invoke it.
1293 default_data_handlers
1295 Default Data Handlers that come bundled with Catalyst. Currently there
1296 are only two default data handlers, for 'application/json' and an
1297 alternative to 'application/x-www-form-urlencoded' which supposed
1298 nested form parameters via CGI::Struct or via CGI::Struct::XS IF you've
1299 installed it.
1300 The 'application/json' data handler is used to parse incoming JSON into
1302 a Perl data structure. It uses JSON::MaybeXS. This allows you to fail
1303 back to JSON::PP, which is a Pure Perl JSON decoder, and has the
1304 smallest dependency impact.
1305 Because we don't wish to add more dependencies to Catalyst, if you wish
1307 to use this new feature we recommend installing Cpanel::JSON::XS in
1308 order to get the best performance. You should add either to your
1309 dependency list (Makefile.PL, dist.ini, cpanfile, etc.)
1310 $c->stack
1312 Returns an arrayref of the internal execution stack (actions that are
1313 currently executing).
1314 $c->stats
1316 Returns the current timing statistics object. By default Catalyst uses
1317 Catalyst::Stats, but can be set otherwise with stats_class.
1318 Even if -Stats is not enabled, the stats object is still available. By
1320 enabling it with "$c->stats->enabled(1)", it can be used to profile
1321 explicitly, although MyApp.pm still won't profile nor output anything
1322 by itself.
1323 $c->stats_class
1325 Returns or sets the stats (timing statistics) class. Catalyst::Stats is
1326 used by default.
1327 $app->stats_class_traits
1329 A arrayref of Moose::Roles that are applied to the stats_class before
1330 creating it.
1331 $app->composed_stats_class
1333 this is the stats_class composed with any 'stats_class_traits'. You
1334 can name the full namespace of the role, or a namespace suffix, which
1335 will then be tried against the following standard namespace prefixes.
1336 $MyApp::TraitFor::Stats::$trait_suffix
1338 Catalyst::TraitFor::Stats::$trait_suffix
1339 So for example if you set:
1341 MyApp->stats_class_traits(['Foo']);
1343 We try each possible role in turn (and throw an error if none load)
1345 Foo
1347 MyApp::TraitFor::Stats::Foo
1348 Catalyst::TraitFor::Stats::Foo
1349 The namespace part 'TraitFor::Stats' was chosen to assist in backwards
1351 compatibility with CatalystX::RoleApplicator which previously provided
1352 these features in a stand alone package.
1353 $c->use_stats
1355 Returns 1 when stats collection is enabled.
1356 Note that this is a static method, not an accessor and should be
1358 overridden by declaring "sub use_stats { 1 }" in your MyApp.pm, not by
1359 calling "$c->use_stats(1)".
1360 $c->write( $data )
1362 Writes $data to the output stream. When using this method directly, you
1363 will need to manually set the "Content-Length" header to the length of
1364 your output data, if known.
1365 version
1367 Returns the Catalyst version number. Mostly useful for "powered by"
1368 messages in template systems.
1369
1371 There are a number of 'base' config variables which can be set:
1372 • "always_catch_http_exceptions" - As of version 5.90060 Catalyst
1374 rethrows errors conforming to the interface described by
1375 Plack::Middleware::HTTPExceptions and lets the middleware deal with
1376 it. Set true to get the deprecated behaviour and have Catalyst
1377 catch HTTP exceptions.
1378 • "default_model" - The default model picked if you say "$c->model".
1380 See "$c->model($name)".
1381 • "default_view" - The default view to be rendered or returned when
1383 "$c->view" is called. See "$c->view($name)".
1384 • "disable_component_resolution_regex_fallback" - Turns off the
1386 deprecated component resolution functionality so that if any of the
1387 component methods (e.g. "$c->controller('Foo')") are called then
1388 regex search will not be attempted on string values and instead
1389 "undef" will be returned.
1390 • "home" - The application home directory. In an uninstalled
1392 application, this is the top level application directory. In an
1393 installed application, this will be the directory containing
1394 "MyApp.pm".
1395 • "ignore_frontend_proxy" - See "PROXY SUPPORT"
1397 • "name" - The name of the application in debug messages and the
1399 debug and welcome screens
1400 • "parse_on_demand" - The request body (for example file uploads)
1402 will not be parsed until it is accessed. This allows you to (for
1403 example) check authentication (and reject the upload) before
1404 actually receiving all the data. See "ON-DEMAND PARSER"
1405 • "root" - The root directory for templates. Usually this is just a
1407 subdirectory of the home directory, but you can set it to change
1408 the templates to a different directory.
1409 • "search_extra" - Array reference passed to Module::Pluggable to for
1411 additional namespaces from which components will be loaded (and
1412 constructed and stored in "$c->components").
1413 • "show_internal_actions" - If true, causes internal actions such as
1415 "_DISPATCH" to be shown in hit debug tables in the test server.
1416 • "use_request_uri_for_path" - Controls if the "REQUEST_URI" or
1418 "PATH_INFO" environment variable should be used for determining the
1419 request path.
1420 Most web server environments pass the requested path to the
1422 application using environment variables, from which Catalyst has to
1423 reconstruct the request base (i.e. the top level path to / in the
1424 application, exposed as "$c->request->base") and the request path
1425 below that base.
1426 There are two methods of doing this, both of which have advantages
1428 and disadvantages. Which method is used is determined by the
1429 "$c->config(use_request_uri_for_path)" setting (which can either be
1430 true or false).
1431 use_request_uri_for_path => 0
1433 This is the default (and the) traditional method that Catalyst
1434 has used for determining the path information. The path is
1435 generated from a combination of the "PATH_INFO" and
1436 "SCRIPT_NAME" environment variables. The allows the
1437 application to behave correctly when "mod_rewrite" is being
1438 used to redirect requests into the application, as these
1439 variables are adjusted by mod_rewrite to take account for the
1440 redirect.
1441 However this method has the major disadvantage that it is
1443 impossible to correctly decode some elements of the path, as
1444 RFC 3875 says: ""Unlike a URI path, the PATH_INFO is not
1445 URL-encoded, and cannot contain path-segment parameters."" This
1446 means PATH_INFO is always decoded, and therefore Catalyst can't
1447 distinguish / vs %2F in paths (in addition to other encoded
1448 values).
1449 use_request_uri_for_path => 1
1451 This method uses the "REQUEST_URI" and "SCRIPT_NAME"
1452 environment variables. As "REQUEST_URI" is never decoded, this
1453 means that applications using this mode can correctly handle
1454 URIs including the %2F character (i.e. with
1455 "AllowEncodedSlashes" set to "On" in Apache).
1456 Given that this method of path resolution is provably more
1458 correct, it is recommended that you use this unless you have a
1459 specific need to deploy your application in a non-standard
1460 environment, and you are aware of the implications of not being
1461 able to handle encoded URI paths correctly.
1462 However it also means that in a number of cases when the app
1464 isn't installed directly at a path, but instead is having paths
1465 rewritten into it (e.g. as a .cgi/fcgi in a public_html
1466 directory, with mod_rewrite in a .htaccess file, or when SSI is
1467 used to rewrite pages into the app, or when sub-paths of the
1468 app are exposed at other URIs than that which the app is
1469 'normally' based at with "mod_rewrite"), the resolution of
1470 "$c->request->base" will be incorrect.
1471 • "using_frontend_proxy" - See "PROXY SUPPORT".
1473 • "using_frontend_proxy_path" - Enabled
1475 Plack::Middleware::ReverseProxyPath on your application (if
1476 installed, otherwise log an error). This is useful if your
1477 application is not running on the 'root' (or /) of your host
1478 server. NOTE if you use this feature you should add the required
1479 middleware to your project dependency list since its not
1480 automatically a dependency of Catalyst. This has been done since
1481 not all people need this feature and we wish to restrict the growth
1482 of Catalyst dependencies.
1483 • "encoding" - See "ENCODING"
1485 This now defaults to 'UTF-8'. You my turn it off by setting this
1487 configuration value to undef.
1488 • "abort_chain_on_error_fix"
1490 Defaults to true.
1492 When there is an error in an action chain, the default behavior is
1494 to abort the processing of the remaining actions to avoid running
1495 them when the application is in an unexpected state.
1496 Before version 5.90070, the default used to be false. To keep the
1498 old behaviour, you can explicitly set the value to false. E.g.
1499 __PACKAGE__->config(abort_chain_on_error_fix => 0);
1501 If this setting is set to false, then the remaining actions are
1503 performed and the error is caught at the end of the chain.
1504 • "use_hash_multivalue_in_request"
1506 In Catalyst::Request the methods "query_parameters",
1508 "body_parametes" and "parameters" return a hashref where values
1509 might be scalar or an arrayref depending on the incoming data. In
1510 many cases this can be undesirable as it leads one to writing
1511 defensive code like the following:
1512 my ($val) = ref($c->req->parameters->{a}) ?
1514 @{$c->req->parameters->{a}} :
1515 $c->req->parameters->{a};
1516 Setting this configuration item to true will make Catalyst populate
1518 the attributes underlying these methods with an instance of
1519 Hash::MultiValue which is used by Plack::Request and others to
1520 solve this very issue. You may prefer this behavior to the
1521 default, if so enable this option (be warned if you enable it in a
1522 legacy application we are not sure if it is completely backwardly
1523 compatible).
1524 • "skip_complex_post_part_handling"
1526 When creating body parameters from a POST, if we run into a
1528 multipart POST that does not contain uploads, but instead contains
1529 inlined complex data (very uncommon) we cannot reliably convert
1530 that into field => value pairs. So instead we create an instance
1531 of Catalyst::Request::PartData. If this causes issue for you, you
1532 can disable this by setting "skip_complex_post_part_handling" to
1533 true (default is false).
1534 • "skip_body_param_unicode_decoding"
1536 Generally we decode incoming POST params based on your declared
1538 encoding (the default for this is to decode UTF-8). If this is
1539 causing you trouble and you do not wish to turn all encoding
1540 support off (with the "encoding" configuration parameter) you may
1541 disable this step atomically by setting this configuration
1542 parameter to true.
1543 • "do_not_decode_query"
1545 If true, then do not try to character decode any wide characters in
1547 your request URL query or keywords. Most readings of the relevant
1548 specifications suggest these should be UTF-* encoded, which is the
1549 default that Catalyst will use, however if you are creating a lot
1550 of URLs manually or have external evil clients, this might cause
1551 you trouble. If you find the changes introduced in Catalyst
1552 version 5.90080+ break some of your query code, you may disable the
1553 UTF-8 decoding globally using this configuration.
1554 This setting takes precedence over "default_query_encoding"
1556 • "do_not_check_query_encoding"
1558 Catalyst versions 5.90080 - 5.90106 would decode query parts of an
1560 incoming request but would not raise an exception when the decoding
1561 failed due to incorrect unicode. It now does, but if this change
1562 is giving you trouble you may disable it by setting this
1563 configuration to true.
1564 • "default_query_encoding"
1566 By default we decode query and keywords in your request URL using
1568 UTF-8, which is our reading of the relevant specifications. This
1569 setting allows one to specify a fixed value for how to decode your
1570 query. You might need this if you are doing a lot of custom
1571 encoding of your URLs and not using UTF-8.
1572 • "use_chained_args_0_special_case"
1574 In older versions of Catalyst, when more than one action matched
1576 the same path AND all those matching actions declared Args(0), we'd
1577 break the tie by choosing the first action defined. We now
1578 normalized how Args(0) works so that it follows the same rule as
1579 Args(N), which is to say when we need to break a tie we choose the
1580 LAST action defined. If this breaks your code and you don't have
1581 time to update to follow the new normalized approach, you may set
1582 this value to true and it will globally revert to the original
1583 chaining behavior.
1584 • "psgi_middleware" - See "PSGI MIDDLEWARE".
1586 • "data_handlers" - See "DATA HANDLERS".
1588 • "stats_class_traits"
1590 An arrayref of Moose::Roles that get composed into your stats
1592 class.
1593 • "request_class_traits"
1595 An arrayref of Moose::Roles that get composed into your request
1597 class.
1598 • "response_class_traits"
1600 An arrayref of Moose::Roles that get composed into your response
1602 class.
1603 • "inject_components"
1605 A Hashref of Catalyst::Component subclasses that are 'injected'
1607 into configuration. For example:
1608 MyApp->config({
1610 inject_components => {
1611 'Controller::Err' => { from_component => 'Local::Controller::Errors' },
1612 'Model::Zoo' => { from_component => 'Local::Model::Foo' },
1613 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] },
1614 },
1615 'Controller::Err' => { a => 100, b=>200, namespace=>'error' },
1616 'Model::Zoo' => { a => 2 },
1617 'Model::Foo' => { a => 100 },
1618 });
1619 Generally Catalyst looks for components in your Model/View or
1621 Controller directories. However for cases when you which to use an
1622 existing component and you don't need any customization (where for
1623 when you can apply a role to customize it) you may inject those
1624 components into your application. Please note any configuration
1625 should be done 'in the normal way', with a key under configuration
1626 named after the component affix, as in the above example.
1627 Using this type of injection allows you to construct significant
1629 amounts of your application with only configuration!. This may or
1630 may not lead to increased code understanding.
1631 Please not you may also call the ->inject_components application
1633 method as well, although you must do so BEFORE setup.
1634
1636 Generally when you throw an exception inside an Action (or somewhere in
1637 your stack, such as in a model that an Action is calling) that
1638 exception is caught by Catalyst and unless you either catch it yourself
1639 (via eval or something like Try::Tiny or by reviewing the "error"
1640 stack, it will eventually reach "finalize_errors" and return either the
1641 debugging error stack page, or the default error page. However, if
1642 your exception can be caught by Plack::Middleware::HTTPExceptions,
1643 Catalyst will instead rethrow it so that it can be handled by that
1644 middleware (which is part of the default middleware). For example this
1645 would allow
1646 use HTTP::Throwable::Factory 'http_throw';
1648 sub throws_exception :Local {
1650 my ($self, $c) = @_;
1651 http_throw(SeeOther => { location =>
1653 $c->uri_for($self->action_for('redirect')) });
1654 }
1656
1658 Catalyst uses internal actions like "_DISPATCH", "_BEGIN", "_AUTO",
1659 "_ACTION", and "_END". These are by default not shown in the private
1660 action table, but you can make them visible with a config parameter.
1661 MyApp->config(show_internal_actions => 1);
1663
1665 The request body is usually parsed at the beginning of a request, but
1666 if you want to handle input yourself, you can enable on-demand parsing
1667 with a config parameter.
1668 MyApp->config(parse_on_demand => 1);
1670
1672 Many production servers operate using the common double-server
1673 approach, with a lightweight frontend web server passing requests to a
1674 larger backend server. An application running on the backend server
1675 must deal with two problems: the remote user always appears to be
1676 127.0.0.1 and the server's hostname will appear to be "localhost"
1677 regardless of the virtual host that the user connected through.
1678 Catalyst will automatically detect this situation when you are running
1680 the frontend and backend servers on the same machine. The following
1681 changes are made to the request.
1682 $c->req->address is set to the user's real IP address, as read from
1684 the HTTP X-Forwarded-For header.
1685 The host value for $c->req->base and $c->req->uri is set to the real
1687 host, as read from the HTTP X-Forwarded-Host header.
1688 Additionally, you may be running your backend application on an
1690 insecure connection (port 80) while your frontend proxy is running
1691 under SSL. If there is a discrepancy in the ports, use the HTTP header
1692 "X-Forwarded-Port" to tell Catalyst what port the frontend listens on.
1693 This will allow all URIs to be created properly.
1694 In the case of passing in:
1696 X-Forwarded-Port: 443
1698 All calls to "uri_for" will result in an https link, as is expected.
1700 Obviously, your web server must support these headers for this to work.
1702 In a more complex server farm environment where you may have your
1704 frontend proxy server(s) on different machines, you will need to set a
1705 configuration option to tell Catalyst to read the proxied data from the
1706 headers.
1707 MyApp->config(using_frontend_proxy => 1);
1709 If you do not wish to use the proxy support at all, you may set:
1711 MyApp->config(ignore_frontend_proxy => 0);
1713 Note about psgi files
1715 Note that if you supply your own .psgi file, calling
1716 "MyApp->psgi_app(@_);", then this will not happen automatically.
1717 You either need to apply Plack::Middleware::ReverseProxy yourself in
1719 your psgi, for example:
1720 builder {
1722 enable "Plack::Middleware::ReverseProxy";
1723 MyApp->psgi_app
1724 };
1725 This will unconditionally add the ReverseProxy support, or you need to
1727 call "$app = MyApp->apply_default_middlewares($app)" (to conditionally
1728 apply the support depending upon your config).
1729 See Catalyst::PSGI for more information.
1731
1733 Catalyst has been tested under Apache 2's threading "mpm_worker",
1734 "mpm_winnt", and the standalone forking HTTP server on Windows. We
1735 believe the Catalyst core to be thread-safe.
1736 If you plan to operate in a threaded environment, remember that all
1738 other modules you are using must also be thread-safe. Some modules,
1739 most notably DBD::SQLite, are not thread-safe.
1740
1742 The Catalyst::Request object uses HTTP::Body to populate 'classic' HTML
1743 form parameters and URL search query fields. However it has become
1744 common for various alternative content types to be PUT or POSTed to
1745 your controllers and actions. People working on RESTful APIs, or using
1746 AJAX often use JSON, XML and other content types when communicating
1747 with an application server. In order to better support this use case,
1748 Catalyst defines a global configuration option, "data_handlers", which
1749 lets you associate a content type with a coderef that parses that
1750 content type into something Perl can readily access.
1751 package MyApp::Web;
1753 use Catalyst;
1755 use JSON::MaybeXS;
1756 __PACKAGE__->config(
1758 data_handlers => {
1759 'application/json' => sub { local $/; decode_json $_->getline },
1760 },
1761 ## Any other configuration.
1762 );
1763 __PACKAGE__->setup;
1765 By default Catalyst comes with a generic JSON data handler similar to
1767 the example given above, which uses JSON::MaybeXS to provide either
1768 JSON::PP (a pure Perl, dependency free JSON parser) or Cpanel::JSON::XS
1769 if you have it installed (if you want the faster XS parser, add it to
1770 you project Makefile.PL or dist.ini, cpanfile, etc.)
1771 The "data_handlers" configuration is a hashref whose keys are HTTP
1773 Content-Types (matched against the incoming request type using a regexp
1774 such as to be case insensitive) and whose values are coderefs that
1775 receive a localized version of $_ which is a filehandle object pointing
1776 to received body.
1777 This feature is considered an early access release and we reserve the
1779 right to alter the interface in order to provide a performant and
1780 secure solution to alternative request body content. Your reports
1781 welcomed!
1782
1784 You can define middleware, defined as Plack::Middleware or a compatible
1785 interface in configuration. Your middleware definitions are in the
1786 form of an arrayref under the configuration key "psgi_middleware".
1787 Here's an example with details to follow:
1788 package MyApp::Web;
1790 use Catalyst;
1792 use Plack::Middleware::StackTrace;
1793 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1795 __PACKAGE__->config(
1797 'psgi_middleware', [
1798 'Debug',
1799 '+MyApp::Custom',
1800 $stacktrace_middleware,
1801 'Session' => {store => 'File'},
1802 sub {
1803 my $app = shift;
1804 return sub {
1805 my $env = shift;
1806 $env->{myapp.customkey} = 'helloworld';
1807 $app->($env);
1808 },
1809 },
1810 ],
1811 );
1812 __PACKAGE__->setup;
1814 So the general form is:
1816 __PACKAGE__->config(psgi_middleware => \@middleware_definitions);
1818 Where @middleware is one or more of the following, applied in the
1820 REVERSE of the order listed (to make it function similarly to
1821 Plack::Builder:
1822 Alternatively, you may also define middleware by calling the
1824 "setup_middleware" package method:
1825 package MyApp::Web;
1827 use Catalyst;
1829 __PACKAGE__->setup_middleware( \@middleware_definitions);
1831 __PACKAGE__->setup;
1832 In the case where you do both (use 'setup_middleware' and
1834 configuration) the package call to setup_middleware will be applied
1835 earlier (in other words its middleware will wrap closer to the
1836 application). Keep this in mind since in some cases the order of
1837 middleware is important.
1838 The two approaches are not exclusive.
1840 Middleware Object
1842 An already initialized object that conforms to the
1843 Plack::Middleware specification:
1844 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1846 __PACKAGE__->config(
1848 'psgi_middleware', [
1849 $stacktrace_middleware,
1850 ]);
1851 coderef
1853 A coderef that is an inlined middleware:
1854 __PACKAGE__->config(
1856 'psgi_middleware', [
1857 sub {
1858 my $app = shift;
1859 return sub {
1860 my $env = shift;
1861 if($env->{PATH_INFO} =~m/forced/) {
1862 Plack::App::File
1863 ->new(file=>TestApp->path_to(qw/share static forced.txt/))
1864 ->call($env);
1865 } else {
1866 return $app->($env);
1867 }
1868 },
1869 },
1870 ]);
1871 a scalar
1873 We assume the scalar refers to a namespace after normalizing it
1874 using the following rules:
1875 (1) If the scalar is prefixed with a "+" (as in "+MyApp::Foo") then
1877 the full string is assumed to be 'as is', and we just install and
1878 use the middleware.
1879 (2) If the scalar begins with "Plack::Middleware" or your
1881 application namespace (the package name of your Catalyst
1882 application subclass), we also assume then that it is a full
1883 namespace, and use it.
1884 (3) Lastly, we then assume that the scalar is a partial namespace,
1886 and attempt to resolve it first by looking for it under your
1887 application namespace (for example if you application is
1888 "MyApp::Web" and the scalar is "MyMiddleware", we'd look under
1889 "MyApp::Web::Middleware::MyMiddleware") and if we don't find it
1890 there, we will then look under the regular Plack::Middleware
1891 namespace (i.e. for the previous we'd try
1892 "Plack::Middleware::MyMiddleware"). We look under your application
1893 namespace first to let you 'override' common Plack::Middleware
1894 locally, should you find that a good idea.
1895 Examples:
1897 package MyApp::Web;
1899 __PACKAGE__->config(
1901 'psgi_middleware', [
1902 'Debug', ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap
1903 'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap
1904 '+MyApp::Custom', ## MyApp::Custom->wrap
1905 ],
1906 );
1907 a scalar followed by a hashref
1909 Just like the previous, except the following "HashRef" is used as
1910 arguments to initialize the middleware object.
1911 __PACKAGE__->config(
1913 'psgi_middleware', [
1914 'Session' => {store => 'File'},
1915 ]);
1916 Please see PSGI for more on middleware.
1918
1920 Starting in Catalyst version 5.90080 encoding is automatically enabled
1921 and set to encode all body responses to UTF8 when possible and
1922 applicable. Following is documentation on this process. If you are
1923 using an older version of Catalyst you should review documentation for
1924 that version since a lot has changed.
1925 By default encoding is now 'UTF-8'. You may turn it off by setting the
1927 encoding configuration to undef.
1928 MyApp->config(encoding => undef);
1930 This is recommended for temporary backwards compatibility only.
1932 To turn it off for a single request use the clear_encoding method to
1934 turn off encoding for this request. This can be useful when you are
1935 setting the body to be an arbitrary block of bytes, especially if that
1936 block happens to be a block of UTF8 text.
1937 Encoding is automatically applied when the content-type is set to a
1939 type that can be encoded. Currently we encode when the content type
1940 matches the following regular expression:
1941 $content_type =~ /^text|xml$|javascript$/
1943 Encoding is set on the application, but it is copied to the context
1945 object so that you can override it on a request basis.
1946 Be default we don't automatically encode 'application/json' since the
1948 most common approaches to generating this type of response (Either via
1949 Catalyst::View::JSON or Catalyst::Action::REST) will do so already and
1950 we want to avoid double encoding issues.
1951 If you are producing JSON response in an unconventional manner (such as
1953 via a template or manual strings) you should perform the UTF8 encoding
1954 manually as well such as to conform to the JSON specification.
1955 NOTE: We also examine the value of $c->response->content_encoding. If
1957 you set this (like for example 'gzip', and manually gzipping the body)
1958 we assume that you have done all the necessary encoding yourself, since
1959 we cannot encode the gzipped contents. If you use a plugin like
1960 Catalyst::Plugin::Compress you need to update to a modern version in
1961 order to have this function correctly with the new UTF8 encoding code,
1962 or you can use Plack::Middleware::Deflater or (probably best) do your
1963 compression on a front end proxy.
1964 Methods
1966 encoding
1967 Returns an instance of an "Encode" encoding
1968 print $c->encoding->name
1970 handle_unicode_encoding_exception ($exception_context)
1972 Method called when decoding process for a request fails.
1973 An $exception_context hashref is provided to allow you to override
1975 the behaviour of your application when given data with incorrect
1976 encodings.
1977 The default method throws exceptions in the case of invalid request
1979 parameters (resulting in a 500 error), but ignores errors in upload
1980 filenames.
1981 The keys passed in the $exception_context hash are:
1983 param_value
1985 The value which was not able to be decoded.
1986 error_msg
1988 The exception received from Encode.
1989 encoding_step
1991 What type of data was being decoded. Valid values are
1992 (currently) "params" - for request parameters / arguments /
1993 captures and "uploads" - for request upload filenames.
1994
1996 IRC:
1997 Join #catalyst on irc.perl.org.
1999 Mailing Lists:
2001 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
2003 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
2004 Web:
2006 http://catalyst.perl.org
2008 Wiki:
2010 http://dev.catalyst.perl.org
2012
2014 Task::Catalyst - All you need to start with Catalyst
2015 Catalyst::Manual - The Catalyst Manual
2016 Catalyst::Component, Catalyst::Controller - Base classes for components
2017 Catalyst::Engine - Core engine
2018 Catalyst::Log - Log class.
2019 Catalyst::Request - Request object
2020 Catalyst::Response - Response object
2021 Catalyst::Test - The test suite.
2023 sri: Sebastian Riedel <sri@cpan.org>
2024
2026 abw: Andy Wardley
2027 acme: Leon Brocard <leon@astray.com>
2029 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
2031 andrewalker: André Walker <andre@cpan.org>
2033 Andrew Bramble
2035 Andrew Ford <A.Ford@ford-mason.co.uk>
2037 Andrew Ruthven
2039 andyg: Andy Grundman <andy@hybridized.org>
2041 audreyt: Audrey Tang
2043 bricas: Brian Cassidy <bricas@cpan.org>
2045 Caelum: Rafael Kitover <rkitover@io.com>
2047 chansen: Christian Hansen
2049 Chase Venters <chase.venters@gmail.com>
2051 chicks: Christopher Hicks
2053 Chisel Wright <pause@herlpacker.co.uk>
2055 Danijel Milicevic <me@danijel.de>
2057 davewood: David Schmidt <davewood@cpan.org>
2059 David Kamholz <dkamholz@cpan.org>
2061 David Naughton <naughton@umn.edu>
2063 David E. Wheeler
2065 dhoss: Devin Austin <dhoss@cpan.org>
2067 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
2069 Drew Taylor
2071 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
2073 esskar: Sascha Kiefer
2075 fireartist: Carl Franks <cfranks@cpan.org>
2077 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
2079 gabb: Danijel Milicevic
2081 Gary Ashton Jones
2083 Gavin Henry <ghenry@perl.me.uk>
2085 Geoff Richards
2087 groditi: Guillermo Roditi <groditi@gmail.com>
2089 hobbs: Andrew Rodland <andrew@cleverdomain.org>
2091 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
2093 jcamacho: Juan Camacho
2095 jester: Jesse Sheidlower <jester@panix.com>
2097 jhannah: Jay Hannah <jay@jays.net>
2099 Jody Belka
2101 Johan Lindstrom
2103 jon: Jon Schutz <jjschutz@cpan.org>
2105 Jonathan Rockway <jrockway@cpan.org>
2107 Kieren Diment <kd@totaldatasolution.com>
2109 konobi: Scott McWhirter <konobi@cpan.org>
2111 marcus: Marcus Ramberg <mramberg@cpan.org>
2113 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
2115 mgrimes: Mark Grimes <mgrimes@cpan.org>
2117 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
2119 mugwump: Sam Vilain
2121 naughton: David Naughton
2123 ningu: David Kamholz <dkamholz@cpan.org>
2125 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
2127 numa: Dan Sully <daniel@cpan.org>
2129 obra: Jesse Vincent
2131 Octavian Rasnita
2133 omega: Andreas Marienborg
2135 Oleg Kostyuk <cub.uanic@gmail.com>
2137 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
2139 rafl: Florian Ragwitz <rafl@debian.org>
2141 random: Roland Lammel <lammel@cpan.org>
2143 revmischa: Mischa Spiegelmock <revmischa@cpan.org>
2145 Robert Sedlacek <rs@474.at>
2147 rrwo: Robert Rothenberg <rrwo@cpan.org>
2149 SpiceMan: Marcel Montes
2151 sky: Arthur Bergman
2153 szbalint: Balint Szilakszi <szbalint@cpan.org>
2155 t0m: Tomas Doran <bobtfish@bobtfish.net>
2157 Ulf Edvinsson
2159 vanstyn: Henry Van Styn <vanstyn@cpan.org>
2161 Viljo Marrandi <vilts@yahoo.com>
2163 Will Hawes <info@whawes.co.uk>
2165 willert: Sebastian Willert <willert@cpan.org>
2167 wreis: Wallace Reis <wreis@cpan.org>
2169 Yuval Kogman <nothingmuch@woobling.org>
2171 rainboxx: Matthias Dietrich <perl@rainboxx.de>
2173 dd070: Dhaval Dhanani <dhaval070@gmail.com>
2175 Upasana <me@upasana.me>
2177 John Napiorkowski (jnap) <jjnapiork@cpan.org>
2179
2181 Copyright (c) 2005-2015, the above named PROJECT FOUNDER and
2182 CONTRIBUTORS.
2183
2185 This library is free software. You can redistribute it and/or modify it
2186 under the same terms as Perl itself.
2187perl v5.34.0 2021-07-22 Catalyst(3)