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->finalize_body
742 Finalizes body.
743 $c->finalize_cookies
745 Finalizes cookies.
746 $c->finalize_error
748 Finalizes error. If there is only one error in "error" and it is an
749 object that does "as_psgi" or "code" we rethrow the error and presume
750 it caught by middleware up the ladder. Otherwise we return the
751 debugging error page (in debug mode) or we return the default error
752 page (production mode).
753 $c->finalize_headers
755 Finalizes headers.
756 $c->finalize_encoding
758 Make sure your body is encoded properly IF you set an encoding. By
759 default the encoding is UTF-8 but you can disable it by explicitly
760 setting the encoding configuration value to undef.
761 We can only encode when the body is a scalar. Methods for encoding via
763 the streaming interfaces (such as "write" and "write_fh" on
764 Catalyst::Response are available).
765 See "ENCODING".
767 $c->finalize_output
769 An alias for finalize_body.
770 $c->finalize_read
772 Finalizes the input after reading is complete.
773 $c->finalize_uploads
775 Finalizes uploads. Cleans up any temporary files.
776 $c->get_action( $action, $namespace )
778 Gets an action in a given namespace.
779 $c->get_actions( $action, $namespace )
781 Gets all actions of a given name in a namespace and all parent
782 namespaces.
783 $app->handle_request( @arguments )
785 Called to handle each HTTP request.
786 $class->prepare( @arguments )
788 Creates a Catalyst context from an engine-specific request (Apache,
789 CGI, etc.).
790 $c->prepare_action
792 Prepares action. See Catalyst::Dispatcher.
793 $c->prepare_body
795 Prepares message body.
796 $c->prepare_body_chunk( $chunk )
798 Prepares a chunk of data before sending it to HTTP::Body.
799 See Catalyst::Engine.
801 $c->prepare_body_parameters
803 Prepares body parameters.
804 $c->prepare_connection
806 Prepares connection.
807 $c->prepare_cookies
809 Prepares cookies by ensuring that the attribute on the request object
810 has been built.
811 $c->prepare_headers
813 Prepares request headers by ensuring that the attribute on the request
814 object has been built.
815 $c->prepare_parameters
817 Prepares parameters.
818 $c->prepare_path
820 Prepares path and base.
821 $c->prepare_query_parameters
823 Prepares query parameters.
824 $c->log_request
826 Writes information about the request to the debug logs. This includes:
827 · Request method, path, and remote IP address
829 · Query keywords (see "query_keywords" in Catalyst::Request)
831 · Request parameters
833 · File uploads
835 $c->log_response
837 Writes information about the response to the debug logs by calling
838 "$c->log_response_status_line" and "$c->log_response_headers".
839 $c->log_response_status_line($response)
841 Writes one line of information about the response to the debug logs.
842 This includes:
843 · Response status code
845 · Content-Type header (if present)
847 · Content-Length header (if present)
849 $c->log_response_headers($headers);
851 Hook method which can be wrapped by plugins to log the response
852 headers. No-op in the default implementation.
853 $c->log_request_parameters( query => {}, body => {} )
855 Logs request parameters to debug logs
856 $c->log_request_uploads
858 Logs file uploads included in the request to the debug logs. The
859 parameter name, filename, file type, and file size are all included in
860 the debug logs.
861 $c->log_request_headers($headers);
863 Hook method which can be wrapped by plugins to log the request headers.
864 No-op in the default implementation.
865 $c->log_headers($type => $headers)
867 Logs HTTP::Headers (either request or response) to the debug logs.
868 $c->prepare_read
870 Prepares the input for reading.
871 $c->prepare_request
873 Prepares the engine request.
874 $c->prepare_uploads
876 Prepares uploads.
877 $c->prepare_write
879 Prepares the output for writing.
880 $c->request_class
882 Returns or sets the request class. Defaults to Catalyst::Request.
883 $app->request_class_traits
885 An arrayref of Moose::Roles which are applied to the request class.
886 You can name the full namespace of the role, or a namespace suffix,
887 which will then be tried against the following standard namespace
888 prefixes.
889 $MyApp::TraitFor::Request::$trait_suffix
891 Catalyst::TraitFor::Request::$trait_suffix
892 So for example if you set:
894 MyApp->request_class_traits(['Foo']);
896 We try each possible role in turn (and throw an error if none load)
898 Foo
900 MyApp::TraitFor::Request::Foo
901 Catalyst::TraitFor::Request::Foo
902 The namespace part 'TraitFor::Request' was chosen to assist in
904 backwards compatibility with CatalystX::RoleApplicator which previously
905 provided these features in a stand alone package.
906 $app->composed_request_class
908 This is the request class which has been composed with any
909 request_class_traits.
910 $c->response_class
912 Returns or sets the response class. Defaults to Catalyst::Response.
913 $app->response_class_traits
915 An arrayref of Moose::Roles which are applied to the response class.
916 You can name the full namespace of the role, or a namespace suffix,
917 which will then be tried against the following standard namespace
918 prefixes.
919 $MyApp::TraitFor::Response::$trait_suffix
921 Catalyst::TraitFor::Response::$trait_suffix
922 So for example if you set:
924 MyApp->response_class_traits(['Foo']);
926 We try each possible role in turn (and throw an error if none load)
928 Foo
930 MyApp::TraitFor::Response::Foo
931 Catalyst::TraitFor::Responset::Foo
932 The namespace part 'TraitFor::Response' was chosen to assist in
934 backwards compatibility with CatalystX::RoleApplicator which previously
935 provided these features in a stand alone package.
936 $app->composed_response_class
938 This is the request class which has been composed with any
939 response_class_traits.
940 $c->read( [$maxlength] )
942 Reads a chunk of data from the request body. This method is designed to
943 be used in a while loop, reading $maxlength bytes on every call.
944 $maxlength defaults to the size of the request if not specified.
945 You have to set "MyApp->config(parse_on_demand => 1)" to use this
947 directly.
948 Warning: If you use read(), Catalyst will not process the body, so you
950 will not be able to access POST parameters or file uploads via
951 $c->request. You must handle all body parsing yourself.
952 $c->run
954 Starts the engine.
955 $c->set_action( $action, $code, $namespace, $attrs )
957 Sets an action in a given namespace.
958 $c->setup_actions($component)
960 Sets up actions for a component.
961 $c->setup_components
963 This method is called internally to set up the application's
964 components.
965 It finds modules by calling the locate_components method, expands them
967 to package names with the expand_component_module method, and then
968 installs each component into the application.
969 The "setup_components" config option is passed to both of the above
971 methods.
972 Installation of each component is performed by the setup_component
974 method, below.
975 $app->setup_injected_components
977 Called by setup_compoents to setup components that are injected.
978 $app->setup_injected_component( $injected_component_name, $config )
980 Setup a given injected component.
981 $app->inject_component($MyApp_Component_name => \%args);
983 Add a component that is injected at setup:
984 MyApp->inject_component( 'Model::Foo' => { from_component => 'Common::Foo' } );
986 Must be called before ->setup. Expects a component name for your
988 current application and \%args where
989 from_component
991 The target component being injected into your application
992 roles
994 An arrayref of Moose::Roles that are applied to your component.
995 Example
997 MyApp->inject_component(
999 'Model::Foo' => {
1000 from_component => 'Common::Model::Foo',
1001 roles => ['Role1', 'Role2'],
1002 });
1003 $app->inject_components
1005 Inject a list of components:
1006 MyApp->inject_components(
1008 'Model::FooOne' => {
1009 from_component => 'Common::Model::Foo',
1010 roles => ['Role1', 'Role2'],
1011 },
1012 'Model::FooTwo' => {
1013 from_component => 'Common::Model::Foo',
1014 roles => ['Role1', 'Role2'],
1015 });
1016 $c->locate_components( $setup_component_config )
1018 This method is meant to provide a list of component modules that should
1019 be setup for the application. By default, it will use
1020 Module::Pluggable.
1021 Specify a "setup_components" config option to pass additional options
1023 directly to Module::Pluggable. To add additional search paths, specify
1024 a key named "search_extra" as an array reference. Items in the array
1025 beginning with "::" will have the application class name prepended to
1026 them.
1027 $c->expand_component_module( $component, $setup_component_config )
1029 Components found by "locate_components" will be passed to this method,
1030 which is expected to return a list of component (package) names to be
1031 set up.
1032 $app->delayed_setup_component
1034 Returns a coderef that points to a setup_component instance. Used
1035 internally for when you want to delay setup until the first time the
1036 component is called.
1037 $c->setup_component
1039 $app->config_for( $component_name )
1040 Return the application level configuration (which is not yet merged
1041 with any local component configuration, via $component_class->config)
1042 for the named component or component object. Example:
1043 MyApp->config(
1045 'Model::Foo' => { a => 1, b => 2},
1046 );
1047 my $config = MyApp->config_for('MyApp::Model::Foo');
1049 In this case $config is the hashref "{a=>1, b=>2}".
1051 This is also handy for looking up configuration for a plugin, to make
1053 sure you follow existing Catalyst standards for where a plugin should
1054 put its configuration.
1055 $c->setup_dispatcher
1057 Sets up dispatcher.
1058 $c->setup_engine
1060 Sets up engine.
1061 $c->apply_default_middlewares
1063 Adds the following Plack middlewares to your application, since they
1064 are useful and commonly needed:
1065 Plack::Middleware::LighttpdScriptNameFix (if you are using Lighttpd),
1067 Plack::Middleware::IIS6ScriptNameFix (always applied since this
1068 middleware is smart enough to conditionally apply itself).
1069 We will also automatically add Plack::Middleware::ReverseProxy if we
1071 notice that your HTTP $env variable "REMOTE_ADDR" is '127.0.0.1'. This
1072 is usually an indication that your server is running behind a proxy
1073 frontend. However in 2014 this is often not the case. We preserve
1074 this code for backwards compatibility however I highly recommend that
1075 if you are running the server behind a front end proxy that you clearly
1076 indicate so with the "using_frontend_proxy" configuration setting to
1077 true for your environment configurations that run behind a proxy. This
1078 way if you change your front end proxy address someday your code would
1079 inexplicably stop working as expected.
1080 Additionally if we detect we are using Nginx, we add a bit of custom
1082 middleware to solve some problems with the way that server handles
1083 $ENV{PATH_INFO} and $ENV{SCRIPT_NAME}.
1084 Please NOTE that if you do use "using_frontend_proxy" the middleware is
1086 now adding via "registered_middleware" rather than this method.
1087 If you are using Lighttpd or IIS6 you may wish to apply these
1089 middlewares. In general this is no longer a common case but we have
1090 this here for backward compatibility.
1091 App->psgi_app
1093 App->to_app
1094 Returns a PSGI application code reference for the catalyst application
1095 $c. This is the bare application created without the
1096 "apply_default_middlewares" method called. We do however apply
1097 "registered_middleware" since those are integral to how Catalyst
1098 functions. Also, unlike starting your application with a generated
1099 server script (via Catalyst::Devel and "catalyst.pl") we do not attempt
1100 to return a valid PSGI application using any existing "${myapp}.psgi"
1101 scripts in your $HOME directory.
1102 NOTE "apply_default_middlewares" was originally created when the first
1104 PSGI port was done for v5.90000. These are middlewares that are added
1105 to achieve backward compatibility with older applications. If you
1106 start your application using one of the supplied server scripts
1107 (generated with Catalyst::Devel and the project skeleton script
1108 "catalyst.pl") we apply "apply_default_middlewares" automatically.
1109 This was done so that pre and post PSGI port applications would work
1110 the same way.
1111 This is what you want to be using to retrieve the PSGI application code
1113 reference of your Catalyst application for use in a custom .psgi or in
1114 your own created server modules.
1115 $c->setup_home
1117 Sets up the home directory.
1118 $c->setup_encoding
1120 Sets up the input/output encoding. See ENCODING
1121 handle_unicode_encoding_exception
1123 Hook to let you customize how encoding errors are handled. By default
1124 we just throw an exception and the default error page will pick it up.
1125 Receives a hashref of debug information. Example of call (from the
1126 Catalyst internals):
1127 my $decoded_after_fail = $c->handle_unicode_encoding_exception({
1129 param_value => $value,
1130 error_msg => $_,
1131 encoding_step => 'params',
1132 });
1133 The calling code expects to receive a decoded string or an exception.
1135 You can override this for custom handling of unicode errors. By default
1137 we just die. If you want a custom response here, one approach is to
1138 throw an HTTP style exception, instead of returning a decoded string or
1139 throwing a generic exception.
1140 sub handle_unicode_encoding_exception {
1142 my ($c, $params) = @_;
1143 HTTP::Exception::BAD_REQUEST->throw(status_message=>$params->{error_msg});
1144 }
1145 Alternatively you can 'catch' the error, stash it and write handling
1147 code later in your application:
1148 sub handle_unicode_encoding_exception {
1150 my ($c, $params) = @_;
1151 $c->stash(BAD_UNICODE_DATA=>$params);
1152 # return a dummy string.
1153 return 1;
1154 }
1155 <B>NOTE:</b> Please keep in mind that once an error like this occurs,
1157 the request setup is still ongoing, which means the state of $c and
1158 related context parts like the request and response may not be setup up
1159 correctly (since we haven't finished the setup yet). If you throw an
1160 exception the setup is aborted.
1161 $c->setup_log
1163 Sets up log by instantiating a Catalyst::Log object and passing it to
1164 "log()". Pass in a comma-delimited list of levels to set the log to.
1165 This method also installs a "debug" method that returns a true value
1167 into the catalyst subclass if the "debug" level is passed in the comma-
1168 delimited list, or if the $CATALYST_DEBUG environment variable is set
1169 to a true value.
1170 Note that if the log has already been setup, by either a previous call
1172 to "setup_log" or by a call such as "__PACKAGE__->log( MyLogger->new
1173 )", that this method won't actually set up the log object.
1174 $c->setup_plugins
1176 Sets up plugins.
1177 $c->setup_stats
1179 Sets up timing statistics class.
1180 $c->registered_plugins
1182 Returns a sorted list of the plugins which have either been stated in
1183 the import list.
1184 If passed a given plugin name, it will report a boolean value
1186 indicating whether or not that plugin is loaded. A fully qualified
1187 name is required if the plugin name does not begin with
1188 "Catalyst::Plugin::".
1189 if ($c->registered_plugins('Some::Plugin')) {
1191 ...
1192 }
1193 default_middleware
1195 Returns a list of instantiated PSGI middleware objects which is the
1196 default middleware that is active for this application (taking any
1197 configuration options into account, excluding your custom added
1198 middleware via the "psgi_middleware" configuration option). You can
1199 override this method if you wish to change the default middleware
1200 (although do so at risk since some middleware is vital to application
1201 function.)
1202 The current default middleware list is:
1204 Catalyst::Middleware::Stash
1206 Plack::Middleware::HTTPExceptions
1207 Plack::Middleware::RemoveRedundantBody
1208 Plack::Middleware::FixMissingBodyInRedirect
1209 Plack::Middleware::ContentLength
1210 Plack::Middleware::MethodOverride
1211 Plack::Middleware::Head
1212 If the configuration setting "using_frontend_proxy" is true we add:
1214 Plack::Middleware::ReverseProxy
1216 If the configuration setting "using_frontend_proxy_path" is true we
1218 add:
1219 Plack::Middleware::ReverseProxyPath
1221 But NOTE that Plack::Middleware::ReverseProxyPath is not a dependency
1223 of the Catalyst distribution so if you want to use this option you
1224 should add it to your project distribution file.
1225 These middlewares will be added at "setup_middleware" during the
1227 "setup" phase of application startup.
1228 registered_middlewares
1230 Read only accessor that returns an array of all the middleware in the
1231 order that they were added (which is the REVERSE of the order they will
1232 be applied).
1233 The values returned will be either instances of Plack::Middleware or of
1235 a compatible interface, or a coderef, which is assumed to be inlined
1236 middleware
1237 setup_middleware (?@middleware)
1239 Read configuration information stored in configuration key
1240 "psgi_middleware" or from passed @args.
1241 See under "CONFIGURATION" information regarding "psgi_middleware" and
1243 how to use it to enable Plack::Middleware
1244 This method is automatically called during 'setup' of your application,
1246 so you really don't need to invoke it. However you may do so if you
1247 find the idea of loading middleware via configuration weird :). For
1248 example:
1249 package MyApp;
1251 use Catalyst;
1253 __PACKAGE__->setup_middleware('Head');
1255 __PACKAGE__->setup;
1256 When we read middleware definitions from configuration, we reverse the
1258 list which sounds odd but is likely how you expect it to work if you
1259 have prior experience with Plack::Builder or if you previously used the
1260 plugin Catalyst::Plugin::EnableMiddleware (which is now considered
1261 deprecated)
1262 So basically your middleware handles an incoming request from the first
1264 registered middleware, down and handles the response from the last
1265 middleware up.
1266 registered_data_handlers
1268 A read only copy of registered Data Handlers returned as a Hash, where
1269 each key is a content type and each value is a subref that attempts to
1270 decode that content type.
1271 setup_data_handlers (?@data_handler)
1273 Read configuration information stored in configuration key
1274 "data_handlers" or from passed @args.
1275 See under "CONFIGURATION" information regarding "data_handlers".
1277 This method is automatically called during 'setup' of your application,
1279 so you really don't need to invoke it.
1280 default_data_handlers
1282 Default Data Handlers that come bundled with Catalyst. Currently there
1283 are only two default data handlers, for 'application/json' and an
1284 alternative to 'application/x-www-form-urlencoded' which supposed
1285 nested form parameters via CGI::Struct or via CGI::Struct::XS IF you've
1286 installed it.
1287 The 'application/json' data handler is used to parse incoming JSON into
1289 a Perl data structure. It uses JSON::MaybeXS. This allows you to fail
1290 back to JSON::PP, which is a Pure Perl JSON decoder, and has the
1291 smallest dependency impact.
1292 Because we don't wish to add more dependencies to Catalyst, if you wish
1294 to use this new feature we recommend installing Cpanel::JSON::XS in
1295 order to get the best performance. You should add either to your
1296 dependency list (Makefile.PL, dist.ini, cpanfile, etc.)
1297 $c->stack
1299 Returns an arrayref of the internal execution stack (actions that are
1300 currently executing).
1301 $c->stats
1303 Returns the current timing statistics object. By default Catalyst uses
1304 Catalyst::Stats, but can be set otherwise with stats_class.
1305 Even if -Stats is not enabled, the stats object is still available. By
1307 enabling it with "$c->stats->enabled(1)", it can be used to profile
1308 explicitly, although MyApp.pm still won't profile nor output anything
1309 by itself.
1310 $c->stats_class
1312 Returns or sets the stats (timing statistics) class. Catalyst::Stats is
1313 used by default.
1314 $app->stats_class_traits
1316 A arrayref of Moose::Roles that are applied to the stats_class before
1317 creating it.
1318 $app->composed_stats_class
1320 this is the stats_class composed with any 'stats_class_traits'. You
1321 can name the full namespace of the role, or a namespace suffix, which
1322 will then be tried against the following standard namespace prefixes.
1323 $MyApp::TraitFor::Stats::$trait_suffix
1325 Catalyst::TraitFor::Stats::$trait_suffix
1326 So for example if you set:
1328 MyApp->stats_class_traits(['Foo']);
1330 We try each possible role in turn (and throw an error if none load)
1332 Foo
1334 MyApp::TraitFor::Stats::Foo
1335 Catalyst::TraitFor::Stats::Foo
1336 The namespace part 'TraitFor::Stats' was chosen to assist in backwards
1338 compatibility with CatalystX::RoleApplicator which previously provided
1339 these features in a stand alone package.
1340 $c->use_stats
1342 Returns 1 when stats collection is enabled.
1343 Note that this is a static method, not an accessor and should be
1345 overridden by declaring "sub use_stats { 1 }" in your MyApp.pm, not by
1346 calling "$c->use_stats(1)".
1347 $c->write( $data )
1349 Writes $data to the output stream. When using this method directly, you
1350 will need to manually set the "Content-Length" header to the length of
1351 your output data, if known.
1352 version
1354 Returns the Catalyst version number. Mostly useful for "powered by"
1355 messages in template systems.
1356
1358 There are a number of 'base' config variables which can be set:
1359 · "always_catch_http_exceptions" - As of version 5.90060 Catalyst
1361 rethrows errors conforming to the interface described by
1362 Plack::Middleware::HTTPExceptions and lets the middleware deal with
1363 it. Set true to get the deprecated behaviour and have Catalyst
1364 catch HTTP exceptions.
1365 · "default_model" - The default model picked if you say "$c->model".
1367 See "$c->model($name)".
1368 · "default_view" - The default view to be rendered or returned when
1370 "$c->view" is called. See "$c->view($name)".
1371 · "disable_component_resolution_regex_fallback" - Turns off the
1373 deprecated component resolution functionality so that if any of the
1374 component methods (e.g. "$c->controller('Foo')") are called then
1375 regex search will not be attempted on string values and instead
1376 "undef" will be returned.
1377 · "home" - The application home directory. In an uninstalled
1379 application, this is the top level application directory. In an
1380 installed application, this will be the directory containing
1381 "MyApp.pm".
1382 · "ignore_frontend_proxy" - See "PROXY SUPPORT"
1384 · "name" - The name of the application in debug messages and the
1386 debug and welcome screens
1387 · "parse_on_demand" - The request body (for example file uploads)
1389 will not be parsed until it is accessed. This allows you to (for
1390 example) check authentication (and reject the upload) before
1391 actually receiving all the data. See "ON-DEMAND PARSER"
1392 · "root" - The root directory for templates. Usually this is just a
1394 subdirectory of the home directory, but you can set it to change
1395 the templates to a different directory.
1396 · "search_extra" - Array reference passed to Module::Pluggable to for
1398 additional namespaces from which components will be loaded (and
1399 constructed and stored in "$c->components").
1400 · "show_internal_actions" - If true, causes internal actions such as
1402 "_DISPATCH" to be shown in hit debug tables in the test server.
1403 · "use_request_uri_for_path" - Controls if the "REQUEST_URI" or
1405 "PATH_INFO" environment variable should be used for determining the
1406 request path.
1407 Most web server environments pass the requested path to the
1409 application using environment variables, from which Catalyst has to
1410 reconstruct the request base (i.e. the top level path to / in the
1411 application, exposed as "$c->request->base") and the request path
1412 below that base.
1413 There are two methods of doing this, both of which have advantages
1415 and disadvantages. Which method is used is determined by the
1416 "$c->config(use_request_uri_for_path)" setting (which can either be
1417 true or false).
1418 use_request_uri_for_path => 0
1420 This is the default (and the) traditional method that Catalyst
1421 has used for determining the path information. The path is
1422 generated from a combination of the "PATH_INFO" and
1423 "SCRIPT_NAME" environment variables. The allows the
1424 application to behave correctly when "mod_rewrite" is being
1425 used to redirect requests into the application, as these
1426 variables are adjusted by mod_rewrite to take account for the
1427 redirect.
1428 However this method has the major disadvantage that it is
1430 impossible to correctly decode some elements of the path, as
1431 RFC 3875 says: ""Unlike a URI path, the PATH_INFO is not
1432 URL-encoded, and cannot contain path-segment parameters."" This
1433 means PATH_INFO is always decoded, and therefore Catalyst can't
1434 distinguish / vs %2F in paths (in addition to other encoded
1435 values).
1436 use_request_uri_for_path => 1
1438 This method uses the "REQUEST_URI" and "SCRIPT_NAME"
1439 environment variables. As "REQUEST_URI" is never decoded, this
1440 means that applications using this mode can correctly handle
1441 URIs including the %2F character (i.e. with
1442 "AllowEncodedSlashes" set to "On" in Apache).
1443 Given that this method of path resolution is provably more
1445 correct, it is recommended that you use this unless you have a
1446 specific need to deploy your application in a non-standard
1447 environment, and you are aware of the implications of not being
1448 able to handle encoded URI paths correctly.
1449 However it also means that in a number of cases when the app
1451 isn't installed directly at a path, but instead is having paths
1452 rewritten into it (e.g. as a .cgi/fcgi in a public_html
1453 directory, with mod_rewrite in a .htaccess file, or when SSI is
1454 used to rewrite pages into the app, or when sub-paths of the
1455 app are exposed at other URIs than that which the app is
1456 'normally' based at with "mod_rewrite"), the resolution of
1457 "$c->request->base" will be incorrect.
1458 · "using_frontend_proxy" - See "PROXY SUPPORT".
1460 · "using_frontend_proxy_path" - Enabled
1462 Plack::Middleware::ReverseProxyPath on your application (if
1463 installed, otherwise log an error). This is useful if your
1464 application is not running on the 'root' (or /) of your host
1465 server. NOTE if you use this feature you should add the required
1466 middleware to your project dependency list since its not
1467 automatically a dependency of Catalyst. This has been done since
1468 not all people need this feature and we wish to restrict the growth
1469 of Catalyst dependencies.
1470 · "encoding" - See "ENCODING"
1472 This now defaults to 'UTF-8'. You my turn it off by setting this
1474 configuration value to undef.
1475 · "abort_chain_on_error_fix"
1477 Defaults to true.
1479 When there is an error in an action chain, the default behavior is
1481 to abort the processing of the remaining actions to avoid running
1482 them when the application is in an unexpected state.
1483 Before version 5.90070, the default used to be false. To keep the
1485 old behaviour, you can explicitly set the value to false. E.g.
1486 __PACKAGE__->config(abort_chain_on_error_fix => 0);
1488 If this setting is set to false, then the remaining actions are
1490 performed and the error is caught at the end of the chain.
1491 · "use_hash_multivalue_in_request"
1493 In Catalyst::Request the methods "query_parameters",
1495 "body_parametes" and "parameters" return a hashref where values
1496 might be scalar or an arrayref depending on the incoming data. In
1497 many cases this can be undesirable as it leads one to writing
1498 defensive code like the following:
1499 my ($val) = ref($c->req->parameters->{a}) ?
1501 @{$c->req->parameters->{a}} :
1502 $c->req->parameters->{a};
1503 Setting this configuration item to true will make Catalyst populate
1505 the attributes underlying these methods with an instance of
1506 Hash::MultiValue which is used by Plack::Request and others to
1507 solve this very issue. You may prefer this behavior to the
1508 default, if so enable this option (be warned if you enable it in a
1509 legacy application we are not sure if it is completely backwardly
1510 compatible).
1511 · "skip_complex_post_part_handling"
1513 When creating body parameters from a POST, if we run into a
1515 multipart POST that does not contain uploads, but instead contains
1516 inlined complex data (very uncommon) we cannot reliably convert
1517 that into field => value pairs. So instead we create an instance
1518 of Catalyst::Request::PartData. If this causes issue for you, you
1519 can disable this by setting "skip_complex_post_part_handling" to
1520 true (default is false).
1521 · "skip_body_param_unicode_decoding"
1523 Generally we decode incoming POST params based on your declared
1525 encoding (the default for this is to decode UTF-8). If this is
1526 causing you trouble and you do not wish to turn all encoding
1527 support off (with the "encoding" configuration parameter) you may
1528 disable this step atomically by setting this configuration
1529 parameter to true.
1530 · "do_not_decode_query"
1532 If true, then do not try to character decode any wide characters in
1534 your request URL query or keywords. Most readings of the relevant
1535 specifications suggest these should be UTF-* encoded, which is the
1536 default that Catalyst will use, however if you are creating a lot
1537 of URLs manually or have external evil clients, this might cause
1538 you trouble. If you find the changes introduced in Catalyst
1539 version 5.90080+ break some of your query code, you may disable the
1540 UTF-8 decoding globally using this configuration.
1541 This setting takes precedence over "default_query_encoding"
1543 · "do_not_check_query_encoding"
1545 Catalyst versions 5.90080 - 5.90106 would decode query parts of an
1547 incoming request but would not raise an exception when the decoding
1548 failed due to incorrect unicode. It now does, but if this change
1549 is giving you trouble you may disable it by setting this
1550 configuration to true.
1551 · "default_query_encoding"
1553 By default we decode query and keywords in your request URL using
1555 UTF-8, which is our reading of the relevant specifications. This
1556 setting allows one to specify a fixed value for how to decode your
1557 query. You might need this if you are doing a lot of custom
1558 encoding of your URLs and not using UTF-8.
1559 · "use_chained_args_0_special_case"
1561 In older versions of Catalyst, when more than one action matched
1563 the same path AND all those matching actions declared Args(0), we'd
1564 break the tie by choosing the first action defined. We now
1565 normalized how Args(0) works so that it follows the same rule as
1566 Args(N), which is to say when we need to break a tie we choose the
1567 LAST action defined. If this breaks your code and you don't have
1568 time to update to follow the new normalized approach, you may set
1569 this value to true and it will globally revert to the original
1570 chaining behavior.
1571 · "psgi_middleware" - See "PSGI MIDDLEWARE".
1573 · "data_handlers" - See "DATA HANDLERS".
1575 · "stats_class_traits"
1577 An arrayref of Moose::Roles that get composed into your stats
1579 class.
1580 · "request_class_traits"
1582 An arrayref of Moose::Roles that get composed into your request
1584 class.
1585 · "response_class_traits"
1587 An arrayref of Moose::Roles that get composed into your response
1589 class.
1590 · "inject_components"
1592 A Hashref of Catalyst::Component subclasses that are 'injected'
1594 into configuration. For example:
1595 MyApp->config({
1597 inject_components => {
1598 'Controller::Err' => { from_component => 'Local::Controller::Errors' },
1599 'Model::Zoo' => { from_component => 'Local::Model::Foo' },
1600 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] },
1601 },
1602 'Controller::Err' => { a => 100, b=>200, namespace=>'error' },
1603 'Model::Zoo' => { a => 2 },
1604 'Model::Foo' => { a => 100 },
1605 });
1606 Generally Catalyst looks for components in your Model/View or
1608 Controller directories. However for cases when you which to use an
1609 existing component and you don't need any customization (where for
1610 when you can apply a role to customize it) you may inject those
1611 components into your application. Please note any configuration
1612 should be done 'in the normal way', with a key under configuration
1613 named after the component affix, as in the above example.
1614 Using this type of injection allows you to construct significant
1616 amounts of your application with only configuration!. This may or
1617 may not lead to increased code understanding.
1618 Please not you may also call the ->inject_components application
1620 method as well, although you must do so BEFORE setup.
1621
1623 Generally when you throw an exception inside an Action (or somewhere in
1624 your stack, such as in a model that an Action is calling) that
1625 exception is caught by Catalyst and unless you either catch it yourself
1626 (via eval or something like Try::Tiny or by reviewing the "error"
1627 stack, it will eventually reach "finalize_errors" and return either the
1628 debugging error stack page, or the default error page. However, if
1629 your exception can be caught by Plack::Middleware::HTTPExceptions,
1630 Catalyst will instead rethrow it so that it can be handled by that
1631 middleware (which is part of the default middleware). For example this
1632 would allow
1633 use HTTP::Throwable::Factory 'http_throw';
1635 sub throws_exception :Local {
1637 my ($self, $c) = @_;
1638 http_throw(SeeOther => { location =>
1640 $c->uri_for($self->action_for('redirect')) });
1641 }
1643
1645 Catalyst uses internal actions like "_DISPATCH", "_BEGIN", "_AUTO",
1646 "_ACTION", and "_END". These are by default not shown in the private
1647 action table, but you can make them visible with a config parameter.
1648 MyApp->config(show_internal_actions => 1);
1650
1652 The request body is usually parsed at the beginning of a request, but
1653 if you want to handle input yourself, you can enable on-demand parsing
1654 with a config parameter.
1655 MyApp->config(parse_on_demand => 1);
1657
1659 Many production servers operate using the common double-server
1660 approach, with a lightweight frontend web server passing requests to a
1661 larger backend server. An application running on the backend server
1662 must deal with two problems: the remote user always appears to be
1663 127.0.0.1 and the server's hostname will appear to be "localhost"
1664 regardless of the virtual host that the user connected through.
1665 Catalyst will automatically detect this situation when you are running
1667 the frontend and backend servers on the same machine. The following
1668 changes are made to the request.
1669 $c->req->address is set to the user's real IP address, as read from
1671 the HTTP X-Forwarded-For header.
1672 The host value for $c->req->base and $c->req->uri is set to the real
1674 host, as read from the HTTP X-Forwarded-Host header.
1675 Additionally, you may be running your backend application on an
1677 insecure connection (port 80) while your frontend proxy is running
1678 under SSL. If there is a discrepancy in the ports, use the HTTP header
1679 "X-Forwarded-Port" to tell Catalyst what port the frontend listens on.
1680 This will allow all URIs to be created properly.
1681 In the case of passing in:
1683 X-Forwarded-Port: 443
1685 All calls to "uri_for" will result in an https link, as is expected.
1687 Obviously, your web server must support these headers for this to work.
1689 In a more complex server farm environment where you may have your
1691 frontend proxy server(s) on different machines, you will need to set a
1692 configuration option to tell Catalyst to read the proxied data from the
1693 headers.
1694 MyApp->config(using_frontend_proxy => 1);
1696 If you do not wish to use the proxy support at all, you may set:
1698 MyApp->config(ignore_frontend_proxy => 0);
1700 Note about psgi files
1702 Note that if you supply your own .psgi file, calling
1703 "MyApp->psgi_app(@_);", then this will not happen automatically.
1704 You either need to apply Plack::Middleware::ReverseProxy yourself in
1706 your psgi, for example:
1707 builder {
1709 enable "Plack::Middleware::ReverseProxy";
1710 MyApp->psgi_app
1711 };
1712 This will unconditionally add the ReverseProxy support, or you need to
1714 call "$app = MyApp->apply_default_middlewares($app)" (to conditionally
1715 apply the support depending upon your config).
1716 See Catalyst::PSGI for more information.
1718
1720 Catalyst has been tested under Apache 2's threading "mpm_worker",
1721 "mpm_winnt", and the standalone forking HTTP server on Windows. We
1722 believe the Catalyst core to be thread-safe.
1723 If you plan to operate in a threaded environment, remember that all
1725 other modules you are using must also be thread-safe. Some modules,
1726 most notably DBD::SQLite, are not thread-safe.
1727
1729 The Catalyst::Request object uses HTTP::Body to populate 'classic' HTML
1730 form parameters and URL search query fields. However it has become
1731 common for various alternative content types to be PUT or POSTed to
1732 your controllers and actions. People working on RESTful APIs, or using
1733 AJAX often use JSON, XML and other content types when communicating
1734 with an application server. In order to better support this use case,
1735 Catalyst defines a global configuration option, "data_handlers", which
1736 lets you associate a content type with a coderef that parses that
1737 content type into something Perl can readily access.
1738 package MyApp::Web;
1740 use Catalyst;
1742 use JSON::MaybeXS;
1743 __PACKAGE__->config(
1745 data_handlers => {
1746 'application/json' => sub { local $/; decode_json $_->getline },
1747 },
1748 ## Any other configuration.
1749 );
1750 __PACKAGE__->setup;
1752 By default Catalyst comes with a generic JSON data handler similar to
1754 the example given above, which uses JSON::MaybeXS to provide either
1755 JSON::PP (a pure Perl, dependency free JSON parser) or Cpanel::JSON::XS
1756 if you have it installed (if you want the faster XS parser, add it to
1757 you project Makefile.PL or dist.ini, cpanfile, etc.)
1758 The "data_handlers" configuration is a hashref whose keys are HTTP
1760 Content-Types (matched against the incoming request type using a regexp
1761 such as to be case insensitive) and whose values are coderefs that
1762 receive a localized version of $_ which is a filehandle object pointing
1763 to received body.
1764 This feature is considered an early access release and we reserve the
1766 right to alter the interface in order to provide a performant and
1767 secure solution to alternative request body content. Your reports
1768 welcomed!
1769
1771 You can define middleware, defined as Plack::Middleware or a compatible
1772 interface in configuration. Your middleware definitions are in the
1773 form of an arrayref under the configuration key "psgi_middleware".
1774 Here's an example with details to follow:
1775 package MyApp::Web;
1777 use Catalyst;
1779 use Plack::Middleware::StackTrace;
1780 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1782 __PACKAGE__->config(
1784 'psgi_middleware', [
1785 'Debug',
1786 '+MyApp::Custom',
1787 $stacktrace_middleware,
1788 'Session' => {store => 'File'},
1789 sub {
1790 my $app = shift;
1791 return sub {
1792 my $env = shift;
1793 $env->{myapp.customkey} = 'helloworld';
1794 $app->($env);
1795 },
1796 },
1797 ],
1798 );
1799 __PACKAGE__->setup;
1801 So the general form is:
1803 __PACKAGE__->config(psgi_middleware => \@middleware_definitions);
1805 Where @middleware is one or more of the following, applied in the
1807 REVERSE of the order listed (to make it function similarly to
1808 Plack::Builder:
1809 Alternatively, you may also define middleware by calling the
1811 "setup_middleware" package method:
1812 package MyApp::Web;
1814 use Catalyst;
1816 __PACKAGE__->setup_middleware( \@middleware_definitions);
1818 __PACKAGE__->setup;
1819 In the case where you do both (use 'setup_middleware' and
1821 configuration) the package call to setup_middleware will be applied
1822 earlier (in other words its middleware will wrap closer to the
1823 application). Keep this in mind since in some cases the order of
1824 middleware is important.
1825 The two approaches are not exclusive.
1827 Middleware Object
1829 An already initialized object that conforms to the
1830 Plack::Middleware specification:
1831 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1833 __PACKAGE__->config(
1835 'psgi_middleware', [
1836 $stacktrace_middleware,
1837 ]);
1838 coderef
1840 A coderef that is an inlined middleware:
1841 __PACKAGE__->config(
1843 'psgi_middleware', [
1844 sub {
1845 my $app = shift;
1846 return sub {
1847 my $env = shift;
1848 if($env->{PATH_INFO} =~m/forced/) {
1849 Plack::App::File
1850 ->new(file=>TestApp->path_to(qw/share static forced.txt/))
1851 ->call($env);
1852 } else {
1853 return $app->($env);
1854 }
1855 },
1856 },
1857 ]);
1858 a scalar
1860 We assume the scalar refers to a namespace after normalizing it
1861 using the following rules:
1862 (1) If the scalar is prefixed with a "+" (as in "+MyApp::Foo") then
1864 the full string is assumed to be 'as is', and we just install and
1865 use the middleware.
1866 (2) If the scalar begins with "Plack::Middleware" or your
1868 application namespace (the package name of your Catalyst
1869 application subclass), we also assume then that it is a full
1870 namespace, and use it.
1871 (3) Lastly, we then assume that the scalar is a partial namespace,
1873 and attempt to resolve it first by looking for it under your
1874 application namespace (for example if you application is
1875 "MyApp::Web" and the scalar is "MyMiddleware", we'd look under
1876 "MyApp::Web::Middleware::MyMiddleware") and if we don't find it
1877 there, we will then look under the regular Plack::Middleware
1878 namespace (i.e. for the previous we'd try
1879 "Plack::Middleware::MyMiddleware"). We look under your application
1880 namespace first to let you 'override' common Plack::Middleware
1881 locally, should you find that a good idea.
1882 Examples:
1884 package MyApp::Web;
1886 __PACKAGE__->config(
1888 'psgi_middleware', [
1889 'Debug', ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap
1890 'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap
1891 '+MyApp::Custom', ## MyApp::Custom->wrap
1892 ],
1893 );
1894 a scalar followed by a hashref
1896 Just like the previous, except the following "HashRef" is used as
1897 arguments to initialize the middleware object.
1898 __PACKAGE__->config(
1900 'psgi_middleware', [
1901 'Session' => {store => 'File'},
1902 ]);
1903 Please see PSGI for more on middleware.
1905
1907 Starting in Catalyst version 5.90080 encoding is automatically enabled
1908 and set to encode all body responses to UTF8 when possible and
1909 applicable. Following is documentation on this process. If you are
1910 using an older version of Catalyst you should review documentation for
1911 that version since a lot has changed.
1912 By default encoding is now 'UTF-8'. You may turn it off by setting the
1914 encoding configuration to undef.
1915 MyApp->config(encoding => undef);
1917 This is recommended for temporary backwards compatibility only.
1919 To turn it off for a single request use the clear_encoding method to
1921 turn off encoding for this request. This can be useful when you are
1922 setting the body to be an arbitrary block of bytes, especially if that
1923 block happens to be a block of UTF8 text.
1924 Encoding is automatically applied when the content-type is set to a
1926 type that can be encoded. Currently we encode when the content type
1927 matches the following regular expression:
1928 $content_type =~ /^text|xml$|javascript$/
1930 Encoding is set on the application, but it is copied to the context
1932 object so that you can override it on a request basis.
1933 Be default we don't automatically encode 'application/json' since the
1935 most common approaches to generating this type of response (Either via
1936 Catalyst::View::JSON or Catalyst::Action::REST) will do so already and
1937 we want to avoid double encoding issues.
1938 If you are producing JSON response in an unconventional manner (such as
1940 via a template or manual strings) you should perform the UTF8 encoding
1941 manually as well such as to conform to the JSON specification.
1942 NOTE: We also examine the value of $c->response->content_encoding. If
1944 you set this (like for example 'gzip', and manually gzipping the body)
1945 we assume that you have done all the necessary encoding yourself, since
1946 we cannot encode the gzipped contents. If you use a plugin like
1947 Catalyst::Plugin::Compress you need to update to a modern version in
1948 order to have this function correctly with the new UTF8 encoding code,
1949 or you can use Plack::Middleware::Deflater or (probably best) do your
1950 compression on a front end proxy.
1951 Methods
1953 encoding
1954 Returns an instance of an "Encode" encoding
1955 print $c->encoding->name
1957 handle_unicode_encoding_exception ($exception_context)
1959 Method called when decoding process for a request fails.
1960 An $exception_context hashref is provided to allow you to override
1962 the behaviour of your application when given data with incorrect
1963 encodings.
1964 The default method throws exceptions in the case of invalid request
1966 parameters (resulting in a 500 error), but ignores errors in upload
1967 filenames.
1968 The keys passed in the $exception_context hash are:
1970 param_value
1972 The value which was not able to be decoded.
1973 error_msg
1975 The exception received from Encode.
1976 encoding_step
1978 What type of data was being decoded. Valid values are
1979 (currently) "params" - for request parameters / arguments /
1980 captures and "uploads" - for request upload filenames.
1981
1983 IRC:
1984 Join #catalyst on irc.perl.org.
1986 Mailing Lists:
1988 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
1990 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
1991 Web:
1993 http://catalyst.perl.org
1995 Wiki:
1997 http://dev.catalyst.perl.org
1999
2001 Task::Catalyst - All you need to start with Catalyst
2002 Catalyst::Manual - The Catalyst Manual
2003 Catalyst::Component, Catalyst::Controller - Base classes for components
2004 Catalyst::Engine - Core engine
2005 Catalyst::Log - Log class.
2006 Catalyst::Request - Request object
2007 Catalyst::Response - Response object
2008 Catalyst::Test - The test suite.
2010 sri: Sebastian Riedel <sri@cpan.org>
2011
2013 abw: Andy Wardley
2014 acme: Leon Brocard <leon@astray.com>
2016 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
2018 andrewalker: André Walker <andre@cpan.org>
2020 Andrew Bramble
2022 Andrew Ford <A.Ford@ford-mason.co.uk>
2024 Andrew Ruthven
2026 andyg: Andy Grundman <andy@hybridized.org>
2028 audreyt: Audrey Tang
2030 bricas: Brian Cassidy <bricas@cpan.org>
2032 Caelum: Rafael Kitover <rkitover@io.com>
2034 chansen: Christian Hansen
2036 Chase Venters <chase.venters@gmail.com>
2038 chicks: Christopher Hicks
2040 Chisel Wright <pause@herlpacker.co.uk>
2042 Danijel Milicevic <me@danijel.de>
2044 davewood: David Schmidt <davewood@cpan.org>
2046 David Kamholz <dkamholz@cpan.org>
2048 David Naughton <naughton@umn.edu>
2050 David E. Wheeler
2052 dhoss: Devin Austin <dhoss@cpan.org>
2054 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
2056 Drew Taylor
2058 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
2060 esskar: Sascha Kiefer
2062 fireartist: Carl Franks <cfranks@cpan.org>
2064 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
2066 gabb: Danijel Milicevic
2068 Gary Ashton Jones
2070 Gavin Henry <ghenry@perl.me.uk>
2072 Geoff Richards
2074 groditi: Guillermo Roditi <groditi@gmail.com>
2076 hobbs: Andrew Rodland <andrew@cleverdomain.org>
2078 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
2080 jcamacho: Juan Camacho
2082 jester: Jesse Sheidlower <jester@panix.com>
2084 jhannah: Jay Hannah <jay@jays.net>
2086 Jody Belka
2088 Johan Lindstrom
2090 jon: Jon Schutz <jjschutz@cpan.org>
2092 Jonathan Rockway <jrockway@cpan.org>
2094 Kieren Diment <kd@totaldatasolution.com>
2096 konobi: Scott McWhirter <konobi@cpan.org>
2098 marcus: Marcus Ramberg <mramberg@cpan.org>
2100 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
2102 mgrimes: Mark Grimes <mgrimes@cpan.org>
2104 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
2106 mugwump: Sam Vilain
2108 naughton: David Naughton
2110 ningu: David Kamholz <dkamholz@cpan.org>
2112 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
2114 numa: Dan Sully <daniel@cpan.org>
2116 obra: Jesse Vincent
2118 Octavian Rasnita
2120 omega: Andreas Marienborg
2122 Oleg Kostyuk <cub.uanic@gmail.com>
2124 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
2126 rafl: Florian Ragwitz <rafl@debian.org>
2128 random: Roland Lammel <lammel@cpan.org>
2130 revmischa: Mischa Spiegelmock <revmischa@cpan.org>
2132 Robert Sedlacek <rs@474.at>
2134 SpiceMan: Marcel Montes
2136 sky: Arthur Bergman
2138 szbalint: Balint Szilakszi <szbalint@cpan.org>
2140 t0m: Tomas Doran <bobtfish@bobtfish.net>
2142 Ulf Edvinsson
2144 vanstyn: Henry Van Styn <vanstyn@cpan.org>
2146 Viljo Marrandi <vilts@yahoo.com>
2148 Will Hawes <info@whawes.co.uk>
2150 willert: Sebastian Willert <willert@cpan.org>
2152 wreis: Wallace Reis <wreis@cpan.org>
2154 Yuval Kogman <nothingmuch@woobling.org>
2156 rainboxx: Matthias Dietrich <perl@rainboxx.de>
2158 dd070: Dhaval Dhanani <dhaval070@gmail.com>
2160 Upasana <me@upasana.me>
2162 John Napiorkowski (jnap) <jjnapiork@cpan.org>
2164
2166 Copyright (c) 2005-2015, the above named PROJECT FOUNDER and
2167 CONTRIBUTORS.
2168
2170 This library is free software. You can redistribute it and/or modify it
2171 under the same terms as Perl itself.
2172perl v5.28.0 2018-09-23 Catalyst(3)