3 Catalyst - The Elegant MVC Web Application Framework
7 <a href="https://badge.fury.io/pl/Catalyst-Runtime"><img src="https://badge.fury.io/pl/Catalyst-Runtime.svg" alt="CPAN version" height="18"></a>
8 <a href="https://travis-ci.org/perl-catalyst/catalyst-runtime/"><img src="https://api.travis-ci.org/perl-catalyst/catalyst-runtime.png" alt="Catalyst></a>
9 <a href="http://cpants.cpanauthors.org/dist/Catalyst-Runtime"><img src="http://cpants.cpanauthors.org/dist/Catalyst-Runtime.png" alt='Kwalitee Score' /></a>
14 See the [Catalyst::Manual](https://metacpan.org/pod/Catalyst::Manual) distribution for comprehensive
15 documentation and tutorials.
17 # Install Catalyst::Devel for helpers and other development tools
18 # use the helper to create a new application
21 # add models, views, controllers
22 script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
23 script/myapp_create.pl view MyTemplate TT
24 script/myapp_create.pl controller Search
26 # built in testserver -- use -r to restart automatically on changes
27 # --help to see all available options
28 script/myapp_server.pl
30 # command line testing interface
31 script/myapp_test.pl /yada
34 use Catalyst qw/-Debug/; # include plugins here as well
36 ### In lib/MyApp/Controller/Root.pm (autocreated)
37 sub foo : Chained('/') Args() { # called for /foo, /foo/1, /foo/1/2, etc.
38 my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
39 $c->stash->{template} = 'foo.tt'; # set the template
40 # lookup something from db -- stash vars are passed to TT
42 $c->model('Database::Foo')->search( { country => $args[0] } );
43 if ( $c->req->params->{bar} ) { # access GET or POST parameters
44 $c->forward( 'bar' ); # process another action
45 # do something else after forward returns
49 # The foo.tt TT template can use the stash data from the database
50 [% WHILE (item = data.next) %]
54 # called for /bar/of/soap, /bar/of/soap/10, etc.
55 sub bar : Chained('/') PathPart('/bar/of/soap') Args() { ... }
57 # called after all actions are finished
59 my ( $self, $c ) = @_;
60 if ( scalar @{ $c->error } ) { ... } # handle errors
61 return if $c->res->body; # already have a response
62 $c->forward( 'MyApp::View::TT' ); # render template
65 See [Catalyst::Manual::Intro](https://metacpan.org/pod/Catalyst::Manual::Intro) for additional information.
69 Catalyst is a modern framework for making web applications without the
70 pain usually associated with this process. This document is a reference
71 to the main Catalyst application. If you are a new user, we suggest you
72 start with [Catalyst::Manual::Tutorial](https://metacpan.org/pod/Catalyst::Manual::Tutorial) or [Catalyst::Manual::Intro](https://metacpan.org/pod/Catalyst::Manual::Intro).
74 See [Catalyst::Manual](https://metacpan.org/pod/Catalyst::Manual) for more documentation.
76 Catalyst plugins can be loaded by naming them as arguments to the "use
77 Catalyst" statement. Omit the `Catalyst::Plugin::` prefix from the
78 plugin name, i.e., `Catalyst::Plugin::My::Module` becomes
81 use Catalyst qw/My::Module/;
83 If your plugin starts with a name other than `Catalyst::Plugin::`, you can
84 fully qualify the name by using a unary plus:
88 +Fully::Qualified::Plugin::Name
91 Special flags like `-Debug` can also be specified as
92 arguments when Catalyst is loaded:
94 use Catalyst qw/-Debug My::Module/;
96 The position of plugins and flags in the chain is important, because
97 they are loaded in the order in which they appear.
99 The following flags are supported:
103 Enables debug output. You can also force this setting from the system
104 environment with CATALYST\_DEBUG or <MYAPP>\_DEBUG. The environment
105 settings override the application, with <MYAPP>\_DEBUG having the highest
108 This sets the log level to 'debug' and enables full debug output on the
109 error screen. If you only want the latter, see [$c->debug](https://metacpan.org/pod/$c->debug).
113 Forces Catalyst to use a specific home directory, e.g.:
115 use Catalyst qw[-Home=/usr/mst];
117 This can also be done in the shell environment by setting either the
118 `CATALYST_HOME` environment variable or `MYAPP_HOME`; where `MYAPP`
119 is replaced with the uppercased name of your application, any "::" in
120 the name will be replaced with underscores, e.g. MyApp::Web should use
121 MYAPP\_WEB\_HOME. If both variables are set, the MYAPP\_HOME one will be used.
123 If none of these are set, Catalyst will attempt to automatically detect the
124 home directory. If you are working in a development environment, Catalyst
125 will try and find the directory containing either Makefile.PL, Build.PL,
126 dist.ini, or cpanfile. If the application has been installed into the system
127 (i.e. you have done `make install`), then Catalyst will use the path to your
128 application module, without the .pm extension (e.g., /foo/MyApp if your
129 application was installed at /foo/MyApp.pm)
133 use Catalyst '-Log=warn,fatal,error';
135 Specifies a comma-delimited list of log levels.
139 Enables statistics collection and reporting.
141 use Catalyst qw/-Stats=1/;
143 You can also force this setting from the system environment with CATALYST\_STATS
144 or <MYAPP>\_STATS. The environment settings override the application, with
145 <MYAPP>\_STATS having the highest priority.
147 Stats are also enabled if [debugging ](#debug) is enabled.
151 ## INFORMATION ABOUT THE CURRENT REQUEST
155 Returns a [Catalyst::Action](https://metacpan.org/pod/Catalyst::Action) object for the current action, which
156 stringifies to the action name. See [Catalyst::Action](https://metacpan.org/pod/Catalyst::Action).
160 Returns the namespace of the current action, i.e., the URI prefix
161 corresponding to the controller of the current action. For example:
163 # in Controller::Foo::Bar
164 $c->namespace; # returns 'foo/bar';
170 Returns the current [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request) object, giving access to
171 information about the current client request (including parameters,
172 cookies, HTTP headers, etc.). See [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request).
174 ## REQUEST FLOW HANDLING
176 ## $c->forward( $action \[, \\@arguments \] )
178 ## $c->forward( $class, $method, \[, \\@arguments \] )
180 This is one way of calling another action (method) in the same or
181 a different controller. You can also use `$self->my_method($c, @args)`
182 in the same controller or `$c->controller('MyController')->my_method($c, @args)`
183 in a different controller.
184 The main difference is that 'forward' uses some of the Catalyst request
185 cycle overhead, including debugging, which may be useful to you. On the
186 other hand, there are some complications to using 'forward', restrictions
187 on values returned from 'forward', and it may not handle errors as you prefer.
188 Whether you use 'forward' or not is up to you; it is not considered superior to
189 the other ways to call a method.
191 'forward' calls another action, by its private name. If you give a
192 class name but no method, `process()` is called. You may also optionally
193 pass arguments in an arrayref. The action will receive the arguments in
194 `@_` and `$c->req->args`. Upon returning from the function,
195 `$c->req->args` will be restored to the previous values.
197 Any data `return`ed from the action forwarded to, will be returned by the
200 my $foodata = $c->forward('/foo');
201 $c->forward('index');
202 $c->forward(qw/Model::DBIC::Foo do_stuff/);
203 $c->forward('View::TT');
205 Note that [forward](#c-forward-action-arguments) implies
206 an `eval { }` around the call (actually
207 [execute](#c-execute-class-coderef) does), thus rendering all
208 exceptions thrown by the called action non-fatal and pushing them onto
209 $c->error instead. If you want `die` to propagate you need to do something
213 die join "\n", @{ $c->error } if @{ $c->error };
215 Or make sure to always return true values from your actions and write
218 $c->forward('foo') || return;
220 Another note is that `$c->forward` always returns a scalar because it
221 actually returns $c->state which operates in a scalar context.
222 Thus, something like:
226 in an action that is forwarded to is going to return a scalar,
227 i.e. how many items are in that array, which is probably not what you want.
228 If you need to return an array then return a reference to it,
231 $c->stash->{array} = \@array;
233 and access it from the stash.
235 Keep in mind that the `end` method used is that of the caller action. So a `$c->detach` inside a forwarded action would run the `end` method from the original action requested.
237 ## $c->detach( $action \[, \\@arguments \] )
239 ## $c->detach( $class, $method, \[, \\@arguments \] )
243 The same as [forward](#c-forward-action-arguments), but
244 doesn't return to the previous action when processing is finished.
246 When called with no arguments it escapes the processing chain entirely.
248 ## $c->visit( $action \[, \\@arguments \] )
250 ## $c->visit( $action \[, \\@captures, \\@arguments \] )
252 ## $c->visit( $class, $method, \[, \\@arguments \] )
254 ## $c->visit( $class, $method, \[, \\@captures, \\@arguments \] )
256 Almost the same as [forward](#c-forward-action-arguments),
257 but does a full dispatch, instead of just calling the new `$action` /
258 `$class->$method`. This means that `begin`, `auto` and the method
259 you go to are called, just like a new request.
261 In addition both `$c->action` and `$c->namespace` are localized.
262 This means, for example, that `$c->action` methods such as
263 [name](https://metacpan.org/pod/Catalyst::Action#name), [class](https://metacpan.org/pod/Catalyst::Action#class) and
264 [reverse](https://metacpan.org/pod/Catalyst::Action#reverse) return information for the visited action
265 when they are invoked within the visited action. This is different from the
266 behavior of [forward](#c-forward-action-arguments), which
267 continues to use the $c->action object from the caller action even when
268 invoked from the called action.
270 `$c->stash` is kept unchanged.
272 In effect, [visit](#c-visit-action-captures-arguments)
273 allows you to "wrap" another action, just as it would have been called by
274 dispatching from a URL, while the analogous
275 [go](#c-go-action-captures-arguments) allows you to
276 transfer control to another action as if it had been reached directly from a URL.
278 ## $c->go( $action \[, \\@arguments \] )
280 ## $c->go( $action \[, \\@captures, \\@arguments \] )
282 ## $c->go( $class, $method, \[, \\@arguments \] )
284 ## $c->go( $class, $method, \[, \\@captures, \\@arguments \] )
286 The relationship between `go` and
287 [visit](#c-visit-action-captures-arguments) is the same as
288 the relationship between
289 [forward](#c-forward-class-method-arguments) and
290 [detach](#c-detach-action-arguments). Like `$c->visit`,
291 `$c->go` will perform a full dispatch on the specified action or method,
292 with localized `$c->action` and `$c->namespace`. Like `detach`,
293 `go` escapes the processing of the current request chain on completion, and
294 does not return to its cunless blessed $cunless blessed $caller.
296 @arguments are arguments to the final destination of $action. @captures are
297 arguments to the intermediate steps, if any, on the way to the final sub of
304 Returns the current [Catalyst::Response](https://metacpan.org/pod/Catalyst::Response) object, see there for details.
308 Returns a hashref to the stash, which may be used to store data and pass
309 it between components during a request. You can also set hash keys by
310 passing arguments. The stash is automatically sent to the view. The
311 stash is cleared at the end of a request; it cannot be used for
312 persistent storage (for this you must use a session; see
313 [Catalyst::Plugin::Session](https://metacpan.org/pod/Catalyst::Plugin::Session) for a complete system integrated with
316 $c->stash->{foo} = $bar;
317 $c->stash( { moose => 'majestic', qux => 0 } );
318 $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
320 # stash is automatically passed to the view for use in a template
321 $c->forward( 'MyApp::View::TT' );
323 The stash hash is currently stored in the PSGI `$env` and is managed by
324 [Catalyst::Middleware::Stash](https://metacpan.org/pod/Catalyst::Middleware::Stash). Since it's part of the `$env` items in
325 the stash can be accessed in sub applications mounted under your main
326 [Catalyst](https://metacpan.org/pod/Catalyst) application. For example if you delegate the response of an
327 action to another [Catalyst](https://metacpan.org/pod/Catalyst) application, that sub application will have
328 access to all the stash keys of the main one, and if can of course add
329 more keys of its own. However those new keys will not 'bubble' back up
330 to the main application.
332 For more information the best thing to do is to review the test case:
333 t/middleware-stash.t in the distribution /t directory.
337 ## $c->error($error, ...)
339 ## $c->error($arrayref)
341 Returns an arrayref containing error messages. If Catalyst encounters an
342 error while processing a request, it stores the error in $c->error. This
343 method should only be used to store fatal error messages.
345 my @error = @{ $c->error };
349 $c->error('Something bad happened');
351 Calling this will always return an arrayref (if there are no errors it
352 will be an empty arrayref.
356 Contains the return value of the last executed action.
357 Note that << $c->state >> operates in a scalar context which means that all
358 values it returns are scalar.
362 Clear errors. You probably don't want to clear the errors unless you are
363 implementing a custom error screen.
365 This is equivalent to running
371 Returns true if you have errors
375 Returns the most recent error in the stack (the one most recently added...)
376 or nothing if there are no errors.
380 shifts the most recently added error off the error stack and returns if. Returns
381 nothing if there are no more errors.
383 ## COMPONENT ACCESSORS
385 ## $c->controller($name)
387 Gets a [Catalyst::Controller](https://metacpan.org/pod/Catalyst::Controller) instance by name.
389 $c->controller('Foo')->do_stuff;
391 If the name is omitted, will return the controller for the dispatched
394 If you want to search for controllers, pass in a regexp as the argument.
396 # find all controllers that start with Foo
397 my @foo_controllers = $c->controller(qr{^Foo});
401 Gets a [Catalyst::Model](https://metacpan.org/pod/Catalyst::Model) instance by name.
403 $c->model('Foo')->do_stuff;
405 Any extra arguments are directly passed to ACCEPT\_CONTEXT, if the model
406 defines ACCEPT\_CONTEXT. If it does not, the args are discarded.
408 If the name is omitted, it will look for
409 - a model object in $c->stash->{current\_model\_instance}, then
410 - a model name in $c->stash->{current\_model}, then
411 - a config setting 'default\_model', or
412 - check if there is only one model, and return it if that's the case.
414 If you want to search for models, pass in a regexp as the argument.
416 # find all models that start with Foo
417 my @foo_models = $c->model(qr{^Foo});
421 Gets a [Catalyst::View](https://metacpan.org/pod/Catalyst::View) instance by name.
423 $c->view('Foo')->do_stuff;
425 Any extra arguments are directly passed to ACCEPT\_CONTEXT.
427 If the name is omitted, it will look for
428 - a view object in $c->stash->{current\_view\_instance}, then
429 - a view name in $c->stash->{current\_view}, then
430 - a config setting 'default\_view', or
431 - check if there is only one view, and return it if that's the case.
433 If you want to search for views, pass in a regexp as the argument.
435 # find all views that start with Foo
436 my @foo_views = $c->view(qr{^Foo});
440 Returns the available names which can be passed to $c->controller
444 Returns the available names which can be passed to $c->model
448 Returns the available names which can be passed to $c->view
452 ## $c->component($name)
454 Gets a component object by name. This method is not recommended,
455 unless you want to get a specific component by full
456 class. `$c->controller`, `$c->model`, and `$c->view`
457 should be used instead.
459 If `$name` is a regexp, a list of components matched against the full
460 component name will be returned.
462 If Catalyst can't find a component by name, it will fallback to regex
463 matching by default. To disable this behaviour set
464 disable\_component\_resolution\_regex\_fallback to a true value.
466 __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );
468 ## CLASS DATA AND HELPER CLASSES
472 Returns or takes a hashref containing the application's configuration.
474 __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
476 You can also use a `YAML`, `XML` or [Config::General](https://metacpan.org/pod/Config::General) config file
477 like `myapp.conf` in your applications home directory. See
478 [Catalyst::Plugin::ConfigLoader](https://metacpan.org/pod/Catalyst::Plugin::ConfigLoader).
480 ### Cascading configuration
482 The config method is present on all Catalyst components, and configuration
483 will be merged when an application is started. Configuration loaded with
484 [Catalyst::Plugin::ConfigLoader](https://metacpan.org/pod/Catalyst::Plugin::ConfigLoader) takes precedence over other configuration,
485 followed by configuration in your top level `MyApp` class. These two
486 configurations are merged, and then configuration data whose hash key matches a
487 component name is merged with configuration for that component.
489 The configuration for a component is then passed to the `new` method when a
490 component is constructed.
494 MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
495 MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });
497 will mean that `MyApp::Model::Foo` receives the following data when
500 MyApp::Model::Foo->new({
506 It's common practice to use a Moose attribute
507 on the receiving component to access the config value.
509 package MyApp::Model::Foo;
513 # this attr will receive 'baz' at construction time
519 You can then get the value 'baz' by calling $c->model('Foo')->bar
520 (or $self->bar inside code in the model).
522 **NOTE:** you MUST NOT call `$self->config` or `__PACKAGE__->config`
523 as a way of reading config within your code, as this **will not** give you the
524 correctly merged config back. You **MUST** take the config values supplied to
525 the constructor and use those instead.
529 Returns the logging object instance. Unless it is already set, Catalyst
530 sets this up with a [Catalyst::Log](https://metacpan.org/pod/Catalyst::Log) object. To use your own log class,
531 set the logger with the `__PACKAGE__->log` method prior to calling
532 `__PACKAGE__->setup`.
534 __PACKAGE__->log( MyLogger->new );
539 $c->log->info( 'Now logging with my own logger!' );
541 Your log class should implement the methods described in
542 [Catalyst::Log](https://metacpan.org/pod/Catalyst::Log).
546 Returned True if there's a valid encoding
550 Clears the encoding for the current context
554 Sets or gets the application encoding. Setting encoding takes either an
555 Encoding object or a string that we try to resolve via [Encode::find\_encoding](https://metacpan.org/pod/Encode::find_encoding).
557 You would expect to get the encoding object back if you attempt to set it. If
558 there is a failure you will get undef returned and an error message in the log.
562 Returns 1 if debug mode is enabled, 0 otherwise.
564 You can enable debug mode in several ways:
566 - By calling myapp\_server.pl with the -d flag
567 - With the environment variables MYAPP\_DEBUG, or CATALYST\_DEBUG
568 - The -Debug option in your MyApp.pm
569 - By declaring `sub debug { 1 }` in your MyApp.pm.
571 The first three also set the log level to 'debug'.
573 Calling `$c->debug(1)` has no effect.
577 Returns the dispatcher instance. See [Catalyst::Dispatcher](https://metacpan.org/pod/Catalyst::Dispatcher).
581 Returns the engine instance. See [Catalyst::Engine](https://metacpan.org/pod/Catalyst::Engine).
585 ## $c->path\_to(@path)
587 Merges `@path` with `$c->config->{home}` and returns a
588 [Path::Class::Dir](https://metacpan.org/pod/Path::Class::Dir) object. Note you can usually use this object as
589 a filename, but sometimes you will have to explicitly stringify it
590 yourself by calling the `->stringify` method.
594 $c->path_to( 'db', 'sqlite.db' );
598 Initializes the dispatcher and engine, loads any plugins, and loads the
599 model, view, and controller components. You may also specify an array
600 of plugins to load here, if you choose to not load them in the `use
604 MyApp->setup( qw/-Debug/ );
606 **Note:** You **should not** wrap this method with method modifiers
607 or bad things will happen - wrap the `setup_finalize` method instead.
609 **Note:** You can create a custom setup stage that will execute when the
610 application is starting. Use this to customize setup.
612 MyApp->setup(-Custom=value);
615 my ($class, $value) = @_;
618 Can be handy if you want to hook into the setup phase.
620 ## $app->setup\_finalize
622 A hook to attach modifiers to. This method does not do anything except set the
623 `setup_finished` accessor.
625 Applying method modifiers to the `setup` method doesn't work, because of quirky things done for plugin setup.
629 after setup_finalize => sub {
635 ## $c->uri\_for( $path?, @args?, \\%query\_values? )
637 ## $c->uri\_for( $action, \\@captures?, @args?, \\%query\_values? )
639 ## $c->uri\_for( $action, \[@captures, @args\], \\%query\_values? )
641 Constructs an absolute [URI](https://metacpan.org/pod/URI) object based on the application root, the
642 provided path, and the additional arguments and query parameters provided.
643 When used as a string, provides a textual URI. If you need more flexibility
644 than this (i.e. the option to provide relative URIs etc.) see
645 [Catalyst::Plugin::SmartURI](https://metacpan.org/pod/Catalyst::Plugin::SmartURI).
647 If no arguments are provided, the URI for the current action is returned.
648 To return the current action and also provide @args, use
649 `$c->uri_for( $c->action, @args )`.
651 If the first argument is a string, it is taken as a public URI path relative
652 to `$c->namespace` (if it doesn't begin with a forward slash) or
653 relative to the application root (if it does). It is then merged with
654 `$c->request->base`; any `@args` are appended as additional path
655 components; and any `%query_values` are appended as `?foo=bar` parameters.
657 If the first argument is a [Catalyst::Action](https://metacpan.org/pod/Catalyst::Action) it represents an action which
658 will have its path resolved using `$c->dispatcher->uri_for_action`. The
659 optional `\@captures` argument (an arrayref) allows passing the captured
660 variables that are needed to fill in the paths of Chained and Regex actions;
661 once the path is resolved, `uri_for` continues as though a path was
662 provided, appending any arguments or parameters and creating an absolute
665 The captures for the current request can be found in
666 `$c->request->captures`, and actions can be resolved using
667 `Catalyst::Controller->action_for($name)`. If you have a private action
668 path, use `$c->uri_for_action` instead.
670 # Equivalent to $c->req->uri
671 $c->uri_for($c->action, $c->req->captures,
672 @{ $c->req->args }, $c->req->params);
674 # For the Foo action in the Bar controller
675 $c->uri_for($c->controller('Bar')->action_for('Foo'));
677 # Path to a static resource
678 $c->uri_for('/static/images/logo.png');
680 In general the scheme of the generated URI object will follow the incoming request
681 however if your targeted action or action chain has the Scheme attribute it will
684 Also, if the targeted Action or Action chain declares Args/CaptureArgs that have
685 type constraints, we will require that your proposed URL verify on those declared
688 ## $c->uri\_for\_action( $path, \\@captures\_and\_args?, @args?, \\%query\_values? )
690 ## $c->uri\_for\_action( $action, \\@captures\_and\_args?, @args?, \\%query\_values? )
694 A private path to the Catalyst action you want to create a URI for.
696 This is a shortcut for calling `$c->dispatcher->get_action_by_path($path)` and passing the resulting `$action` and the remaining arguments to `$c->uri_for`.
698 You can also pass in a Catalyst::Action object, in which case it is passed to
701 Note that although the path looks like a URI that dispatches to the wanted action, it is not a URI, but an internal path to that action.
703 For example, if the action looks like:
705 package MyApp::Controller::Users;
707 sub lst : Path('the-list') {}
711 $c->uri_for_action('/users/lst')
713 and it will create the URI /users/the-list.
715 - \\@captures\_and\_args?
717 Optional array reference of Captures (i.e. `<CaptureArgs or $c-`req->captures>)
718 and arguments to the request. Usually used with [Catalyst::DispatchType::Chained](https://metacpan.org/pod/Catalyst::DispatchType::Chained)
719 to interpolate all the parameters in the URI.
723 Optional list of extra arguments - can be supplied in the
724 `\@captures_and_args?` array ref, or here - whichever is easier for your
727 Your action can have zero, a fixed or a variable number of args (e.g.
728 `Args(1)` for a fixed number or `Args()` for a variable number)..
732 Optional array reference of query parameters to append. E.g.
738 /rest/of/your/uri?foo=bar
740 ## $c->welcome\_message
742 Returns the Catalyst welcome HTML page.
746 Contains a hash of options passed from the application script, including
747 the original ARGV the script received, the processed values from that
748 ARGV and any extra arguments to the script which were not processed.
750 This can be used to add custom options to your application's scripts
751 and setup your application differently depending on the values of these
756 These methods are not meant to be used by end users.
760 Returns a hash of components.
762 ## $c->context\_class
764 Returns or sets the context class.
768 Returns a hashref containing coderefs and execution counts (needed for
769 deep recursion detection).
773 Returns the number of actions on the current internal execution stack.
777 Dispatches a request to actions.
779 ## $c->dispatcher\_class
781 Returns or sets the dispatcher class.
785 Returns a list of 2-element array references (name, structure) pairs
786 that will be dumped on the error page in debug mode.
790 Returns or sets the engine class.
792 ## $c->execute( $class, $coderef )
794 Execute a coderef in given class and catch exceptions. Errors are available
799 Finalizes the request.
801 ## $c->finalize\_body
805 ## $c->finalize\_cookies
809 ## $c->finalize\_error
811 Finalizes error. If there is only one error in ["error"](#error) and it is an object that
812 does `as_psgi` or `code` we rethrow the error and presume it caught by middleware
813 up the ladder. Otherwise we return the debugging error page (in debug mode) or we
814 return the default error page (production mode).
816 ## $c->finalize\_headers
820 ## $c->finalize\_encoding
822 Make sure your body is encoded properly IF you set an encoding. By
823 default the encoding is UTF-8 but you can disable it by explicitly setting the
824 encoding configuration value to undef.
826 We can only encode when the body is a scalar. Methods for encoding via the
827 streaming interfaces (such as `write` and `write_fh` on [Catalyst::Response](https://metacpan.org/pod/Catalyst::Response)
830 See ["ENCODING"](#encoding).
832 ## $c->finalize\_output
834 An alias for finalize\_body.
836 ## $c->finalize\_read
838 Finalizes the input after reading is complete.
840 ## $c->finalize\_uploads
842 Finalizes uploads. Cleans up any temporary files.
844 ## $c->get\_action( $action, $namespace )
846 Gets an action in a given namespace.
848 ## $c->get\_actions( $action, $namespace )
850 Gets all actions of a given name in a namespace and all parent
853 ## $app->handle\_request( @arguments )
855 Called to handle each HTTP request.
857 ## $class->prepare( @arguments )
859 Creates a Catalyst context from an engine-specific request (Apache, CGI,
862 ## $c->prepare\_action
864 Prepares action. See [Catalyst::Dispatcher](https://metacpan.org/pod/Catalyst::Dispatcher).
868 Prepares message body.
870 ## $c->prepare\_body\_chunk( $chunk )
872 Prepares a chunk of data before sending it to [HTTP::Body](https://metacpan.org/pod/HTTP::Body).
874 See [Catalyst::Engine](https://metacpan.org/pod/Catalyst::Engine).
876 ## $c->prepare\_body\_parameters
878 Prepares body parameters.
880 ## $c->prepare\_connection
884 ## $c->prepare\_cookies
886 Prepares cookies by ensuring that the attribute on the request
887 object has been built.
889 ## $c->prepare\_headers
891 Prepares request headers by ensuring that the attribute on the request
892 object has been built.
894 ## $c->prepare\_parameters
900 Prepares path and base.
902 ## $c->prepare\_query\_parameters
904 Prepares query parameters.
908 Writes information about the request to the debug logs. This includes:
910 - Request method, path, and remote IP address
911 - Query keywords (see ["query\_keywords" in Catalyst::Request](https://metacpan.org/pod/Catalyst::Request#query_keywords))
917 Writes information about the response to the debug logs by calling
918 `$c->log_response_status_line` and `$c->log_response_headers`.
920 ## $c->log\_response\_status\_line($response)
922 Writes one line of information about the response to the debug logs. This includes:
924 - Response status code
925 - Content-Type header (if present)
926 - Content-Length header (if present)
928 ## $c->log\_response\_headers($headers);
930 Hook method which can be wrapped by plugins to log the response headers.
931 No-op in the default implementation.
933 ## $c->log\_request\_parameters( query => {}, body => {} )
935 Logs request parameters to debug logs
937 ## $c->log\_request\_uploads
939 Logs file uploads included in the request to the debug logs.
940 The parameter name, filename, file type, and file size are all included in
943 ## $c->log\_request\_headers($headers);
945 Hook method which can be wrapped by plugins to log the request headers.
946 No-op in the default implementation.
948 ## $c->log\_headers($type => $headers)
950 Logs [HTTP::Headers](https://metacpan.org/pod/HTTP::Headers) (either request or response) to the debug logs.
954 Prepares the input for reading.
956 ## $c->prepare\_request
958 Prepares the engine request.
960 ## $c->prepare\_uploads
964 ## $c->prepare\_write
966 Prepares the output for writing.
968 ## $c->request\_class
970 Returns or sets the request class. Defaults to [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request).
972 ## $app->request\_class\_traits
974 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the request class.
976 ## $app->composed\_request\_class
978 This is the request class which has been composed with any request\_class\_traits.
980 ## $c->response\_class
982 Returns or sets the response class. Defaults to [Catalyst::Response](https://metacpan.org/pod/Catalyst::Response).
984 ## $app->response\_class\_traits
986 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the response class.
988 ## $app->composed\_response\_class
990 This is the request class which has been composed with any response\_class\_traits.
992 ## $c->read( \[$maxlength\] )
994 Reads a chunk of data from the request body. This method is designed to
995 be used in a while loop, reading `$maxlength` bytes on every call.
996 `$maxlength` defaults to the size of the request if not specified.
998 You have to set `MyApp->config(parse_on_demand => 1)` to use this
1001 Warning: If you use read(), Catalyst will not process the body,
1002 so you will not be able to access POST parameters or file uploads via
1003 $c->request. You must handle all body parsing yourself.
1009 ## $c->set\_action( $action, $code, $namespace, $attrs )
1011 Sets an action in a given namespace.
1013 ## $c->setup\_actions($component)
1015 Sets up actions for a component.
1017 ## $c->setup\_components
1019 This method is called internally to set up the application's components.
1021 It finds modules by calling the [locate\_components](https://metacpan.org/pod/locate_components) method, expands them to
1022 package names with the [expand\_component\_module](https://metacpan.org/pod/expand_component_module) method, and then installs
1023 each component into the application.
1025 The `setup_components` config option is passed to both of the above methods.
1027 Installation of each component is performed by the [setup\_component](https://metacpan.org/pod/setup_component) method,
1030 ## $app->setup\_injected\_components
1032 Called by setup\_compoents to setup components that are injected.
1034 ## $app->setup\_injected\_component( $injected\_component\_name, $config )
1036 Setup a given injected component.
1038 ## $app->inject\_component($MyApp\_Component\_name => \\%args);
1040 Add a component that is injected at setup:
1042 MyApp->inject_component( 'Model::Foo' => { from_component => 'Common::Foo' } );
1044 Must be called before ->setup. Expects a component name for your
1045 current application and \\%args where
1049 The target component being injected into your application
1053 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that are applied to your component.
1057 MyApp->inject_component(
1059 from_component => 'Common::Model::Foo',
1060 roles => ['Role1', 'Role2'],
1063 ## $app->inject\_components
1065 Inject a list of components:
1067 MyApp->inject_components(
1068 'Model::FooOne' => {
1069 from_component => 'Common::Model::Foo',
1070 roles => ['Role1', 'Role2'],
1072 'Model::FooTwo' => {
1073 from_component => 'Common::Model::Foo',
1074 roles => ['Role1', 'Role2'],
1077 ## $c->locate\_components( $setup\_component\_config )
1079 This method is meant to provide a list of component modules that should be
1080 setup for the application. By default, it will use [Module::Pluggable](https://metacpan.org/pod/Module::Pluggable).
1082 Specify a `setup_components` config option to pass additional options directly
1083 to [Module::Pluggable](https://metacpan.org/pod/Module::Pluggable). To add additional search paths, specify a key named
1084 `search_extra` as an array reference. Items in the array beginning with `::`
1085 will have the application class name prepended to them.
1087 ## $c->expand\_component\_module( $component, $setup\_component\_config )
1089 Components found by `locate_components` will be passed to this method, which
1090 is expected to return a list of component (package) names to be set up.
1092 ## $app->delayed\_setup\_component
1094 Returns a coderef that points to a setup\_component instance. Used
1095 internally for when you want to delay setup until the first time
1096 the component is called.
1098 ## $c->setup\_component
1100 ## $app->config\_for( $component\_name )
1102 Return the application level configuration (which is not yet merged with any
1103 local component configuration, via $component\_class->config) for the named
1104 component or component object. Example:
1107 'Model::Foo' => { a => 1, b => 2},
1110 my $config = MyApp->config_for('MyApp::Model::Foo');
1112 In this case $config is the hashref ` {a=`1, b=>2} >.
1114 This is also handy for looking up configuration for a plugin, to make sure you follow
1115 existing [Catalyst](https://metacpan.org/pod/Catalyst) standards for where a plugin should put its configuration.
1117 ## $c->setup\_dispatcher
1121 ## $c->setup\_engine
1125 ## $c->apply\_default\_middlewares
1127 Adds the following [Plack](https://metacpan.org/pod/Plack) middlewares to your application, since they are
1128 useful and commonly needed:
1130 [Plack::Middleware::LighttpdScriptNameFix](https://metacpan.org/pod/Plack::Middleware::LighttpdScriptNameFix) (if you are using Lighttpd),
1131 [Plack::Middleware::IIS6ScriptNameFix](https://metacpan.org/pod/Plack::Middleware::IIS6ScriptNameFix) (always applied since this middleware
1132 is smart enough to conditionally apply itself).
1134 We will also automatically add [Plack::Middleware::ReverseProxy](https://metacpan.org/pod/Plack::Middleware::ReverseProxy) if we notice
1135 that your HTTP $env variable `REMOTE_ADDR` is '127.0.0.1'. This is usually
1136 an indication that your server is running behind a proxy frontend. However in
1137 2014 this is often not the case. We preserve this code for backwards compatibility
1138 however I **highly** recommend that if you are running the server behind a front
1139 end proxy that you clearly indicate so with the `using_frontend_proxy` configuration
1140 setting to true for your environment configurations that run behind a proxy. This
1141 way if you change your front end proxy address someday your code would inexplicably
1142 stop working as expected.
1144 Additionally if we detect we are using Nginx, we add a bit of custom middleware
1145 to solve some problems with the way that server handles $ENV{PATH\_INFO} and
1148 Please **NOTE** that if you do use `using_frontend_proxy` the middleware is now
1149 adding via `registered_middleware` rather than this method.
1151 If you are using Lighttpd or IIS6 you may wish to apply these middlewares. In
1152 general this is no longer a common case but we have this here for backward
1159 Returns a PSGI application code reference for the catalyst application
1160 `$c`. This is the bare application created without the `apply_default_middlewares`
1161 method called. We do however apply `registered_middleware` since those are
1162 integral to how [Catalyst](https://metacpan.org/pod/Catalyst) functions. Also, unlike starting your application
1163 with a generated server script (via [Catalyst::Devel](https://metacpan.org/pod/Catalyst::Devel) and `catalyst.pl`) we do
1164 not attempt to return a valid [PSGI](https://metacpan.org/pod/PSGI) application using any existing `${myapp}.psgi`
1165 scripts in your $HOME directory.
1167 **NOTE** `apply_default_middlewares` was originally created when the first PSGI
1168 port was done for v5.90000. These are middlewares that are added to achieve
1169 backward compatibility with older applications. If you start your application
1170 using one of the supplied server scripts (generated with [Catalyst::Devel](https://metacpan.org/pod/Catalyst::Devel) and
1171 the project skeleton script `catalyst.pl`) we apply `apply_default_middlewares`
1172 automatically. This was done so that pre and post PSGI port applications would
1175 This is what you want to be using to retrieve the PSGI application code
1176 reference of your Catalyst application for use in a custom `.psgi` or in your
1177 own created server modules.
1181 Sets up the home directory.
1183 ## $c->setup\_encoding
1185 Sets up the input/output encoding. See [ENCODING](https://metacpan.org/pod/ENCODING)
1187 ## handle\_unicode\_encoding\_exception
1189 Hook to let you customize how encoding errors are handled. By default
1190 we just throw an exception. Receives a hashref of debug information.
1193 $c->handle_unicode_encoding_exception({
1194 param_value => $value,
1196 encoding_step => 'params',
1201 Sets up log by instantiating a [Catalyst::Log](https://metacpan.org/pod/Catalyst::Log) object and
1202 passing it to `log()`. Pass in a comma-delimited list of levels to set the
1205 This method also installs a `debug` method that returns a true value into the
1206 catalyst subclass if the "debug" level is passed in the comma-delimited list,
1207 or if the `$CATALYST_DEBUG` environment variable is set to a true value.
1209 Note that if the log has already been setup, by either a previous call to
1210 `setup_log` or by a call such as `__PACKAGE__->log( MyLogger->new )`,
1211 that this method won't actually set up the log object.
1213 ## $c->setup\_plugins
1219 Sets up timing statistics class.
1221 ## $c->registered\_plugins
1223 Returns a sorted list of the plugins which have either been stated in the
1226 If passed a given plugin name, it will report a boolean value indicating
1227 whether or not that plugin is loaded. A fully qualified name is required if
1228 the plugin name does not begin with `Catalyst::Plugin::`.
1230 if ($c->registered_plugins('Some::Plugin')) {
1234 ## default\_middleware
1236 Returns a list of instantiated PSGI middleware objects which is the default
1237 middleware that is active for this application (taking any configuration
1238 options into account, excluding your custom added middleware via the `psgi_middleware`
1239 configuration option). You can override this method if you wish to change
1240 the default middleware (although do so at risk since some middleware is vital
1241 to application function.)
1243 The current default middleware list is:
1245 Catalyst::Middleware::Stash
1246 Plack::Middleware::HTTPExceptions
1247 Plack::Middleware::RemoveRedundantBody
1248 Plack::Middleware::FixMissingBodyInRedirect
1249 Plack::Middleware::ContentLength
1250 Plack::Middleware::MethodOverride
1251 Plack::Middleware::Head
1253 If the configuration setting `using_frontend_proxy` is true we add:
1255 Plack::Middleware::ReverseProxy
1257 If the configuration setting `using_frontend_proxy_path` is true we add:
1259 Plack::Middleware::ReverseProxyPath
1261 But **NOTE** that [Plack::Middleware::ReverseProxyPath](https://metacpan.org/pod/Plack::Middleware::ReverseProxyPath) is not a dependency of the
1262 [Catalyst](https://metacpan.org/pod/Catalyst) distribution so if you want to use this option you should add it to
1263 your project distribution file.
1265 These middlewares will be added at ["setup\_middleware"](#setup_middleware) during the
1266 ["setup"](#setup) phase of application startup.
1268 ## registered\_middlewares
1270 Read only accessor that returns an array of all the middleware in the order
1271 that they were added (which is the REVERSE of the order they will be applied).
1273 The values returned will be either instances of [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware) or of a
1274 compatible interface, or a coderef, which is assumed to be inlined middleware
1276 ## setup\_middleware (?@middleware)
1278 Read configuration information stored in configuration key `psgi_middleware` or
1281 See under ["CONFIGURATION"](#configuration) information regarding `psgi_middleware` and how
1282 to use it to enable [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware)
1284 This method is automatically called during 'setup' of your application, so
1285 you really don't need to invoke it. However you may do so if you find the idea
1286 of loading middleware via configuration weird :). For example:
1292 __PACKAGE__->setup_middleware('Head');
1295 When we read middleware definitions from configuration, we reverse the list
1296 which sounds odd but is likely how you expect it to work if you have prior
1297 experience with [Plack::Builder](https://metacpan.org/pod/Plack::Builder) or if you previously used the plugin
1298 [Catalyst::Plugin::EnableMiddleware](https://metacpan.org/pod/Catalyst::Plugin::EnableMiddleware) (which is now considered deprecated)
1300 So basically your middleware handles an incoming request from the first
1301 registered middleware, down and handles the response from the last middleware
1304 ## registered\_data\_handlers
1306 A read only copy of registered Data Handlers returned as a Hash, where each key
1307 is a content type and each value is a subref that attempts to decode that content
1310 ## setup\_data\_handlers (?@data\_handler)
1312 Read configuration information stored in configuration key `data_handlers` or
1315 See under ["CONFIGURATION"](#configuration) information regarding `data_handlers`.
1317 This method is automatically called during 'setup' of your application, so
1318 you really don't need to invoke it.
1320 ## default\_data\_handlers
1322 Default Data Handlers that come bundled with [Catalyst](https://metacpan.org/pod/Catalyst). Currently there are
1323 only two default data handlers, for 'application/json' and an alternative to
1324 'application/x-www-form-urlencoded' which supposed nested form parameters via
1325 [CGI::Struct](https://metacpan.org/pod/CGI::Struct) or via [CGI::Struct::XS](https://metacpan.org/pod/CGI::Struct::XS) IF you've installed it.
1327 The 'application/json' data handler is used to parse incoming JSON into a Perl
1328 data structure. It used either [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS) or [JSON](https://metacpan.org/pod/JSON), depending on which
1329 is installed. This allows you to fail back to [JSON:PP](JSON:PP), which is a Pure Perl
1330 JSON decoder, and has the smallest dependency impact.
1332 Because we don't wish to add more dependencies to [Catalyst](https://metacpan.org/pod/Catalyst), if you wish to
1333 use this new feature we recommend installing [JSON](https://metacpan.org/pod/JSON) or [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS) in
1334 order to get the best performance. You should add either to your dependency
1335 list (Makefile.PL, dist.ini, cpanfile, etc.)
1339 Returns an arrayref of the internal execution stack (actions that are
1340 currently executing).
1344 Returns the current timing statistics object. By default Catalyst uses
1345 [Catalyst::Stats](https://metacpan.org/pod/Catalyst::Stats), but can be set otherwise with
1346 [stats\_class](#c-stats_class).
1348 Even if [-Stats](#stats) is not enabled, the stats object is still
1349 available. By enabling it with ` $c-`stats->enabled(1) >, it can be used to
1350 profile explicitly, although MyApp.pm still won't profile nor output anything
1355 Returns or sets the stats (timing statistics) class. [Catalyst::Stats](https://metacpan.org/pod/Catalyst::Stats) is used by default.
1357 ## $app->stats\_class\_traits
1359 A arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that are applied to the stats\_class before creating it.
1361 ## $app->composed\_stats\_class
1363 this is the stats\_class composed with any 'stats\_class\_traits'.
1367 Returns 1 when [stats collection](#stats) is enabled.
1369 Note that this is a static method, not an accessor and should be overridden
1370 by declaring `sub use_stats { 1 }` in your MyApp.pm, not by calling `$c->use_stats(1)`.
1372 ## $c->write( $data )
1374 Writes $data to the output stream. When using this method directly, you
1375 will need to manually set the `Content-Length` header to the length of
1376 your output data, if known.
1380 Returns the Catalyst version number. Mostly useful for "powered by"
1381 messages in template systems.
1385 There are a number of 'base' config variables which can be set:
1387 - `always_catch_http_exceptions` - As of version 5.90060 Catalyst
1388 rethrows errors conforming to the interface described by
1389 [Plack::Middleware::HTTPExceptions](https://metacpan.org/pod/Plack::Middleware::HTTPExceptions) and lets the middleware deal with it.
1390 Set true to get the deprecated behaviour and have Catalyst catch HTTP exceptions.
1391 - `default_model` - The default model picked if you say `$c->model`. See ["$c->model($name)"](#c-model-name).
1392 - `default_view` - The default view to be rendered or returned when `$c->view` is called. See ["$c->view($name)"](#c-view-name).
1393 - `disable_component_resolution_regex_fallback` - Turns
1394 off the deprecated component resolution functionality so
1395 that if any of the component methods (e.g. `$c->controller('Foo')`)
1396 are called then regex search will not be attempted on string values and
1397 instead `undef` will be returned.
1398 - `home` - The application home directory. In an uninstalled application,
1399 this is the top level application directory. In an installed application,
1400 this will be the directory containing `MyApp.pm`.
1401 - `ignore_frontend_proxy` - See ["PROXY SUPPORT"](#proxy-support)
1402 - `name` - The name of the application in debug messages and the debug and
1404 - `parse_on_demand` - The request body (for example file uploads) will not be parsed
1405 until it is accessed. This allows you to (for example) check authentication (and reject
1406 the upload) before actually receiving all the data. See ["ON-DEMAND PARSER"](#on-demand-parser)
1407 - `root` - The root directory for templates. Usually this is just a
1408 subdirectory of the home directory, but you can set it to change the
1409 templates to a different directory.
1410 - `search_extra` - Array reference passed to Module::Pluggable to for additional
1411 namespaces from which components will be loaded (and constructed and stored in
1413 - `show_internal_actions` - If true, causes internal actions such as `_DISPATCH`
1414 to be shown in hit debug tables in the test server.
1415 - `use_request_uri_for_path` - Controls if the `REQUEST_URI` or `PATH_INFO` environment
1416 variable should be used for determining the request path.
1418 Most web server environments pass the requested path to the application using environment variables,
1419 from which Catalyst has to reconstruct the request base (i.e. the top level path to / in the application,
1420 exposed as `$c->request->base`) and the request path below that base.
1422 There are two methods of doing this, both of which have advantages and disadvantages. Which method is used
1423 is determined by the `$c->config(use_request_uri_for_path)` setting (which can either be true or false).
1425 - use\_request\_uri\_for\_path => 0
1427 This is the default (and the) traditional method that Catalyst has used for determining the path information.
1428 The path is generated from a combination of the `PATH_INFO` and `SCRIPT_NAME` environment variables.
1429 The allows the application to behave correctly when `mod_rewrite` is being used to redirect requests
1430 into the application, as these variables are adjusted by mod\_rewrite to take account for the redirect.
1432 However this method has the major disadvantage that it is impossible to correctly decode some elements
1433 of the path, as RFC 3875 says: "`Unlike a URI path, the PATH_INFO is not URL-encoded, and cannot
1434 contain path-segment parameters.`" This means PATH\_INFO is **always** decoded, and therefore Catalyst
1435 can't distinguish / vs %2F in paths (in addition to other encoded values).
1437 - use\_request\_uri\_for\_path => 1
1439 This method uses the `REQUEST_URI` and `SCRIPT_NAME` environment variables. As `REQUEST_URI` is never
1440 decoded, this means that applications using this mode can correctly handle URIs including the %2F character
1441 (i.e. with `AllowEncodedSlashes` set to `On` in Apache).
1443 Given that this method of path resolution is provably more correct, it is recommended that you use
1444 this unless you have a specific need to deploy your application in a non-standard environment, and you are
1445 aware of the implications of not being able to handle encoded URI paths correctly.
1447 However it also means that in a number of cases when the app isn't installed directly at a path, but instead
1448 is having paths rewritten into it (e.g. as a .cgi/fcgi in a public\_html directory, with mod\_rewrite in a
1449 .htaccess file, or when SSI is used to rewrite pages into the app, or when sub-paths of the app are exposed
1450 at other URIs than that which the app is 'normally' based at with `mod_rewrite`), the resolution of
1451 `$c->request->base` will be incorrect.
1453 - `using_frontend_proxy` - See ["PROXY SUPPORT"](#proxy-support).
1454 - `using_frontend_proxy_path` - Enabled [Plack::Middleware::ReverseProxyPath](https://metacpan.org/pod/Plack::Middleware::ReverseProxyPath) on your application (if
1455 installed, otherwise log an error). This is useful if your application is not running on the
1456 'root' (or /) of your host server. **NOTE** if you use this feature you should add the required
1457 middleware to your project dependency list since its not automatically a dependency of [Catalyst](https://metacpan.org/pod/Catalyst).
1458 This has been done since not all people need this feature and we wish to restrict the growth of
1459 [Catalyst](https://metacpan.org/pod/Catalyst) dependencies.
1460 - `encoding` - See ["ENCODING"](#encoding)
1462 This now defaults to 'UTF-8'. You my turn it off by setting this configuration
1465 - `abort_chain_on_error_fix`
1467 When there is an error in an action chain, the default behavior is to continue
1468 processing the remaining actions and then catch the error upon chain end. This
1469 can lead to running actions when the application is in an unexpected state. If
1470 you have this issue, setting this config value to true will promptly exit a
1471 chain when there is an error raised in any action (thus terminating the chain
1476 __PACKAGE__->config(abort_chain_on_error_fix => 1);
1478 In the future this might become the default behavior.
1480 - `use_hash_multivalue_in_request`
1482 In [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request) the methods `query_parameters`, `body_parametes`
1483 and `parameters` return a hashref where values might be scalar or an arrayref
1484 depending on the incoming data. In many cases this can be undesirable as it
1485 leads one to writing defensive code like the following:
1487 my ($val) = ref($c->req->parameters->{a}) ?
1488 @{$c->req->parameters->{a}} :
1489 $c->req->parameters->{a};
1491 Setting this configuration item to true will make [Catalyst](https://metacpan.org/pod/Catalyst) populate the
1492 attributes underlying these methods with an instance of [Hash::MultiValue](https://metacpan.org/pod/Hash::MultiValue)
1493 which is used by [Plack::Request](https://metacpan.org/pod/Plack::Request) and others to solve this very issue. You
1494 may prefer this behavior to the default, if so enable this option (be warned
1495 if you enable it in a legacy application we are not sure if it is completely
1496 backwardly compatible).
1498 - `skip_complex_post_part_handling`
1500 When creating body parameters from a POST, if we run into a multpart POST
1501 that does not contain uploads, but instead contains inlined complex data
1502 (very uncommon) we cannot reliably convert that into field => value pairs. So
1503 instead we create an instance of [Catalyst::Request::PartData](https://metacpan.org/pod/Catalyst::Request::PartData). If this causes
1504 issue for you, you can disable this by setting `skip_complex_post_part_handling`
1505 to true (default is false).
1507 - `skip_body_param_unicode_decoding`
1509 Generally we decode incoming POST params based on your declared encoding (the
1510 default for this is to decode UTF-8). If this is causing you trouble and you
1511 do not wish to turn all encoding support off (with the `encoding` configuration
1512 parameter) you may disable this step atomically by setting this configuration
1515 - `do_not_decode_query`
1517 If true, then do not try to character decode any wide characters in your
1518 request URL query or keywords. Most readings of the relevent specifications
1519 suggest these should be UTF-\* encoded, which is the default that [Catalyst](https://metacpan.org/pod/Catalyst)
1520 will use, hwoever if you are creating a lot of URLs manually or have external
1521 evil clients, this might cause you trouble. If you find the changes introduced
1522 in Catalyst version 5.90080+ break some of your query code, you may disable
1523 the UTF-8 decoding globally using this configuration.
1525 This setting takes precedence over `default_query_encoding` and
1526 `decode_query_using_global_encoding`
1528 - `default_query_encoding`
1530 By default we decode query and keywords in your request URL using UTF-8, which
1531 is our reading of the relevent specifications. This setting allows one to
1532 specify a fixed value for how to decode your query. You might need this if
1533 you are doing a lot of custom encoding of your URLs and not using UTF-8.
1535 This setting take precedence over `decode_query_using_global_encoding`.
1537 - `decode_query_using_global_encoding`
1539 Setting this to true will default your query decoding to whatever your
1540 general global encoding is (the default is UTF-8).
1542 - `use_chained_args_0_special_case`
1544 In older versions of Catalyst, when more than one action matched the same path
1545 AND all those matching actions declared Args(0), we'd break the tie by choosing
1546 the first action defined. We now normalized how Args(0) works so that it
1547 follows the same rule as Args(N), which is to say when we need to break a tie
1548 we choose the LAST action defined. If this breaks your code and you don't
1549 have time to update to follow the new normalized approach, you may set this
1550 value to true and it will globally revert to the original chaining behavior.
1552 - `psgi_middleware` - See ["PSGI MIDDLEWARE"](#psgi-middleware).
1553 - `data_handlers` - See ["DATA HANDLERS"](#data-handlers).
1554 - `stats_class_traits`
1556 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get componsed into your stats class.
1558 - `request_class_traits`
1560 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get componsed into your request class.
1562 - `response_class_traits`
1564 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get componsed into your response class.
1566 - `inject_components`
1568 A Hashref of [Catalyst::Component](https://metacpan.org/pod/Catalyst::Component) subclasses that are 'injected' into configuration.
1572 inject_components => {
1573 'Controller::Err' => { from_component => 'Local::Controller::Errors' },
1574 'Model::Zoo' => { from_component => 'Local::Model::Foo' },
1575 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] },
1577 'Controller::Err' => { a => 100, b=>200, namespace=>'error' },
1578 'Model::Zoo' => { a => 2 },
1579 'Model::Foo' => { a => 100 },
1582 Generally [Catalyst](https://metacpan.org/pod/Catalyst) looks for components in your Model/View or Controller directories.
1583 However for cases when you which to use an existing component and you don't need any
1584 customization (where for when you can apply a role to customize it) you may inject those
1585 components into your application. Please note any configuration should be done 'in the
1586 normal way', with a key under configuration named after the component affix, as in the
1589 Using this type of injection allows you to construct significant amounts of your application
1590 with only configuration!. This may or may not lead to increased code understanding.
1592 Please not you may also call the ->inject\_components application method as well, although
1593 you must do so BEFORE setup.
1597 Generally when you throw an exception inside an Action (or somewhere in
1598 your stack, such as in a model that an Action is calling) that exception
1599 is caught by Catalyst and unless you either catch it yourself (via eval
1600 or something like [Try::Tiny](https://metacpan.org/pod/Try::Tiny) or by reviewing the ["error"](#error) stack, it
1601 will eventually reach ["finalize\_errors"](#finalize_errors) and return either the debugging
1602 error stack page, or the default error page. However, if your exception
1603 can be caught by [Plack::Middleware::HTTPExceptions](https://metacpan.org/pod/Plack::Middleware::HTTPExceptions), [Catalyst](https://metacpan.org/pod/Catalyst) will
1604 instead rethrow it so that it can be handled by that middleware (which
1605 is part of the default middleware). For example this would allow
1607 use HTTP::Throwable::Factory 'http_throw';
1609 sub throws_exception :Local {
1610 my ($self, $c) = @_;
1612 http_throw(SeeOther => { location =>
1613 $c->uri_for($self->action_for('redirect')) });
1619 Catalyst uses internal actions like `_DISPATCH`, `_BEGIN`, `_AUTO`,
1620 `_ACTION`, and `_END`. These are by default not shown in the private
1621 action table, but you can make them visible with a config parameter.
1623 MyApp->config(show_internal_actions => 1);
1627 The request body is usually parsed at the beginning of a request,
1628 but if you want to handle input yourself, you can enable on-demand
1629 parsing with a config parameter.
1631 MyApp->config(parse_on_demand => 1);
1635 Many production servers operate using the common double-server approach,
1636 with a lightweight frontend web server passing requests to a larger
1637 backend server. An application running on the backend server must deal
1638 with two problems: the remote user always appears to be `127.0.0.1` and
1639 the server's hostname will appear to be `localhost` regardless of the
1640 virtual host that the user connected through.
1642 Catalyst will automatically detect this situation when you are running
1643 the frontend and backend servers on the same machine. The following
1644 changes are made to the request.
1646 $c->req->address is set to the user's real IP address, as read from
1647 the HTTP X-Forwarded-For header.
1649 The host value for $c->req->base and $c->req->uri is set to the real
1650 host, as read from the HTTP X-Forwarded-Host header.
1652 Additionally, you may be running your backend application on an insecure
1653 connection (port 80) while your frontend proxy is running under SSL. If there
1654 is a discrepancy in the ports, use the HTTP header `X-Forwarded-Port` to
1655 tell Catalyst what port the frontend listens on. This will allow all URIs to
1656 be created properly.
1658 In the case of passing in:
1660 X-Forwarded-Port: 443
1662 All calls to `uri_for` will result in an https link, as is expected.
1664 Obviously, your web server must support these headers for this to work.
1666 In a more complex server farm environment where you may have your
1667 frontend proxy server(s) on different machines, you will need to set a
1668 configuration option to tell Catalyst to read the proxied data from the
1671 MyApp->config(using_frontend_proxy => 1);
1673 If you do not wish to use the proxy support at all, you may set:
1675 MyApp->config(ignore_frontend_proxy => 0);
1677 ## Note about psgi files
1679 Note that if you supply your own .psgi file, calling
1680 `MyApp->psgi_app(@_);`, then **this will not happen automatically**.
1682 You either need to apply [Plack::Middleware::ReverseProxy](https://metacpan.org/pod/Plack::Middleware::ReverseProxy) yourself
1683 in your psgi, for example:
1686 enable "Plack::Middleware::ReverseProxy";
1690 This will unconditionally add the ReverseProxy support, or you need to call
1691 `$app = MyApp->apply_default_middlewares($app)` (to conditionally
1692 apply the support depending upon your config).
1694 See [Catalyst::PSGI](https://metacpan.org/pod/Catalyst::PSGI) for more information.
1698 Catalyst has been tested under Apache 2's threading `mpm_worker`,
1699 `mpm_winnt`, and the standalone forking HTTP server on Windows. We
1700 believe the Catalyst core to be thread-safe.
1702 If you plan to operate in a threaded environment, remember that all other
1703 modules you are using must also be thread-safe. Some modules, most notably
1704 [DBD::SQLite](https://metacpan.org/pod/DBD::SQLite), are not thread-safe.
1708 The [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request) object uses [HTTP::Body](https://metacpan.org/pod/HTTP::Body) to populate 'classic' HTML
1709 form parameters and URL search query fields. However it has become common
1710 for various alternative content types to be PUT or POSTed to your controllers
1711 and actions. People working on RESTful APIs, or using AJAX often use JSON,
1712 XML and other content types when communicating with an application server. In
1713 order to better support this use case, [Catalyst](https://metacpan.org/pod/Catalyst) defines a global configuration
1714 option, `data_handlers`, which lets you associate a content type with a coderef
1715 that parses that content type into something Perl can readily access.
1722 __PACKAGE__->config(
1724 'application/json' => sub { local $/; decode_json $_->getline },
1726 ## Any other configuration.
1731 By default [Catalyst](https://metacpan.org/pod/Catalyst) comes with a generic JSON data handler similar to the
1732 example given above, which uses [JSON::Maybe](https://metacpan.org/pod/JSON::Maybe) to provide either [JSON::PP](https://metacpan.org/pod/JSON::PP)
1733 (a pure Perl, dependency free JSON parser) or [Cpanel::JSON::XS](https://metacpan.org/pod/Cpanel::JSON::XS) if you have
1734 it installed (if you want the faster XS parser, add it to you project Makefile.PL
1735 or dist.ini, cpanfile, etc.)
1737 The `data_handlers` configuration is a hashref whose keys are HTTP Content-Types
1738 (matched against the incoming request type using a regexp such as to be case
1739 insensitive) and whose values are coderefs that receive a localized version of
1740 `$_` which is a filehandle object pointing to received body.
1742 This feature is considered an early access release and we reserve the right
1743 to alter the interface in order to provide a performant and secure solution to
1744 alternative request body content. Your reports welcomed!
1748 You can define middleware, defined as [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware) or a compatible
1749 interface in configuration. Your middleware definitions are in the form of an
1750 arrayref under the configuration key `psgi_middleware`. Here's an example
1751 with details to follow:
1756 use Plack::Middleware::StackTrace;
1758 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1760 __PACKAGE__->config(
1761 'psgi_middleware', [
1764 $stacktrace_middleware,
1765 'Session' => {store => 'File'},
1770 $env->{myapp.customkey} = 'helloworld';
1779 So the general form is:
1781 __PACKAGE__->config(psgi_middleware => \@middleware_definitions);
1783 Where `@middleware` is one or more of the following, applied in the REVERSE of
1784 the order listed (to make it function similarly to [Plack::Builder](https://metacpan.org/pod/Plack::Builder):
1786 Alternatively, you may also define middleware by calling the ["setup\_middleware"](#setup_middleware)
1793 __PACKAGE__->setup_middleware( \@middleware_definitions);
1796 In the case where you do both (use 'setup\_middleware' and configuration) the
1797 package call to setup\_middleware will be applied earlier (in other words its
1798 middleware will wrap closer to the application). Keep this in mind since in
1799 some cases the order of middleware is important.
1801 The two approaches are not exclusive.
1805 An already initialized object that conforms to the [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware)
1808 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1810 __PACKAGE__->config(
1811 'psgi_middleware', [
1812 $stacktrace_middleware,
1819 A coderef that is an inlined middleware:
1821 __PACKAGE__->config(
1822 'psgi_middleware', [
1827 if($env->{PATH_INFO} =~m/forced/) {
1829 ->new(file=>TestApp->path_to(qw/share static forced.txt/))
1832 return $app->($env);
1843 We assume the scalar refers to a namespace after normalizing it using the
1846 (1) If the scalar is prefixed with a "+" (as in `+MyApp::Foo`) then the full string
1847 is assumed to be 'as is', and we just install and use the middleware.
1849 (2) If the scalar begins with "Plack::Middleware" or your application namespace
1850 (the package name of your Catalyst application subclass), we also assume then
1851 that it is a full namespace, and use it.
1853 (3) Lastly, we then assume that the scalar is a partial namespace, and attempt to
1854 resolve it first by looking for it under your application namespace (for example
1855 if you application is "MyApp::Web" and the scalar is "MyMiddleware", we'd look
1856 under "MyApp::Web::Middleware::MyMiddleware") and if we don't find it there, we
1857 will then look under the regular [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware) namespace (i.e. for the
1858 previous we'd try "Plack::Middleware::MyMiddleware"). We look under your application
1859 namespace first to let you 'override' common [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware) locally, should
1860 you find that a good idea.
1866 __PACKAGE__->config(
1867 'psgi_middleware', [
1868 'Debug', ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap
1869 'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap
1870 '+MyApp::Custom', ## MyApp::Custom->wrap
1875 - a scalar followed by a hashref
1877 Just like the previous, except the following `HashRef` is used as arguments
1878 to initialize the middleware object.
1880 __PACKAGE__->config(
1881 'psgi_middleware', [
1882 'Session' => {store => 'File'},
1885 Please see [PSGI](https://metacpan.org/pod/PSGI) for more on middleware.
1889 Starting in [Catalyst](https://metacpan.org/pod/Catalyst) version 5.90080 encoding is automatically enabled
1890 and set to encode all body responses to UTF8 when possible and applicable.
1891 Following is documentation on this process. If you are using an older
1892 version of [Catalyst](https://metacpan.org/pod/Catalyst) you should review documentation for that version since
1895 By default encoding is now 'UTF-8'. You may turn it off by setting
1896 the encoding configuration to undef.
1898 MyApp->config(encoding => undef);
1900 This is recommended for temporary backwards compatibility only.
1902 Encoding is automatically applied when the content-type is set to
1903 a type that can be encoded. Currently we encode when the content type
1904 matches the following regular expression:
1906 $content_type =~ /^text|xml$|javascript$/
1908 Encoding is set on the application, but it is copied to the context object
1909 so that you can override it on a request basis.
1911 Be default we don't automatically encode 'application/json' since the most
1912 common approaches to generating this type of response (Either via [Catalyst::View::JSON](https://metacpan.org/pod/Catalyst::View::JSON)
1913 or [Catalyst::Action::REST](https://metacpan.org/pod/Catalyst::Action::REST)) will do so already and we want to avoid double
1916 If you are producing JSON response in an unconventional manner (such
1917 as via a template or manual strings) you should perform the UTF8 encoding
1918 manually as well such as to conform to the JSON specification.
1920 NOTE: We also examine the value of $c->response->content\_encoding. If
1921 you set this (like for example 'gzip', and manually gzipping the body)
1922 we assume that you have done all the necessary encoding yourself, since
1923 we cannot encode the gzipped contents. If you use a plugin like
1924 [Catalyst::Plugin::Compress](https://metacpan.org/pod/Catalyst::Plugin::Compress) you need to update to a modern version in order
1925 to have this function correctly with the new UTF8 encoding code, or you
1926 can use [Plack::Middleware::Deflater](https://metacpan.org/pod/Plack::Middleware::Deflater) or (probably best) do your compression on
1933 Returns an instance of an `Encode` encoding
1935 print $c->encoding->name
1937 - handle\_unicode\_encoding\_exception ($exception\_context)
1939 Method called when decoding process for a request fails.
1941 An `$exception_context` hashref is provided to allow you to override the
1942 behaviour of your application when given data with incorrect encodings.
1944 The default method throws exceptions in the case of invalid request parameters
1945 (resulting in a 500 error), but ignores errors in upload filenames.
1947 The keys passed in the `$exception_context` hash are:
1951 The value which was not able to be decoded.
1955 The exception received from [Encode](https://metacpan.org/pod/Encode).
1959 What type of data was being decoded. Valid values are (currently)
1960 `params` - for request parameters / arguments / captures
1961 and `uploads` - for request upload filenames.
1967 Join #catalyst on irc.perl.org.
1971 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
1972 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
1976 http://catalyst.perl.org
1980 http://dev.catalyst.perl.org
1984 ## [Task::Catalyst](https://metacpan.org/pod/Task::Catalyst) - All you need to start with Catalyst
1986 ## [Catalyst::Manual](https://metacpan.org/pod/Catalyst::Manual) - The Catalyst Manual
1988 ## [Catalyst::Component](https://metacpan.org/pod/Catalyst::Component), [Catalyst::Controller](https://metacpan.org/pod/Catalyst::Controller) - Base classes for components
1990 ## [Catalyst::Engine](https://metacpan.org/pod/Catalyst::Engine) - Core engine
1992 ## [Catalyst::Log](https://metacpan.org/pod/Catalyst::Log) - Log class.
1994 ## [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request) - Request object
1996 ## [Catalyst::Response](https://metacpan.org/pod/Catalyst::Response) - Response object
1998 ## [Catalyst::Test](https://metacpan.org/pod/Catalyst::Test) - The test suite.
2002 sri: Sebastian Riedel <sri@cpan.org>
2008 acme: Leon Brocard <leon@astray.com>
2010 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
2012 andrewalker: André Walker <andre@cpan.org>
2016 Andrew Ford <A.Ford@ford-mason.co.uk>
2020 andyg: Andy Grundman <andy@hybridized.org>
2022 audreyt: Audrey Tang
2024 bricas: Brian Cassidy <bricas@cpan.org>
2026 Caelum: Rafael Kitover <rkitover@io.com>
2028 chansen: Christian Hansen
2030 chicks: Christopher Hicks
2032 Chisel Wright `pause@herlpacker.co.uk`
2034 Danijel Milicevic `me@danijel.de`
2036 davewood: David Schmidt <davewood@cpan.org>
2038 David Kamholz <dkamholz@cpan.org>
2040 David Naughton, `naughton@umn.edu`
2044 dhoss: Devin Austin <dhoss@cpan.org>
2046 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
2050 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
2052 esskar: Sascha Kiefer
2054 fireartist: Carl Franks <cfranks@cpan.org>
2056 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
2058 gabb: Danijel Milicevic
2062 Gavin Henry `ghenry@perl.me.uk`
2066 groditi: Guillermo Roditi <groditi@gmail.com>
2068 hobbs: Andrew Rodland <andrew@cleverdomain.org>
2070 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
2072 jcamacho: Juan Camacho
2074 jester: Jesse Sheidlower `jester@panix.com`
2076 jhannah: Jay Hannah <jay@jays.net>
2082 jon: Jon Schutz <jjschutz@cpan.org>
2084 Jonathan Rockway `<jrockway@cpan.org>`
2086 Kieren Diment `kd@totaldatasolution.com`
2088 konobi: Scott McWhirter <konobi@cpan.org>
2090 marcus: Marcus Ramberg <mramberg@cpan.org>
2092 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
2094 mgrimes: Mark Grimes <mgrimes@cpan.org>
2096 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
2100 naughton: David Naughton
2102 ningu: David Kamholz <dkamholz@cpan.org>
2104 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
2106 numa: Dan Sully <daniel@cpan.org>
2112 omega: Andreas Marienborg
2114 Oleg Kostyuk <cub.uanic@gmail.com>
2116 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
2118 rafl: Florian Ragwitz <rafl@debian.org>
2120 random: Roland Lammel <lammel@cpan.org>
2122 Robert Sedlacek `<rs@474.at>`
2124 SpiceMan: Marcel Montes
2128 szbalint: Balint Szilakszi <szbalint@cpan.org>
2130 t0m: Tomas Doran <bobtfish@bobtfish.net>
2134 vanstyn: Henry Van Styn <vanstyn@cpan.org>
2136 Viljo Marrandi `vilts@yahoo.com`
2138 Will Hawes `info@whawes.co.uk`
2140 willert: Sebastian Willert <willert@cpan.org>
2142 wreis: Wallace Reis <wreis@cpan.org>
2144 Yuval Kogman, `nothingmuch@woobling.org`
2146 rainboxx: Matthias Dietrich, `perl@rainboxx.de`
2148 dd070: Dhaval Dhanani <dhaval070@gmail.com>
2150 Upasana <me@upasana.me>
2152 John Napiorkowski (jnap) <jjnapiork@cpan.org>
2156 Copyright (c) 2005-2015, the above named PROJECT FOUNDER and CONTRIBUTORS.
2160 This library is free software. You can redistribute it and/or modify it under
2161 the same terms as Perl itself.