Revert incorrect fixes for parsing of attributes with empty parens
[catagits/Catalyst-Runtime.git] / README.mkdn
CommitLineData
9e7f288e 1# NAME
2
3Catalyst - The Elegant MVC Web Application Framework
4
5<div>
6
7 <a href="https://badge.fury.io/pl/Catalyst-Runtime"><img src="https://badge.fury.io/pl/Catalyst-Runtime.svg" alt="CPAN version" height="18"></a>
8 <a href="https://travis-ci.org/perl-catalyst/catalyst-runtime/"><img src="https://api.travis-ci.org/perl-catalyst/catalyst-runtime.png" alt="Catalyst></a>
9 <a href="http://cpants.cpanauthors.org/dist/Catalyst-Runtime"><img src="http://cpants.cpanauthors.org/dist/Catalyst-Runtime.png" alt='Kwalitee Score' /></a>
10</div>
11
12# SYNOPSIS
13
14See the [Catalyst::Manual](https://metacpan.org/pod/Catalyst::Manual) distribution for comprehensive
15documentation and tutorials.
16
136c3a0d 17 # Building Catalyst for development
18 cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
19 cpanm --installdeps --with-develop .
5edd9ca8 20 perl Makefile.PL
136c3a0d 21
9e7f288e 22 # Install Catalyst::Devel for helpers and other development tools
23 # use the helper to create a new application
24 catalyst.pl MyApp
25
26 # add models, views, controllers
27 script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
28 script/myapp_create.pl view MyTemplate TT
29 script/myapp_create.pl controller Search
30
31 # built in testserver -- use -r to restart automatically on changes
32 # --help to see all available options
33 script/myapp_server.pl
34
35 # command line testing interface
36 script/myapp_test.pl /yada
37
38 ### in lib/MyApp.pm
39 use Catalyst qw/-Debug/; # include plugins here as well
40
41 ### In lib/MyApp/Controller/Root.pm (autocreated)
42 sub foo : Chained('/') Args() { # called for /foo, /foo/1, /foo/1/2, etc.
43 my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
44 $c->stash->{template} = 'foo.tt'; # set the template
45 # lookup something from db -- stash vars are passed to TT
46 $c->stash->{data} =
47 $c->model('Database::Foo')->search( { country => $args[0] } );
48 if ( $c->req->params->{bar} ) { # access GET or POST parameters
49 $c->forward( 'bar' ); # process another action
50 # do something else after forward returns
51 }
52 }
53
54 # The foo.tt TT template can use the stash data from the database
55 [% WHILE (item = data.next) %]
56 [% item.foo %]
57 [% END %]
58
59 # called for /bar/of/soap, /bar/of/soap/10, etc.
60 sub bar : Chained('/') PathPart('/bar/of/soap') Args() { ... }
61
62 # called after all actions are finished
63 sub end : Action {
64 my ( $self, $c ) = @_;
65 if ( scalar @{ $c->error } ) { ... } # handle errors
66 return if $c->res->body; # already have a response
67 $c->forward( 'MyApp::View::TT' ); # render template
68 }
69
70See [Catalyst::Manual::Intro](https://metacpan.org/pod/Catalyst::Manual::Intro) for additional information.
71
72# DESCRIPTION
73
74Catalyst is a modern framework for making web applications without the
75pain usually associated with this process. This document is a reference
76to the main Catalyst application. If you are a new user, we suggest you
77start with [Catalyst::Manual::Tutorial](https://metacpan.org/pod/Catalyst::Manual::Tutorial) or [Catalyst::Manual::Intro](https://metacpan.org/pod/Catalyst::Manual::Intro).
78
79See [Catalyst::Manual](https://metacpan.org/pod/Catalyst::Manual) for more documentation.
80
81Catalyst plugins can be loaded by naming them as arguments to the "use
82Catalyst" statement. Omit the `Catalyst::Plugin::` prefix from the
83plugin name, i.e., `Catalyst::Plugin::My::Module` becomes
84`My::Module`.
85
86 use Catalyst qw/My::Module/;
87
88If your plugin starts with a name other than `Catalyst::Plugin::`, you can
89fully qualify the name by using a unary plus:
90
91 use Catalyst qw/
92 My::Module
93 +Fully::Qualified::Plugin::Name
94 /;
95
96Special flags like `-Debug` can also be specified as
97arguments when Catalyst is loaded:
98
99 use Catalyst qw/-Debug My::Module/;
100
101The position of plugins and flags in the chain is important, because
102they are loaded in the order in which they appear.
103
104The following flags are supported:
105
106## -Debug
107
108Enables debug output. You can also force this setting from the system
109environment with CATALYST\_DEBUG or <MYAPP>\_DEBUG. The environment
110settings override the application, with <MYAPP>\_DEBUG having the highest
111priority.
112
113This sets the log level to 'debug' and enables full debug output on the
114error screen. If you only want the latter, see [$c->debug](https://metacpan.org/pod/$c->debug).
115
116## -Home
117
118Forces Catalyst to use a specific home directory, e.g.:
119
120 use Catalyst qw[-Home=/usr/mst];
121
122This can also be done in the shell environment by setting either the
123`CATALYST_HOME` environment variable or `MYAPP_HOME`; where `MYAPP`
124is replaced with the uppercased name of your application, any "::" in
125the name will be replaced with underscores, e.g. MyApp::Web should use
126MYAPP\_WEB\_HOME. If both variables are set, the MYAPP\_HOME one will be used.
127
128If none of these are set, Catalyst will attempt to automatically detect the
129home directory. If you are working in a development environment, Catalyst
130will try and find the directory containing either Makefile.PL, Build.PL,
131dist.ini, or cpanfile. If the application has been installed into the system
132(i.e. you have done `make install`), then Catalyst will use the path to your
133application module, without the .pm extension (e.g., /foo/MyApp if your
134application was installed at /foo/MyApp.pm)
135
136## -Log
137
138 use Catalyst '-Log=warn,fatal,error';
139
140Specifies a comma-delimited list of log levels.
141
142## -Stats
143
144Enables statistics collection and reporting.
145
146 use Catalyst qw/-Stats=1/;
147
148You can also force this setting from the system environment with CATALYST\_STATS
149or <MYAPP>\_STATS. The environment settings override the application, with
150<MYAPP>\_STATS having the highest priority.
151
152Stats are also enabled if [debugging ](#debug) is enabled.
153
154# METHODS
155
156## INFORMATION ABOUT THE CURRENT REQUEST
157
158## $c->action
159
160Returns a [Catalyst::Action](https://metacpan.org/pod/Catalyst::Action) object for the current action, which
161stringifies to the action name. See [Catalyst::Action](https://metacpan.org/pod/Catalyst::Action).
162
163## $c->namespace
164
165Returns the namespace of the current action, i.e., the URI prefix
166corresponding to the controller of the current action. For example:
167
168 # in Controller::Foo::Bar
169 $c->namespace; # returns 'foo/bar';
170
171## $c->request
172
173## $c->req
174
175Returns the current [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request) object, giving access to
176information about the current client request (including parameters,
177cookies, HTTP headers, etc.). See [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request).
178
179## REQUEST FLOW HANDLING
180
181## $c->forward( $action \[, \\@arguments \] )
182
183## $c->forward( $class, $method, \[, \\@arguments \] )
184
185This is one way of calling another action (method) in the same or
186a different controller. You can also use `$self->my_method($c, @args)`
187in the same controller or `$c->controller('MyController')->my_method($c, @args)`
188in a different controller.
189The main difference is that 'forward' uses some of the Catalyst request
190cycle overhead, including debugging, which may be useful to you. On the
191other hand, there are some complications to using 'forward', restrictions
192on values returned from 'forward', and it may not handle errors as you prefer.
193Whether you use 'forward' or not is up to you; it is not considered superior to
194the other ways to call a method.
195
196'forward' calls another action, by its private name. If you give a
197class name but no method, `process()` is called. You may also optionally
198pass arguments in an arrayref. The action will receive the arguments in
199`@_` and `$c->req->args`. Upon returning from the function,
200`$c->req->args` will be restored to the previous values.
201
202Any data `return`ed from the action forwarded to, will be returned by the
203call to forward.
204
205 my $foodata = $c->forward('/foo');
206 $c->forward('index');
207 $c->forward(qw/Model::DBIC::Foo do_stuff/);
208 $c->forward('View::TT');
209
210Note that [forward](#c-forward-action-arguments) implies
211an `eval { }` around the call (actually
212[execute](#c-execute-class-coderef) does), thus rendering all
213exceptions thrown by the called action non-fatal and pushing them onto
214$c->error instead. If you want `die` to propagate you need to do something
215like:
216
217 $c->forward('foo');
218 die join "\n", @{ $c->error } if @{ $c->error };
219
220Or make sure to always return true values from your actions and write
221your code like this:
222
223 $c->forward('foo') || return;
224
225Another note is that `$c->forward` always returns a scalar because it
226actually returns $c->state which operates in a scalar context.
227Thus, something like:
228
229 return @array;
230
231in an action that is forwarded to is going to return a scalar,
232i.e. how many items are in that array, which is probably not what you want.
233If you need to return an array then return a reference to it,
234or stash it like so:
235
236 $c->stash->{array} = \@array;
237
238and access it from the stash.
239
240Keep in mind that the `end` method used is that of the caller action. So a `$c->detach` inside a forwarded action would run the `end` method from the original action requested.
241
242## $c->detach( $action \[, \\@arguments \] )
243
244## $c->detach( $class, $method, \[, \\@arguments \] )
245
246## $c->detach()
247
248The same as [forward](#c-forward-action-arguments), but
249doesn't return to the previous action when processing is finished.
250
251When called with no arguments it escapes the processing chain entirely.
252
253## $c->visit( $action \[, \\@arguments \] )
254
255## $c->visit( $action \[, \\@captures, \\@arguments \] )
256
257## $c->visit( $class, $method, \[, \\@arguments \] )
258
259## $c->visit( $class, $method, \[, \\@captures, \\@arguments \] )
260
261Almost the same as [forward](#c-forward-action-arguments),
262but does a full dispatch, instead of just calling the new `$action` /
263`$class->$method`. This means that `begin`, `auto` and the method
264you go to are called, just like a new request.
265
266In addition both `$c->action` and `$c->namespace` are localized.
267This means, for example, that `$c->action` methods such as
268[name](https://metacpan.org/pod/Catalyst::Action#name), [class](https://metacpan.org/pod/Catalyst::Action#class) and
269[reverse](https://metacpan.org/pod/Catalyst::Action#reverse) return information for the visited action
270when they are invoked within the visited action. This is different from the
271behavior of [forward](#c-forward-action-arguments), which
272continues to use the $c->action object from the caller action even when
273invoked from the called action.
274
275`$c->stash` is kept unchanged.
276
277In effect, [visit](#c-visit-action-captures-arguments)
278allows you to "wrap" another action, just as it would have been called by
279dispatching from a URL, while the analogous
280[go](#c-go-action-captures-arguments) allows you to
281transfer control to another action as if it had been reached directly from a URL.
282
283## $c->go( $action \[, \\@arguments \] )
284
285## $c->go( $action \[, \\@captures, \\@arguments \] )
286
287## $c->go( $class, $method, \[, \\@arguments \] )
288
289## $c->go( $class, $method, \[, \\@captures, \\@arguments \] )
290
291The relationship between `go` and
292[visit](#c-visit-action-captures-arguments) is the same as
293the relationship between
294[forward](#c-forward-class-method-arguments) and
295[detach](#c-detach-action-arguments). Like `$c->visit`,
296`$c->go` will perform a full dispatch on the specified action or method,
297with localized `$c->action` and `$c->namespace`. Like `detach`,
298`go` escapes the processing of the current request chain on completion, and
299does not return to its cunless blessed $cunless blessed $caller.
300
301@arguments are arguments to the final destination of $action. @captures are
302arguments to the intermediate steps, if any, on the way to the final sub of
303$action.
304
305## $c->response
306
307## $c->res
308
309Returns the current [Catalyst::Response](https://metacpan.org/pod/Catalyst::Response) object, see there for details.
310
311## $c->stash
312
313Returns a hashref to the stash, which may be used to store data and pass
314it between components during a request. You can also set hash keys by
315passing arguments. The stash is automatically sent to the view. The
316stash is cleared at the end of a request; it cannot be used for
317persistent storage (for this you must use a session; see
318[Catalyst::Plugin::Session](https://metacpan.org/pod/Catalyst::Plugin::Session) for a complete system integrated with
319Catalyst).
320
321 $c->stash->{foo} = $bar;
322 $c->stash( { moose => 'majestic', qux => 0 } );
323 $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
324
325 # stash is automatically passed to the view for use in a template
326 $c->forward( 'MyApp::View::TT' );
327
328The stash hash is currently stored in the PSGI `$env` and is managed by
329[Catalyst::Middleware::Stash](https://metacpan.org/pod/Catalyst::Middleware::Stash). Since it's part of the `$env` items in
330the stash can be accessed in sub applications mounted under your main
331[Catalyst](https://metacpan.org/pod/Catalyst) application. For example if you delegate the response of an
332action to another [Catalyst](https://metacpan.org/pod/Catalyst) application, that sub application will have
333access to all the stash keys of the main one, and if can of course add
334more keys of its own. However those new keys will not 'bubble' back up
335to the main application.
336
337For more information the best thing to do is to review the test case:
338t/middleware-stash.t in the distribution /t directory.
339
340## $c->error
341
342## $c->error($error, ...)
343
344## $c->error($arrayref)
345
346Returns an arrayref containing error messages. If Catalyst encounters an
347error while processing a request, it stores the error in $c->error. This
348method should only be used to store fatal error messages.
349
350 my @error = @{ $c->error };
351
352Add a new error.
353
354 $c->error('Something bad happened');
355
356Calling this will always return an arrayref (if there are no errors it
357will be an empty arrayref.
358
359## $c->state
360
361Contains the return value of the last executed action.
362Note that << $c->state >> operates in a scalar context which means that all
363values it returns are scalar.
364
365## $c->clear\_errors
366
367Clear errors. You probably don't want to clear the errors unless you are
368implementing a custom error screen.
369
370This is equivalent to running
371
372 $c->error(0);
373
374## $c->has\_errors
375
376Returns true if you have errors
377
378## $c->last\_error
379
380Returns the most recent error in the stack (the one most recently added...)
381or nothing if there are no errors.
382
383## shift\_errors
384
385shifts the most recently added error off the error stack and returns if. Returns
386nothing if there are no more errors.
387
388## COMPONENT ACCESSORS
389
390## $c->controller($name)
391
392Gets a [Catalyst::Controller](https://metacpan.org/pod/Catalyst::Controller) instance by name.
393
394 $c->controller('Foo')->do_stuff;
395
396If the name is omitted, will return the controller for the dispatched
397action.
398
399If you want to search for controllers, pass in a regexp as the argument.
400
401 # find all controllers that start with Foo
402 my @foo_controllers = $c->controller(qr{^Foo});
403
404## $c->model($name)
405
406Gets a [Catalyst::Model](https://metacpan.org/pod/Catalyst::Model) instance by name.
407
408 $c->model('Foo')->do_stuff;
409
410Any extra arguments are directly passed to ACCEPT\_CONTEXT, if the model
411defines ACCEPT\_CONTEXT. If it does not, the args are discarded.
412
413If the name is omitted, it will look for
414 - a model object in $c->stash->{current\_model\_instance}, then
415 - a model name in $c->stash->{current\_model}, then
416 - a config setting 'default\_model', or
417 - check if there is only one model, and return it if that's the case.
418
419If you want to search for models, pass in a regexp as the argument.
420
421 # find all models that start with Foo
422 my @foo_models = $c->model(qr{^Foo});
423
424## $c->view($name)
425
426Gets a [Catalyst::View](https://metacpan.org/pod/Catalyst::View) instance by name.
427
428 $c->view('Foo')->do_stuff;
429
430Any extra arguments are directly passed to ACCEPT\_CONTEXT.
431
432If the name is omitted, it will look for
433 - a view object in $c->stash->{current\_view\_instance}, then
434 - a view name in $c->stash->{current\_view}, then
435 - a config setting 'default\_view', or
436 - check if there is only one view, and return it if that's the case.
437
438If you want to search for views, pass in a regexp as the argument.
439
440 # find all views that start with Foo
441 my @foo_views = $c->view(qr{^Foo});
442
443## $c->controllers
444
445Returns the available names which can be passed to $c->controller
446
447## $c->models
448
449Returns the available names which can be passed to $c->model
450
451## $c->views
452
453Returns the available names which can be passed to $c->view
454
455## $c->comp($name)
456
457## $c->component($name)
458
459Gets a component object by name. This method is not recommended,
460unless you want to get a specific component by full
461class. `$c->controller`, `$c->model`, and `$c->view`
462should be used instead.
463
464If `$name` is a regexp, a list of components matched against the full
465component name will be returned.
466
467If Catalyst can't find a component by name, it will fallback to regex
468matching by default. To disable this behaviour set
469disable\_component\_resolution\_regex\_fallback to a true value.
470
471 __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );
472
473## CLASS DATA AND HELPER CLASSES
474
475## $c->config
476
477Returns or takes a hashref containing the application's configuration.
478
479 __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
480
481You can also use a `YAML`, `XML` or [Config::General](https://metacpan.org/pod/Config::General) config file
482like `myapp.conf` in your applications home directory. See
483[Catalyst::Plugin::ConfigLoader](https://metacpan.org/pod/Catalyst::Plugin::ConfigLoader).
484
485### Cascading configuration
486
487The config method is present on all Catalyst components, and configuration
488will be merged when an application is started. Configuration loaded with
489[Catalyst::Plugin::ConfigLoader](https://metacpan.org/pod/Catalyst::Plugin::ConfigLoader) takes precedence over other configuration,
490followed by configuration in your top level `MyApp` class. These two
491configurations are merged, and then configuration data whose hash key matches a
492component name is merged with configuration for that component.
493
494The configuration for a component is then passed to the `new` method when a
495component is constructed.
496
497For example:
498
499 MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
500 MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });
501
502will mean that `MyApp::Model::Foo` receives the following data when
503constructed:
504
505 MyApp::Model::Foo->new({
506 bar => 'baz',
507 quux => 'frob',
508 overrides => 'me',
509 });
510
511It's common practice to use a Moose attribute
512on the receiving component to access the config value.
513
514 package MyApp::Model::Foo;
515
516 use Moose;
517
518 # this attr will receive 'baz' at construction time
519 has 'bar' => (
520 is => 'rw',
521 isa => 'Str',
522 );
523
524You can then get the value 'baz' by calling $c->model('Foo')->bar
525(or $self->bar inside code in the model).
526
527**NOTE:** you MUST NOT call `$self->config` or `__PACKAGE__->config`
528as a way of reading config within your code, as this **will not** give you the
529correctly merged config back. You **MUST** take the config values supplied to
530the constructor and use those instead.
531
532## $c->log
533
534Returns the logging object instance. Unless it is already set, Catalyst
535sets this up with a [Catalyst::Log](https://metacpan.org/pod/Catalyst::Log) object. To use your own log class,
536set the logger with the `__PACKAGE__->log` method prior to calling
537`__PACKAGE__->setup`.
538
539 __PACKAGE__->log( MyLogger->new );
540 __PACKAGE__->setup;
541
542And later:
543
544 $c->log->info( 'Now logging with my own logger!' );
545
546Your log class should implement the methods described in
547[Catalyst::Log](https://metacpan.org/pod/Catalyst::Log).
548
549## has\_encoding
550
551Returned True if there's a valid encoding
552
553## clear\_encoding
554
555Clears the encoding for the current context
556
557## encoding
558
559Sets or gets the application encoding. Setting encoding takes either an
560Encoding object or a string that we try to resolve via [Encode::find\_encoding](https://metacpan.org/pod/Encode::find_encoding).
561
562You would expect to get the encoding object back if you attempt to set it. If
563there is a failure you will get undef returned and an error message in the log.
564
565## $c->debug
566
567Returns 1 if debug mode is enabled, 0 otherwise.
568
569You can enable debug mode in several ways:
570
571- By calling myapp\_server.pl with the -d flag
572- With the environment variables MYAPP\_DEBUG, or CATALYST\_DEBUG
573- The -Debug option in your MyApp.pm
574- By declaring `sub debug { 1 }` in your MyApp.pm.
575
576The first three also set the log level to 'debug'.
577
578Calling `$c->debug(1)` has no effect.
579
580## $c->dispatcher
581
582Returns the dispatcher instance. See [Catalyst::Dispatcher](https://metacpan.org/pod/Catalyst::Dispatcher).
583
584## $c->engine
585
586Returns the engine instance. See [Catalyst::Engine](https://metacpan.org/pod/Catalyst::Engine).
587
588## UTILITY METHODS
589
590## $c->path\_to(@path)
591
592Merges `@path` with `$c->config->{home}` and returns a
593[Path::Class::Dir](https://metacpan.org/pod/Path::Class::Dir) object. Note you can usually use this object as
594a filename, but sometimes you will have to explicitly stringify it
595yourself by calling the `->stringify` method.
596
597For example:
598
599 $c->path_to( 'db', 'sqlite.db' );
600
601## MyApp->setup
602
603Initializes the dispatcher and engine, loads any plugins, and loads the
604model, view, and controller components. You may also specify an array
605of plugins to load here, if you choose to not load them in the `use
606Catalyst` line.
607
608 MyApp->setup;
609 MyApp->setup( qw/-Debug/ );
610
611**Note:** You **should not** wrap this method with method modifiers
612or bad things will happen - wrap the `setup_finalize` method instead.
613
614**Note:** You can create a custom setup stage that will execute when the
615application is starting. Use this to customize setup.
616
617 MyApp->setup(-Custom=value);
618
619 sub setup_custom {
620 my ($class, $value) = @_;
621 }
622
623Can be handy if you want to hook into the setup phase.
624
625## $app->setup\_finalize
626
627A hook to attach modifiers to. This method does not do anything except set the
628`setup_finished` accessor.
629
630Applying method modifiers to the `setup` method doesn't work, because of quirky things done for plugin setup.
631
632Example:
633
634 after setup_finalize => sub {
635 my $app = shift;
636
637 ## do stuff here..
638 };
639
640## $c->uri\_for( $path?, @args?, \\%query\_values? )
641
642## $c->uri\_for( $action, \\@captures?, @args?, \\%query\_values? )
643
644## $c->uri\_for( $action, \[@captures, @args\], \\%query\_values? )
645
646Constructs an absolute [URI](https://metacpan.org/pod/URI) object based on the application root, the
647provided path, and the additional arguments and query parameters provided.
648When used as a string, provides a textual URI. If you need more flexibility
649than this (i.e. the option to provide relative URIs etc.) see
650[Catalyst::Plugin::SmartURI](https://metacpan.org/pod/Catalyst::Plugin::SmartURI).
651
652If no arguments are provided, the URI for the current action is returned.
653To return the current action and also provide @args, use
654`$c->uri_for( $c->action, @args )`.
655
656If the first argument is a string, it is taken as a public URI path relative
657to `$c->namespace` (if it doesn't begin with a forward slash) or
658relative to the application root (if it does). It is then merged with
659`$c->request->base`; any `@args` are appended as additional path
660components; and any `%query_values` are appended as `?foo=bar` parameters.
661
662If the first argument is a [Catalyst::Action](https://metacpan.org/pod/Catalyst::Action) it represents an action which
663will have its path resolved using `$c->dispatcher->uri_for_action`. The
664optional `\@captures` argument (an arrayref) allows passing the captured
665variables that are needed to fill in the paths of Chained and Regex actions;
666once the path is resolved, `uri_for` continues as though a path was
667provided, appending any arguments or parameters and creating an absolute
668URI.
669
670The captures for the current request can be found in
671`$c->request->captures`, and actions can be resolved using
672`Catalyst::Controller->action_for($name)`. If you have a private action
673path, use `$c->uri_for_action` instead.
674
675 # Equivalent to $c->req->uri
676 $c->uri_for($c->action, $c->req->captures,
677 @{ $c->req->args }, $c->req->params);
678
679 # For the Foo action in the Bar controller
680 $c->uri_for($c->controller('Bar')->action_for('Foo'));
681
682 # Path to a static resource
683 $c->uri_for('/static/images/logo.png');
684
685In general the scheme of the generated URI object will follow the incoming request
686however if your targeted action or action chain has the Scheme attribute it will
687use that instead.
688
689Also, if the targeted Action or Action chain declares Args/CaptureArgs that have
690type constraints, we will require that your proposed URL verify on those declared
691constraints.
692
693## $c->uri\_for\_action( $path, \\@captures\_and\_args?, @args?, \\%query\_values? )
694
695## $c->uri\_for\_action( $action, \\@captures\_and\_args?, @args?, \\%query\_values? )
696
697- $path
698
699 A private path to the Catalyst action you want to create a URI for.
700
701 This is a shortcut for calling `$c->dispatcher->get_action_by_path($path)` and passing the resulting `$action` and the remaining arguments to `$c->uri_for`.
702
703 You can also pass in a Catalyst::Action object, in which case it is passed to
704 `$c->uri_for`.
705
706 Note that although the path looks like a URI that dispatches to the wanted action, it is not a URI, but an internal path to that action.
707
708 For example, if the action looks like:
709
710 package MyApp::Controller::Users;
711
712 sub lst : Path('the-list') {}
713
714 You can use:
715
716 $c->uri_for_action('/users/lst')
717
718 and it will create the URI /users/the-list.
719
720- \\@captures\_and\_args?
721
722 Optional array reference of Captures (i.e. `<CaptureArgs or $c-`req->captures>)
723 and arguments to the request. Usually used with [Catalyst::DispatchType::Chained](https://metacpan.org/pod/Catalyst::DispatchType::Chained)
724 to interpolate all the parameters in the URI.
725
726- @args?
727
728 Optional list of extra arguments - can be supplied in the
729 `\@captures_and_args?` array ref, or here - whichever is easier for your
730 code.
731
732 Your action can have zero, a fixed or a variable number of args (e.g.
733 `Args(1)` for a fixed number or `Args()` for a variable number)..
734
735- \\%query\_values?
736
737 Optional array reference of query parameters to append. E.g.
738
739 { foo => 'bar' }
740
741 will generate
742
743 /rest/of/your/uri?foo=bar
744
745## $c->welcome\_message
746
747Returns the Catalyst welcome HTML page.
748
749## run\_options
750
751Contains a hash of options passed from the application script, including
752the original ARGV the script received, the processed values from that
753ARGV and any extra arguments to the script which were not processed.
754
755This can be used to add custom options to your application's scripts
756and setup your application differently depending on the values of these
757options.
758
759# INTERNAL METHODS
760
761These methods are not meant to be used by end users.
762
763## $c->components
764
765Returns a hash of components.
766
767## $c->context\_class
768
769Returns or sets the context class.
770
771## $c->counter
772
773Returns a hashref containing coderefs and execution counts (needed for
774deep recursion detection).
775
776## $c->depth
777
778Returns the number of actions on the current internal execution stack.
779
780## $c->dispatch
781
782Dispatches a request to actions.
783
784## $c->dispatcher\_class
785
786Returns or sets the dispatcher class.
787
788## $c->dump\_these
789
790Returns a list of 2-element array references (name, structure) pairs
791that will be dumped on the error page in debug mode.
792
793## $c->engine\_class
794
795Returns or sets the engine class.
796
797## $c->execute( $class, $coderef )
798
799Execute a coderef in given class and catch exceptions. Errors are available
800via $c->error.
801
802## $c->finalize
803
804Finalizes the request.
805
806## $c->finalize\_body
807
808Finalizes body.
809
810## $c->finalize\_cookies
811
812Finalizes cookies.
813
814## $c->finalize\_error
815
816Finalizes error. If there is only one error in ["error"](#error) and it is an object that
817does `as_psgi` or `code` we rethrow the error and presume it caught by middleware
818up the ladder. Otherwise we return the debugging error page (in debug mode) or we
819return the default error page (production mode).
820
821## $c->finalize\_headers
822
823Finalizes headers.
824
825## $c->finalize\_encoding
826
827Make sure your body is encoded properly IF you set an encoding. By
828default the encoding is UTF-8 but you can disable it by explicitly setting the
829encoding configuration value to undef.
830
831We can only encode when the body is a scalar. Methods for encoding via the
832streaming interfaces (such as `write` and `write_fh` on [Catalyst::Response](https://metacpan.org/pod/Catalyst::Response)
833are available).
834
835See ["ENCODING"](#encoding).
836
837## $c->finalize\_output
838
839An alias for finalize\_body.
840
841## $c->finalize\_read
842
843Finalizes the input after reading is complete.
844
845## $c->finalize\_uploads
846
847Finalizes uploads. Cleans up any temporary files.
848
849## $c->get\_action( $action, $namespace )
850
851Gets an action in a given namespace.
852
853## $c->get\_actions( $action, $namespace )
854
855Gets all actions of a given name in a namespace and all parent
856namespaces.
857
858## $app->handle\_request( @arguments )
859
860Called to handle each HTTP request.
861
862## $class->prepare( @arguments )
863
864Creates a Catalyst context from an engine-specific request (Apache, CGI,
865etc.).
866
867## $c->prepare\_action
868
869Prepares action. See [Catalyst::Dispatcher](https://metacpan.org/pod/Catalyst::Dispatcher).
870
871## $c->prepare\_body
872
873Prepares message body.
874
875## $c->prepare\_body\_chunk( $chunk )
876
877Prepares a chunk of data before sending it to [HTTP::Body](https://metacpan.org/pod/HTTP::Body).
878
879See [Catalyst::Engine](https://metacpan.org/pod/Catalyst::Engine).
880
881## $c->prepare\_body\_parameters
882
883Prepares body parameters.
884
885## $c->prepare\_connection
886
887Prepares connection.
888
889## $c->prepare\_cookies
890
891Prepares cookies by ensuring that the attribute on the request
892object has been built.
893
894## $c->prepare\_headers
895
896Prepares request headers by ensuring that the attribute on the request
897object has been built.
898
899## $c->prepare\_parameters
900
901Prepares parameters.
902
903## $c->prepare\_path
904
905Prepares path and base.
906
907## $c->prepare\_query\_parameters
908
909Prepares query parameters.
910
911## $c->log\_request
912
913Writes information about the request to the debug logs. This includes:
914
915- Request method, path, and remote IP address
916- Query keywords (see ["query\_keywords" in Catalyst::Request](https://metacpan.org/pod/Catalyst::Request#query_keywords))
917- Request parameters
918- File uploads
919
920## $c->log\_response
921
922Writes information about the response to the debug logs by calling
923`$c->log_response_status_line` and `$c->log_response_headers`.
924
925## $c->log\_response\_status\_line($response)
926
927Writes one line of information about the response to the debug logs. This includes:
928
929- Response status code
930- Content-Type header (if present)
931- Content-Length header (if present)
932
933## $c->log\_response\_headers($headers);
934
935Hook method which can be wrapped by plugins to log the response headers.
936No-op in the default implementation.
937
938## $c->log\_request\_parameters( query => {}, body => {} )
939
940Logs request parameters to debug logs
941
942## $c->log\_request\_uploads
943
944Logs file uploads included in the request to the debug logs.
945The parameter name, filename, file type, and file size are all included in
946the debug logs.
947
948## $c->log\_request\_headers($headers);
949
950Hook method which can be wrapped by plugins to log the request headers.
951No-op in the default implementation.
952
953## $c->log\_headers($type => $headers)
954
955Logs [HTTP::Headers](https://metacpan.org/pod/HTTP::Headers) (either request or response) to the debug logs.
956
957## $c->prepare\_read
958
959Prepares the input for reading.
960
961## $c->prepare\_request
962
963Prepares the engine request.
964
965## $c->prepare\_uploads
966
967Prepares uploads.
968
969## $c->prepare\_write
970
971Prepares the output for writing.
972
973## $c->request\_class
974
975Returns or sets the request class. Defaults to [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request).
976
977## $app->request\_class\_traits
978
979An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the request class.
980
981## $app->composed\_request\_class
982
983This is the request class which has been composed with any request\_class\_traits.
984
985## $c->response\_class
986
987Returns or sets the response class. Defaults to [Catalyst::Response](https://metacpan.org/pod/Catalyst::Response).
988
989## $app->response\_class\_traits
990
991An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the response class.
992
993## $app->composed\_response\_class
994
995This is the request class which has been composed with any response\_class\_traits.
996
997## $c->read( \[$maxlength\] )
998
999Reads a chunk of data from the request body. This method is designed to
1000be used in a while loop, reading `$maxlength` bytes on every call.
1001`$maxlength` defaults to the size of the request if not specified.
1002
1003You have to set `MyApp->config(parse_on_demand => 1)` to use this
1004directly.
1005
1006Warning: If you use read(), Catalyst will not process the body,
1007so you will not be able to access POST parameters or file uploads via
1008$c->request. You must handle all body parsing yourself.
1009
1010## $c->run
1011
1012Starts the engine.
1013
1014## $c->set\_action( $action, $code, $namespace, $attrs )
1015
1016Sets an action in a given namespace.
1017
1018## $c->setup\_actions($component)
1019
1020Sets up actions for a component.
1021
1022## $c->setup\_components
1023
1024This method is called internally to set up the application's components.
1025
1026It finds modules by calling the [locate\_components](https://metacpan.org/pod/locate_components) method, expands them to
1027package names with the [expand\_component\_module](https://metacpan.org/pod/expand_component_module) method, and then installs
1028each component into the application.
1029
1030The `setup_components` config option is passed to both of the above methods.
1031
1032Installation of each component is performed by the [setup\_component](https://metacpan.org/pod/setup_component) method,
1033below.
1034
1035## $app->setup\_injected\_components
1036
1037Called by setup\_compoents to setup components that are injected.
1038
1039## $app->setup\_injected\_component( $injected\_component\_name, $config )
1040
1041Setup a given injected component.
1042
1043## $app->inject\_component($MyApp\_Component\_name => \\%args);
1044
1045Add a component that is injected at setup:
1046
1047 MyApp->inject_component( 'Model::Foo' => { from_component => 'Common::Foo' } );
1048
1049Must be called before ->setup. Expects a component name for your
1050current application and \\%args where
1051
1052- from\_component
1053
1054 The target component being injected into your application
1055
1056- roles
1057
1058 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that are applied to your component.
1059
1060Example
1061
1062 MyApp->inject_component(
1063 'Model::Foo' => {
1064 from_component => 'Common::Model::Foo',
1065 roles => ['Role1', 'Role2'],
1066 });
1067
1068## $app->inject\_components
1069
1070Inject a list of components:
1071
1072 MyApp->inject_components(
1073 'Model::FooOne' => {
1074 from_component => 'Common::Model::Foo',
1075 roles => ['Role1', 'Role2'],
1076 },
1077 'Model::FooTwo' => {
1078 from_component => 'Common::Model::Foo',
1079 roles => ['Role1', 'Role2'],
1080 });
1081
1082## $c->locate\_components( $setup\_component\_config )
1083
1084This method is meant to provide a list of component modules that should be
1085setup for the application. By default, it will use [Module::Pluggable](https://metacpan.org/pod/Module::Pluggable).
1086
1087Specify a `setup_components` config option to pass additional options directly
1088to [Module::Pluggable](https://metacpan.org/pod/Module::Pluggable). To add additional search paths, specify a key named
1089`search_extra` as an array reference. Items in the array beginning with `::`
1090will have the application class name prepended to them.
1091
1092## $c->expand\_component\_module( $component, $setup\_component\_config )
1093
1094Components found by `locate_components` will be passed to this method, which
1095is expected to return a list of component (package) names to be set up.
1096
1097## $app->delayed\_setup\_component
1098
1099Returns a coderef that points to a setup\_component instance. Used
1100internally for when you want to delay setup until the first time
1101the component is called.
1102
1103## $c->setup\_component
1104
1105## $app->config\_for( $component\_name )
1106
1107Return the application level configuration (which is not yet merged with any
1108local component configuration, via $component\_class->config) for the named
1109component or component object. Example:
1110
1111 MyApp->config(
1112 'Model::Foo' => { a => 1, b => 2},
1113 );
1114
1115 my $config = MyApp->config_for('MyApp::Model::Foo');
1116
1117In this case $config is the hashref ` {a=`1, b=>2} >.
1118
1119This is also handy for looking up configuration for a plugin, to make sure you follow
1120existing [Catalyst](https://metacpan.org/pod/Catalyst) standards for where a plugin should put its configuration.
1121
1122## $c->setup\_dispatcher
1123
1124Sets up dispatcher.
1125
1126## $c->setup\_engine
1127
1128Sets up engine.
1129
1130## $c->apply\_default\_middlewares
1131
1132Adds the following [Plack](https://metacpan.org/pod/Plack) middlewares to your application, since they are
1133useful and commonly needed:
1134
1135[Plack::Middleware::LighttpdScriptNameFix](https://metacpan.org/pod/Plack::Middleware::LighttpdScriptNameFix) (if you are using Lighttpd),
1136[Plack::Middleware::IIS6ScriptNameFix](https://metacpan.org/pod/Plack::Middleware::IIS6ScriptNameFix) (always applied since this middleware
1137is smart enough to conditionally apply itself).
1138
1139We will also automatically add [Plack::Middleware::ReverseProxy](https://metacpan.org/pod/Plack::Middleware::ReverseProxy) if we notice
1140that your HTTP $env variable `REMOTE_ADDR` is '127.0.0.1'. This is usually
1141an indication that your server is running behind a proxy frontend. However in
11422014 this is often not the case. We preserve this code for backwards compatibility
1143however I **highly** recommend that if you are running the server behind a front
1144end proxy that you clearly indicate so with the `using_frontend_proxy` configuration
1145setting to true for your environment configurations that run behind a proxy. This
1146way if you change your front end proxy address someday your code would inexplicably
1147stop working as expected.
1148
1149Additionally if we detect we are using Nginx, we add a bit of custom middleware
1150to solve some problems with the way that server handles $ENV{PATH\_INFO} and
1151$ENV{SCRIPT\_NAME}.
1152
1153Please **NOTE** that if you do use `using_frontend_proxy` the middleware is now
1154adding via `registered_middleware` rather than this method.
1155
1156If you are using Lighttpd or IIS6 you may wish to apply these middlewares. In
1157general this is no longer a common case but we have this here for backward
1158compatibility.
1159
1160## App->psgi\_app
1161
1162## App->to\_app
1163
1164Returns a PSGI application code reference for the catalyst application
1165`$c`. This is the bare application created without the `apply_default_middlewares`
1166method called. We do however apply `registered_middleware` since those are
1167integral to how [Catalyst](https://metacpan.org/pod/Catalyst) functions. Also, unlike starting your application
1168with a generated server script (via [Catalyst::Devel](https://metacpan.org/pod/Catalyst::Devel) and `catalyst.pl`) we do
1169not attempt to return a valid [PSGI](https://metacpan.org/pod/PSGI) application using any existing `${myapp}.psgi`
1170scripts in your $HOME directory.
1171
1172**NOTE** `apply_default_middlewares` was originally created when the first PSGI
1173port was done for v5.90000. These are middlewares that are added to achieve
1174backward compatibility with older applications. If you start your application
1175using one of the supplied server scripts (generated with [Catalyst::Devel](https://metacpan.org/pod/Catalyst::Devel) and
1176the project skeleton script `catalyst.pl`) we apply `apply_default_middlewares`
1177automatically. This was done so that pre and post PSGI port applications would
1178work the same way.
1179
1180This is what you want to be using to retrieve the PSGI application code
1181reference of your Catalyst application for use in a custom `.psgi` or in your
1182own created server modules.
1183
1184## $c->setup\_home
1185
1186Sets up the home directory.
1187
1188## $c->setup\_encoding
1189
1190Sets up the input/output encoding. See [ENCODING](https://metacpan.org/pod/ENCODING)
1191
1192## handle\_unicode\_encoding\_exception
1193
1194Hook to let you customize how encoding errors are handled. By default
1195we just throw an exception. Receives a hashref of debug information.
1196Example:
1197
1198 $c->handle_unicode_encoding_exception({
1199 param_value => $value,
1200 error_msg => $_,
1201 encoding_step => 'params',
1202 });
1203
1204## $c->setup\_log
1205
1206Sets up log by instantiating a [Catalyst::Log](https://metacpan.org/pod/Catalyst::Log) object and
1207passing it to `log()`. Pass in a comma-delimited list of levels to set the
1208log to.
1209
1210This method also installs a `debug` method that returns a true value into the
1211catalyst subclass if the "debug" level is passed in the comma-delimited list,
1212or if the `$CATALYST_DEBUG` environment variable is set to a true value.
1213
1214Note that if the log has already been setup, by either a previous call to
1215`setup_log` or by a call such as `__PACKAGE__->log( MyLogger->new )`,
1216that this method won't actually set up the log object.
1217
1218## $c->setup\_plugins
1219
1220Sets up plugins.
1221
1222## $c->setup\_stats
1223
1224Sets up timing statistics class.
1225
1226## $c->registered\_plugins
1227
1228Returns a sorted list of the plugins which have either been stated in the
1229import list.
1230
1231If passed a given plugin name, it will report a boolean value indicating
1232whether or not that plugin is loaded. A fully qualified name is required if
1233the plugin name does not begin with `Catalyst::Plugin::`.
1234
1235 if ($c->registered_plugins('Some::Plugin')) {
1236 ...
1237 }
1238
1239## default\_middleware
1240
1241Returns a list of instantiated PSGI middleware objects which is the default
1242middleware that is active for this application (taking any configuration
1243options into account, excluding your custom added middleware via the `psgi_middleware`
1244configuration option). You can override this method if you wish to change
1245the default middleware (although do so at risk since some middleware is vital
1246to application function.)
1247
1248The current default middleware list is:
1249
1250 Catalyst::Middleware::Stash
1251 Plack::Middleware::HTTPExceptions
1252 Plack::Middleware::RemoveRedundantBody
1253 Plack::Middleware::FixMissingBodyInRedirect
1254 Plack::Middleware::ContentLength
1255 Plack::Middleware::MethodOverride
1256 Plack::Middleware::Head
1257
1258If the configuration setting `using_frontend_proxy` is true we add:
1259
1260 Plack::Middleware::ReverseProxy
1261
1262If the configuration setting `using_frontend_proxy_path` is true we add:
1263
1264 Plack::Middleware::ReverseProxyPath
1265
1266But **NOTE** that [Plack::Middleware::ReverseProxyPath](https://metacpan.org/pod/Plack::Middleware::ReverseProxyPath) is not a dependency of the
1267[Catalyst](https://metacpan.org/pod/Catalyst) distribution so if you want to use this option you should add it to
1268your project distribution file.
1269
1270These middlewares will be added at ["setup\_middleware"](#setup_middleware) during the
1271["setup"](#setup) phase of application startup.
1272
1273## registered\_middlewares
1274
1275Read only accessor that returns an array of all the middleware in the order
1276that they were added (which is the REVERSE of the order they will be applied).
1277
1278The values returned will be either instances of [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware) or of a
1279compatible interface, or a coderef, which is assumed to be inlined middleware
1280
1281## setup\_middleware (?@middleware)
1282
1283Read configuration information stored in configuration key `psgi_middleware` or
1284from passed @args.
1285
1286See under ["CONFIGURATION"](#configuration) information regarding `psgi_middleware` and how
1287to use it to enable [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware)
1288
1289This method is automatically called during 'setup' of your application, so
1290you really don't need to invoke it. However you may do so if you find the idea
1291of loading middleware via configuration weird :). For example:
1292
1293 package MyApp;
1294
1295 use Catalyst;
1296
1297 __PACKAGE__->setup_middleware('Head');
1298 __PACKAGE__->setup;
1299
1300When we read middleware definitions from configuration, we reverse the list
1301which sounds odd but is likely how you expect it to work if you have prior
1302experience with [Plack::Builder](https://metacpan.org/pod/Plack::Builder) or if you previously used the plugin
1303[Catalyst::Plugin::EnableMiddleware](https://metacpan.org/pod/Catalyst::Plugin::EnableMiddleware) (which is now considered deprecated)
1304
1305So basically your middleware handles an incoming request from the first
1306registered middleware, down and handles the response from the last middleware
1307up.
1308
1309## registered\_data\_handlers
1310
1311A read only copy of registered Data Handlers returned as a Hash, where each key
1312is a content type and each value is a subref that attempts to decode that content
1313type.
1314
1315## setup\_data\_handlers (?@data\_handler)
1316
1317Read configuration information stored in configuration key `data_handlers` or
1318from passed @args.
1319
1320See under ["CONFIGURATION"](#configuration) information regarding `data_handlers`.
1321
1322This method is automatically called during 'setup' of your application, so
1323you really don't need to invoke it.
1324
1325## default\_data\_handlers
1326
1327Default Data Handlers that come bundled with [Catalyst](https://metacpan.org/pod/Catalyst). Currently there are
1328only two default data handlers, for 'application/json' and an alternative to
1329'application/x-www-form-urlencoded' which supposed nested form parameters via
1330[CGI::Struct](https://metacpan.org/pod/CGI::Struct) or via [CGI::Struct::XS](https://metacpan.org/pod/CGI::Struct::XS) IF you've installed it.
1331
1332The 'application/json' data handler is used to parse incoming JSON into a Perl
1333data structure. It used either [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS) or [JSON](https://metacpan.org/pod/JSON), depending on which
1334is installed. This allows you to fail back to [JSON:PP](JSON:PP), which is a Pure Perl
1335JSON decoder, and has the smallest dependency impact.
1336
1337Because we don't wish to add more dependencies to [Catalyst](https://metacpan.org/pod/Catalyst), if you wish to
1338use this new feature we recommend installing [JSON](https://metacpan.org/pod/JSON) or [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS) in
1339order to get the best performance. You should add either to your dependency
1340list (Makefile.PL, dist.ini, cpanfile, etc.)
1341
1342## $c->stack
1343
1344Returns an arrayref of the internal execution stack (actions that are
1345currently executing).
1346
1347## $c->stats
1348
1349Returns the current timing statistics object. By default Catalyst uses
1350[Catalyst::Stats](https://metacpan.org/pod/Catalyst::Stats), but can be set otherwise with
1351[stats\_class](#c-stats_class).
1352
1353Even if [-Stats](#stats) is not enabled, the stats object is still
1354available. By enabling it with ` $c-`stats->enabled(1) >, it can be used to
1355profile explicitly, although MyApp.pm still won't profile nor output anything
1356by itself.
1357
1358## $c->stats\_class
1359
1360Returns or sets the stats (timing statistics) class. [Catalyst::Stats](https://metacpan.org/pod/Catalyst::Stats) is used by default.
1361
1362## $app->stats\_class\_traits
1363
1364A arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that are applied to the stats\_class before creating it.
1365
1366## $app->composed\_stats\_class
1367
1368this is the stats\_class composed with any 'stats\_class\_traits'.
1369
1370## $c->use\_stats
1371
1372Returns 1 when [stats collection](#stats) is enabled.
1373
1374Note that this is a static method, not an accessor and should be overridden
1375by declaring `sub use_stats { 1 }` in your MyApp.pm, not by calling `$c->use_stats(1)`.
1376
1377## $c->write( $data )
1378
1379Writes $data to the output stream. When using this method directly, you
1380will need to manually set the `Content-Length` header to the length of
1381your output data, if known.
1382
1383## version
1384
1385Returns the Catalyst version number. Mostly useful for "powered by"
1386messages in template systems.
1387
1388# CONFIGURATION
1389
1390There are a number of 'base' config variables which can be set:
1391
1392- `always_catch_http_exceptions` - As of version 5.90060 Catalyst
1393rethrows errors conforming to the interface described by
1394[Plack::Middleware::HTTPExceptions](https://metacpan.org/pod/Plack::Middleware::HTTPExceptions) and lets the middleware deal with it.
1395Set true to get the deprecated behaviour and have Catalyst catch HTTP exceptions.
1396- `default_model` - The default model picked if you say `$c->model`. See ["$c->model($name)"](#c-model-name).
1397- `default_view` - The default view to be rendered or returned when `$c->view` is called. See ["$c->view($name)"](#c-view-name).
1398- `disable_component_resolution_regex_fallback` - Turns
1399off the deprecated component resolution functionality so
1400that if any of the component methods (e.g. `$c->controller('Foo')`)
1401are called then regex search will not be attempted on string values and
1402instead `undef` will be returned.
1403- `home` - The application home directory. In an uninstalled application,
1404this is the top level application directory. In an installed application,
1405this will be the directory containing `MyApp.pm`.
1406- `ignore_frontend_proxy` - See ["PROXY SUPPORT"](#proxy-support)
1407- `name` - The name of the application in debug messages and the debug and
1408welcome screens
1409- `parse_on_demand` - The request body (for example file uploads) will not be parsed
1410until it is accessed. This allows you to (for example) check authentication (and reject
1411the upload) before actually receiving all the data. See ["ON-DEMAND PARSER"](#on-demand-parser)
1412- `root` - The root directory for templates. Usually this is just a
1413subdirectory of the home directory, but you can set it to change the
1414templates to a different directory.
1415- `search_extra` - Array reference passed to Module::Pluggable to for additional
1416namespaces from which components will be loaded (and constructed and stored in
1417`$c->components`).
1418- `show_internal_actions` - If true, causes internal actions such as `_DISPATCH`
1419to be shown in hit debug tables in the test server.
1420- `use_request_uri_for_path` - Controls if the `REQUEST_URI` or `PATH_INFO` environment
1421variable should be used for determining the request path.
1422
1423 Most web server environments pass the requested path to the application using environment variables,
1424 from which Catalyst has to reconstruct the request base (i.e. the top level path to / in the application,
1425 exposed as `$c->request->base`) and the request path below that base.
1426
1427 There are two methods of doing this, both of which have advantages and disadvantages. Which method is used
1428 is determined by the `$c->config(use_request_uri_for_path)` setting (which can either be true or false).
1429
1430 - use\_request\_uri\_for\_path => 0
1431
1432 This is the default (and the) traditional method that Catalyst has used for determining the path information.
1433 The path is generated from a combination of the `PATH_INFO` and `SCRIPT_NAME` environment variables.
1434 The allows the application to behave correctly when `mod_rewrite` is being used to redirect requests
1435 into the application, as these variables are adjusted by mod\_rewrite to take account for the redirect.
1436
1437 However this method has the major disadvantage that it is impossible to correctly decode some elements
1438 of the path, as RFC 3875 says: "`Unlike a URI path, the PATH_INFO is not URL-encoded, and cannot
1439 contain path-segment parameters.`" This means PATH\_INFO is **always** decoded, and therefore Catalyst
1440 can't distinguish / vs %2F in paths (in addition to other encoded values).
1441
1442 - use\_request\_uri\_for\_path => 1
1443
1444 This method uses the `REQUEST_URI` and `SCRIPT_NAME` environment variables. As `REQUEST_URI` is never
1445 decoded, this means that applications using this mode can correctly handle URIs including the %2F character
1446 (i.e. with `AllowEncodedSlashes` set to `On` in Apache).
1447
d1467830 1448 Given that this method of path resolution is probably more correct, it is recommended that you use
9e7f288e 1449 this unless you have a specific need to deploy your application in a non-standard environment, and you are
1450 aware of the implications of not being able to handle encoded URI paths correctly.
1451
1452 However it also means that in a number of cases when the app isn't installed directly at a path, but instead
1453 is having paths rewritten into it (e.g. as a .cgi/fcgi in a public\_html directory, with mod\_rewrite in a
1454 .htaccess file, or when SSI is used to rewrite pages into the app, or when sub-paths of the app are exposed
1455 at other URIs than that which the app is 'normally' based at with `mod_rewrite`), the resolution of
1456 `$c->request->base` will be incorrect.
1457
1458- `using_frontend_proxy` - See ["PROXY SUPPORT"](#proxy-support).
1459- `using_frontend_proxy_path` - Enabled [Plack::Middleware::ReverseProxyPath](https://metacpan.org/pod/Plack::Middleware::ReverseProxyPath) on your application (if
1460installed, otherwise log an error). This is useful if your application is not running on the
1461'root' (or /) of your host server. **NOTE** if you use this feature you should add the required
d1467830 1462middleware to your project dependency list since it's not automatically a dependency of [Catalyst](https://metacpan.org/pod/Catalyst).
9e7f288e 1463This has been done since not all people need this feature and we wish to restrict the growth of
1464[Catalyst](https://metacpan.org/pod/Catalyst) dependencies.
1465- `encoding` - See ["ENCODING"](#encoding)
1466
1467 This now defaults to 'UTF-8'. You my turn it off by setting this configuration
1468 value to undef.
1469
1470- `abort_chain_on_error_fix`
1471
1472 When there is an error in an action chain, the default behavior is to continue
1473 processing the remaining actions and then catch the error upon chain end. This
1474 can lead to running actions when the application is in an unexpected state. If
1475 you have this issue, setting this config value to true will promptly exit a
1476 chain when there is an error raised in any action (thus terminating the chain
1477 early.)
1478
1479 use like:
1480
1481 __PACKAGE__->config(abort_chain_on_error_fix => 1);
1482
1483 In the future this might become the default behavior.
1484
1485- `use_hash_multivalue_in_request`
1486
1487 In [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request) the methods `query_parameters`, `body_parametes`
1488 and `parameters` return a hashref where values might be scalar or an arrayref
1489 depending on the incoming data. In many cases this can be undesirable as it
1490 leads one to writing defensive code like the following:
1491
1492 my ($val) = ref($c->req->parameters->{a}) ?
1493 @{$c->req->parameters->{a}} :
1494 $c->req->parameters->{a};
1495
1496 Setting this configuration item to true will make [Catalyst](https://metacpan.org/pod/Catalyst) populate the
1497 attributes underlying these methods with an instance of [Hash::MultiValue](https://metacpan.org/pod/Hash::MultiValue)
1498 which is used by [Plack::Request](https://metacpan.org/pod/Plack::Request) and others to solve this very issue. You
1499 may prefer this behavior to the default, if so enable this option (be warned
1500 if you enable it in a legacy application we are not sure if it is completely
1501 backwardly compatible).
1502
1503- `skip_complex_post_part_handling`
1504
79fb8f95 1505 When creating body parameters from a POST, if we run into a multipart POST
9e7f288e 1506 that does not contain uploads, but instead contains inlined complex data
1507 (very uncommon) we cannot reliably convert that into field => value pairs. So
1508 instead we create an instance of [Catalyst::Request::PartData](https://metacpan.org/pod/Catalyst::Request::PartData). If this causes
1509 issue for you, you can disable this by setting `skip_complex_post_part_handling`
1510 to true (default is false).
1511
1512- `skip_body_param_unicode_decoding`
1513
1514 Generally we decode incoming POST params based on your declared encoding (the
1515 default for this is to decode UTF-8). If this is causing you trouble and you
1516 do not wish to turn all encoding support off (with the `encoding` configuration
1517 parameter) you may disable this step atomically by setting this configuration
1518 parameter to true.
1519
1520- `do_not_decode_query`
1521
1522 If true, then do not try to character decode any wide characters in your
d1467830 1523 request URL query or keywords. Most readings of the relevant specifications
9e7f288e 1524 suggest these should be UTF-\* encoded, which is the default that [Catalyst](https://metacpan.org/pod/Catalyst)
79fb8f95 1525 will use, however if you are creating a lot of URLs manually or have external
9e7f288e 1526 evil clients, this might cause you trouble. If you find the changes introduced
1527 in Catalyst version 5.90080+ break some of your query code, you may disable
1528 the UTF-8 decoding globally using this configuration.
1529
1530 This setting takes precedence over `default_query_encoding` and
1531 `decode_query_using_global_encoding`
1532
1533- `default_query_encoding`
1534
1535 By default we decode query and keywords in your request URL using UTF-8, which
79fb8f95 1536 is our reading of the relevant specifications. This setting allows one to
9e7f288e 1537 specify a fixed value for how to decode your query. You might need this if
1538 you are doing a lot of custom encoding of your URLs and not using UTF-8.
1539
1540 This setting take precedence over `decode_query_using_global_encoding`.
1541
1542- `decode_query_using_global_encoding`
1543
1544 Setting this to true will default your query decoding to whatever your
1545 general global encoding is (the default is UTF-8).
1546
1547- `use_chained_args_0_special_case`
1548
1549 In older versions of Catalyst, when more than one action matched the same path
1550 AND all those matching actions declared Args(0), we'd break the tie by choosing
1551 the first action defined. We now normalized how Args(0) works so that it
1552 follows the same rule as Args(N), which is to say when we need to break a tie
1553 we choose the LAST action defined. If this breaks your code and you don't
1554 have time to update to follow the new normalized approach, you may set this
1555 value to true and it will globally revert to the original chaining behavior.
1556
1557- `psgi_middleware` - See ["PSGI MIDDLEWARE"](#psgi-middleware).
1558- `data_handlers` - See ["DATA HANDLERS"](#data-handlers).
1559- `stats_class_traits`
1560
79fb8f95 1561 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get composed into your stats class.
9e7f288e 1562
1563- `request_class_traits`
1564
79fb8f95 1565 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get composed into your request class.
9e7f288e 1566
1567- `response_class_traits`
1568
79fb8f95 1569 An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get composed into your response class.
9e7f288e 1570
1571- `inject_components`
1572
1573 A Hashref of [Catalyst::Component](https://metacpan.org/pod/Catalyst::Component) subclasses that are 'injected' into configuration.
1574 For example:
1575
1576 MyApp->config({
1577 inject_components => {
1578 'Controller::Err' => { from_component => 'Local::Controller::Errors' },
1579 'Model::Zoo' => { from_component => 'Local::Model::Foo' },
1580 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] },
1581 },
1582 'Controller::Err' => { a => 100, b=>200, namespace=>'error' },
1583 'Model::Zoo' => { a => 2 },
1584 'Model::Foo' => { a => 100 },
1585 });
1586
1587 Generally [Catalyst](https://metacpan.org/pod/Catalyst) looks for components in your Model/View or Controller directories.
1588 However for cases when you which to use an existing component and you don't need any
1589 customization (where for when you can apply a role to customize it) you may inject those
1590 components into your application. Please note any configuration should be done 'in the
1591 normal way', with a key under configuration named after the component affix, as in the
1592 above example.
1593
1594 Using this type of injection allows you to construct significant amounts of your application
1595 with only configuration!. This may or may not lead to increased code understanding.
1596
1597 Please not you may also call the ->inject\_components application method as well, although
1598 you must do so BEFORE setup.
1599
1600# EXCEPTIONS
1601
1602Generally when you throw an exception inside an Action (or somewhere in
1603your stack, such as in a model that an Action is calling) that exception
1604is caught by Catalyst and unless you either catch it yourself (via eval
1605or something like [Try::Tiny](https://metacpan.org/pod/Try::Tiny) or by reviewing the ["error"](#error) stack, it
1606will eventually reach ["finalize\_errors"](#finalize_errors) and return either the debugging
1607error stack page, or the default error page. However, if your exception
1608can be caught by [Plack::Middleware::HTTPExceptions](https://metacpan.org/pod/Plack::Middleware::HTTPExceptions), [Catalyst](https://metacpan.org/pod/Catalyst) will
1609instead rethrow it so that it can be handled by that middleware (which
1610is part of the default middleware). For example this would allow
1611
1612 use HTTP::Throwable::Factory 'http_throw';
1613
1614 sub throws_exception :Local {
1615 my ($self, $c) = @_;
1616
1617 http_throw(SeeOther => { location =>
1618 $c->uri_for($self->action_for('redirect')) });
1619
1620 }
1621
1622# INTERNAL ACTIONS
1623
1624Catalyst uses internal actions like `_DISPATCH`, `_BEGIN`, `_AUTO`,
1625`_ACTION`, and `_END`. These are by default not shown in the private
1626action table, but you can make them visible with a config parameter.
1627
1628 MyApp->config(show_internal_actions => 1);
1629
1630# ON-DEMAND PARSER
1631
1632The request body is usually parsed at the beginning of a request,
1633but if you want to handle input yourself, you can enable on-demand
1634parsing with a config parameter.
1635
1636 MyApp->config(parse_on_demand => 1);
1637
1638# PROXY SUPPORT
1639
1640Many production servers operate using the common double-server approach,
1641with a lightweight frontend web server passing requests to a larger
1642backend server. An application running on the backend server must deal
1643with two problems: the remote user always appears to be `127.0.0.1` and
1644the server's hostname will appear to be `localhost` regardless of the
1645virtual host that the user connected through.
1646
1647Catalyst will automatically detect this situation when you are running
1648the frontend and backend servers on the same machine. The following
1649changes are made to the request.
1650
1651 $c->req->address is set to the user's real IP address, as read from
1652 the HTTP X-Forwarded-For header.
1653
1654 The host value for $c->req->base and $c->req->uri is set to the real
1655 host, as read from the HTTP X-Forwarded-Host header.
1656
1657Additionally, you may be running your backend application on an insecure
1658connection (port 80) while your frontend proxy is running under SSL. If there
1659is a discrepancy in the ports, use the HTTP header `X-Forwarded-Port` to
1660tell Catalyst what port the frontend listens on. This will allow all URIs to
1661be created properly.
1662
1663In the case of passing in:
1664
1665 X-Forwarded-Port: 443
1666
1667All calls to `uri_for` will result in an https link, as is expected.
1668
1669Obviously, your web server must support these headers for this to work.
1670
1671In a more complex server farm environment where you may have your
1672frontend proxy server(s) on different machines, you will need to set a
1673configuration option to tell Catalyst to read the proxied data from the
1674headers.
1675
1676 MyApp->config(using_frontend_proxy => 1);
1677
1678If you do not wish to use the proxy support at all, you may set:
1679
1680 MyApp->config(ignore_frontend_proxy => 0);
1681
1682## Note about psgi files
1683
1684Note that if you supply your own .psgi file, calling
1685`MyApp->psgi_app(@_);`, then **this will not happen automatically**.
1686
1687You either need to apply [Plack::Middleware::ReverseProxy](https://metacpan.org/pod/Plack::Middleware::ReverseProxy) yourself
1688in your psgi, for example:
1689
1690 builder {
1691 enable "Plack::Middleware::ReverseProxy";
1692 MyApp->psgi_app
1693 };
1694
1695This will unconditionally add the ReverseProxy support, or you need to call
1696`$app = MyApp->apply_default_middlewares($app)` (to conditionally
1697apply the support depending upon your config).
1698
1699See [Catalyst::PSGI](https://metacpan.org/pod/Catalyst::PSGI) for more information.
1700
1701# THREAD SAFETY
1702
1703Catalyst has been tested under Apache 2's threading `mpm_worker`,
1704`mpm_winnt`, and the standalone forking HTTP server on Windows. We
1705believe the Catalyst core to be thread-safe.
1706
1707If you plan to operate in a threaded environment, remember that all other
1708modules you are using must also be thread-safe. Some modules, most notably
1709[DBD::SQLite](https://metacpan.org/pod/DBD::SQLite), are not thread-safe.
1710
1711# DATA HANDLERS
1712
1713The [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request) object uses [HTTP::Body](https://metacpan.org/pod/HTTP::Body) to populate 'classic' HTML
1714form parameters and URL search query fields. However it has become common
1715for various alternative content types to be PUT or POSTed to your controllers
1716and actions. People working on RESTful APIs, or using AJAX often use JSON,
1717XML and other content types when communicating with an application server. In
1718order to better support this use case, [Catalyst](https://metacpan.org/pod/Catalyst) defines a global configuration
1719option, `data_handlers`, which lets you associate a content type with a coderef
1720that parses that content type into something Perl can readily access.
1721
1722 package MyApp::Web;
1723
1724 use Catalyst;
1725 use JSON::Maybe;
1726
1727 __PACKAGE__->config(
1728 data_handlers => {
1729 'application/json' => sub { local $/; decode_json $_->getline },
1730 },
1731 ## Any other configuration.
1732 );
1733
1734 __PACKAGE__->setup;
1735
1736By default [Catalyst](https://metacpan.org/pod/Catalyst) comes with a generic JSON data handler similar to the
1737example given above, which uses [JSON::Maybe](https://metacpan.org/pod/JSON::Maybe) to provide either [JSON::PP](https://metacpan.org/pod/JSON::PP)
1738(a pure Perl, dependency free JSON parser) or [Cpanel::JSON::XS](https://metacpan.org/pod/Cpanel::JSON::XS) if you have
1739it installed (if you want the faster XS parser, add it to you project Makefile.PL
1740or dist.ini, cpanfile, etc.)
1741
1742The `data_handlers` configuration is a hashref whose keys are HTTP Content-Types
1743(matched against the incoming request type using a regexp such as to be case
1744insensitive) and whose values are coderefs that receive a localized version of
1745`$_` which is a filehandle object pointing to received body.
1746
1747This feature is considered an early access release and we reserve the right
1748to alter the interface in order to provide a performant and secure solution to
1749alternative request body content. Your reports welcomed!
1750
1751# PSGI MIDDLEWARE
1752
1753You can define middleware, defined as [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware) or a compatible
1754interface in configuration. Your middleware definitions are in the form of an
1755arrayref under the configuration key `psgi_middleware`. Here's an example
1756with details to follow:
1757
1758 package MyApp::Web;
1759
1760 use Catalyst;
1761 use Plack::Middleware::StackTrace;
1762
1763 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1764
1765 __PACKAGE__->config(
1766 'psgi_middleware', [
1767 'Debug',
1768 '+MyApp::Custom',
1769 $stacktrace_middleware,
1770 'Session' => {store => 'File'},
1771 sub {
1772 my $app = shift;
1773 return sub {
1774 my $env = shift;
1775 $env->{myapp.customkey} = 'helloworld';
1776 $app->($env);
1777 },
1778 },
1779 ],
1780 );
1781
1782 __PACKAGE__->setup;
1783
1784So the general form is:
1785
1786 __PACKAGE__->config(psgi_middleware => \@middleware_definitions);
1787
1788Where `@middleware` is one or more of the following, applied in the REVERSE of
1789the order listed (to make it function similarly to [Plack::Builder](https://metacpan.org/pod/Plack::Builder):
1790
1791Alternatively, you may also define middleware by calling the ["setup\_middleware"](#setup_middleware)
1792package method:
1793
1794 package MyApp::Web;
1795
1796 use Catalyst;
1797
1798 __PACKAGE__->setup_middleware( \@middleware_definitions);
1799 __PACKAGE__->setup;
1800
1801In the case where you do both (use 'setup\_middleware' and configuration) the
1802package call to setup\_middleware will be applied earlier (in other words its
1803middleware will wrap closer to the application). Keep this in mind since in
1804some cases the order of middleware is important.
1805
1806The two approaches are not exclusive.
1807
1808- Middleware Object
1809
1810 An already initialized object that conforms to the [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware)
1811 specification:
1812
1813 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
1814
1815 __PACKAGE__->config(
1816 'psgi_middleware', [
1817 $stacktrace_middleware,
1818 ]);
1819
1820
1821
1822- coderef
1823
1824 A coderef that is an inlined middleware:
1825
1826 __PACKAGE__->config(
1827 'psgi_middleware', [
1828 sub {
1829 my $app = shift;
1830 return sub {
1831 my $env = shift;
1832 if($env->{PATH_INFO} =~m/forced/) {
1833 Plack::App::File
1834 ->new(file=>TestApp->path_to(qw/share static forced.txt/))
1835 ->call($env);
1836 } else {
1837 return $app->($env);
1838 }
1839 },
1840 },
1841 ]);
1842
1843
1844
1845
1846- a scalar
1847
1848 We assume the scalar refers to a namespace after normalizing it using the
1849 following rules:
1850
1851 (1) If the scalar is prefixed with a "+" (as in `+MyApp::Foo`) then the full string
1852 is assumed to be 'as is', and we just install and use the middleware.
1853
1854 (2) If the scalar begins with "Plack::Middleware" or your application namespace
1855 (the package name of your Catalyst application subclass), we also assume then
1856 that it is a full namespace, and use it.
1857
1858 (3) Lastly, we then assume that the scalar is a partial namespace, and attempt to
1859 resolve it first by looking for it under your application namespace (for example
1860 if you application is "MyApp::Web" and the scalar is "MyMiddleware", we'd look
1861 under "MyApp::Web::Middleware::MyMiddleware") and if we don't find it there, we
1862 will then look under the regular [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware) namespace (i.e. for the
1863 previous we'd try "Plack::Middleware::MyMiddleware"). We look under your application
1864 namespace first to let you 'override' common [Plack::Middleware](https://metacpan.org/pod/Plack::Middleware) locally, should
1865 you find that a good idea.
1866
1867 Examples:
1868
1869 package MyApp::Web;
1870
1871 __PACKAGE__->config(
1872 'psgi_middleware', [
1873 'Debug', ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap
1874 'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap
1875 '+MyApp::Custom', ## MyApp::Custom->wrap
1876 ],
1877 );
1878
1879
1880- a scalar followed by a hashref
1881
1882 Just like the previous, except the following `HashRef` is used as arguments
1883 to initialize the middleware object.
1884
1885 __PACKAGE__->config(
1886 'psgi_middleware', [
1887 'Session' => {store => 'File'},
1888 ]);
1889
1890Please see [PSGI](https://metacpan.org/pod/PSGI) for more on middleware.
1891
1892# ENCODING
1893
1894Starting in [Catalyst](https://metacpan.org/pod/Catalyst) version 5.90080 encoding is automatically enabled
1895and set to encode all body responses to UTF8 when possible and applicable.
1896Following is documentation on this process. If you are using an older
1897version of [Catalyst](https://metacpan.org/pod/Catalyst) you should review documentation for that version since
1898a lot has changed.
1899
1900By default encoding is now 'UTF-8'. You may turn it off by setting
1901the encoding configuration to undef.
1902
1903 MyApp->config(encoding => undef);
1904
1905This is recommended for temporary backwards compatibility only.
1906
1907Encoding is automatically applied when the content-type is set to
1908a type that can be encoded. Currently we encode when the content type
1909matches the following regular expression:
1910
1911 $content_type =~ /^text|xml$|javascript$/
1912
1913Encoding is set on the application, but it is copied to the context object
1914so that you can override it on a request basis.
1915
1916Be default we don't automatically encode 'application/json' since the most
1917common approaches to generating this type of response (Either via [Catalyst::View::JSON](https://metacpan.org/pod/Catalyst::View::JSON)
1918or [Catalyst::Action::REST](https://metacpan.org/pod/Catalyst::Action::REST)) will do so already and we want to avoid double
1919encoding issues.
1920
1921If you are producing JSON response in an unconventional manner (such
1922as via a template or manual strings) you should perform the UTF8 encoding
1923manually as well such as to conform to the JSON specification.
1924
1925NOTE: We also examine the value of $c->response->content\_encoding. If
1926you set this (like for example 'gzip', and manually gzipping the body)
1927we assume that you have done all the necessary encoding yourself, since
1928we cannot encode the gzipped contents. If you use a plugin like
1929[Catalyst::Plugin::Compress](https://metacpan.org/pod/Catalyst::Plugin::Compress) you need to update to a modern version in order
1930to have this function correctly with the new UTF8 encoding code, or you
1931can use [Plack::Middleware::Deflater](https://metacpan.org/pod/Plack::Middleware::Deflater) or (probably best) do your compression on
1932a front end proxy.
1933
1934## Methods
1935
1936- encoding
1937
1938 Returns an instance of an `Encode` encoding
1939
1940 print $c->encoding->name
1941
1942- handle\_unicode\_encoding\_exception ($exception\_context)
1943
1944 Method called when decoding process for a request fails.
1945
1946 An `$exception_context` hashref is provided to allow you to override the
1947 behaviour of your application when given data with incorrect encodings.
1948
1949 The default method throws exceptions in the case of invalid request parameters
1950 (resulting in a 500 error), but ignores errors in upload filenames.
1951
1952 The keys passed in the `$exception_context` hash are:
1953
1954 - param\_value
1955
1956 The value which was not able to be decoded.
1957
1958 - error\_msg
1959
1960 The exception received from [Encode](https://metacpan.org/pod/Encode).
1961
1962 - encoding\_step
1963
1964 What type of data was being decoded. Valid values are (currently)
1965 `params` - for request parameters / arguments / captures
1966 and `uploads` - for request upload filenames.
1967
1968# SUPPORT
1969
1970IRC:
1971
1972 Join #catalyst on irc.perl.org.
1973
1974Mailing Lists:
1975
1976 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
1977 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
1978
1979Web:
1980
1981 http://catalyst.perl.org
1982
1983Wiki:
1984
1985 http://dev.catalyst.perl.org
1986
1987# SEE ALSO
1988
1989## [Task::Catalyst](https://metacpan.org/pod/Task::Catalyst) - All you need to start with Catalyst
1990
1991## [Catalyst::Manual](https://metacpan.org/pod/Catalyst::Manual) - The Catalyst Manual
1992
1993## [Catalyst::Component](https://metacpan.org/pod/Catalyst::Component), [Catalyst::Controller](https://metacpan.org/pod/Catalyst::Controller) - Base classes for components
1994
1995## [Catalyst::Engine](https://metacpan.org/pod/Catalyst::Engine) - Core engine
1996
1997## [Catalyst::Log](https://metacpan.org/pod/Catalyst::Log) - Log class.
1998
1999## [Catalyst::Request](https://metacpan.org/pod/Catalyst::Request) - Request object
2000
2001## [Catalyst::Response](https://metacpan.org/pod/Catalyst::Response) - Response object
2002
2003## [Catalyst::Test](https://metacpan.org/pod/Catalyst::Test) - The test suite.
2004
2005# PROJECT FOUNDER
2006
2007sri: Sebastian Riedel <sri@cpan.org>
2008
2009# CONTRIBUTORS
2010
2011abw: Andy Wardley
2012
2013acme: Leon Brocard <leon@astray.com>
2014
2015abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
2016
d1467830 2017andrewalker: André Walker <andre@cpan.org>
9e7f288e 2018
2019Andrew Bramble
2020
2021Andrew Ford <A.Ford@ford-mason.co.uk>
2022
2023Andrew Ruthven
2024
2025andyg: Andy Grundman <andy@hybridized.org>
2026
2027audreyt: Audrey Tang
2028
2029bricas: Brian Cassidy <bricas@cpan.org>
2030
2031Caelum: Rafael Kitover <rkitover@io.com>
2032
2033chansen: Christian Hansen
2034
2035chicks: Christopher Hicks
2036
2037Chisel Wright `pause@herlpacker.co.uk`
2038
2039Danijel Milicevic `me@danijel.de`
2040
2041davewood: David Schmidt <davewood@cpan.org>
2042
2043David Kamholz <dkamholz@cpan.org>
2044
2045David Naughton, `naughton@umn.edu`
2046
2047David E. Wheeler
2048
2049dhoss: Devin Austin <dhoss@cpan.org>
2050
2051dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
2052
2053Drew Taylor
2054
2055dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
2056
2057esskar: Sascha Kiefer
2058
2059fireartist: Carl Franks <cfranks@cpan.org>
2060
2061frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
2062
2063gabb: Danijel Milicevic
2064
2065Gary Ashton Jones
2066
2067Gavin Henry `ghenry@perl.me.uk`
2068
2069Geoff Richards
2070
2071groditi: Guillermo Roditi <groditi@gmail.com>
2072
2073hobbs: Andrew Rodland <andrew@cleverdomain.org>
2074
d1467830 2075ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
9e7f288e 2076
2077jcamacho: Juan Camacho
2078
2079jester: Jesse Sheidlower `jester@panix.com`
2080
2081jhannah: Jay Hannah <jay@jays.net>
2082
2083Jody Belka
2084
2085Johan Lindstrom
2086
2087jon: Jon Schutz <jjschutz@cpan.org>
2088
2089Jonathan Rockway `<jrockway@cpan.org>`
2090
2091Kieren Diment `kd@totaldatasolution.com`
2092
2093konobi: Scott McWhirter <konobi@cpan.org>
2094
2095marcus: Marcus Ramberg <mramberg@cpan.org>
2096
83757b9e 2097Mischa Spiegelmock <revmischa@cpan.org>
2098
9e7f288e 2099miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
2100
2101mgrimes: Mark Grimes <mgrimes@cpan.org>
2102
2103mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
2104
2105mugwump: Sam Vilain
2106
2107naughton: David Naughton
2108
2109ningu: David Kamholz <dkamholz@cpan.org>
2110
2111nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
2112
2113numa: Dan Sully <daniel@cpan.org>
2114
2115obra: Jesse Vincent
2116
2117Octavian Rasnita
2118
2119omega: Andreas Marienborg
2120
2121Oleg Kostyuk <cub.uanic@gmail.com>
2122
2123phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
2124
2125rafl: Florian Ragwitz <rafl@debian.org>
2126
2127random: Roland Lammel <lammel@cpan.org>
2128
2129Robert Sedlacek `<rs@474.at>`
2130
2131SpiceMan: Marcel Montes
2132
2133sky: Arthur Bergman
2134
2135szbalint: Balint Szilakszi <szbalint@cpan.org>
2136
2137t0m: Tomas Doran <bobtfish@bobtfish.net>
2138
2139Ulf Edvinsson
2140
2141vanstyn: Henry Van Styn <vanstyn@cpan.org>
2142
2143Viljo Marrandi `vilts@yahoo.com`
2144
2145Will Hawes `info@whawes.co.uk`
2146
2147willert: Sebastian Willert <willert@cpan.org>
2148
2149wreis: Wallace Reis <wreis@cpan.org>
2150
2151Yuval Kogman, `nothingmuch@woobling.org`
2152
2153rainboxx: Matthias Dietrich, `perl@rainboxx.de`
2154
2155dd070: Dhaval Dhanani <dhaval070@gmail.com>
2156
2157Upasana <me@upasana.me>
2158
2159John Napiorkowski (jnap) <jjnapiork@cpan.org>
2160
2161# COPYRIGHT
2162
2163Copyright (c) 2005-2015, the above named PROJECT FOUNDER and CONTRIBUTORS.
2164
2165# LICENSE
2166
2167This library is free software. You can redistribute it and/or modify it under
2168the same terms as Perl itself.