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`
- `skip_complex_post_part_handling`
- When creating body parameters from a POST, if we run into a multpart POST
+ When creating body parameters from a POST, if we run into a multipart POST
that does not contain uploads, but instead contains inlined complex data
(very uncommon) we cannot reliably convert that into field => value pairs. So
instead we create an instance of [Catalyst::Request::PartData](https://metacpan.org/pod/Catalyst::Request::PartData). If this causes
If true, then do not try to character decode any wide characters in your
request URL query or keywords. Most readings of the relevant specifications
suggest these should be UTF-\* encoded, which is the default that [Catalyst](https://metacpan.org/pod/Catalyst)
- will use, hwoever if you are creating a lot of URLs manually or have external
+ will use, however if you are creating a lot of URLs manually or have external
evil clients, this might cause you trouble. If you find the changes introduced
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`
By default we decode query and keywords in your request URL using UTF-8, which
- is our reading of the relevent specifications. This setting allows one to
+ is our reading of the relevant specifications. This setting allows one to
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
- `data_handlers` - See ["DATA HANDLERS"](#data-handlers).
- `stats_class_traits`
- An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get componsed into your stats class.
+ An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get composed into your stats class.
- `request_class_traits`
- An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get componsed into your request class.
+ An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get composed into your request class.
- `response_class_traits`
- An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get componsed into your response class.
+ An arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that get composed into your response class.
- `inject_components`
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:
chansen: Christian Hansen
+Chase Venters <chase.venters@gmail.com>
+
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