Catalyst - The Elegant MVC Web Application Framework
-<div>
-
- <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>
- <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>
- <a href="http://cpants.cpanauthors.org/dist/Catalyst-Runtime"><img src="http://cpants.cpanauthors.org/dist/Catalyst-Runtime.png" alt='Kwalitee Score' /></a>
-</div>
-
# SYNOPSIS
See the [Catalyst::Manual](https://metacpan.org/pod/Catalyst::Manual) distribution for comprehensive
documentation and tutorials.
- # Building Catalyst for development
- cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
- cpanm --installdeps --with-develop .
- perl Makefile.PL
-
# Install Catalyst::Devel for helpers and other development tools
# use the helper to create a new application
catalyst.pl MyApp
`$c->go` will perform a full dispatch on the specified action or method,
with localized `$c->action` and `$c->namespace`. Like `detach`,
`go` escapes the processing of the current request chain on completion, and
-does not return to its cunless blessed $cunless blessed $caller.
+does not return to its caller.
@arguments are arguments to the final destination of $action. @captures are
arguments to the intermediate steps, if any, on the way to the final sub of
Note that << $c->state >> operates in a scalar context which means that all
values it returns are scalar.
+Please note that if an action throws an exception, the value of state
+should no longer be considered the return if the last action. It is generally
+going to be 0, which indicates an error state. Examine $c->error for error
+details.
+
## $c->clear\_errors
Clear errors. You probably don't want to clear the errors unless you are
## $c->last\_error
Returns the most recent error in the stack (the one most recently added...)
-or nothing if there are no errors.
+or nothing if there are no errors. This does not modify the contents of the
+error stack.
## shift\_errors
-shifts the most recently added error off the error stack and returns if. Returns
+shifts the most recently added error off the error stack and returns it. Returns
+nothing if there are no more errors.
+
+## pop\_errors
+
+pops the most recently added error off the error stack and returns it. Returns
nothing if there are no more errors.
## COMPONENT ACCESSORS
## do stuff here..
};
-## $c->uri\_for( $path?, @args?, \\%query\_values? )
+## $c->uri\_for( $path?, @args?, \\%query\_values?, \\$fragment? )
-## $c->uri\_for( $action, \\@captures?, @args?, \\%query\_values? )
+## $c->uri\_for( $action, \\@captures?, @args?, \\%query\_values?, \\$fragment? )
-## $c->uri\_for( $action, \[@captures, @args\], \\%query\_values? )
+## $c->uri\_for( $action, \[@captures, @args\], \\%query\_values?, \\$fragment? )
Constructs an absolute [URI](https://metacpan.org/pod/URI) object based on the application root, the
provided path, and the additional arguments and query parameters provided.
`$c->request->base`; any `@args` are appended as additional path
components; and any `%query_values` are appended as `?foo=bar` parameters.
+**NOTE** If you are using this 'stringy' first argument, we skip encoding and
+allow you to declare something like:
+
+ $c->uri_for('/foo/bar#baz')
+
+Where 'baz' is a URI fragment. We consider this first argument string to be
+'expert' mode where you are expected to create a valid URL and we for the most
+part just pass it through without a lot of internal effort to escape and encode.
+
If the first argument is a [Catalyst::Action](https://metacpan.org/pod/Catalyst::Action) it represents an action which
will have its path resolved using `$c->dispatcher->uri_for_action`. The
optional `\@captures` argument (an arrayref) allows passing the captured
- \\@captures\_and\_args?
- Optional array reference of Captures (i.e. `<CaptureArgs or $c-`req->captures>)
+ Optional array reference of Captures (i.e. `CaptureArgs` or `$c->req->captures`)
and arguments to the request. Usually used with [Catalyst::DispatchType::Chained](https://metacpan.org/pod/Catalyst::DispatchType::Chained)
to interpolate all the parameters in the URI.
## $app->request\_class\_traits
-An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the request class.
+An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the request class. You can
+name the full namespace of the role, or a namespace suffix, which will then
+be tried against the following standard namespace prefixes.
+
+ $MyApp::TraitFor::Request::$trait_suffix
+ Catalyst::TraitFor::Request::$trait_suffix
+
+So for example if you set:
+
+ MyApp->request_class_traits(['Foo']);
+
+We try each possible role in turn (and throw an error if none load)
+
+ Foo
+ MyApp::TraitFor::Request::Foo
+ Catalyst::TraitFor::Request::Foo
+
+The namespace part 'TraitFor::Request' was chosen to assist in backwards
+compatibility with [CatalystX::RoleApplicator](https://metacpan.org/pod/CatalystX::RoleApplicator) which previously provided
+these features in a stand alone package.
## $app->composed\_request\_class
## $app->response\_class\_traits
-An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the response class.
+An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s which are applied to the response class. You can
+name the full namespace of the role, or a namespace suffix, which will then
+be tried against the following standard namespace prefixes.
+
+ $MyApp::TraitFor::Response::$trait_suffix
+ Catalyst::TraitFor::Response::$trait_suffix
+
+So for example if you set:
+
+ MyApp->response_class_traits(['Foo']);
+
+We try each possible role in turn (and throw an error if none load)
+
+ Foo
+ MyApp::TraitFor::Response::Foo
+ Catalyst::TraitFor::Responset::Foo
+
+The namespace part 'TraitFor::Response' was chosen to assist in backwards
+compatibility with [CatalystX::RoleApplicator](https://metacpan.org/pod/CatalystX::RoleApplicator) which previously provided
+these features in a stand alone package.
## $app->composed\_response\_class
my $config = MyApp->config_for('MyApp::Model::Foo');
-In this case $config is the hashref ` {a=`1, b=>2} >.
+In this case $config is the hashref `{a=>1, b=>2}`.
This is also handy for looking up configuration for a plugin, to make sure you follow
existing [Catalyst](https://metacpan.org/pod/Catalyst) standards for where a plugin should put its configuration.
## handle\_unicode\_encoding\_exception
-Hook to let you customize how encoding errors are handled. By default
-we just throw an exception. Receives a hashref of debug information.
-Example:
+Hook to let you customize how encoding errors are handled. By default
+we just throw an exception and the default error page will pick it up.
+Receives a hashref of debug information. Example of call (from the
+Catalyst internals):
- $c->handle_unicode_encoding_exception({
- param_value => $value,
- error_msg => $_,
- encoding_step => 'params',
- });
+ my $decoded_after_fail = $c->handle_unicode_encoding_exception({
+ param_value => $value,
+ error_msg => $_,
+ encoding_step => 'params',
+ });
+
+The calling code expects to receive a decoded string or an exception.
+
+You can override this for custom handling of unicode errors. By
+default we just die. If you want a custom response here, one approach
+is to throw an HTTP style exception, instead of returning a decoded
+string or throwing a generic exception.
+
+ sub handle_unicode_encoding_exception {
+ my ($c, $params) = @_;
+ HTTP::Exception::BAD_REQUEST->throw(status_message=>$params->{error_msg});
+ }
+
+Alternatively you can 'catch' the error, stash it and write handling code later
+in your application:
+
+ sub handle_unicode_encoding_exception {
+ my ($c, $params) = @_;
+ $c->stash(BAD_UNICODE_DATA=>$params);
+ # return a dummy string.
+ return 1;
+ }
+
+<B>NOTE:</b> Please keep in mind that once an error like this occurs,
+the request setup is still ongoing, which means the state of `$c` and
+related context parts like the request and response may not be setup
+up correctly (since we haven't finished the setup yet). If you throw
+an exception the setup is aborted.
## $c->setup\_log
[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.
The 'application/json' data handler is used to parse incoming JSON into a Perl
-data structure. It used either [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS) or [JSON](https://metacpan.org/pod/JSON), depending on which
-is installed. This allows you to fail back to [JSON:PP](JSON:PP), which is a Pure Perl
-JSON decoder, and has the smallest dependency impact.
+data structure. It uses [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS). This allows you to fail back to
+[JSON::PP](https://metacpan.org/pod/JSON::PP), which is a Pure Perl JSON decoder, and has the smallest dependency
+impact.
Because we don't wish to add more dependencies to [Catalyst](https://metacpan.org/pod/Catalyst), if you wish to
-use this new feature we recommend installing [JSON](https://metacpan.org/pod/JSON) or [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS) in
-order to get the best performance. You should add either to your dependency
-list (Makefile.PL, dist.ini, cpanfile, etc.)
+use this new feature we recommend installing [Cpanel::JSON::XS](https://metacpan.org/pod/Cpanel::JSON::XS) in order to get
+the best performance. You should add either to your dependency list
+(Makefile.PL, dist.ini, cpanfile, etc.)
## $c->stack
[stats\_class](#c-stats_class).
Even if [-Stats](#stats) is not enabled, the stats object is still
-available. By enabling it with ` $c-`stats->enabled(1) >, it can be used to
+available. By enabling it with `$c->stats->enabled(1)`, it can be used to
profile explicitly, although MyApp.pm still won't profile nor output anything
by itself.
## $app->composed\_stats\_class
-this is the stats\_class composed with any 'stats\_class\_traits'.
+this is the stats\_class composed with any 'stats\_class\_traits'. You can
+name the full namespace of the role, or a namespace suffix, which will then
+be tried against the following standard namespace prefixes.
+
+ $MyApp::TraitFor::Stats::$trait_suffix
+ Catalyst::TraitFor::Stats::$trait_suffix
+
+So for example if you set:
+
+ MyApp->stats_class_traits(['Foo']);
+
+We try each possible role in turn (and throw an error if none load)
+
+ Foo
+ MyApp::TraitFor::Stats::Foo
+ Catalyst::TraitFor::Stats::Foo
+
+The namespace part 'TraitFor::Stats' was chosen to assist in backwards
+compatibility with [CatalystX::RoleApplicator](https://metacpan.org/pod/CatalystX::RoleApplicator) which previously provided
+these features in a stand alone package.
## $c->use\_stats
decoded, this means that applications using this mode can correctly handle URIs including the %2F character
(i.e. with `AllowEncodedSlashes` set to `On` in Apache).
- Given that this method of path resolution is probably more correct, it is recommended that you use
+ Given that this method of path resolution is provably more correct, it is recommended that you use
this unless you have a specific need to deploy your application in a non-standard environment, and you are
aware of the implications of not being able to handle encoded URI paths correctly.
- `using_frontend_proxy_path` - Enabled [Plack::Middleware::ReverseProxyPath](https://metacpan.org/pod/Plack::Middleware::ReverseProxyPath) on your application (if
installed, otherwise log an error). This is useful if your application is not running on the
'root' (or /) of your host server. **NOTE** if you use this feature you should add the required
-middleware to your project dependency list since it's not automatically a dependency of [Catalyst](https://metacpan.org/pod/Catalyst).
+middleware to your project dependency list since its not automatically a dependency of [Catalyst](https://metacpan.org/pod/Catalyst).
This has been done since not all people need this feature and we wish to restrict the growth of
[Catalyst](https://metacpan.org/pod/Catalyst) dependencies.
- `encoding` - See ["ENCODING"](#encoding)
- `abort_chain_on_error_fix`
- When there is an error in an action chain, the default behavior is to continue
- processing the remaining actions and then catch the error upon chain end. This
- can lead to running actions when the application is in an unexpected state. If
- you have this issue, setting this config value to true will promptly exit a
- chain when there is an error raised in any action (thus terminating the chain
- early.)
+ Defaults to true.
+
+ When there is an error in an action chain, the default behavior is to
+ abort the processing of the remaining actions to avoid running them
+ when the application is in an unexpected state.
- use like:
+ Before version 5.90070, the default used to be false. To keep the old
+ behaviour, you can explicitly set the value to false. E.g.
- __PACKAGE__->config(abort_chain_on_error_fix => 1);
+ __PACKAGE__->config(abort_chain_on_error_fix => 0);
- In the future this might become the default behavior.
+ If this setting is set to false, then the remaining actions are
+ performed and the error is caught at the end of the chain.
- `use_hash_multivalue_in_request`
in Catalyst version 5.90080+ break some of your query code, you may disable
the UTF-8 decoding globally using this configuration.
- This setting takes precedence over `default_query_encoding` and
- `decode_query_using_global_encoding`
+ This setting takes precedence over `default_query_encoding`
+
+- `do_not_check_query_encoding`
+
+ Catalyst versions 5.90080 - 5.90106 would decode query parts of an incoming
+ request but would not raise an exception when the decoding failed due to
+ incorrect unicode. It now does, but if this change is giving you trouble
+ you may disable it by setting this configuration to true.
- `default_query_encoding`
specify a fixed value for how to decode your query. You might need this if
you are doing a lot of custom encoding of your URLs and not using UTF-8.
- This setting take precedence over `decode_query_using_global_encoding`.
-
-- `decode_query_using_global_encoding`
-
- Setting this to true will default your query decoding to whatever your
- general global encoding is (the default is UTF-8).
-
- `use_chained_args_0_special_case`
In older versions of Catalyst, when more than one action matched the same path
package MyApp::Web;
use Catalyst;
- use JSON::Maybe;
+ use JSON::MaybeXS;
__PACKAGE__->config(
data_handlers => {
__PACKAGE__->setup;
By default [Catalyst](https://metacpan.org/pod/Catalyst) comes with a generic JSON data handler similar to the
-example given above, which uses [JSON::Maybe](https://metacpan.org/pod/JSON::Maybe) to provide either [JSON::PP](https://metacpan.org/pod/JSON::PP)
+example given above, which uses [JSON::MaybeXS](https://metacpan.org/pod/JSON::MaybeXS) to provide either [JSON::PP](https://metacpan.org/pod/JSON::PP)
(a pure Perl, dependency free JSON parser) or [Cpanel::JSON::XS](https://metacpan.org/pod/Cpanel::JSON::XS) if you have
it installed (if you want the faster XS parser, add it to you project Makefile.PL
or dist.ini, cpanfile, etc.)
This is recommended for temporary backwards compatibility only.
+To turn it off for a single request use the [clear\_encoding](https://metacpan.org/pod/clear_encoding)
+method to turn off encoding for this request. This can be useful
+when you are setting the body to be an arbitrary block of bytes,
+especially if that block happens to be a block of UTF8 text.
+
Encoding is automatically applied when the content-type is set to
a type that can be encoded. Currently we encode when the content type
matches the following regular expression:
chicks: Christopher Hicks
-Chisel Wright `pause@herlpacker.co.uk`
+Chisel Wright <pause@herlpacker.co.uk>
-Danijel Milicevic `me@danijel.de`
+Danijel Milicevic <me@danijel.de>
davewood: David Schmidt <davewood@cpan.org>
David Kamholz <dkamholz@cpan.org>
-David Naughton, `naughton@umn.edu`
+David Naughton <naughton@umn.edu>
David E. Wheeler
Gary Ashton Jones
-Gavin Henry `ghenry@perl.me.uk`
+Gavin Henry <ghenry@perl.me.uk>
Geoff Richards
jcamacho: Juan Camacho
-jester: Jesse Sheidlower `jester@panix.com`
+jester: Jesse Sheidlower <jester@panix.com>
jhannah: Jay Hannah <jay@jays.net>
jon: Jon Schutz <jjschutz@cpan.org>
-Jonathan Rockway `<jrockway@cpan.org>`
+Jonathan Rockway <jrockway@cpan.org>
-Kieren Diment `kd@totaldatasolution.com`
+Kieren Diment <kd@totaldatasolution.com>
konobi: Scott McWhirter <konobi@cpan.org>
marcus: Marcus Ramberg <mramberg@cpan.org>
-Mischa Spiegelmock <revmischa@cpan.org>
-
miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
mgrimes: Mark Grimes <mgrimes@cpan.org>
random: Roland Lammel <lammel@cpan.org>
-Robert Sedlacek `<rs@474.at>`
+revmischa: Mischa Spiegelmock <revmischa@cpan.org>
+
+Robert Sedlacek <rs@474.at>
SpiceMan: Marcel Montes
vanstyn: Henry Van Styn <vanstyn@cpan.org>
-Viljo Marrandi `vilts@yahoo.com`
+Viljo Marrandi <vilts@yahoo.com>
-Will Hawes `info@whawes.co.uk`
+Will Hawes <info@whawes.co.uk>
willert: Sebastian Willert <willert@cpan.org>
wreis: Wallace Reis <wreis@cpan.org>
-Yuval Kogman, `nothingmuch@woobling.org`
+Yuval Kogman <nothingmuch@woobling.org>
-rainboxx: Matthias Dietrich, `perl@rainboxx.de`
+rainboxx: Matthias Dietrich <perl@rainboxx.de>
dd070: Dhaval Dhanani <dhaval070@gmail.com>
projects / catagits/Catalyst-Runtime.git / blobdiff