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