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 # Building Catalyst for development
18 cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
19 cpanm --installdeps --with-develop .
22 # Install Catalyst::Devel for helpers and other development tools
23 # use the helper to create a new application
26 # add models, views, controllers
27 script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
28 script/myapp_create.pl view MyTemplate TT
29 script/myapp_create.pl controller Search
31 # built in testserver -- use -r to restart automatically on changes
32 # --help to see all available options
33 script/myapp_server.pl
35 # command line testing interface
36 script/myapp_test.pl /yada
39 use Catalyst qw/-Debug/; # include plugins here as well
41 ### In lib/MyApp/Controller/Root.pm (autocreated)
42 sub foo : Chained('/') Args() { # called for /foo, /foo/1, /foo/1/2, etc.
43 my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
44 $c->stash->{template} = 'foo.tt'; # set the template
45 # lookup something from db -- stash vars are passed to TT
47 $c->model('Database::Foo')->search( { country => $args[0] } );
48 if ( $c->req->params->{bar} ) { # access GET or POST parameters
49 $c->forward( 'bar' ); # process another action
50 # do something else after forward returns
54 # The foo.tt TT template can use the stash data from the database
55 [% WHILE (item = data.next) %]
59 # called for /bar/of/soap, /bar/of/soap/10, etc.
60 sub bar : Chained('/') PathPart('/bar/of/soap') Args() { ... }
62 # called after all actions are finished
64 my ( $self, $c ) = @_;
65 if ( scalar @{ $c->error } ) { ... } # handle errors
66 return if $c->res->body; # already have a response
67 $c->forward( 'MyApp::View::TT' ); # render template
70 See [Catalyst::Manual::Intro](https://metacpan.org/pod/Catalyst::Manual::Intro) for additional information.
74 Catalyst is a modern framework for making web applications without the
75 pain usually associated with this process. This document is a reference
76 to the main Catalyst application. If you are a new user, we suggest you
77 start with [Catalyst::Manual::Tutorial](https://metacpan.org/pod/Catalyst::Manual::Tutorial) or [Catalyst::Manual::Intro](https://metacpan.org/pod/Catalyst::Manual::Intro).
79 See [Catalyst::Manual](https://metacpan.org/pod/Catalyst::Manual) for more documentation.
81 Catalyst plugins can be loaded by naming them as arguments to the "use
82 Catalyst" statement. Omit the `Catalyst::Plugin::` prefix from the
83 plugin name, i.e., `Catalyst::Plugin::My::Module` becomes
86 use Catalyst qw/My::Module/;
88 If your plugin starts with a name other than `Catalyst::Plugin::`, you can
89 fully qualify the name by using a unary plus:
93 +Fully::Qualified::Plugin::Name
96 Special flags like `-Debug` can also be specified as
97 arguments when Catalyst is loaded:
99 use Catalyst qw/-Debug My::Module/;
101 The position of plugins and flags in the chain is important, because
102 they are loaded in the order in which they appear.
104 The following flags are supported:
108 Enables debug output. You can also force this setting from the system
109 environment with CATALYST\_DEBUG or <MYAPP>\_DEBUG. The environment
110 settings override the application, with <MYAPP>\_DEBUG having the highest
113 This sets the log level to 'debug' and enables full debug output on the
114 error screen. If you only want the latter, see [$c->debug](https://metacpan.org/pod/$c->debug).
118 Forces Catalyst to use a specific home directory, e.g.:
120 use Catalyst qw[-Home=/usr/mst];
122 This can also be done in the shell environment by setting either the
123 `CATALYST_HOME` environment variable or `MYAPP_HOME`; where `MYAPP`
124 is replaced with the uppercased name of your application, any "::" in
125 the name will be replaced with underscores, e.g. MyApp::Web should use
126 MYAPP\_WEB\_HOME. If both variables are set, the MYAPP\_HOME one will be used.
128 If none of these are set, Catalyst will attempt to automatically detect the
129 home directory. If you are working in a development environment, Catalyst
130 will try and find the directory containing either Makefile.PL, Build.PL,
131 dist.ini, or cpanfile. If the application has been installed into the system
132 (i.e. you have done `make install`), then Catalyst will use the path to your
133 application module, without the .pm extension (e.g., /foo/MyApp if your
134 application was installed at /foo/MyApp.pm)
138 use Catalyst '-Log=warn,fatal,error';
140 Specifies a comma-delimited list of log levels.
144 Enables statistics collection and reporting.
146 use Catalyst qw/-Stats=1/;
148 You can also force this setting from the system environment with CATALYST\_STATS
149 or <MYAPP>\_STATS. The environment settings override the application, with
150 <MYAPP>\_STATS having the highest priority.
152 Stats are also enabled if [debugging ](#debug) is enabled.
156 ## INFORMATION ABOUT THE CURRENT REQUEST
160 Returns a [Catalyst::Action](https://metacpan.org/pod/Catalyst::Action) object for the current action, which
161 stringifies to the action name. See [Catalyst::Action](https://metacpan.org/pod/Catalyst::Action).
165 Returns the namespace of the current action, i.e., the URI prefix
166 corresponding to the controller of the current action. For example:
168 # in Controller::Foo::Bar
169 $c->namespace; # returns 'foo/bar';
175 Returns the current [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request) object, giving access to
176 information about the current client request (including parameters,
177 cookies, HTTP headers, etc.). See [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request).
179 ## REQUEST FLOW HANDLING
181 ## $c->forward( $action \[, \\@arguments \] )
183 ## $c->forward( $class, $method, \[, \\@arguments \] )
185 This is one way of calling another action (method) in the same or
186 a different controller. You can also use `$self->my_method($c, @args)`
187 in the same controller or `$c->controller('MyController')->my_method($c, @args)`
188 in a different controller.
189 The main difference is that 'forward' uses some of the Catalyst request
190 cycle overhead, including debugging, which may be useful to you. On the
191 other hand, there are some complications to using 'forward', restrictions
192 on values returned from 'forward', and it may not handle errors as you prefer.
193 Whether you use 'forward' or not is up to you; it is not considered superior to
194 the other ways to call a method.
196 'forward' calls another action, by its private name. If you give a
197 class name but no method, `process()` is called. You may also optionally
198 pass arguments in an arrayref. The action will receive the arguments in
199 `@_` and `$c->req->args`. Upon returning from the function,
200 `$c->req->args` will be restored to the previous values.
202 Any data `return`ed from the action forwarded to, will be returned by the
205 my $foodata = $c->forward('/foo');
206 $c->forward('index');
207 $c->forward(qw/Model::DBIC::Foo do_stuff/);
208 $c->forward('View::TT');
210 Note that [forward](#c-forward-action-arguments) implies
211 an `eval { }` around the call (actually
212 [execute](#c-execute-class-coderef) does), thus rendering all
213 exceptions thrown by the called action non-fatal and pushing them onto
214 $c->error instead. If you want `die` to propagate you need to do something
218 die join "\n", @{ $c->error } if @{ $c->error };
220 Or make sure to always return true values from your actions and write
223 $c->forward('foo') || return;
225 Another note is that `$c->forward` always returns a scalar because it
226 actually returns $c->state which operates in a scalar context.
227 Thus, something like:
231 in an action that is forwarded to is going to return a scalar,
232 i.e. how many items are in that array, which is probably not what you want.
233 If you need to return an array then return a reference to it,
236 $c->stash->{array} = \@array;
238 and access it from the stash.
240 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.
242 ## $c->detach( $action \[, \\@arguments \] )
244 ## $c->detach( $class, $method, \[, \\@arguments \] )
248 The same as [forward](#c-forward-action-arguments), but
249 doesn't return to the previous action when processing is finished.
251 When called with no arguments it escapes the processing chain entirely.
253 ## $c->visit( $action \[, \\@arguments \] )
255 ## $c->visit( $action \[, \\@captures, \\@arguments \] )
257 ## $c->visit( $class, $method, \[, \\@arguments \] )
259 ## $c->visit( $class, $method, \[, \\@captures, \\@arguments \] )
261 Almost the same as [forward](#c-forward-action-arguments),
262 but does a full dispatch, instead of just calling the new `$action` /
263 `$class->$method`. This means that `begin`, `auto` and the method
264 you go to are called, just like a new request.
266 In addition both `$c->action` and `$c->namespace` are localized.
267 This means, for example, that `$c->action` methods such as
268 [name](https://metacpan.org/pod/Catalyst::Action#name), [class](https://metacpan.org/pod/Catalyst::Action#class) and
269 [reverse](https://metacpan.org/pod/Catalyst::Action#reverse) return information for the visited action
270 when they are invoked within the visited action. This is different from the
271 behavior of [forward](#c-forward-action-arguments), which
272 continues to use the $c->action object from the caller action even when
273 invoked from the called action.
275 `$c->stash` is kept unchanged.
277 In effect, [visit](#c-visit-action-captures-arguments)
278 allows you to "wrap" another action, just as it would have been called by
279 dispatching from a URL, while the analogous
280 [go](#c-go-action-captures-arguments) allows you to
281 transfer control to another action as if it had been reached directly from a URL.
283 ## $c->go( $action \[, \\@arguments \] )
285 ## $c->go( $action \[, \\@captures, \\@arguments \] )
287 ## $c->go( $class, $method, \[, \\@arguments \] )
289 ## $c->go( $class, $method, \[, \\@captures, \\@arguments \] )
291 The relationship between `go` and
292 [visit](#c-visit-action-captures-arguments) is the same as
293 the relationship between
294 [forward](#c-forward-class-method-arguments) and
295 [detach](#c-detach-action-arguments). Like `$c->visit`,
296 `$c->go` will perform a full dispatch on the specified action or method,
297 with localized `$c->action` and `$c->namespace`. Like `detach`,
298 `go` escapes the processing of the current request chain on completion, and
299 does not return to its cunless blessed $cunless blessed $caller.
301 @arguments are arguments to the final destination of $action. @captures are
302 arguments to the intermediate steps, if any, on the way to the final sub of
309 Returns the current [Catalyst::Response](https://metacpan.org/pod/Catalyst::Response) object, see there for details.
313 Returns a hashref to the stash, which may be used to store data and pass
314 it between components during a request. You can also set hash keys by
315 passing arguments. The stash is automatically sent to the view. The
316 stash is cleared at the end of a request; it cannot be used for
317 persistent storage (for this you must use a session; see
318 [Catalyst::Plugin::Session](https://metacpan.org/pod/Catalyst::Plugin::Session) for a complete system integrated with
321 $c->stash->{foo} = $bar;
322 $c->stash( { moose => 'majestic', qux => 0 } );
323 $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
325 # stash is automatically passed to the view for use in a template
326 $c->forward( 'MyApp::View::TT' );
328 The stash hash is currently stored in the PSGI `$env` and is managed by
329 [Catalyst::Middleware::Stash](https://metacpan.org/pod/Catalyst::Middleware::Stash). Since it's part of the `$env` items in
330 the stash can be accessed in sub applications mounted under your main
331 [Catalyst](https://metacpan.org/pod/Catalyst) application. For example if you delegate the response of an
332 action to another [Catalyst](https://metacpan.org/pod/Catalyst) application, that sub application will have
333 access to all the stash keys of the main one, and if can of course add
334 more keys of its own. However those new keys will not 'bubble' back up
335 to the main application.
337 For more information the best thing to do is to review the test case:
338 t/middleware-stash.t in the distribution /t directory.
342 ## $c->error($error, ...)
344 ## $c->error($arrayref)
346 Returns an arrayref containing error messages. If Catalyst encounters an
347 error while processing a request, it stores the error in $c->error. This
348 method should only be used to store fatal error messages.
350 my @error = @{ $c->error };
354 $c->error('Something bad happened');
356 Calling this will always return an arrayref (if there are no errors it
357 will be an empty arrayref.
361 Contains the return value of the last executed action.
362 Note that << $c->state >> operates in a scalar context which means that all
363 values it returns are scalar.
367 Clear errors. You probably don't want to clear the errors unless you are
368 implementing a custom error screen.
370 This is equivalent to running
376 Returns true if you have errors
380 Returns the most recent error in the stack (the one most recently added...)
381 or nothing if there are no errors.
385 shifts the most recently added error off the error stack and returns if. Returns
386 nothing if there are no more errors.
388 ## COMPONENT ACCESSORS
390 ## $c->controller($name)
392 Gets a [Catalyst::Controller](https://metacpan.org/pod/Catalyst::Controller) instance by name.
394 $c->controller('Foo')->do_stuff;
396 If the name is omitted, will return the controller for the dispatched
399 If you want to search for controllers, pass in a regexp as the argument.
401 # find all controllers that start with Foo
402 my @foo_controllers = $c->controller(qr{^Foo});
406 Gets a [Catalyst::Model](https://metacpan.org/pod/Catalyst::Model) instance by name.
408 $c->model('Foo')->do_stuff;
410 Any extra arguments are directly passed to ACCEPT\_CONTEXT, if the model
411 defines ACCEPT\_CONTEXT. If it does not, the args are discarded.
413 If the name is omitted, it will look for
414 - a model object in $c->stash->{current\_model\_instance}, then
415 - a model name in $c->stash->{current\_model}, then
416 - a config setting 'default\_model', or
417 - check if there is only one model, and return it if that's the case.
419 If you want to search for models, pass in a regexp as the argument.
421 # find all models that start with Foo
422 my @foo_models = $c->model(qr{^Foo});
426 Gets a [Catalyst::View](https://metacpan.org/pod/Catalyst::View) instance by name.
428 $c->view('Foo')->do_stuff;
430 Any extra arguments are directly passed to ACCEPT\_CONTEXT.
432 If the name is omitted, it will look for
433 - a view object in $c->stash->{current\_view\_instance}, then
434 - a view name in $c->stash->{current\_view}, then
435 - a config setting 'default\_view', or
436 - check if there is only one view, and return it if that's the case.
438 If you want to search for views, pass in a regexp as the argument.
440 # find all views that start with Foo
441 my @foo_views = $c->view(qr{^Foo});
445 Returns the available names which can be passed to $c->controller
449 Returns the available names which can be passed to $c->model
453 Returns the available names which can be passed to $c->view
457 ## $c->component($name)
459 Gets a component object by name. This method is not recommended,
460 unless you want to get a specific component by full
461 class. `$c->controller`, `$c->model`, and `$c->view`
462 should be used instead.
464 If `$name` is a regexp, a list of components matched against the full
465 component name will be returned.
467 If Catalyst can't find a component by name, it will fallback to regex
468 matching by default. To disable this behaviour set
469 disable\_component\_resolution\_regex\_fallback to a true value.
471 __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );
473 ## CLASS DATA AND HELPER CLASSES
477 Returns or takes a hashref containing the application's configuration.
479 __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
481 You can also use a `YAML`, `XML` or [Config::General](https://metacpan.org/pod/Config::General) config file
482 like `myapp.conf` in your applications home directory. See
483 [Catalyst::Plugin::ConfigLoader](https://metacpan.org/pod/Catalyst::Plugin::ConfigLoader).
485 ### Cascading configuration
487 The config method is present on all Catalyst components, and configuration
488 will be merged when an application is started. Configuration loaded with
489 [Catalyst::Plugin::ConfigLoader](https://metacpan.org/pod/Catalyst::Plugin::ConfigLoader) takes precedence over other configuration,
490 followed by configuration in your top level `MyApp` class. These two
491 configurations are merged, and then configuration data whose hash key matches a
492 component name is merged with configuration for that component.
494 The configuration for a component is then passed to the `new` method when a
495 component is constructed.
499 MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
500 MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });
502 will mean that `MyApp::Model::Foo` receives the following data when
505 MyApp::Model::Foo->new({
511 It's common practice to use a Moose attribute
512 on the receiving component to access the config value.
514 package MyApp::Model::Foo;
518 # this attr will receive 'baz' at construction time
524 You can then get the value 'baz' by calling $c->model('Foo')->bar
525 (or $self->bar inside code in the model).
527 **NOTE:** you MUST NOT call `$self->config` or `__PACKAGE__->config`
528 as a way of reading config within your code, as this **will not** give you the
529 correctly merged config back. You **MUST** take the config values supplied to
530 the constructor and use those instead.
534 Returns the logging object instance. Unless it is already set, Catalyst
535 sets this up with a [Catalyst::Log](https://metacpan.org/pod/Catalyst::Log) object. To use your own log class,
536 set the logger with the `__PACKAGE__->log` method prior to calling
537 `__PACKAGE__->setup`.
539 __PACKAGE__->log( MyLogger->new );
544 $c->log->info( 'Now logging with my own logger!' );
546 Your log class should implement the methods described in
547 [Catalyst::Log](https://metacpan.org/pod/Catalyst::Log).
551 Returned True if there's a valid encoding
555 Clears the encoding for the current context
559 Sets or gets the application encoding. Setting encoding takes either an
560 Encoding object or a string that we try to resolve via [Encode::find\_encoding](https://metacpan.org/pod/Encode::find_encoding).
562 You would expect to get the encoding object back if you attempt to set it. If
563 there is a failure you will get undef returned and an error message in the log.
567 Returns 1 if debug mode is enabled, 0 otherwise.
569 You can enable debug mode in several ways:
571 - By calling myapp\_server.pl with the -d flag
572 - With the environment variables MYAPP\_DEBUG, or CATALYST\_DEBUG
573 - The -Debug option in your MyApp.pm
574 - By declaring `sub debug { 1 }` in your MyApp.pm.
576 The first three also set the log level to 'debug'.
578 Calling `$c->debug(1)` has no effect.
582 Returns the dispatcher instance. See [Catalyst::Dispatcher](https://metacpan.org/pod/Catalyst::Dispatcher).
586 Returns the engine instance. See [Catalyst::Engine](https://metacpan.org/pod/Catalyst::Engine).
590 ## $c->path\_to(@path)
592 Merges `@path` with `$c->config->{home}` and returns a
593 [Path::Class::Dir](https://metacpan.org/pod/Path::Class::Dir) object. Note you can usually use this object as
594 a filename, but sometimes you will have to explicitly stringify it
595 yourself by calling the `->stringify` method.
599 $c->path_to( 'db', 'sqlite.db' );
603 Initializes the dispatcher and engine, loads any plugins, and loads the
604 model, view, and controller components. You may also specify an array
605 of plugins to load here, if you choose to not load them in the `use
609 MyApp->setup( qw/-Debug/ );
611 **Note:** You **should not** wrap this method with method modifiers
612 or bad things will happen - wrap the `setup_finalize` method instead.
614 **Note:** You can create a custom setup stage that will execute when the
615 application is starting. Use this to customize setup.
617 MyApp->setup(-Custom=value);
620 my ($class, $value) = @_;
623 Can be handy if you want to hook into the setup phase.
625 ## $app->setup\_finalize
627 A hook to attach modifiers to. This method does not do anything except set the
628 `setup_finished` accessor.
630 Applying method modifiers to the `setup` method doesn't work, because of quirky things done for plugin setup.
634 after setup_finalize => sub {
640 ## $c->uri\_for( $path?, @args?, \\%query\_values? )
642 ## $c->uri\_for( $action, \\@captures?, @args?, \\%query\_values? )
644 ## $c->uri\_for( $action, \[@captures, @args\], \\%query\_values? )
646 Constructs an absolute [URI](https://metacpan.org/pod/URI) object based on the application root, the
647 provided path, and the additional arguments and query parameters provided.
648 When used as a string, provides a textual URI. If you need more flexibility
649 than this (i.e. the option to provide relative URIs etc.) see
650 [Catalyst::Plugin::SmartURI](https://metacpan.org/pod/Catalyst::Plugin::SmartURI).
652 If no arguments are provided, the URI for the current action is returned.
653 To return the current action and also provide @args, use
654 `$c->uri_for( $c->action, @args )`.
656 If the first argument is a string, it is taken as a public URI path relative
657 to `$c->namespace` (if it doesn't begin with a forward slash) or
658 relative to the application root (if it does). It is then merged with
659 `$c->request->base`; any `@args` are appended as additional path
660 components; and any `%query_values` are appended as `?foo=bar` parameters.
662 If the first argument is a [Catalyst::Action](https://metacpan.org/pod/Catalyst::Action) it represents an action which
663 will have its path resolved using `$c->dispatcher->uri_for_action`. The
664 optional `\@captures` argument (an arrayref) allows passing the captured
665 variables that are needed to fill in the paths of Chained and Regex actions;
666 once the path is resolved, `uri_for` continues as though a path was
667 provided, appending any arguments or parameters and creating an absolute
670 The captures for the current request can be found in
671 `$c->request->captures`, and actions can be resolved using
672 `Catalyst::Controller->action_for($name)`. If you have a private action
673 path, use `$c->uri_for_action` instead.
675 # Equivalent to $c->req->uri
676 $c->uri_for($c->action, $c->req->captures,
677 @{ $c->req->args }, $c->req->params);
679 # For the Foo action in the Bar controller
680 $c->uri_for($c->controller('Bar')->action_for('Foo'));
682 # Path to a static resource
683 $c->uri_for('/static/images/logo.png');
685 In general the scheme of the generated URI object will follow the incoming request
686 however if your targeted action or action chain has the Scheme attribute it will
689 Also, if the targeted Action or Action chain declares Args/CaptureArgs that have
690 type constraints, we will require that your proposed URL verify on those declared
693 ## $c->uri\_for\_action( $path, \\@captures\_and\_args?, @args?, \\%query\_values? )
695 ## $c->uri\_for\_action( $action, \\@captures\_and\_args?, @args?, \\%query\_values? )
699 A private path to the Catalyst action you want to create a URI for.
701 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`.
703 You can also pass in a Catalyst::Action object, in which case it is passed to
706 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.
708 For example, if the action looks like:
710 package MyApp::Controller::Users;
712 sub lst : Path('the-list') {}
716 $c->uri_for_action('/users/lst')
718 and it will create the URI /users/the-list.
720 - \\@captures\_and\_args?
722 Optional array reference of Captures (i.e. `<CaptureArgs or $c-`req->captures>)
723 and arguments to the request. Usually used with [Catalyst::DispatchType::Chained](https://metacpan.org/pod/Catalyst::DispatchType::Chained)
724 to interpolate all the parameters in the URI.
728 Optional list of extra arguments - can be supplied in the
729 `\@captures_and_args?` array ref, or here - whichever is easier for your
732 Your action can have zero, a fixed or a variable number of args (e.g.
733 `Args(1)` for a fixed number or `Args()` for a variable number)..
737 Optional array reference of query parameters to append. E.g.
743 /rest/of/your/uri?foo=bar
745 ## $c->welcome\_message
747 Returns the Catalyst welcome HTML page.
751 Contains a hash of options passed from the application script, including
752 the original ARGV the script received, the processed values from that
753 ARGV and any extra arguments to the script which were not processed.
755 This can be used to add custom options to your application's scripts
756 and setup your application differently depending on the values of these
761 These methods are not meant to be used by end users.
765 Returns a hash of components.
767 ## $c->context\_class
769 Returns or sets the context class.
773 Returns a hashref containing coderefs and execution counts (needed for
774 deep recursion detection).
778 Returns the number of actions on the current internal execution stack.
782 Dispatches a request to actions.
784 ## $c->dispatcher\_class
786 Returns or sets the dispatcher class.
790 Returns a list of 2-element array references (name, structure) pairs
791 that will be dumped on the error page in debug mode.
795 Returns or sets the engine class.
797 ## $c->execute( $class, $coderef )
799 Execute a coderef in given class and catch exceptions. Errors are available
804 Finalizes the request.
806 ## $c->finalize\_body
810 ## $c->finalize\_cookies
814 ## $c->finalize\_error
816 Finalizes error. If there is only one error in ["error"](#error) and it is an object that
817 does `as_psgi` or `code` we rethrow the error and presume it caught by middleware
818 up the ladder. Otherwise we return the debugging error page (in debug mode) or we
819 return the default error page (production mode).
821 ## $c->finalize\_headers
825 ## $c->finalize\_encoding
827 Make sure your body is encoded properly IF you set an encoding. By
828 default the encoding is UTF-8 but you can disable it by explicitly setting the
829 encoding configuration value to undef.
831 We can only encode when the body is a scalar. Methods for encoding via the
832 streaming interfaces (such as `write` and `write_fh` on [Catalyst::Response](https://metacpan.org/pod/Catalyst::Response)
835 See ["ENCODING"](#encoding).
837 ## $c->finalize\_output
839 An alias for finalize\_body.
841 ## $c->finalize\_read
843 Finalizes the input after reading is complete.
845 ## $c->finalize\_uploads
847 Finalizes uploads. Cleans up any temporary files.
849 ## $c->get\_action( $action, $namespace )
851 Gets an action in a given namespace.
853 ## $c->get\_actions( $action, $namespace )
855 Gets all actions of a given name in a namespace and all parent
858 ## $app->handle\_request( @arguments )
860 Called to handle each HTTP request.
862 ## $class->prepare( @arguments )
864 Creates a Catalyst context from an engine-specific request (Apache, CGI,
867 ## $c->prepare\_action
869 Prepares action. See [Catalyst::Dispatcher](https://metacpan.org/pod/Catalyst::Dispatcher).
873 Prepares message body.
875 ## $c->prepare\_body\_chunk( $chunk )
877 Prepares a chunk of data before sending it to [HTTP::Body](https://metacpan.org/pod/HTTP::Body).
879 See [Catalyst::Engine](https://metacpan.org/pod/Catalyst::Engine).
881 ## $c->prepare\_body\_parameters
883 Prepares body parameters.
885 ## $c->prepare\_connection
889 ## $c->prepare\_cookies
891 Prepares cookies by ensuring that the attribute on the request
892 object has been built.
894 ## $c->prepare\_headers
896 Prepares request headers by ensuring that the attribute on the request
897 object has been built.
899 ## $c->prepare\_parameters
905 Prepares path and base.
907 ## $c->prepare\_query\_parameters
909 Prepares query parameters.
913 Writes information about the request to the debug logs. This includes:
915 - Request method, path, and remote IP address
916 - Query keywords (see ["query\_keywords" in Catalyst::Request](https://metacpan.org/pod/Catalyst::Request#query_keywords))
922 Writes information about the response to the debug logs by calling
923 `$c->log_response_status_line` and `$c->log_response_headers`.
925 ## $c->log\_response\_status\_line($response)
927 Writes one line of information about the response to the debug logs. This includes:
929 - Response status code
930 - Content-Type header (if present)
931 - Content-Length header (if present)
933 ## $c->log\_response\_headers($headers);
935 Hook method which can be wrapped by plugins to log the response headers.
936 No-op in the default implementation.
938 ## $c->log\_request\_parameters( query => {}, body => {} )
940 Logs request parameters to debug logs
942 ## $c->log\_request\_uploads
944 Logs file uploads included in the request to the debug logs.
945 The parameter name, filename, file type, and file size are all included in
948 ## $c->log\_request\_headers($headers);
950 Hook method which can be wrapped by plugins to log the request headers.
951 No-op in the default implementation.
953 ## $c->log\_headers($type => $headers)
955 Logs [HTTP::Headers](https://metacpan.org/pod/HTTP::Headers) (either request or response) to the debug logs.
959 Prepares the input for reading.
961 ## $c->prepare\_request
963 Prepares the engine request.
965 ## $c->prepare\_uploads
969 ## $c->prepare\_write
971 Prepares the output for writing.
973 ## $c->request\_class
975 Returns or sets the request class. Defaults to [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request).
977 ## $app->request\_class\_traits
979 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the request class.
981 ## $app->composed\_request\_class
983 This is the request class which has been composed with any request\_class\_traits.
985 ## $c->response\_class
987 Returns or sets the response class. Defaults to [Catalyst::Response](https://metacpan.org/pod/Catalyst::Response).
989 ## $app->response\_class\_traits
991 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the response class.
993 ## $app->composed\_response\_class
995 This is the request class which has been composed with any response\_class\_traits.
997 ## $c->read( \[$maxlength\] )
999 Reads a chunk of data from the request body. This method is designed to
1000 be used in a while loop, reading `$maxlength` bytes on every call.
1001 `$maxlength` defaults to the size of the request if not specified.
1003 You have to set `MyApp->config(parse_on_demand => 1)` to use this
1006 Warning: If you use read(), Catalyst will not process the body,
1007 so you will not be able to access POST parameters or file uploads via
1008 $c->request. You must handle all body parsing yourself.
1014 ## $c->set\_action( $action, $code, $namespace, $attrs )
1016 Sets an action in a given namespace.
1018 ## $c->setup\_actions($component)
1020 Sets up actions for a component.
1022 ## $c->setup\_components
1024 This method is called internally to set up the application's components.
1026 It finds modules by calling the [locate\_components](https://metacpan.org/pod/locate_components) method, expands them to
1027 package names with the [expand\_component\_module](https://metacpan.org/pod/expand_component_module) method, and then installs
1028 each component into the application.
1030 The `setup_components` config option is passed to both of the above methods.
1032 Installation of each component is performed by the [setup\_component](https://metacpan.org/pod/setup_component) method,
1035 ## $app->setup\_injected\_components
1037 Called by setup\_compoents to setup components that are injected.
1039 ## $app->setup\_injected\_component( $injected\_component\_name, $config )
1041 Setup a given injected component.
1043 ## $app->inject\_component($MyApp\_Component\_name => \\%args);
1045 Add a component that is injected at setup:
1047 MyApp->inject_component( 'Model::Foo' => { from_component => 'Common::Foo' } );
1049 Must be called before ->setup. Expects a component name for your
1050 current application and \\%args where
1054 The target component being injected into your application
1058 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that are applied to your component.
1062 MyApp->inject_component(
1064 from_component => 'Common::Model::Foo',
1065 roles => ['Role1', 'Role2'],
1068 ## $app->inject\_components
1070 Inject a list of components:
1072 MyApp->inject_components(
1073 'Model::FooOne' => {
1074 from_component => 'Common::Model::Foo',
1075 roles => ['Role1', 'Role2'],
1077 'Model::FooTwo' => {
1078 from_component => 'Common::Model::Foo',
1079 roles => ['Role1', 'Role2'],
1082 ## $c->locate\_components( $setup\_component\_config )
1084 This method is meant to provide a list of component modules that should be
1085 setup for the application. By default, it will use [Module::Pluggable](https://metacpan.org/pod/Module::Pluggable).
1087 Specify a `setup_components` config option to pass additional options directly
1088 to [Module::Pluggable](https://metacpan.org/pod/Module::Pluggable). To add additional search paths, specify a key named
1089 `search_extra` as an array reference. Items in the array beginning with `::`
1090 will have the application class name prepended to them.
1092 ## $c->expand\_component\_module( $component, $setup\_component\_config )
1094 Components found by `locate_components` will be passed to this method, which
1095 is expected to return a list of component (package) names to be set up.
1097 ## $app->delayed\_setup\_component
1099 Returns a coderef that points to a setup\_component instance. Used
1100 internally for when you want to delay setup until the first time
1101 the component is called.
1103 ## $c->setup\_component
1105 ## $app->config\_for( $component\_name )
1107 Return the application level configuration (which is not yet merged with any
1108 local component configuration, via $component\_class->config) for the named
1109 component or component object. Example:
1112 'Model::Foo' => { a => 1, b => 2},
1115 my $config = MyApp->config_for('MyApp::Model::Foo');
1117 In this case $config is the hashref ` {a=`1, b=>2} >.
1119 This is also handy for looking up configuration for a plugin, to make sure you follow
1120 existing [Catalyst](https://metacpan.org/pod/Catalyst) standards for where a plugin should put its configuration.
1122 ## $c->setup\_dispatcher
1126 ## $c->setup\_engine
1130 ## $c->apply\_default\_middlewares
1132 Adds the following [Plack](https://metacpan.org/pod/Plack) middlewares to your application, since they are
1133 useful and commonly needed:
1135 [Plack::Middleware::LighttpdScriptNameFix](https://metacpan.org/pod/Plack::Middleware::LighttpdScriptNameFix) (if you are using Lighttpd),
1136 [Plack::Middleware::IIS6ScriptNameFix](https://metacpan.org/pod/Plack::Middleware::IIS6ScriptNameFix) (always applied since this middleware
1137 is smart enough to conditionally apply itself).
1139 We will also automatically add [Plack::Middleware::ReverseProxy](https://metacpan.org/pod/Plack::Middleware::ReverseProxy) if we notice
1140 that your HTTP $env variable `REMOTE_ADDR` is '127.0.0.1'. This is usually
1141 an indication that your server is running behind a proxy frontend. However in
1142 2014 this is often not the case. We preserve this code for backwards compatibility
1143 however I **highly** recommend that if you are running the server behind a front
1144 end proxy that you clearly indicate so with the `using_frontend_proxy` configuration
1145 setting to true for your environment configurations that run behind a proxy. This
1146 way if you change your front end proxy address someday your code would inexplicably
1147 stop working as expected.
1149 Additionally if we detect we are using Nginx, we add a bit of custom middleware
1150 to solve some problems with the way that server handles $ENV{PATH\_INFO} and
1153 Please **NOTE** that if you do use `using_frontend_proxy` the middleware is now
1154 adding via `registered_middleware` rather than this method.
1156 If you are using Lighttpd or IIS6 you may wish to apply these middlewares. In
1157 general this is no longer a common case but we have this here for backward
1164 Returns a PSGI application code reference for the catalyst application
1165 `$c`. This is the bare application created without the `apply_default_middlewares`
1166 method called. We do however apply `registered_middleware` since those are
1167 integral to how [Catalyst](https://metacpan.org/pod/Catalyst) functions. Also, unlike starting your application
1168 with a generated server script (via [Catalyst::Devel](https://metacpan.org/pod/Catalyst::Devel) and `catalyst.pl`) we do
1169 not attempt to return a valid [PSGI](https://metacpan.org/pod/PSGI) application using any existing `${myapp}.psgi`
1170 scripts in your $HOME directory.
1172 **NOTE** `apply_default_middlewares` was originally created when the first PSGI
1173 port was done for v5.90000. These are middlewares that are added to achieve
1174 backward compatibility with older applications. If you start your application
1175 using one of the supplied server scripts (generated with [Catalyst::Devel](https://metacpan.org/pod/Catalyst::Devel) and
1176 the project skeleton script `catalyst.pl`) we apply `apply_default_middlewares`
1177 automatically. This was done so that pre and post PSGI port applications would
1180 This is what you want to be using to retrieve the PSGI application code
1181 reference of your Catalyst application for use in a custom `.psgi` or in your
1182 own created server modules.
1186 Sets up the home directory.
1188 ## $c->setup\_encoding
1190 Sets up the input/output encoding. See [ENCODING](https://metacpan.org/pod/ENCODING)
1192 ## handle\_unicode\_encoding\_exception
1194 Hook to let you customize how encoding errors are handled. By default
1195 we just throw an exception. Receives a hashref of debug information.
1198 $c->handle_unicode_encoding_exception({
1199 param_value => $value,
1201 encoding_step => 'params',
1206 Sets up log by instantiating a [Catalyst::Log](https://metacpan.org/pod/Catalyst::Log) object and
1207 passing it to `log()`. Pass in a comma-delimited list of levels to set the
1210 This method also installs a `debug` method that returns a true value into the
1211 catalyst subclass if the "debug" level is passed in the comma-delimited list,
1212 or if the `$CATALYST_DEBUG` environment variable is set to a true value.
1214 Note that if the log has already been setup, by either a previous call to
1215 `setup_log` or by a call such as `__PACKAGE__->log( MyLogger->new )`,
1216 that this method won't actually set up the log object.
1218 ## $c->setup\_plugins
1224 Sets up timing statistics class.
1226 ## $c->registered\_plugins
1228 Returns a sorted list of the plugins which have either been stated in the
1231 If passed a given plugin name, it will report a boolean value indicating
1232 whether or not that plugin is loaded. A fully qualified name is required if
1233 the plugin name does not begin with `Catalyst::Plugin::`.
1235 if ($c->registered_plugins('Some::Plugin')) {
1239 ## default\_middleware
1241 Returns a list of instantiated PSGI middleware objects which is the default
1242 middleware that is active for this application (taking any configuration
1243 options into account, excluding your custom added middleware via the `psgi_middleware`
1244 configuration option). You can override this method if you wish to change
1245 the default middleware (although do so at risk since some middleware is vital
1246 to application function.)
1248 The current default middleware list is:
1250 Catalyst::Middleware::Stash
1251 Plack::Middleware::HTTPExceptions
1252 Plack::Middleware::RemoveRedundantBody
1253 Plack::Middleware::FixMissingBodyInRedirect
1254 Plack::Middleware::ContentLength
1255 Plack::Middleware::MethodOverride
1256 Plack::Middleware::Head
1258 If the configuration setting `using_frontend_proxy` is true we add:
1260 Plack::Middleware::ReverseProxy
1262 If the configuration setting `using_frontend_proxy_path` is true we add:
1264 Plack::Middleware::ReverseProxyPath
1266 But **NOTE** that [Plack::Middleware::ReverseProxyPath](https://metacpan.org/pod/Plack::Middleware::ReverseProxyPath) is not a dependency of the
1267 [Catalyst](https://metacpan.org/pod/Catalyst) distribution so if you want to use this option you should add it to
1268 your project distribution file.
1270 These middlewares will be added at ["setup\_middleware"](#setup_middleware) during the
1271 ["setup"](#setup) phase of application startup.
1273 ## registered\_middlewares
1275 Read only accessor that returns an array of all the middleware in the order
1276 that they were added (which is the REVERSE of the order they will be applied).
1278 The values returned will be either instances of [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware) or of a
1279 compatible interface, or a coderef, which is assumed to be inlined middleware
1281 ## setup\_middleware (?@middleware)
1283 Read configuration information stored in configuration key `psgi_middleware` or
1286 See under ["CONFIGURATION"](#configuration) information regarding `psgi_middleware` and how
1287 to use it to enable [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware)
1289 This method is automatically called during 'setup' of your application, so
1290 you really don't need to invoke it. However you may do so if you find the idea
1291 of loading middleware via configuration weird :). For example:
1297 __PACKAGE__->setup_middleware('Head');
1300 When we read middleware definitions from configuration, we reverse the list
1301 which sounds odd but is likely how you expect it to work if you have prior
1302 experience with [Plack::Builder](https://metacpan.org/pod/Plack::Builder) or if you previously used the plugin
1303 [Catalyst::Plugin::EnableMiddleware](https://metacpan.org/pod/Catalyst::Plugin::EnableMiddleware) (which is now considered deprecated)
1305 So basically your middleware handles an incoming request from the first
1306 registered middleware, down and handles the response from the last middleware
1309 ## registered\_data\_handlers
1311 A read only copy of registered Data Handlers returned as a Hash, where each key
1312 is a content type and each value is a subref that attempts to decode that content
1315 ## setup\_data\_handlers (?@data\_handler)
1317 Read configuration information stored in configuration key `data_handlers` or
1320 See under ["CONFIGURATION"](#configuration) information regarding `data_handlers`.
1322 This method is automatically called during 'setup' of your application, so
1323 you really don't need to invoke it.
1325 ## default\_data\_handlers
1327 Default Data Handlers that come bundled with [Catalyst](https://metacpan.org/pod/Catalyst). Currently there are
1328 only two default data handlers, for 'application/json' and an alternative to
1329 'application/x-www-form-urlencoded' which supposed nested form parameters via
1330 [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.
1332 The 'application/json' data handler is used to parse incoming JSON into a Perl
1333 data structure. It used either [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS) or [JSON](https://metacpan.org/pod/JSON), depending on which
1334 is installed. This allows you to fail back to [JSON:PP](JSON:PP), which is a Pure Perl
1335 JSON decoder, and has the smallest dependency impact.
1337 Because we don't wish to add more dependencies to [Catalyst](https://metacpan.org/pod/Catalyst), if you wish to
1338 use this new feature we recommend installing [JSON](https://metacpan.org/pod/JSON) or [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS) in
1339 order to get the best performance. You should add either to your dependency
1340 list (Makefile.PL, dist.ini, cpanfile, etc.)
1344 Returns an arrayref of the internal execution stack (actions that are
1345 currently executing).
1349 Returns the current timing statistics object. By default Catalyst uses
1350 [Catalyst::Stats](https://metacpan.org/pod/Catalyst::Stats), but can be set otherwise with
1351 [stats\_class](#c-stats_class).
1353 Even if [-Stats](#stats) is not enabled, the stats object is still
1354 available. By enabling it with ` $c-`stats->enabled(1) >, it can be used to
1355 profile explicitly, although MyApp.pm still won't profile nor output anything
1360 Returns or sets the stats (timing statistics) class. [Catalyst::Stats](https://metacpan.org/pod/Catalyst::Stats) is used by default.
1362 ## $app->stats\_class\_traits
1364 A arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that are applied to the stats\_class before creating it.
1366 ## $app->composed\_stats\_class
1368 this is the stats\_class composed with any 'stats\_class\_traits'.
1372 Returns 1 when [stats collection](#stats) is enabled.
1374 Note that this is a static method, not an accessor and should be overridden
1375 by declaring `sub use_stats { 1 }` in your MyApp.pm, not by calling `$c->use_stats(1)`.
1377 ## $c->write( $data )
1379 Writes $data to the output stream. When using this method directly, you
1380 will need to manually set the `Content-Length` header to the length of
1381 your output data, if known.
1385 Returns the Catalyst version number. Mostly useful for "powered by"
1386 messages in template systems.
1390 There are a number of 'base' config variables which can be set:
1392 - `always_catch_http_exceptions` - As of version 5.90060 Catalyst
1393 rethrows errors conforming to the interface described by
1394 [Plack::Middleware::HTTPExceptions](https://metacpan.org/pod/Plack::Middleware::HTTPExceptions) and lets the middleware deal with it.
1395 Set true to get the deprecated behaviour and have Catalyst catch HTTP exceptions.
1396 - `default_model` - The default model picked if you say `$c->model`. See ["$c->model($name)"](#c-model-name).
1397 - `default_view` - The default view to be rendered or returned when `$c->view` is called. See ["$c->view($name)"](#c-view-name).
1398 - `disable_component_resolution_regex_fallback` - Turns
1399 off the deprecated component resolution functionality so
1400 that if any of the component methods (e.g. `$c->controller('Foo')`)
1401 are called then regex search will not be attempted on string values and
1402 instead `undef` will be returned.
1403 - `home` - The application home directory. In an uninstalled application,
1404 this is the top level application directory. In an installed application,
1405 this will be the directory containing `MyApp.pm`.
1406 - `ignore_frontend_proxy` - See ["PROXY SUPPORT"](#proxy-support)
1407 - `name` - The name of the application in debug messages and the debug and
1409 - `parse_on_demand` - The request body (for example file uploads) will not be parsed
1410 until it is accessed. This allows you to (for example) check authentication (and reject
1411 the upload) before actually receiving all the data. See ["ON-DEMAND PARSER"](#on-demand-parser)
1412 - `root` - The root directory for templates. Usually this is just a
1413 subdirectory of the home directory, but you can set it to change the
1414 templates to a different directory.
1415 - `search_extra` - Array reference passed to Module::Pluggable to for additional
1416 namespaces from which components will be loaded (and constructed and stored in
1418 - `show_internal_actions` - If true, causes internal actions such as `_DISPATCH`
1419 to be shown in hit debug tables in the test server.
1420 - `use_request_uri_for_path` - Controls if the `REQUEST_URI` or `PATH_INFO` environment
1421 variable should be used for determining the request path.
1423 Most web server environments pass the requested path to the application using environment variables,
1424 from which Catalyst has to reconstruct the request base (i.e. the top level path to / in the application,
1425 exposed as `$c->request->base`) and the request path below that base.
1427 There are two methods of doing this, both of which have advantages and disadvantages. Which method is used
1428 is determined by the `$c->config(use_request_uri_for_path)` setting (which can either be true or false).
1430 - use\_request\_uri\_for\_path => 0
1432 This is the default (and the) traditional method that Catalyst has used for determining the path information.
1433 The path is generated from a combination of the `PATH_INFO` and `SCRIPT_NAME` environment variables.
1434 The allows the application to behave correctly when `mod_rewrite` is being used to redirect requests
1435 into the application, as these variables are adjusted by mod\_rewrite to take account for the redirect.
1437 However this method has the major disadvantage that it is impossible to correctly decode some elements
1438 of the path, as RFC 3875 says: "`Unlike a URI path, the PATH_INFO is not URL-encoded, and cannot
1439 contain path-segment parameters.`" This means PATH\_INFO is **always** decoded, and therefore Catalyst
1440 can't distinguish / vs %2F in paths (in addition to other encoded values).
1442 - use\_request\_uri\_for\_path => 1
1444 This method uses the `REQUEST_URI` and `SCRIPT_NAME` environment variables. As `REQUEST_URI` is never
1445 decoded, this means that applications using this mode can correctly handle URIs including the %2F character
1446 (i.e. with `AllowEncodedSlashes` set to `On` in Apache).
1448 Given that this method of path resolution is probably more correct, it is recommended that you use
1449 this unless you have a specific need to deploy your application in a non-standard environment, and you are
1450 aware of the implications of not being able to handle encoded URI paths correctly.
1452 However it also means that in a number of cases when the app isn't installed directly at a path, but instead
1453 is having paths rewritten into it (e.g. as a .cgi/fcgi in a public\_html directory, with mod\_rewrite in a
1454 .htaccess file, or when SSI is used to rewrite pages into the app, or when sub-paths of the app are exposed
1455 at other URIs than that which the app is 'normally' based at with `mod_rewrite`), the resolution of
1456 `$c->request->base` will be incorrect.
1458 - `using_frontend_proxy` - See ["PROXY SUPPORT"](#proxy-support).
1459 - `using_frontend_proxy_path` - Enabled [Plack::Middleware::ReverseProxyPath](https://metacpan.org/pod/Plack::Middleware::ReverseProxyPath) on your application (if
1460 installed, otherwise log an error). This is useful if your application is not running on the
1461 'root' (or /) of your host server. **NOTE** if you use this feature you should add the required
1462 middleware to your project dependency list since it's not automatically a dependency of [Catalyst](https://metacpan.org/pod/Catalyst).
1463 This has been done since not all people need this feature and we wish to restrict the growth of
1464 [Catalyst](https://metacpan.org/pod/Catalyst) dependencies.
1465 - `encoding` - See ["ENCODING"](#encoding)
1467 This now defaults to 'UTF-8'. You my turn it off by setting this configuration
1470 - `abort_chain_on_error_fix`
1472 When there is an error in an action chain, the default behavior is to continue
1473 processing the remaining actions and then catch the error upon chain end. This
1474 can lead to running actions when the application is in an unexpected state. If
1475 you have this issue, setting this config value to true will promptly exit a
1476 chain when there is an error raised in any action (thus terminating the chain
1481 __PACKAGE__->config(abort_chain_on_error_fix => 1);
1483 In the future this might become the default behavior.
1485 - `use_hash_multivalue_in_request`
1487 In [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request) the methods `query_parameters`, `body_parametes`
1488 and `parameters` return a hashref where values might be scalar or an arrayref
1489 depending on the incoming data. In many cases this can be undesirable as it
1490 leads one to writing defensive code like the following:
1492 my ($val) = ref($c->req->parameters->{a}) ?
1493 @{$c->req->parameters->{a}} :
1494 $c->req->parameters->{a};
1496 Setting this configuration item to true will make [Catalyst](https://metacpan.org/pod/Catalyst) populate the
1497 attributes underlying these methods with an instance of [Hash::MultiValue](https://metacpan.org/pod/Hash::MultiValue)
1498 which is used by [Plack::Request](https://metacpan.org/pod/Plack::Request) and others to solve this very issue. You
1499 may prefer this behavior to the default, if so enable this option (be warned
1500 if you enable it in a legacy application we are not sure if it is completely
1501 backwardly compatible).
1503 - `skip_complex_post_part_handling`
1505 When creating body parameters from a POST, if we run into a multipart POST
1506 that does not contain uploads, but instead contains inlined complex data
1507 (very uncommon) we cannot reliably convert that into field => value pairs. So
1508 instead we create an instance of [Catalyst::Request::PartData](https://metacpan.org/pod/Catalyst::Request::PartData). If this causes
1509 issue for you, you can disable this by setting `skip_complex_post_part_handling`
1510 to true (default is false).
1512 - `skip_body_param_unicode_decoding`
1514 Generally we decode incoming POST params based on your declared encoding (the
1515 default for this is to decode UTF-8). If this is causing you trouble and you
1516 do not wish to turn all encoding support off (with the `encoding` configuration
1517 parameter) you may disable this step atomically by setting this configuration
1520 - `do_not_decode_query`
1522 If true, then do not try to character decode any wide characters in your
1523 request URL query or keywords. Most readings of the relevant specifications
1524 suggest these should be UTF-\* encoded, which is the default that [Catalyst](https://metacpan.org/pod/Catalyst)
1525 will use, however if you are creating a lot of URLs manually or have external
1526 evil clients, this might cause you trouble. If you find the changes introduced
1527 in Catalyst version 5.90080+ break some of your query code, you may disable
1528 the UTF-8 decoding globally using this configuration.
1530 This setting takes precedence over `default_query_encoding` and
1531 `decode_query_using_global_encoding`
1533 - `default_query_encoding`
1535 By default we decode query and keywords in your request URL using UTF-8, which
1536 is our reading of the relevant specifications. This setting allows one to
1537 specify a fixed value for how to decode your query. You might need this if
1538 you are doing a lot of custom encoding of your URLs and not using UTF-8.
1540 This setting take precedence over `decode_query_using_global_encoding`.
1542 - `decode_query_using_global_encoding`
1544 Setting this to true will default your query decoding to whatever your
1545 general global encoding is (the default is UTF-8).
1547 - `use_chained_args_0_special_case`
1549 In older versions of Catalyst, when more than one action matched the same path
1550 AND all those matching actions declared Args(0), we'd break the tie by choosing
1551 the first action defined. We now normalized how Args(0) works so that it
1552 follows the same rule as Args(N), which is to say when we need to break a tie
1553 we choose the LAST action defined. If this breaks your code and you don't
1554 have time to update to follow the new normalized approach, you may set this
1555 value to true and it will globally revert to the original chaining behavior.
1557 - `psgi_middleware` - See ["PSGI MIDDLEWARE"](#psgi-middleware).
1558 - `data_handlers` - See ["DATA HANDLERS"](#data-handlers).
1559 - `stats_class_traits`
1561 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get composed into your stats class.
1563 - `request_class_traits`
1565 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get composed into your request class.
1567 - `response_class_traits`
1569 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get composed into your response class.
1571 - `inject_components`
1573 A Hashref of [Catalyst::Component](https://metacpan.org/pod/Catalyst::Component) subclasses that are 'injected' into configuration.
1577 inject_components => {
1578 'Controller::Err' => { from_component => 'Local::Controller::Errors' },
1579 'Model::Zoo' => { from_component => 'Local::Model::Foo' },
1580 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] },
1582 'Controller::Err' => { a => 100, b=>200, namespace=>'error' },
1583 'Model::Zoo' => { a => 2 },
1584 'Model::Foo' => { a => 100 },
1587 Generally [Catalyst](https://metacpan.org/pod/Catalyst) looks for components in your Model/View or Controller directories.
1588 However for cases when you which to use an existing component and you don't need any
1589 customization (where for when you can apply a role to customize it) you may inject those
1590 components into your application. Please note any configuration should be done 'in the
1591 normal way', with a key under configuration named after the component affix, as in the
1594 Using this type of injection allows you to construct significant amounts of your application
1595 with only configuration!. This may or may not lead to increased code understanding.
1597 Please not you may also call the ->inject\_components application method as well, although
1598 you must do so BEFORE setup.
1602 Generally when you throw an exception inside an Action (or somewhere in
1603 your stack, such as in a model that an Action is calling) that exception
1604 is caught by Catalyst and unless you either catch it yourself (via eval
1605 or something like [Try::Tiny](https://metacpan.org/pod/Try::Tiny) or by reviewing the ["error"](#error) stack, it
1606 will eventually reach ["finalize\_errors"](#finalize_errors) and return either the debugging
1607 error stack page, or the default error page. However, if your exception
1608 can be caught by [Plack::Middleware::HTTPExceptions](https://metacpan.org/pod/Plack::Middleware::HTTPExceptions), [Catalyst](https://metacpan.org/pod/Catalyst) will
1609 instead rethrow it so that it can be handled by that middleware (which
1610 is part of the default middleware). For example this would allow
1612 use HTTP::Throwable::Factory 'http_throw';
1614 sub throws_exception :Local {
1615 my ($self, $c) = @_;
1617 http_throw(SeeOther => { location =>
1618 $c->uri_for($self->action_for('redirect')) });
1624 Catalyst uses internal actions like `_DISPATCH`, `_BEGIN`, `_AUTO`,
1625 `_ACTION`, and `_END`. These are by default not shown in the private
1626 action table, but you can make them visible with a config parameter.
1628 MyApp->config(show_internal_actions => 1);
1632 The request body is usually parsed at the beginning of a request,
1633 but if you want to handle input yourself, you can enable on-demand
1634 parsing with a config parameter.
1636 MyApp->config(parse_on_demand => 1);
1640 Many production servers operate using the common double-server approach,
1641 with a lightweight frontend web server passing requests to a larger
1642 backend server. An application running on the backend server must deal
1643 with two problems: the remote user always appears to be `127.0.0.1` and
1644 the server's hostname will appear to be `localhost` regardless of the
1645 virtual host that the user connected through.
1647 Catalyst will automatically detect this situation when you are running
1648 the frontend and backend servers on the same machine. The following
1649 changes are made to the request.
1651 $c->req->address is set to the user's real IP address, as read from
1652 the HTTP X-Forwarded-For header.
1654 The host value for $c->req->base and $c->req->uri is set to the real
1655 host, as read from the HTTP X-Forwarded-Host header.
1657 Additionally, you may be running your backend application on an insecure
1658 connection (port 80) while your frontend proxy is running under SSL. If there
1659 is a discrepancy in the ports, use the HTTP header `X-Forwarded-Port` to
1660 tell Catalyst what port the frontend listens on. This will allow all URIs to
1661 be created properly.
1663 In the case of passing in:
1665 X-Forwarded-Port: 443
1667 All calls to `uri_for` will result in an https link, as is expected.
1669 Obviously, your web server must support these headers for this to work.
1671 In a more complex server farm environment where you may have your
1672 frontend proxy server(s) on different machines, you will need to set a
1673 configuration option to tell Catalyst to read the proxied data from the
1676 MyApp->config(using_frontend_proxy => 1);
1678 If you do not wish to use the proxy support at all, you may set:
1680 MyApp->config(ignore_frontend_proxy => 0);
1682 ## Note about psgi files
1684 Note that if you supply your own .psgi file, calling
1685 `MyApp->psgi_app(@_);`, then **this will not happen automatically**.
1687 You either need to apply [Plack::Middleware::ReverseProxy](https://metacpan.org/pod/Plack::Middleware::ReverseProxy) yourself
1688 in your psgi, for example:
1691 enable "Plack::Middleware::ReverseProxy";
1695 This will unconditionally add the ReverseProxy support, or you need to call
1696 `$app = MyApp->apply_default_middlewares($app)` (to conditionally
1697 apply the support depending upon your config).
1699 See [Catalyst::PSGI](https://metacpan.org/pod/Catalyst::PSGI) for more information.
1703 Catalyst has been tested under Apache 2's threading `mpm_worker`,
1704 `mpm_winnt`, and the standalone forking HTTP server on Windows. We
1705 believe the Catalyst core to be thread-safe.
1707 If you plan to operate in a threaded environment, remember that all other
1708 modules you are using must also be thread-safe. Some modules, most notably
1709 [DBD::SQLite](https://metacpan.org/pod/DBD::SQLite), are not thread-safe.
1713 The [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request) object uses [HTTP::Body](https://metacpan.org/pod/HTTP::Body) to populate 'classic' HTML
1714 form parameters and URL search query fields. However it has become common
1715 for various alternative content types to be PUT or POSTed to your controllers
1716 and actions. People working on RESTful APIs, or using AJAX often use JSON,
1717 XML and other content types when communicating with an application server. In
1718 order to better support this use case, [Catalyst](https://metacpan.org/pod/Catalyst) defines a global configuration
1719 option, `data_handlers`, which lets you associate a content type with a coderef
1720 that parses that content type into something Perl can readily access.
1727 __PACKAGE__->config(
1729 'application/json' => sub { local $/; decode_json $_->getline },
1731 ## Any other configuration.
1736 By default [Catalyst](https://metacpan.org/pod/Catalyst) comes with a generic JSON data handler similar to the
1737 example given above, which uses [JSON::Maybe](https://metacpan.org/pod/JSON::Maybe) to provide either [JSON::PP](https://metacpan.org/pod/JSON::PP)
1738 (a pure Perl, dependency free JSON parser) or [Cpanel::JSON::XS](https://metacpan.org/pod/Cpanel::JSON::XS) if you have
1739 it installed (if you want the faster XS parser, add it to you project Makefile.PL
1740 or dist.ini, cpanfile, etc.)
1742 The `data_handlers` configuration is a hashref whose keys are HTTP Content-Types
1743 (matched against the incoming request type using a regexp such as to be case
1744 insensitive) and whose values are coderefs that receive a localized version of
1745 `$_` which is a filehandle object pointing to received body.
1747 This feature is considered an early access release and we reserve the right
1748 to alter the interface in order to provide a performant and secure solution to
1749 alternative request body content. Your reports welcomed!
1753 You can define middleware, defined as [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware) or a compatible
1754 interface in configuration. Your middleware definitions are in the form of an
1755 arrayref under the configuration key `psgi_middleware`. Here's an example
1756 with details to follow:
1761 use Plack::Middleware::StackTrace;
1763 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1765 __PACKAGE__->config(
1766 'psgi_middleware', [
1769 $stacktrace_middleware,
1770 'Session' => {store => 'File'},
1775 $env->{myapp.customkey} = 'helloworld';
1784 So the general form is:
1786 __PACKAGE__->config(psgi_middleware => \@middleware_definitions);
1788 Where `@middleware` is one or more of the following, applied in the REVERSE of
1789 the order listed (to make it function similarly to [Plack::Builder](https://metacpan.org/pod/Plack::Builder):
1791 Alternatively, you may also define middleware by calling the ["setup\_middleware"](#setup_middleware)
1798 __PACKAGE__->setup_middleware( \@middleware_definitions);
1801 In the case where you do both (use 'setup\_middleware' and configuration) the
1802 package call to setup\_middleware will be applied earlier (in other words its
1803 middleware will wrap closer to the application). Keep this in mind since in
1804 some cases the order of middleware is important.
1806 The two approaches are not exclusive.
1810 An already initialized object that conforms to the [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware)
1813 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1815 __PACKAGE__->config(
1816 'psgi_middleware', [
1817 $stacktrace_middleware,
1824 A coderef that is an inlined middleware:
1826 __PACKAGE__->config(
1827 'psgi_middleware', [
1832 if($env->{PATH_INFO} =~m/forced/) {
1834 ->new(file=>TestApp->path_to(qw/share static forced.txt/))
1837 return $app->($env);
1848 We assume the scalar refers to a namespace after normalizing it using the
1851 (1) If the scalar is prefixed with a "+" (as in `+MyApp::Foo`) then the full string
1852 is assumed to be 'as is', and we just install and use the middleware.
1854 (2) If the scalar begins with "Plack::Middleware" or your application namespace
1855 (the package name of your Catalyst application subclass), we also assume then
1856 that it is a full namespace, and use it.
1858 (3) Lastly, we then assume that the scalar is a partial namespace, and attempt to
1859 resolve it first by looking for it under your application namespace (for example
1860 if you application is "MyApp::Web" and the scalar is "MyMiddleware", we'd look
1861 under "MyApp::Web::Middleware::MyMiddleware") and if we don't find it there, we
1862 will then look under the regular [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware) namespace (i.e. for the
1863 previous we'd try "Plack::Middleware::MyMiddleware"). We look under your application
1864 namespace first to let you 'override' common [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware) locally, should
1865 you find that a good idea.
1871 __PACKAGE__->config(
1872 'psgi_middleware', [
1873 'Debug', ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap
1874 'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap
1875 '+MyApp::Custom', ## MyApp::Custom->wrap
1880 - a scalar followed by a hashref
1882 Just like the previous, except the following `HashRef` is used as arguments
1883 to initialize the middleware object.
1885 __PACKAGE__->config(
1886 'psgi_middleware', [
1887 'Session' => {store => 'File'},
1890 Please see [PSGI](https://metacpan.org/pod/PSGI) for more on middleware.
1894 Starting in [Catalyst](https://metacpan.org/pod/Catalyst) version 5.90080 encoding is automatically enabled
1895 and set to encode all body responses to UTF8 when possible and applicable.
1896 Following is documentation on this process. If you are using an older
1897 version of [Catalyst](https://metacpan.org/pod/Catalyst) you should review documentation for that version since
1900 By default encoding is now 'UTF-8'. You may turn it off by setting
1901 the encoding configuration to undef.
1903 MyApp->config(encoding => undef);
1905 This is recommended for temporary backwards compatibility only.
1907 Encoding is automatically applied when the content-type is set to
1908 a type that can be encoded. Currently we encode when the content type
1909 matches the following regular expression:
1911 $content_type =~ /^text|xml$|javascript$/
1913 Encoding is set on the application, but it is copied to the context object
1914 so that you can override it on a request basis.
1916 Be default we don't automatically encode 'application/json' since the most
1917 common approaches to generating this type of response (Either via [Catalyst::View::JSON](https://metacpan.org/pod/Catalyst::View::JSON)
1918 or [Catalyst::Action::REST](https://metacpan.org/pod/Catalyst::Action::REST)) will do so already and we want to avoid double
1921 If you are producing JSON response in an unconventional manner (such
1922 as via a template or manual strings) you should perform the UTF8 encoding
1923 manually as well such as to conform to the JSON specification.
1925 NOTE: We also examine the value of $c->response->content\_encoding. If
1926 you set this (like for example 'gzip', and manually gzipping the body)
1927 we assume that you have done all the necessary encoding yourself, since
1928 we cannot encode the gzipped contents. If you use a plugin like
1929 [Catalyst::Plugin::Compress](https://metacpan.org/pod/Catalyst::Plugin::Compress) you need to update to a modern version in order
1930 to have this function correctly with the new UTF8 encoding code, or you
1931 can use [Plack::Middleware::Deflater](https://metacpan.org/pod/Plack::Middleware::Deflater) or (probably best) do your compression on
1938 Returns an instance of an `Encode` encoding
1940 print $c->encoding->name
1942 - handle\_unicode\_encoding\_exception ($exception\_context)
1944 Method called when decoding process for a request fails.
1946 An `$exception_context` hashref is provided to allow you to override the
1947 behaviour of your application when given data with incorrect encodings.
1949 The default method throws exceptions in the case of invalid request parameters
1950 (resulting in a 500 error), but ignores errors in upload filenames.
1952 The keys passed in the `$exception_context` hash are:
1956 The value which was not able to be decoded.
1960 The exception received from [Encode](https://metacpan.org/pod/Encode).
1964 What type of data was being decoded. Valid values are (currently)
1965 `params` - for request parameters / arguments / captures
1966 and `uploads` - for request upload filenames.
1972 Join #catalyst on irc.perl.org.
1976 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
1977 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
1981 http://catalyst.perl.org
1985 http://dev.catalyst.perl.org
1989 ## [Task::Catalyst](https://metacpan.org/pod/Task::Catalyst) - All you need to start with Catalyst
1991 ## [Catalyst::Manual](https://metacpan.org/pod/Catalyst::Manual) - The Catalyst Manual
1993 ## [Catalyst::Component](https://metacpan.org/pod/Catalyst::Component), [Catalyst::Controller](https://metacpan.org/pod/Catalyst::Controller) - Base classes for components
1995 ## [Catalyst::Engine](https://metacpan.org/pod/Catalyst::Engine) - Core engine
1997 ## [Catalyst::Log](https://metacpan.org/pod/Catalyst::Log) - Log class.
1999 ## [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request) - Request object
2001 ## [Catalyst::Response](https://metacpan.org/pod/Catalyst::Response) - Response object
2003 ## [Catalyst::Test](https://metacpan.org/pod/Catalyst::Test) - The test suite.
2007 sri: Sebastian Riedel <sri@cpan.org>
2013 acme: Leon Brocard <leon@astray.com>
2015 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
2017 andrewalker: André Walker <andre@cpan.org>
2021 Andrew Ford <A.Ford@ford-mason.co.uk>
2025 andyg: Andy Grundman <andy@hybridized.org>
2027 audreyt: Audrey Tang
2029 bricas: Brian Cassidy <bricas@cpan.org>
2031 Caelum: Rafael Kitover <rkitover@io.com>
2033 chansen: Christian Hansen
2035 chicks: Christopher Hicks
2037 Chisel Wright `pause@herlpacker.co.uk`
2039 Danijel Milicevic `me@danijel.de`
2041 davewood: David Schmidt <davewood@cpan.org>
2043 David Kamholz <dkamholz@cpan.org>
2045 David Naughton, `naughton@umn.edu`
2049 dhoss: Devin Austin <dhoss@cpan.org>
2051 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
2055 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
2057 esskar: Sascha Kiefer
2059 fireartist: Carl Franks <cfranks@cpan.org>
2061 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
2063 gabb: Danijel Milicevic
2067 Gavin Henry `ghenry@perl.me.uk`
2071 groditi: Guillermo Roditi <groditi@gmail.com>
2073 hobbs: Andrew Rodland <andrew@cleverdomain.org>
2075 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
2077 jcamacho: Juan Camacho
2079 jester: Jesse Sheidlower `jester@panix.com`
2081 jhannah: Jay Hannah <jay@jays.net>
2087 jon: Jon Schutz <jjschutz@cpan.org>
2089 Jonathan Rockway `<jrockway@cpan.org>`
2091 Kieren Diment `kd@totaldatasolution.com`
2093 konobi: Scott McWhirter <konobi@cpan.org>
2095 marcus: Marcus Ramberg <mramberg@cpan.org>
2097 Mischa Spiegelmock <revmischa@cpan.org>
2099 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
2101 mgrimes: Mark Grimes <mgrimes@cpan.org>
2103 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
2107 naughton: David Naughton
2109 ningu: David Kamholz <dkamholz@cpan.org>
2111 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
2113 numa: Dan Sully <daniel@cpan.org>
2119 omega: Andreas Marienborg
2121 Oleg Kostyuk <cub.uanic@gmail.com>
2123 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
2125 rafl: Florian Ragwitz <rafl@debian.org>
2127 random: Roland Lammel <lammel@cpan.org>
2129 Robert Sedlacek `<rs@474.at>`
2131 SpiceMan: Marcel Montes
2135 szbalint: Balint Szilakszi <szbalint@cpan.org>
2137 t0m: Tomas Doran <bobtfish@bobtfish.net>
2141 vanstyn: Henry Van Styn <vanstyn@cpan.org>
2143 Viljo Marrandi `vilts@yahoo.com`
2145 Will Hawes `info@whawes.co.uk`
2147 willert: Sebastian Willert <willert@cpan.org>
2149 wreis: Wallace Reis <wreis@cpan.org>
2151 Yuval Kogman, `nothingmuch@woobling.org`
2153 rainboxx: Matthias Dietrich, `perl@rainboxx.de`
2155 dd070: Dhaval Dhanani <dhaval070@gmail.com>
2157 Upasana <me@upasana.me>
2159 John Napiorkowski (jnap) <jjnapiork@cpan.org>
2163 Copyright (c) 2005-2015, the above named PROJECT FOUNDER and CONTRIBUTORS.
2167 This library is free software. You can redistribute it and/or modify it under
2168 the same terms as Perl itself.