1Catalyst(3) User Contributed Perl Documentation Catalyst(3)
2
6 Catalyst - The Elegant MVC Web Application Framework
7
9 See the Catalyst::Manual distribution for comprehensive documentation
10 and tutorials.
11 # Install Catalyst::Devel for helpers and other development tools
13 # use the helper to create a new application
14 catalyst.pl MyApp
15 # add models, views, controllers
17 script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
18 script/myapp_create.pl view MyTemplate TT
19 script/myapp_create.pl controller Search
20 # built in testserver -- use -r to restart automatically on changes
22 # --help to see all available options
23 script/myapp_server.pl
24 # command line testing interface
26 script/myapp_test.pl /yada
27 ### in lib/MyApp.pm
29 use Catalyst qw/-Debug/; # include plugins here as well
30 ### In lib/MyApp/Controller/Root.pm (autocreated)
32 sub foo : Chained('/') Args() { # called for /foo, /foo/1, /foo/1/2, etc.
33 my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
34 $c->stash->{template} = 'foo.tt'; # set the template
35 # lookup something from db -- stash vars are passed to TT
36 $c->stash->{data} =
37 $c->model('Database::Foo')->search( { country => $args[0] } );
38 if ( $c->req->params->{bar} ) { # access GET or POST parameters
39 $c->forward( 'bar' ); # process another action
40 # do something else after forward returns
41 }
42 }
43 # The foo.tt TT template can use the stash data from the database
45 [% WHILE (item = data.next) %]
46 [% item.foo %]
47 [% END %]
48 # called for /bar/of/soap, /bar/of/soap/10, etc.
50 sub bar : Chained('/') PathPart('/bar/of/soap') Args() { ... }
51 # called after all actions are finished
53 sub end : Action {
54 my ( $self, $c ) = @_;
55 if ( scalar @{ $c->error } ) { ... } # handle errors
56 return if $c->res->body; # already have a response
57 $c->forward( 'MyApp::View::TT' ); # render template
58 }
59 See Catalyst::Manual::Intro for additional information.
61
63 Catalyst is a modern framework for making web applications without the
64 pain usually associated with this process. This document is a reference
65 to the main Catalyst application. If you are a new user, we suggest you
66 start with Catalyst::Manual::Tutorial or Catalyst::Manual::Intro.
67 See Catalyst::Manual for more documentation.
69 Catalyst plugins can be loaded by naming them as arguments to the "use
71 Catalyst" statement. Omit the "Catalyst::Plugin::" prefix from the
72 plugin name, i.e., "Catalyst::Plugin::My::Module" becomes "My::Module".
73 use Catalyst qw/My::Module/;
75 If your plugin starts with a name other than "Catalyst::Plugin::", you
77 can fully qualify the name by using a unary plus:
78 use Catalyst qw/
80 My::Module
81 +Fully::Qualified::Plugin::Name
82 /;
83 Special flags like "-Debug" can also be specified as arguments when
85 Catalyst is loaded:
86 use Catalyst qw/-Debug My::Module/;
88 The position of plugins and flags in the chain is important, because
90 they are loaded in the order in which they appear.
91 The following flags are supported:
93 -Debug
95 Enables debug output. You can also force this setting from the system
96 environment with CATALYST_DEBUG or <MYAPP>_DEBUG. The environment
97 settings override the application, with <MYAPP>_DEBUG having the
98 highest priority.
99 This sets the log level to 'debug' and enables full debug output on the
101 error screen. If you only want the latter, see $c->debug.
102 -Home
104 Forces Catalyst to use a specific home directory, e.g.:
105 use Catalyst qw[-Home=/usr/mst];
107 This can also be done in the shell environment by setting either the
109 "CATALYST_HOME" environment variable or "MYAPP_HOME"; where "MYAPP" is
110 replaced with the uppercased name of your application, any "::" in the
111 name will be replaced with underscores, e.g. MyApp::Web should use
112 MYAPP_WEB_HOME. If both variables are set, the MYAPP_HOME one will be
113 used.
114 If none of these are set, Catalyst will attempt to automatically detect
116 the home directory. If you are working in a development environment,
117 Catalyst will try and find the directory containing either Makefile.PL,
118 Build.PL, dist.ini, or cpanfile. If the application has been installed
119 into the system (i.e. you have done "make install"), then Catalyst will
120 use the path to your application module, without the .pm extension
121 (e.g., /foo/MyApp if your application was installed at /foo/MyApp.pm)
122 -Log
124 use Catalyst '-Log=warn,fatal,error';
125 Specifies a comma-delimited list of log levels.
127 -Stats
129 Enables statistics collection and reporting.
130 use Catalyst qw/-Stats=1/;
132 You can also force this setting from the system environment with
134 CATALYST_STATS or <MYAPP>_STATS. The environment settings override the
135 application, with <MYAPP>_STATS having the highest priority.
136 Stats are also enabled if debugging is enabled.
138
140 INFORMATION ABOUT THE CURRENT REQUEST
141 $c->action
142 Returns a Catalyst::Action object for the current action, which
143 stringifies to the action name. See Catalyst::Action.
144 $c->namespace
146 Returns the namespace of the current action, i.e., the URI prefix
147 corresponding to the controller of the current action. For example:
148 # in Controller::Foo::Bar
150 $c->namespace; # returns 'foo/bar';
151 $c->request
153 $c->req
154 Returns the current Catalyst::Request object, giving access to
155 information about the current client request (including parameters,
156 cookies, HTTP headers, etc.). See Catalyst::Request.
157 REQUEST FLOW HANDLING
159 $c->forward( $action [, \@arguments ] )
160 $c->forward( $class, $method, [, \@arguments ] )
161 This is one way of calling another action (method) in the same or a
162 different controller. You can also use "$self->my_method($c, @args)" in
163 the same controller or "$c->controller('MyController')->my_method($c,
164 @args)" in a different controller. The main difference is that
165 'forward' uses some of the Catalyst request cycle overhead, including
166 debugging, which may be useful to you. On the other hand, there are
167 some complications to using 'forward', restrictions on values returned
168 from 'forward', and it may not handle errors as you prefer. Whether
169 you use 'forward' or not is up to you; it is not considered superior to
170 the other ways to call a method.
171 'forward' calls another action, by its private name. If you give a
173 class name but no method, "process()" is called. You may also
174 optionally pass arguments in an arrayref. The action will receive the
175 arguments in @_ and "$c->req->args". Upon returning from the function,
176 "$c->req->args" will be restored to the previous values.
177 Any data "return"ed from the action forwarded to, will be returned by
179 the call to forward.
180 my $foodata = $c->forward('/foo');
182 $c->forward('index');
183 $c->forward(qw/Model::DBIC::Foo do_stuff/);
184 $c->forward('View::TT');
185 Note that forward implies an "eval { }" around the call (actually
187 execute does), thus rendering all exceptions thrown by the called
188 action non-fatal and pushing them onto $c->error instead. If you want
189 "die" to propagate you need to do something like:
190 $c->forward('foo');
192 die join "\n", @{ $c->error } if @{ $c->error };
193 Or make sure to always return true values from your actions and write
195 your code like this:
196 $c->forward('foo') || return;
198 Another note is that "$c->forward" always returns a scalar because it
200 actually returns $c->state which operates in a scalar context. Thus,
201 something like:
202 return @array;
204 in an action that is forwarded to is going to return a scalar, i.e. how
206 many items are in that array, which is probably not what you want. If
207 you need to return an array then return a reference to it, or stash it
208 like so:
209 $c->stash->{array} = \@array;
211 and access it from the stash.
213 Keep in mind that the "end" method used is that of the caller action.
215 So a "$c->detach" inside a forwarded action would run the "end" method
216 from the original action requested.
217 $c->detach( $action [, \@arguments ] )
219 $c->detach( $class, $method, [, \@arguments ] )
220 $c->detach()
221 The same as forward, but doesn't return to the previous action when
222 processing is finished.
223 When called with no arguments it escapes the processing chain entirely.
225 $c->visit( $action [, \@arguments ] )
227 $c->visit( $action [, \@captures, \@arguments ] )
228 $c->visit( $class, $method, [, \@arguments ] )
229 $c->visit( $class, $method, [, \@captures, \@arguments ] )
230 Almost the same as forward, but does a full dispatch, instead of just
231 calling the new $action / "$class->$method". This means that "begin",
232 "auto" and the method you go to are called, just like a new request.
233 In addition both "$c->action" and "$c->namespace" are localized. This
235 means, for example, that "$c->action" methods such as name, class and
236 reverse return information for the visited action when they are invoked
237 within the visited action. This is different from the behavior of
238 forward, which continues to use the $c->action object from the caller
239 action even when invoked from the called action.
240 "$c->stash" is kept unchanged.
242 In effect, visit allows you to "wrap" another action, just as it would
244 have been called by dispatching from a URL, while the analogous go
245 allows you to transfer control to another action as if it had been
246 reached directly from a URL.
247 $c->go( $action [, \@arguments ] )
249 $c->go( $action [, \@captures, \@arguments ] )
250 $c->go( $class, $method, [, \@arguments ] )
251 $c->go( $class, $method, [, \@captures, \@arguments ] )
252 The relationship between "go" and visit is the same as the relationship
253 between forward and detach. Like "$c->visit", "$c->go" will perform a
254 full dispatch on the specified action or method, with localized
255 "$c->action" and "$c->namespace". Like "detach", "go" escapes the
256 processing of the current request chain on completion, and does not
257 return to its caller.
258 @arguments are arguments to the final destination of $action. @captures
260 are arguments to the intermediate steps, if any, on the way to the
261 final sub of $action.
262 $c->response
264 $c->res
265 Returns the current Catalyst::Response object, see there for details.
266 $c->stash
268 Returns a hashref to the stash, which may be used to store data and
269 pass it between components during a request. You can also set hash keys
270 by passing arguments. The stash is automatically sent to the view. The
271 stash is cleared at the end of a request; it cannot be used for
272 persistent storage (for this you must use a session; see
273 Catalyst::Plugin::Session for a complete system integrated with
274 Catalyst).
275 $c->stash->{foo} = $bar;
277 $c->stash( { moose => 'majestic', qux => 0 } );
278 $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
279 # stash is automatically passed to the view for use in a template
281 $c->forward( 'MyApp::View::TT' );
282 The stash hash is currently stored in the PSGI $env and is managed by
284 Catalyst::Middleware::Stash. Since it's part of the $env items in the
285 stash can be accessed in sub applications mounted under your main
286 Catalyst application. For example if you delegate the response of an
287 action to another Catalyst application, that sub application will have
288 access to all the stash keys of the main one, and if can of course add
289 more keys of its own. However those new keys will not 'bubble' back up
290 to the main application.
291 For more information the best thing to do is to review the test case:
293 t/middleware-stash.t in the distribution /t directory.
294 $c->error
296 $c->error($error, ...)
297 $c->error($arrayref)
298 Returns an arrayref containing error messages. If Catalyst encounters
299 an error while processing a request, it stores the error in $c->error.
300 This method should only be used to store fatal error messages.
301 my @error = @{ $c->error };
303 Add a new error.
305 $c->error('Something bad happened');
307 Calling this will always return an arrayref (if there are no errors it
309 will be an empty arrayref.
310 $c->state
312 Contains the return value of the last executed action. Note that <<
313 $c->state >> operates in a scalar context which means that all values
314 it returns are scalar.
315 Please note that if an action throws an exception, the value of state
317 should no longer be considered the return if the last action. It is
318 generally going to be 0, which indicates an error state. Examine
319 $c->error for error details.
320 $c->clear_errors
322 Clear errors. You probably don't want to clear the errors unless you
323 are implementing a custom error screen.
324 This is equivalent to running
326 $c->error(0);
328 $c->has_errors
330 Returns true if you have errors
331 $c->last_error
333 Returns the most recent error in the stack (the one most recently
334 added...) or nothing if there are no errors. This does not modify the
335 contents of the error stack.
336 shift_errors
338 shifts the most recently added error off the error stack and returns
339 it. Returns nothing if there are no more errors.
340 pop_errors
342 pops the most recently added error off the error stack and returns it.
343 Returns nothing if there are no more errors.
344 COMPONENT ACCESSORS
346 $c->controller($name)
347 Gets a Catalyst::Controller instance by name.
348 $c->controller('Foo')->do_stuff;
350 If the name is omitted, will return the controller for the dispatched
352 action.
353 If you want to search for controllers, pass in a regexp as the
355 argument.
356 # find all controllers that start with Foo
358 my @foo_controllers = $c->controller(qr{^Foo});
359 $c->model($name)
361 Gets a Catalyst::Model instance by name.
362 $c->model('Foo')->do_stuff;
364 Any extra arguments are directly passed to ACCEPT_CONTEXT, if the model
366 defines ACCEPT_CONTEXT. If it does not, the args are discarded.
367 If the name is omitted, it will look for
369 - a model object in $c->stash->{current_model_instance}, then
370 - a model name in $c->stash->{current_model}, then
371 - a config setting 'default_model', or
372 - check if there is only one model, and return it if that's the case.
373 If you want to search for models, pass in a regexp as the argument.
375 # find all models that start with Foo
377 my @foo_models = $c->model(qr{^Foo});
378 $c->view($name)
380 Gets a Catalyst::View instance by name.
381 $c->view('Foo')->do_stuff;
383 Any extra arguments are directly passed to ACCEPT_CONTEXT.
385 If the name is omitted, it will look for
387 - a view object in $c->stash->{current_view_instance}, then
388 - a view name in $c->stash->{current_view}, then
389 - a config setting 'default_view', or
390 - check if there is only one view, and return it if that's the case.
391 If you want to search for views, pass in a regexp as the argument.
393 # find all views that start with Foo
395 my @foo_views = $c->view(qr{^Foo});
396 $c->controllers
398 Returns the available names which can be passed to $c->controller
399 $c->models
401 Returns the available names which can be passed to $c->model
402 $c->views
404 Returns the available names which can be passed to $c->view
405 $c->comp($name)
407 $c->component($name)
408 Gets a component object by name. This method is not recommended, unless
409 you want to get a specific component by full class. "$c->controller",
410 "$c->model", and "$c->view" should be used instead.
411 If $name is a regexp, a list of components matched against the full
413 component name will be returned.
414 If Catalyst can't find a component by name, it will fallback to regex
416 matching by default. To disable this behaviour set
417 disable_component_resolution_regex_fallback to a true value.
418 __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );
420 CLASS DATA AND HELPER CLASSES
422 $c->config
423 Returns or takes a hashref containing the application's configuration.
424 __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
426 You can also use a "YAML", "XML" or Config::General config file like
428 "myapp.conf" in your applications home directory. See
429 Catalyst::Plugin::ConfigLoader.
430 Cascading configuration
432 The config method is present on all Catalyst components, and
434 configuration will be merged when an application is started.
435 Configuration loaded with Catalyst::Plugin::ConfigLoader takes
436 precedence over other configuration, followed by configuration in your
437 top level "MyApp" class. These two configurations are merged, and then
438 configuration data whose hash key matches a component name is merged
439 with configuration for that component.
440 The configuration for a component is then passed to the "new" method
442 when a component is constructed.
443 For example:
445 MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
447 MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });
448 will mean that "MyApp::Model::Foo" receives the following data when
450 constructed:
451 MyApp::Model::Foo->new({
453 bar => 'baz',
454 quux => 'frob',
455 overrides => 'me',
456 });
457 It's common practice to use a Moose attribute on the receiving
459 component to access the config value.
460 package MyApp::Model::Foo;
462 use Moose;
464 # this attr will receive 'baz' at construction time
466 has 'bar' => (
467 is => 'rw',
468 isa => 'Str',
469 );
470 You can then get the value 'baz' by calling $c->model('Foo')->bar (or
472 $self->bar inside code in the model).
473 NOTE: you MUST NOT call "$self->config" or "__PACKAGE__->config" as a
475 way of reading config within your code, as this will not give you the
476 correctly merged config back. You MUST take the config values supplied
477 to the constructor and use those instead.
478 $c->log
480 Returns the logging object instance. Unless it is already set, Catalyst
481 sets this up with a Catalyst::Log object. To use your own log class,
482 set the logger with the "__PACKAGE__->log" method prior to calling
483 "__PACKAGE__->setup".
484 __PACKAGE__->log( MyLogger->new );
486 __PACKAGE__->setup;
487 And later:
489 $c->log->info( 'Now logging with my own logger!' );
491 Your log class should implement the methods described in Catalyst::Log.
493 has_encoding
495 Returned True if there's a valid encoding
496 clear_encoding
498 Clears the encoding for the current context
499 encoding
501 Sets or gets the application encoding. Setting encoding takes either
502 an Encoding object or a string that we try to resolve via
503 Encode::find_encoding.
504 You would expect to get the encoding object back if you attempt to set
506 it. If there is a failure you will get undef returned and an error
507 message in the log.
508 $c->debug
510 Returns 1 if debug mode is enabled, 0 otherwise.
511 You can enable debug mode in several ways:
513 By calling myapp_server.pl with the -d flag
515 With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG
516 The -Debug option in your MyApp.pm
517 By declaring "sub debug { 1 }" in your MyApp.pm.
518 The first three also set the log level to 'debug'.
520 Calling "$c->debug(1)" has no effect.
522 $c->dispatcher
524 Returns the dispatcher instance. See Catalyst::Dispatcher.
525 $c->engine
527 Returns the engine instance. See Catalyst::Engine.
528 UTILITY METHODS
530 $c->path_to(@path)
531 Merges @path with "$c->config->{home}" and returns a Path::Class::Dir
532 object. Note you can usually use this object as a filename, but
533 sometimes you will have to explicitly stringify it yourself by calling
534 the "->stringify" method.
535 For example:
537 $c->path_to( 'db', 'sqlite.db' );
539 MyApp->setup
541 Initializes the dispatcher and engine, loads any plugins, and loads the
542 model, view, and controller components. You may also specify an array
543 of plugins to load here, if you choose to not load them in the "use
544 Catalyst" line.
545 MyApp->setup;
547 MyApp->setup( qw/-Debug/ );
548 Note: You should not wrap this method with method modifiers or bad
550 things will happen - wrap the "setup_finalize" method instead.
551 Note: You can create a custom setup stage that will execute when the
553 application is starting. Use this to customize setup.
554 MyApp->setup(-Custom=value);
556 sub setup_custom {
558 my ($class, $value) = @_;
559 }
560 Can be handy if you want to hook into the setup phase.
562 $app->setup_finalize
564 A hook to attach modifiers to. This method does not do anything except
565 set the "setup_finished" accessor.
566 Applying method modifiers to the "setup" method doesn't work, because
568 of quirky things done for plugin setup.
569 Example:
571 after setup_finalize => sub {
573 my $app = shift;
574 ## do stuff here..
576 };
577 $c->uri_for( $path?, @args?, \%query_values?, \$fragment? )
579 $c->uri_for( $action, \@captures?, @args?, \%query_values?, \$fragment? )
580 $c->uri_for( $action, [@captures, @args], \%query_values?, \$fragment? )
581 Constructs an absolute URI object based on the application root, the
582 provided path, and the additional arguments and query parameters
583 provided. When used as a string, provides a textual URI. If you need
584 more flexibility than this (i.e. the option to provide relative URIs
585 etc.) see Catalyst::Plugin::SmartURI.
586 If no arguments are provided, the URI for the current action is
588 returned. To return the current action and also provide @args, use
589 "$c->uri_for( $c->action, @args )".
590 If the first argument is a string, it is taken as a public URI path
592 relative to "$c->namespace" (if it doesn't begin with a forward slash)
593 or relative to the application root (if it does). It is then merged
594 with "$c->request->base"; any @args are appended as additional path
595 components; and any %query_values are appended as "?foo=bar"
596 parameters.
597 NOTE If you are using this 'stringy' first argument, we skip encoding
599 and allow you to declare something like:
600 $c->uri_for('/foo/bar#baz')
602 Where 'baz' is a URI fragment. We consider this first argument string
604 to be 'expert' mode where you are expected to create a valid URL and we
605 for the most part just pass it through without a lot of internal effort
606 to escape and encode.
607 If the first argument is a Catalyst::Action it represents an action
609 which will have its path resolved using
610 "$c->dispatcher->uri_for_action". The optional "\@captures" argument
611 (an arrayref) allows passing the captured variables that are needed to
612 fill in the paths of Chained and Regex actions; once the path is
613 resolved, "uri_for" continues as though a path was provided, appending
614 any arguments or parameters and creating an absolute URI.
615 The captures for the current request can be found in
617 "$c->request->captures", and actions can be resolved using
618 "Catalyst::Controller->action_for($name)". If you have a private action
619 path, use "$c->uri_for_action" instead.
620 # Equivalent to $c->req->uri
622 $c->uri_for($c->action, $c->req->captures,
623 @{ $c->req->args }, $c->req->params);
624 # For the Foo action in the Bar controller
626 $c->uri_for($c->controller('Bar')->action_for('Foo'));
627 # Path to a static resource
629 $c->uri_for('/static/images/logo.png');
630 In general the scheme of the generated URI object will follow the
632 incoming request however if your targeted action or action chain has
633 the Scheme attribute it will use that instead.
634 Also, if the targeted Action or Action chain declares Args/CaptureArgs
636 that have type constraints, we will require that your proposed URL
637 verify on those declared constraints.
638 $c->uri_for_action( $path, \@captures_and_args?, @args?, \%query_values? )
640 $c->uri_for_action( $action, \@captures_and_args?, @args?, \%query_values?
641 )
642 $path
643 A private path to the Catalyst action you want to create a URI for.
644 This is a shortcut for calling
646 "$c->dispatcher->get_action_by_path($path)" and passing the
647 resulting $action and the remaining arguments to "$c->uri_for".
648 You can also pass in a Catalyst::Action object, in which case it is
650 passed to "$c->uri_for".
651 Note that although the path looks like a URI that dispatches to the
653 wanted action, it is not a URI, but an internal path to that
654 action.
655 For example, if the action looks like:
657 package MyApp::Controller::Users;
659 sub lst : Path('the-list') {}
661 You can use:
663 $c->uri_for_action('/users/lst')
665 and it will create the URI /users/the-list.
667 \@captures_and_args?
669 Optional array reference of Captures (i.e. "CaptureArgs" or
670 "$c->req->captures") and arguments to the request. Usually used
671 with Catalyst::DispatchType::Chained to interpolate all the
672 parameters in the URI.
673 @args?
675 Optional list of extra arguments - can be supplied in the
676 "\@captures_and_args?" array ref, or here - whichever is easier for
677 your code.
678 Your action can have zero, a fixed or a variable number of args
680 (e.g. Args(1) for a fixed number or "Args()" for a variable
681 number)..
682 \%query_values?
684 Optional array reference of query parameters to append. E.g.
685 { foo => 'bar' }
687 will generate
689 /rest/of/your/uri?foo=bar
691 $c->welcome_message
693 Returns the Catalyst welcome HTML page.
694 run_options
696 Contains a hash of options passed from the application script,
697 including the original ARGV the script received, the processed values
698 from that ARGV and any extra arguments to the script which were not
699 processed.
700 This can be used to add custom options to your application's scripts
702 and setup your application differently depending on the values of these
703 options.
704
706 These methods are not meant to be used by end users.
707 $c->components
709 Returns a hash of components.
710 $c->context_class
712 Returns or sets the context class.
713 $c->counter
715 Returns a hashref containing coderefs and execution counts (needed for
716 deep recursion detection).
717 $c->depth
719 Returns the number of actions on the current internal execution stack.
720 $c->dispatch
722 Dispatches a request to actions.
723 $c->dispatcher_class
725 Returns or sets the dispatcher class.
726 $c->dump_these
728 Returns a list of 2-element array references (name, structure) pairs
729 that will be dumped on the error page in debug mode.
730 $c->engine_class
732 Returns or sets the engine class.
733 $c->execute( $class, $coderef )
735 Execute a coderef in given class and catch exceptions. Errors are
736 available via $c->error.
737 $c->finalize
739 Finalizes the request.
740 $c->log_stats
742 Logs statistics.
743 $c->finalize_body
745 Finalizes body.
746 $c->finalize_cookies
748 Finalizes cookies.
749 $c->finalize_error
751 Finalizes error. If there is only one error in "error" and it is an
752 object that does "as_psgi" or "code" we rethrow the error and presume
753 it caught by middleware up the ladder. Otherwise we return the
754 debugging error page (in debug mode) or we return the default error
755 page (production mode).
756 $c->finalize_headers
758 Finalizes headers.
759 $c->finalize_encoding
761 Make sure your body is encoded properly IF you set an encoding. By
762 default the encoding is UTF-8 but you can disable it by explicitly
763 setting the encoding configuration value to undef.
764 We can only encode when the body is a scalar. Methods for encoding via
766 the streaming interfaces (such as "write" and "write_fh" on
767 Catalyst::Response are available).
768 See "ENCODING".
770 $c->finalize_output
772 An alias for finalize_body.
773 $c->finalize_read
775 Finalizes the input after reading is complete.
776 $c->finalize_uploads
778 Finalizes uploads. Cleans up any temporary files.
779 $c->get_action( $action, $namespace )
781 Gets an action in a given namespace.
782 $c->get_actions( $action, $namespace )
784 Gets all actions of a given name in a namespace and all parent
785 namespaces.
786 $app->handle_request( @arguments )
788 Called to handle each HTTP request.
789 $class->prepare( @arguments )
791 Creates a Catalyst context from an engine-specific request (Apache,
792 CGI, etc.).
793 $c->prepare_action
795 Prepares action. See Catalyst::Dispatcher.
796 $c->prepare_body
798 Prepares message body.
799 $c->prepare_body_chunk( $chunk )
801 Prepares a chunk of data before sending it to HTTP::Body.
802 See Catalyst::Engine.
804 $c->prepare_body_parameters
806 Prepares body parameters.
807 $c->prepare_connection
809 Prepares connection.
810 $c->prepare_cookies
812 Prepares cookies by ensuring that the attribute on the request object
813 has been built.
814 $c->prepare_headers
816 Prepares request headers by ensuring that the attribute on the request
817 object has been built.
818 $c->prepare_parameters
820 Prepares parameters.
821 $c->prepare_path
823 Prepares path and base.
824 $c->prepare_query_parameters
826 Prepares query parameters.
827 $c->log_request
829 Writes information about the request to the debug logs. This includes:
830 · Request method, path, and remote IP address
832 · Query keywords (see "query_keywords" in Catalyst::Request)
834 · Request parameters
836 · File uploads
838 $c->log_response
840 Writes information about the response to the debug logs by calling
841 "$c->log_response_status_line" and "$c->log_response_headers".
842 $c->log_response_status_line($response)
844 Writes one line of information about the response to the debug logs.
845 This includes:
846 · Response status code
848 · Content-Type header (if present)
850 · Content-Length header (if present)
852 $c->log_response_headers($headers);
854 Hook method which can be wrapped by plugins to log the response
855 headers. No-op in the default implementation.
856 $c->log_request_parameters( query => {}, body => {} )
858 Logs request parameters to debug logs
859 $c->log_request_uploads
861 Logs file uploads included in the request to the debug logs. The
862 parameter name, filename, file type, and file size are all included in
863 the debug logs.
864 $c->log_request_headers($headers);
866 Hook method which can be wrapped by plugins to log the request headers.
867 No-op in the default implementation.
868 $c->log_headers($type => $headers)
870 Logs HTTP::Headers (either request or response) to the debug logs.
871 $c->prepare_read
873 Prepares the input for reading.
874 $c->prepare_request
876 Prepares the engine request.
877 $c->prepare_uploads
879 Prepares uploads.
880 $c->prepare_write
882 Prepares the output for writing.
883 $c->request_class
885 Returns or sets the request class. Defaults to Catalyst::Request.
886 $app->request_class_traits
888 An arrayref of Moose::Roles which are applied to the request class.
889 You can name the full namespace of the role, or a namespace suffix,
890 which will then be tried against the following standard namespace
891 prefixes.
892 $MyApp::TraitFor::Request::$trait_suffix
894 Catalyst::TraitFor::Request::$trait_suffix
895 So for example if you set:
897 MyApp->request_class_traits(['Foo']);
899 We try each possible role in turn (and throw an error if none load)
901 Foo
903 MyApp::TraitFor::Request::Foo
904 Catalyst::TraitFor::Request::Foo
905 The namespace part 'TraitFor::Request' was chosen to assist in
907 backwards compatibility with CatalystX::RoleApplicator which previously
908 provided these features in a stand alone package.
909 $app->composed_request_class
911 This is the request class which has been composed with any
912 request_class_traits.
913 $c->response_class
915 Returns or sets the response class. Defaults to Catalyst::Response.
916 $app->response_class_traits
918 An arrayref of Moose::Roles which are applied to the response class.
919 You can name the full namespace of the role, or a namespace suffix,
920 which will then be tried against the following standard namespace
921 prefixes.
922 $MyApp::TraitFor::Response::$trait_suffix
924 Catalyst::TraitFor::Response::$trait_suffix
925 So for example if you set:
927 MyApp->response_class_traits(['Foo']);
929 We try each possible role in turn (and throw an error if none load)
931 Foo
933 MyApp::TraitFor::Response::Foo
934 Catalyst::TraitFor::Responset::Foo
935 The namespace part 'TraitFor::Response' was chosen to assist in
937 backwards compatibility with CatalystX::RoleApplicator which previously
938 provided these features in a stand alone package.
939 $app->composed_response_class
941 This is the request class which has been composed with any
942 response_class_traits.
943 $c->read( [$maxlength] )
945 Reads a chunk of data from the request body. This method is designed to
946 be used in a while loop, reading $maxlength bytes on every call.
947 $maxlength defaults to the size of the request if not specified.
948 You have to set "MyApp->config(parse_on_demand => 1)" to use this
950 directly.
951 Warning: If you use read(), Catalyst will not process the body, so you
953 will not be able to access POST parameters or file uploads via
954 $c->request. You must handle all body parsing yourself.
955 $c->run
957 Starts the engine.
958 $c->set_action( $action, $code, $namespace, $attrs )
960 Sets an action in a given namespace.
961 $c->setup_actions($component)
963 Sets up actions for a component.
964 $c->setup_components
966 This method is called internally to set up the application's
967 components.
968 It finds modules by calling the locate_components method, expands them
970 to package names with the expand_component_module method, and then
971 installs each component into the application.
972 The "setup_components" config option is passed to both of the above
974 methods.
975 Installation of each component is performed by the setup_component
977 method, below.
978 $app->setup_injected_components
980 Called by setup_compoents to setup components that are injected.
981 $app->setup_injected_component( $injected_component_name, $config )
983 Setup a given injected component.
984 $app->inject_component($MyApp_Component_name => \%args);
986 Add a component that is injected at setup:
987 MyApp->inject_component( 'Model::Foo' => { from_component => 'Common::Foo' } );
989 Must be called before ->setup. Expects a component name for your
991 current application and \%args where
992 from_component
994 The target component being injected into your application
995 roles
997 An arrayref of Moose::Roles that are applied to your component.
998 Example
1000 MyApp->inject_component(
1002 'Model::Foo' => {
1003 from_component => 'Common::Model::Foo',
1004 roles => ['Role1', 'Role2'],
1005 });
1006 $app->inject_components
1008 Inject a list of components:
1009 MyApp->inject_components(
1011 'Model::FooOne' => {
1012 from_component => 'Common::Model::Foo',
1013 roles => ['Role1', 'Role2'],
1014 },
1015 'Model::FooTwo' => {
1016 from_component => 'Common::Model::Foo',
1017 roles => ['Role1', 'Role2'],
1018 });
1019 $c->locate_components( $setup_component_config )
1021 This method is meant to provide a list of component modules that should
1022 be setup for the application. By default, it will use
1023 Module::Pluggable.
1024 Specify a "setup_components" config option to pass additional options
1026 directly to Module::Pluggable. To add additional search paths, specify
1027 a key named "search_extra" as an array reference. Items in the array
1028 beginning with "::" will have the application class name prepended to
1029 them.
1030 $c->expand_component_module( $component, $setup_component_config )
1032 Components found by "locate_components" will be passed to this method,
1033 which is expected to return a list of component (package) names to be
1034 set up.
1035 $app->delayed_setup_component
1037 Returns a coderef that points to a setup_component instance. Used
1038 internally for when you want to delay setup until the first time the
1039 component is called.
1040 $c->setup_component
1042 $app->config_for( $component_name )
1043 Return the application level configuration (which is not yet merged
1044 with any local component configuration, via $component_class->config)
1045 for the named component or component object. Example:
1046 MyApp->config(
1048 'Model::Foo' => { a => 1, b => 2},
1049 );
1050 my $config = MyApp->config_for('MyApp::Model::Foo');
1052 In this case $config is the hashref "{a=>1, b=>2}".
1054 This is also handy for looking up configuration for a plugin, to make
1056 sure you follow existing Catalyst standards for where a plugin should
1057 put its configuration.
1058 $c->setup_dispatcher
1060 Sets up dispatcher.
1061 $c->setup_engine
1063 Sets up engine.
1064 $c->apply_default_middlewares
1066 Adds the following Plack middlewares to your application, since they
1067 are useful and commonly needed:
1068 Plack::Middleware::LighttpdScriptNameFix (if you are using Lighttpd),
1070 Plack::Middleware::IIS6ScriptNameFix (always applied since this
1071 middleware is smart enough to conditionally apply itself).
1072 We will also automatically add Plack::Middleware::ReverseProxy if we
1074 notice that your HTTP $env variable "REMOTE_ADDR" is '127.0.0.1'. This
1075 is usually an indication that your server is running behind a proxy
1076 frontend. However in 2014 this is often not the case. We preserve
1077 this code for backwards compatibility however I highly recommend that
1078 if you are running the server behind a front end proxy that you clearly
1079 indicate so with the "using_frontend_proxy" configuration setting to
1080 true for your environment configurations that run behind a proxy. This
1081 way if you change your front end proxy address someday your code would
1082 inexplicably stop working as expected.
1083 Additionally if we detect we are using Nginx, we add a bit of custom
1085 middleware to solve some problems with the way that server handles
1086 $ENV{PATH_INFO} and $ENV{SCRIPT_NAME}.
1087 Please NOTE that if you do use "using_frontend_proxy" the middleware is
1089 now adding via "registered_middleware" rather than this method.
1090 If you are using Lighttpd or IIS6 you may wish to apply these
1092 middlewares. In general this is no longer a common case but we have
1093 this here for backward compatibility.
1094 App->psgi_app
1096 App->to_app
1097 Returns a PSGI application code reference for the catalyst application
1098 $c. This is the bare application created without the
1099 "apply_default_middlewares" method called. We do however apply
1100 "registered_middleware" since those are integral to how Catalyst
1101 functions. Also, unlike starting your application with a generated
1102 server script (via Catalyst::Devel and "catalyst.pl") we do not attempt
1103 to return a valid PSGI application using any existing "${myapp}.psgi"
1104 scripts in your $HOME directory.
1105 NOTE "apply_default_middlewares" was originally created when the first
1107 PSGI port was done for v5.90000. These are middlewares that are added
1108 to achieve backward compatibility with older applications. If you
1109 start your application using one of the supplied server scripts
1110 (generated with Catalyst::Devel and the project skeleton script
1111 "catalyst.pl") we apply "apply_default_middlewares" automatically.
1112 This was done so that pre and post PSGI port applications would work
1113 the same way.
1114 This is what you want to be using to retrieve the PSGI application code
1116 reference of your Catalyst application for use in a custom .psgi or in
1117 your own created server modules.
1118 $c->setup_home
1120 Sets up the home directory.
1121 $c->setup_encoding
1123 Sets up the input/output encoding. See ENCODING
1124 handle_unicode_encoding_exception
1126 Hook to let you customize how encoding errors are handled. By default
1127 we just throw an exception and the default error page will pick it up.
1128 Receives a hashref of debug information. Example of call (from the
1129 Catalyst internals):
1130 my $decoded_after_fail = $c->handle_unicode_encoding_exception({
1132 param_value => $value,
1133 error_msg => $_,
1134 encoding_step => 'params',
1135 });
1136 The calling code expects to receive a decoded string or an exception.
1138 You can override this for custom handling of unicode errors. By default
1140 we just die. If you want a custom response here, one approach is to
1141 throw an HTTP style exception, instead of returning a decoded string or
1142 throwing a generic exception.
1143 sub handle_unicode_encoding_exception {
1145 my ($c, $params) = @_;
1146 HTTP::Exception::BAD_REQUEST->throw(status_message=>$params->{error_msg});
1147 }
1148 Alternatively you can 'catch' the error, stash it and write handling
1150 code later in your application:
1151 sub handle_unicode_encoding_exception {
1153 my ($c, $params) = @_;
1154 $c->stash(BAD_UNICODE_DATA=>$params);
1155 # return a dummy string.
1156 return 1;
1157 }
1158 <B>NOTE:</b> Please keep in mind that once an error like this occurs,
1160 the request setup is still ongoing, which means the state of $c and
1161 related context parts like the request and response may not be setup up
1162 correctly (since we haven't finished the setup yet). If you throw an
1163 exception the setup is aborted.
1164 $c->setup_log
1166 Sets up log by instantiating a Catalyst::Log object and passing it to
1167 "log()". Pass in a comma-delimited list of levels to set the log to.
1168 This method also installs a "debug" method that returns a true value
1170 into the catalyst subclass if the "debug" level is passed in the comma-
1171 delimited list, or if the $CATALYST_DEBUG environment variable is set
1172 to a true value.
1173 Note that if the log has already been setup, by either a previous call
1175 to "setup_log" or by a call such as "__PACKAGE__->log( MyLogger->new
1176 )", that this method won't actually set up the log object.
1177 $c->setup_plugins
1179 Sets up plugins.
1180 $c->setup_stats
1182 Sets up timing statistics class.
1183 $c->registered_plugins
1185 Returns a sorted list of the plugins which have either been stated in
1186 the import list.
1187 If passed a given plugin name, it will report a boolean value
1189 indicating whether or not that plugin is loaded. A fully qualified
1190 name is required if the plugin name does not begin with
1191 "Catalyst::Plugin::".
1192 if ($c->registered_plugins('Some::Plugin')) {
1194 ...
1195 }
1196 default_middleware
1198 Returns a list of instantiated PSGI middleware objects which is the
1199 default middleware that is active for this application (taking any
1200 configuration options into account, excluding your custom added
1201 middleware via the "psgi_middleware" configuration option). You can
1202 override this method if you wish to change the default middleware
1203 (although do so at risk since some middleware is vital to application
1204 function.)
1205 The current default middleware list is:
1207 Catalyst::Middleware::Stash
1209 Plack::Middleware::HTTPExceptions
1210 Plack::Middleware::RemoveRedundantBody
1211 Plack::Middleware::FixMissingBodyInRedirect
1212 Plack::Middleware::ContentLength
1213 Plack::Middleware::MethodOverride
1214 Plack::Middleware::Head
1215 If the configuration setting "using_frontend_proxy" is true we add:
1217 Plack::Middleware::ReverseProxy
1219 If the configuration setting "using_frontend_proxy_path" is true we
1221 add:
1222 Plack::Middleware::ReverseProxyPath
1224 But NOTE that Plack::Middleware::ReverseProxyPath is not a dependency
1226 of the Catalyst distribution so if you want to use this option you
1227 should add it to your project distribution file.
1228 These middlewares will be added at "setup_middleware" during the
1230 "setup" phase of application startup.
1231 registered_middlewares
1233 Read only accessor that returns an array of all the middleware in the
1234 order that they were added (which is the REVERSE of the order they will
1235 be applied).
1236 The values returned will be either instances of Plack::Middleware or of
1238 a compatible interface, or a coderef, which is assumed to be inlined
1239 middleware
1240 setup_middleware (?@middleware)
1242 Read configuration information stored in configuration key
1243 "psgi_middleware" or from passed @args.
1244 See under "CONFIGURATION" information regarding "psgi_middleware" and
1246 how to use it to enable Plack::Middleware
1247 This method is automatically called during 'setup' of your application,
1249 so you really don't need to invoke it. However you may do so if you
1250 find the idea of loading middleware via configuration weird :). For
1251 example:
1252 package MyApp;
1254 use Catalyst;
1256 __PACKAGE__->setup_middleware('Head');
1258 __PACKAGE__->setup;
1259 When we read middleware definitions from configuration, we reverse the
1261 list which sounds odd but is likely how you expect it to work if you
1262 have prior experience with Plack::Builder or if you previously used the
1263 plugin Catalyst::Plugin::EnableMiddleware (which is now considered
1264 deprecated)
1265 So basically your middleware handles an incoming request from the first
1267 registered middleware, down and handles the response from the last
1268 middleware up.
1269 registered_data_handlers
1271 A read only copy of registered Data Handlers returned as a Hash, where
1272 each key is a content type and each value is a subref that attempts to
1273 decode that content type.
1274 setup_data_handlers (?@data_handler)
1276 Read configuration information stored in configuration key
1277 "data_handlers" or from passed @args.
1278 See under "CONFIGURATION" information regarding "data_handlers".
1280 This method is automatically called during 'setup' of your application,
1282 so you really don't need to invoke it.
1283 default_data_handlers
1285 Default Data Handlers that come bundled with Catalyst. Currently there
1286 are only two default data handlers, for 'application/json' and an
1287 alternative to 'application/x-www-form-urlencoded' which supposed
1288 nested form parameters via CGI::Struct or via CGI::Struct::XS IF you've
1289 installed it.
1290 The 'application/json' data handler is used to parse incoming JSON into
1292 a Perl data structure. It uses JSON::MaybeXS. This allows you to fail
1293 back to JSON::PP, which is a Pure Perl JSON decoder, and has the
1294 smallest dependency impact.
1295 Because we don't wish to add more dependencies to Catalyst, if you wish
1297 to use this new feature we recommend installing Cpanel::JSON::XS in
1298 order to get the best performance. You should add either to your
1299 dependency list (Makefile.PL, dist.ini, cpanfile, etc.)
1300 $c->stack
1302 Returns an arrayref of the internal execution stack (actions that are
1303 currently executing).
1304 $c->stats
1306 Returns the current timing statistics object. By default Catalyst uses
1307 Catalyst::Stats, but can be set otherwise with stats_class.
1308 Even if -Stats is not enabled, the stats object is still available. By
1310 enabling it with "$c->stats->enabled(1)", it can be used to profile
1311 explicitly, although MyApp.pm still won't profile nor output anything
1312 by itself.
1313 $c->stats_class
1315 Returns or sets the stats (timing statistics) class. Catalyst::Stats is
1316 used by default.
1317 $app->stats_class_traits
1319 A arrayref of Moose::Roles that are applied to the stats_class before
1320 creating it.
1321 $app->composed_stats_class
1323 this is the stats_class composed with any 'stats_class_traits'. You
1324 can name the full namespace of the role, or a namespace suffix, which
1325 will then be tried against the following standard namespace prefixes.
1326 $MyApp::TraitFor::Stats::$trait_suffix
1328 Catalyst::TraitFor::Stats::$trait_suffix
1329 So for example if you set:
1331 MyApp->stats_class_traits(['Foo']);
1333 We try each possible role in turn (and throw an error if none load)
1335 Foo
1337 MyApp::TraitFor::Stats::Foo
1338 Catalyst::TraitFor::Stats::Foo
1339 The namespace part 'TraitFor::Stats' was chosen to assist in backwards
1341 compatibility with CatalystX::RoleApplicator which previously provided
1342 these features in a stand alone package.
1343 $c->use_stats
1345 Returns 1 when stats collection is enabled.
1346 Note that this is a static method, not an accessor and should be
1348 overridden by declaring "sub use_stats { 1 }" in your MyApp.pm, not by
1349 calling "$c->use_stats(1)".
1350 $c->write( $data )
1352 Writes $data to the output stream. When using this method directly, you
1353 will need to manually set the "Content-Length" header to the length of
1354 your output data, if known.
1355 version
1357 Returns the Catalyst version number. Mostly useful for "powered by"
1358 messages in template systems.
1359
1361 There are a number of 'base' config variables which can be set:
1362 · "always_catch_http_exceptions" - As of version 5.90060 Catalyst
1364 rethrows errors conforming to the interface described by
1365 Plack::Middleware::HTTPExceptions and lets the middleware deal with
1366 it. Set true to get the deprecated behaviour and have Catalyst
1367 catch HTTP exceptions.
1368 · "default_model" - The default model picked if you say "$c->model".
1370 See "$c->model($name)".
1371 · "default_view" - The default view to be rendered or returned when
1373 "$c->view" is called. See "$c->view($name)".
1374 · "disable_component_resolution_regex_fallback" - Turns off the
1376 deprecated component resolution functionality so that if any of the
1377 component methods (e.g. "$c->controller('Foo')") are called then
1378 regex search will not be attempted on string values and instead
1379 "undef" will be returned.
1380 · "home" - The application home directory. In an uninstalled
1382 application, this is the top level application directory. In an
1383 installed application, this will be the directory containing
1384 "MyApp.pm".
1385 · "ignore_frontend_proxy" - See "PROXY SUPPORT"
1387 · "name" - The name of the application in debug messages and the
1389 debug and welcome screens
1390 · "parse_on_demand" - The request body (for example file uploads)
1392 will not be parsed until it is accessed. This allows you to (for
1393 example) check authentication (and reject the upload) before
1394 actually receiving all the data. See "ON-DEMAND PARSER"
1395 · "root" - The root directory for templates. Usually this is just a
1397 subdirectory of the home directory, but you can set it to change
1398 the templates to a different directory.
1399 · "search_extra" - Array reference passed to Module::Pluggable to for
1401 additional namespaces from which components will be loaded (and
1402 constructed and stored in "$c->components").
1403 · "show_internal_actions" - If true, causes internal actions such as
1405 "_DISPATCH" to be shown in hit debug tables in the test server.
1406 · "use_request_uri_for_path" - Controls if the "REQUEST_URI" or
1408 "PATH_INFO" environment variable should be used for determining the
1409 request path.
1410 Most web server environments pass the requested path to the
1412 application using environment variables, from which Catalyst has to
1413 reconstruct the request base (i.e. the top level path to / in the
1414 application, exposed as "$c->request->base") and the request path
1415 below that base.
1416 There are two methods of doing this, both of which have advantages
1418 and disadvantages. Which method is used is determined by the
1419 "$c->config(use_request_uri_for_path)" setting (which can either be
1420 true or false).
1421 use_request_uri_for_path => 0
1423 This is the default (and the) traditional method that Catalyst
1424 has used for determining the path information. The path is
1425 generated from a combination of the "PATH_INFO" and
1426 "SCRIPT_NAME" environment variables. The allows the
1427 application to behave correctly when "mod_rewrite" is being
1428 used to redirect requests into the application, as these
1429 variables are adjusted by mod_rewrite to take account for the
1430 redirect.
1431 However this method has the major disadvantage that it is
1433 impossible to correctly decode some elements of the path, as
1434 RFC 3875 says: ""Unlike a URI path, the PATH_INFO is not
1435 URL-encoded, and cannot contain path-segment parameters."" This
1436 means PATH_INFO is always decoded, and therefore Catalyst can't
1437 distinguish / vs %2F in paths (in addition to other encoded
1438 values).
1439 use_request_uri_for_path => 1
1441 This method uses the "REQUEST_URI" and "SCRIPT_NAME"
1442 environment variables. As "REQUEST_URI" is never decoded, this
1443 means that applications using this mode can correctly handle
1444 URIs including the %2F character (i.e. with
1445 "AllowEncodedSlashes" set to "On" in Apache).
1446 Given that this method of path resolution is provably more
1448 correct, it is recommended that you use this unless you have a
1449 specific need to deploy your application in a non-standard
1450 environment, and you are aware of the implications of not being
1451 able to handle encoded URI paths correctly.
1452 However it also means that in a number of cases when the app
1454 isn't installed directly at a path, but instead is having paths
1455 rewritten into it (e.g. as a .cgi/fcgi in a public_html
1456 directory, with mod_rewrite in a .htaccess file, or when SSI is
1457 used to rewrite pages into the app, or when sub-paths of the
1458 app are exposed at other URIs than that which the app is
1459 'normally' based at with "mod_rewrite"), the resolution of
1460 "$c->request->base" will be incorrect.
1461 · "using_frontend_proxy" - See "PROXY SUPPORT".
1463 · "using_frontend_proxy_path" - Enabled
1465 Plack::Middleware::ReverseProxyPath on your application (if
1466 installed, otherwise log an error). This is useful if your
1467 application is not running on the 'root' (or /) of your host
1468 server. NOTE if you use this feature you should add the required
1469 middleware to your project dependency list since its not
1470 automatically a dependency of Catalyst. This has been done since
1471 not all people need this feature and we wish to restrict the growth
1472 of Catalyst dependencies.
1473 · "encoding" - See "ENCODING"
1475 This now defaults to 'UTF-8'. You my turn it off by setting this
1477 configuration value to undef.
1478 · "abort_chain_on_error_fix"
1480 Defaults to true.
1482 When there is an error in an action chain, the default behavior is
1484 to abort the processing of the remaining actions to avoid running
1485 them when the application is in an unexpected state.
1486 Before version 5.90070, the default used to be false. To keep the
1488 old behaviour, you can explicitly set the value to false. E.g.
1489 __PACKAGE__->config(abort_chain_on_error_fix => 0);
1491 If this setting is set to false, then the remaining actions are
1493 performed and the error is caught at the end of the chain.
1494 · "use_hash_multivalue_in_request"
1496 In Catalyst::Request the methods "query_parameters",
1498 "body_parametes" and "parameters" return a hashref where values
1499 might be scalar or an arrayref depending on the incoming data. In
1500 many cases this can be undesirable as it leads one to writing
1501 defensive code like the following:
1502 my ($val) = ref($c->req->parameters->{a}) ?
1504 @{$c->req->parameters->{a}} :
1505 $c->req->parameters->{a};
1506 Setting this configuration item to true will make Catalyst populate
1508 the attributes underlying these methods with an instance of
1509 Hash::MultiValue which is used by Plack::Request and others to
1510 solve this very issue. You may prefer this behavior to the
1511 default, if so enable this option (be warned if you enable it in a
1512 legacy application we are not sure if it is completely backwardly
1513 compatible).
1514 · "skip_complex_post_part_handling"
1516 When creating body parameters from a POST, if we run into a
1518 multipart POST that does not contain uploads, but instead contains
1519 inlined complex data (very uncommon) we cannot reliably convert
1520 that into field => value pairs. So instead we create an instance
1521 of Catalyst::Request::PartData. If this causes issue for you, you
1522 can disable this by setting "skip_complex_post_part_handling" to
1523 true (default is false).
1524 · "skip_body_param_unicode_decoding"
1526 Generally we decode incoming POST params based on your declared
1528 encoding (the default for this is to decode UTF-8). If this is
1529 causing you trouble and you do not wish to turn all encoding
1530 support off (with the "encoding" configuration parameter) you may
1531 disable this step atomically by setting this configuration
1532 parameter to true.
1533 · "do_not_decode_query"
1535 If true, then do not try to character decode any wide characters in
1537 your request URL query or keywords. Most readings of the relevant
1538 specifications suggest these should be UTF-* encoded, which is the
1539 default that Catalyst will use, however if you are creating a lot
1540 of URLs manually or have external evil clients, this might cause
1541 you trouble. If you find the changes introduced in Catalyst
1542 version 5.90080+ break some of your query code, you may disable the
1543 UTF-8 decoding globally using this configuration.
1544 This setting takes precedence over "default_query_encoding"
1546 · "do_not_check_query_encoding"
1548 Catalyst versions 5.90080 - 5.90106 would decode query parts of an
1550 incoming request but would not raise an exception when the decoding
1551 failed due to incorrect unicode. It now does, but if this change
1552 is giving you trouble you may disable it by setting this
1553 configuration to true.
1554 · "default_query_encoding"
1556 By default we decode query and keywords in your request URL using
1558 UTF-8, which is our reading of the relevant specifications. This
1559 setting allows one to specify a fixed value for how to decode your
1560 query. You might need this if you are doing a lot of custom
1561 encoding of your URLs and not using UTF-8.
1562 · "use_chained_args_0_special_case"
1564 In older versions of Catalyst, when more than one action matched
1566 the same path AND all those matching actions declared Args(0), we'd
1567 break the tie by choosing the first action defined. We now
1568 normalized how Args(0) works so that it follows the same rule as
1569 Args(N), which is to say when we need to break a tie we choose the
1570 LAST action defined. If this breaks your code and you don't have
1571 time to update to follow the new normalized approach, you may set
1572 this value to true and it will globally revert to the original
1573 chaining behavior.
1574 · "psgi_middleware" - See "PSGI MIDDLEWARE".
1576 · "data_handlers" - See "DATA HANDLERS".
1578 · "stats_class_traits"
1580 An arrayref of Moose::Roles that get composed into your stats
1582 class.
1583 · "request_class_traits"
1585 An arrayref of Moose::Roles that get composed into your request
1587 class.
1588 · "response_class_traits"
1590 An arrayref of Moose::Roles that get composed into your response
1592 class.
1593 · "inject_components"
1595 A Hashref of Catalyst::Component subclasses that are 'injected'
1597 into configuration. For example:
1598 MyApp->config({
1600 inject_components => {
1601 'Controller::Err' => { from_component => 'Local::Controller::Errors' },
1602 'Model::Zoo' => { from_component => 'Local::Model::Foo' },
1603 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] },
1604 },
1605 'Controller::Err' => { a => 100, b=>200, namespace=>'error' },
1606 'Model::Zoo' => { a => 2 },
1607 'Model::Foo' => { a => 100 },
1608 });
1609 Generally Catalyst looks for components in your Model/View or
1611 Controller directories. However for cases when you which to use an
1612 existing component and you don't need any customization (where for
1613 when you can apply a role to customize it) you may inject those
1614 components into your application. Please note any configuration
1615 should be done 'in the normal way', with a key under configuration
1616 named after the component affix, as in the above example.
1617 Using this type of injection allows you to construct significant
1619 amounts of your application with only configuration!. This may or
1620 may not lead to increased code understanding.
1621 Please not you may also call the ->inject_components application
1623 method as well, although you must do so BEFORE setup.
1624
1626 Generally when you throw an exception inside an Action (or somewhere in
1627 your stack, such as in a model that an Action is calling) that
1628 exception is caught by Catalyst and unless you either catch it yourself
1629 (via eval or something like Try::Tiny or by reviewing the "error"
1630 stack, it will eventually reach "finalize_errors" and return either the
1631 debugging error stack page, or the default error page. However, if
1632 your exception can be caught by Plack::Middleware::HTTPExceptions,
1633 Catalyst will instead rethrow it so that it can be handled by that
1634 middleware (which is part of the default middleware). For example this
1635 would allow
1636 use HTTP::Throwable::Factory 'http_throw';
1638 sub throws_exception :Local {
1640 my ($self, $c) = @_;
1641 http_throw(SeeOther => { location =>
1643 $c->uri_for($self->action_for('redirect')) });
1644 }
1646
1648 Catalyst uses internal actions like "_DISPATCH", "_BEGIN", "_AUTO",
1649 "_ACTION", and "_END". These are by default not shown in the private
1650 action table, but you can make them visible with a config parameter.
1651 MyApp->config(show_internal_actions => 1);
1653
1655 The request body is usually parsed at the beginning of a request, but
1656 if you want to handle input yourself, you can enable on-demand parsing
1657 with a config parameter.
1658 MyApp->config(parse_on_demand => 1);
1660
1662 Many production servers operate using the common double-server
1663 approach, with a lightweight frontend web server passing requests to a
1664 larger backend server. An application running on the backend server
1665 must deal with two problems: the remote user always appears to be
1666 127.0.0.1 and the server's hostname will appear to be "localhost"
1667 regardless of the virtual host that the user connected through.
1668 Catalyst will automatically detect this situation when you are running
1670 the frontend and backend servers on the same machine. The following
1671 changes are made to the request.
1672 $c->req->address is set to the user's real IP address, as read from
1674 the HTTP X-Forwarded-For header.
1675 The host value for $c->req->base and $c->req->uri is set to the real
1677 host, as read from the HTTP X-Forwarded-Host header.
1678 Additionally, you may be running your backend application on an
1680 insecure connection (port 80) while your frontend proxy is running
1681 under SSL. If there is a discrepancy in the ports, use the HTTP header
1682 "X-Forwarded-Port" to tell Catalyst what port the frontend listens on.
1683 This will allow all URIs to be created properly.
1684 In the case of passing in:
1686 X-Forwarded-Port: 443
1688 All calls to "uri_for" will result in an https link, as is expected.
1690 Obviously, your web server must support these headers for this to work.
1692 In a more complex server farm environment where you may have your
1694 frontend proxy server(s) on different machines, you will need to set a
1695 configuration option to tell Catalyst to read the proxied data from the
1696 headers.
1697 MyApp->config(using_frontend_proxy => 1);
1699 If you do not wish to use the proxy support at all, you may set:
1701 MyApp->config(ignore_frontend_proxy => 0);
1703 Note about psgi files
1705 Note that if you supply your own .psgi file, calling
1706 "MyApp->psgi_app(@_);", then this will not happen automatically.
1707 You either need to apply Plack::Middleware::ReverseProxy yourself in
1709 your psgi, for example:
1710 builder {
1712 enable "Plack::Middleware::ReverseProxy";
1713 MyApp->psgi_app
1714 };
1715 This will unconditionally add the ReverseProxy support, or you need to
1717 call "$app = MyApp->apply_default_middlewares($app)" (to conditionally
1718 apply the support depending upon your config).
1719 See Catalyst::PSGI for more information.
1721
1723 Catalyst has been tested under Apache 2's threading "mpm_worker",
1724 "mpm_winnt", and the standalone forking HTTP server on Windows. We
1725 believe the Catalyst core to be thread-safe.
1726 If you plan to operate in a threaded environment, remember that all
1728 other modules you are using must also be thread-safe. Some modules,
1729 most notably DBD::SQLite, are not thread-safe.
1730
1732 The Catalyst::Request object uses HTTP::Body to populate 'classic' HTML
1733 form parameters and URL search query fields. However it has become
1734 common for various alternative content types to be PUT or POSTed to
1735 your controllers and actions. People working on RESTful APIs, or using
1736 AJAX often use JSON, XML and other content types when communicating
1737 with an application server. In order to better support this use case,
1738 Catalyst defines a global configuration option, "data_handlers", which
1739 lets you associate a content type with a coderef that parses that
1740 content type into something Perl can readily access.
1741 package MyApp::Web;
1743 use Catalyst;
1745 use JSON::MaybeXS;
1746 __PACKAGE__->config(
1748 data_handlers => {
1749 'application/json' => sub { local $/; decode_json $_->getline },
1750 },
1751 ## Any other configuration.
1752 );
1753 __PACKAGE__->setup;
1755 By default Catalyst comes with a generic JSON data handler similar to
1757 the example given above, which uses JSON::MaybeXS to provide either
1758 JSON::PP (a pure Perl, dependency free JSON parser) or Cpanel::JSON::XS
1759 if you have it installed (if you want the faster XS parser, add it to
1760 you project Makefile.PL or dist.ini, cpanfile, etc.)
1761 The "data_handlers" configuration is a hashref whose keys are HTTP
1763 Content-Types (matched against the incoming request type using a regexp
1764 such as to be case insensitive) and whose values are coderefs that
1765 receive a localized version of $_ which is a filehandle object pointing
1766 to received body.
1767 This feature is considered an early access release and we reserve the
1769 right to alter the interface in order to provide a performant and
1770 secure solution to alternative request body content. Your reports
1771 welcomed!
1772
1774 You can define middleware, defined as Plack::Middleware or a compatible
1775 interface in configuration. Your middleware definitions are in the
1776 form of an arrayref under the configuration key "psgi_middleware".
1777 Here's an example with details to follow:
1778 package MyApp::Web;
1780 use Catalyst;
1782 use Plack::Middleware::StackTrace;
1783 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1785 __PACKAGE__->config(
1787 'psgi_middleware', [
1788 'Debug',
1789 '+MyApp::Custom',
1790 $stacktrace_middleware,
1791 'Session' => {store => 'File'},
1792 sub {
1793 my $app = shift;
1794 return sub {
1795 my $env = shift;
1796 $env->{myapp.customkey} = 'helloworld';
1797 $app->($env);
1798 },
1799 },
1800 ],
1801 );
1802 __PACKAGE__->setup;
1804 So the general form is:
1806 __PACKAGE__->config(psgi_middleware => \@middleware_definitions);
1808 Where @middleware is one or more of the following, applied in the
1810 REVERSE of the order listed (to make it function similarly to
1811 Plack::Builder:
1812 Alternatively, you may also define middleware by calling the
1814 "setup_middleware" package method:
1815 package MyApp::Web;
1817 use Catalyst;
1819 __PACKAGE__->setup_middleware( \@middleware_definitions);
1821 __PACKAGE__->setup;
1822 In the case where you do both (use 'setup_middleware' and
1824 configuration) the package call to setup_middleware will be applied
1825 earlier (in other words its middleware will wrap closer to the
1826 application). Keep this in mind since in some cases the order of
1827 middleware is important.
1828 The two approaches are not exclusive.
1830 Middleware Object
1832 An already initialized object that conforms to the
1833 Plack::Middleware specification:
1834 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1836 __PACKAGE__->config(
1838 'psgi_middleware', [
1839 $stacktrace_middleware,
1840 ]);
1841 coderef
1843 A coderef that is an inlined middleware:
1844 __PACKAGE__->config(
1846 'psgi_middleware', [
1847 sub {
1848 my $app = shift;
1849 return sub {
1850 my $env = shift;
1851 if($env->{PATH_INFO} =~m/forced/) {
1852 Plack::App::File
1853 ->new(file=>TestApp->path_to(qw/share static forced.txt/))
1854 ->call($env);
1855 } else {
1856 return $app->($env);
1857 }
1858 },
1859 },
1860 ]);
1861 a scalar
1863 We assume the scalar refers to a namespace after normalizing it
1864 using the following rules:
1865 (1) If the scalar is prefixed with a "+" (as in "+MyApp::Foo") then
1867 the full string is assumed to be 'as is', and we just install and
1868 use the middleware.
1869 (2) If the scalar begins with "Plack::Middleware" or your
1871 application namespace (the package name of your Catalyst
1872 application subclass), we also assume then that it is a full
1873 namespace, and use it.
1874 (3) Lastly, we then assume that the scalar is a partial namespace,
1876 and attempt to resolve it first by looking for it under your
1877 application namespace (for example if you application is
1878 "MyApp::Web" and the scalar is "MyMiddleware", we'd look under
1879 "MyApp::Web::Middleware::MyMiddleware") and if we don't find it
1880 there, we will then look under the regular Plack::Middleware
1881 namespace (i.e. for the previous we'd try
1882 "Plack::Middleware::MyMiddleware"). We look under your application
1883 namespace first to let you 'override' common Plack::Middleware
1884 locally, should you find that a good idea.
1885 Examples:
1887 package MyApp::Web;
1889 __PACKAGE__->config(
1891 'psgi_middleware', [
1892 'Debug', ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap
1893 'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap
1894 '+MyApp::Custom', ## MyApp::Custom->wrap
1895 ],
1896 );
1897 a scalar followed by a hashref
1899 Just like the previous, except the following "HashRef" is used as
1900 arguments to initialize the middleware object.
1901 __PACKAGE__->config(
1903 'psgi_middleware', [
1904 'Session' => {store => 'File'},
1905 ]);
1906 Please see PSGI for more on middleware.
1908
1910 Starting in Catalyst version 5.90080 encoding is automatically enabled
1911 and set to encode all body responses to UTF8 when possible and
1912 applicable. Following is documentation on this process. If you are
1913 using an older version of Catalyst you should review documentation for
1914 that version since a lot has changed.
1915 By default encoding is now 'UTF-8'. You may turn it off by setting the
1917 encoding configuration to undef.
1918 MyApp->config(encoding => undef);
1920 This is recommended for temporary backwards compatibility only.
1922 To turn it off for a single request use the clear_encoding method to
1924 turn off encoding for this request. This can be useful when you are
1925 setting the body to be an arbitrary block of bytes, especially if that
1926 block happens to be a block of UTF8 text.
1927 Encoding is automatically applied when the content-type is set to a
1929 type that can be encoded. Currently we encode when the content type
1930 matches the following regular expression:
1931 $content_type =~ /^text|xml$|javascript$/
1933 Encoding is set on the application, but it is copied to the context
1935 object so that you can override it on a request basis.
1936 Be default we don't automatically encode 'application/json' since the
1938 most common approaches to generating this type of response (Either via
1939 Catalyst::View::JSON or Catalyst::Action::REST) will do so already and
1940 we want to avoid double encoding issues.
1941 If you are producing JSON response in an unconventional manner (such as
1943 via a template or manual strings) you should perform the UTF8 encoding
1944 manually as well such as to conform to the JSON specification.
1945 NOTE: We also examine the value of $c->response->content_encoding. If
1947 you set this (like for example 'gzip', and manually gzipping the body)
1948 we assume that you have done all the necessary encoding yourself, since
1949 we cannot encode the gzipped contents. If you use a plugin like
1950 Catalyst::Plugin::Compress you need to update to a modern version in
1951 order to have this function correctly with the new UTF8 encoding code,
1952 or you can use Plack::Middleware::Deflater or (probably best) do your
1953 compression on a front end proxy.
1954 Methods
1956 encoding
1957 Returns an instance of an "Encode" encoding
1958 print $c->encoding->name
1960 handle_unicode_encoding_exception ($exception_context)
1962 Method called when decoding process for a request fails.
1963 An $exception_context hashref is provided to allow you to override
1965 the behaviour of your application when given data with incorrect
1966 encodings.
1967 The default method throws exceptions in the case of invalid request
1969 parameters (resulting in a 500 error), but ignores errors in upload
1970 filenames.
1971 The keys passed in the $exception_context hash are:
1973 param_value
1975 The value which was not able to be decoded.
1976 error_msg
1978 The exception received from Encode.
1979 encoding_step
1981 What type of data was being decoded. Valid values are
1982 (currently) "params" - for request parameters / arguments /
1983 captures and "uploads" - for request upload filenames.
1984
1986 IRC:
1987 Join #catalyst on irc.perl.org.
1989 Mailing Lists:
1991 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
1993 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
1994 Web:
1996 http://catalyst.perl.org
1998 Wiki:
2000 http://dev.catalyst.perl.org
2002
2004 Task::Catalyst - All you need to start with Catalyst
2005 Catalyst::Manual - The Catalyst Manual
2006 Catalyst::Component, Catalyst::Controller - Base classes for components
2007 Catalyst::Engine - Core engine
2008 Catalyst::Log - Log class.
2009 Catalyst::Request - Request object
2010 Catalyst::Response - Response object
2011 Catalyst::Test - The test suite.
2013 sri: Sebastian Riedel <sri@cpan.org>
2014
2016 abw: Andy Wardley
2017 acme: Leon Brocard <leon@astray.com>
2019 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
2021 andrewalker: André Walker <andre@cpan.org>
2023 Andrew Bramble
2025 Andrew Ford <A.Ford@ford-mason.co.uk>
2027 Andrew Ruthven
2029 andyg: Andy Grundman <andy@hybridized.org>
2031 audreyt: Audrey Tang
2033 bricas: Brian Cassidy <bricas@cpan.org>
2035 Caelum: Rafael Kitover <rkitover@io.com>
2037 chansen: Christian Hansen
2039 Chase Venters <chase.venters@gmail.com>
2041 chicks: Christopher Hicks
2043 Chisel Wright <pause@herlpacker.co.uk>
2045 Danijel Milicevic <me@danijel.de>
2047 davewood: David Schmidt <davewood@cpan.org>
2049 David Kamholz <dkamholz@cpan.org>
2051 David Naughton <naughton@umn.edu>
2053 David E. Wheeler
2055 dhoss: Devin Austin <dhoss@cpan.org>
2057 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
2059 Drew Taylor
2061 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
2063 esskar: Sascha Kiefer
2065 fireartist: Carl Franks <cfranks@cpan.org>
2067 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
2069 gabb: Danijel Milicevic
2071 Gary Ashton Jones
2073 Gavin Henry <ghenry@perl.me.uk>
2075 Geoff Richards
2077 groditi: Guillermo Roditi <groditi@gmail.com>
2079 hobbs: Andrew Rodland <andrew@cleverdomain.org>
2081 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
2083 jcamacho: Juan Camacho
2085 jester: Jesse Sheidlower <jester@panix.com>
2087 jhannah: Jay Hannah <jay@jays.net>
2089 Jody Belka
2091 Johan Lindstrom
2093 jon: Jon Schutz <jjschutz@cpan.org>
2095 Jonathan Rockway <jrockway@cpan.org>
2097 Kieren Diment <kd@totaldatasolution.com>
2099 konobi: Scott McWhirter <konobi@cpan.org>
2101 marcus: Marcus Ramberg <mramberg@cpan.org>
2103 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
2105 mgrimes: Mark Grimes <mgrimes@cpan.org>
2107 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
2109 mugwump: Sam Vilain
2111 naughton: David Naughton
2113 ningu: David Kamholz <dkamholz@cpan.org>
2115 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
2117 numa: Dan Sully <daniel@cpan.org>
2119 obra: Jesse Vincent
2121 Octavian Rasnita
2123 omega: Andreas Marienborg
2125 Oleg Kostyuk <cub.uanic@gmail.com>
2127 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
2129 rafl: Florian Ragwitz <rafl@debian.org>
2131 random: Roland Lammel <lammel@cpan.org>
2133 revmischa: Mischa Spiegelmock <revmischa@cpan.org>
2135 Robert Sedlacek <rs@474.at>
2137 rrwo: Robert Rothenberg <rrwo@cpan.org>
2139 SpiceMan: Marcel Montes
2141 sky: Arthur Bergman
2143 szbalint: Balint Szilakszi <szbalint@cpan.org>
2145 t0m: Tomas Doran <bobtfish@bobtfish.net>
2147 Ulf Edvinsson
2149 vanstyn: Henry Van Styn <vanstyn@cpan.org>
2151 Viljo Marrandi <vilts@yahoo.com>
2153 Will Hawes <info@whawes.co.uk>
2155 willert: Sebastian Willert <willert@cpan.org>
2157 wreis: Wallace Reis <wreis@cpan.org>
2159 Yuval Kogman <nothingmuch@woobling.org>
2161 rainboxx: Matthias Dietrich <perl@rainboxx.de>
2163 dd070: Dhaval Dhanani <dhaval070@gmail.com>
2165 Upasana <me@upasana.me>
2167 John Napiorkowski (jnap) <jjnapiork@cpan.org>
2169
2171 Copyright (c) 2005-2015, the above named PROJECT FOUNDER and
2172 CONTRIBUTORS.
2173
2175 This library is free software. You can redistribute it and/or modify it
2176 under the same terms as Perl itself.
2177perl v5.30.0 2019-07-26 Catalyst(3)