X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=README.mkdn;h=6eec9eae5af45273e1afb98f321cc4ef9e853ac5;hp=7889225b4ad66d019d338461f282893aa0dce985;hb=8e322ed0b39da75b8d888025782f496ca781527f;hpb=68b4caec7950a4dc7ed003fe0e78f73baf81f9d3 diff --git a/README.mkdn b/README.mkdn index 7889225..6eec9ea 100644 --- a/README.mkdn +++ b/README.mkdn @@ -2,23 +2,11 @@ Catalyst - The Elegant MVC Web Application Framework -
- - CPAN version - Catalyst></a> - <a href=Kwalitee Score -
- # 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 @@ -296,7 +284,7 @@ the relationship between `$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 @@ -362,6 +350,11 @@ Contains the return value of the last executed action. 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 @@ -378,11 +371,17 @@ Returns true if you have errors ## $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 @@ -637,11 +636,11 @@ Example: ## 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. @@ -659,6 +658,15 @@ relative to the application root (if it does). It is then merged with `$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 @@ -719,7 +727,7 @@ constraints. - \\@captures\_and\_args? - Optional array reference of Captures (i.e. `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. @@ -976,7 +984,26 @@ Returns or sets the request class. Defaults to [Catalyst::Request](https://metac ## $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 @@ -988,7 +1015,26 @@ Returns or sets the response class. Defaults to [Catalyst::Response](https://met ## $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 @@ -1114,7 +1160,7 @@ component or component object. Example: 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. @@ -1191,15 +1237,44 @@ Sets up the input/output encoding. See [ENCODING](https://metacpan.org/pod/ENCOD ## 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; + } + +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 @@ -1330,14 +1405,14 @@ only two default data handlers, for 'application/json' and an alternative to [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 @@ -1351,7 +1426,7 @@ Returns the current timing statistics object. By default Catalyst uses [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. @@ -1365,7 +1440,26 @@ A arrayref of [Moose::Role](https://metacpan.org/pod/Moose::Role)s that are appl ## $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 @@ -1445,7 +1539,7 @@ variable should be used for determining the request path. 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. @@ -1459,7 +1553,7 @@ variable should be used for determining the request path. - `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) @@ -1469,18 +1563,19 @@ This has been done since not all people need this feature and we wish to restric - `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` @@ -1527,8 +1622,14 @@ This has been done since not all people need this feature and we wish to restric 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` @@ -1537,13 +1638,6 @@ This has been done since not all people need this feature and we wish to restric 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 @@ -1722,7 +1816,7 @@ that parses that content type into something Perl can readily access. package MyApp::Web; use Catalyst; - use JSON::Maybe; + use JSON::MaybeXS; __PACKAGE__->config( data_handlers => { @@ -1734,7 +1828,7 @@ that parses that content type into something Perl can readily access. __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.) @@ -1904,6 +1998,11 @@ the encoding configuration to undef. 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: @@ -2036,15 +2135,15 @@ Chase Venters chicks: Christopher Hicks -Chisel Wright `pause@herlpacker.co.uk` +Chisel Wright -Danijel Milicevic `me@danijel.de` +Danijel Milicevic davewood: David Schmidt David Kamholz -David Naughton, `naughton@umn.edu` +David Naughton David E. Wheeler @@ -2066,7 +2165,7 @@ gabb: Danijel Milicevic Gary Ashton Jones -Gavin Henry `ghenry@perl.me.uk` +Gavin Henry Geoff Richards @@ -2078,7 +2177,7 @@ ilmari: Dagfinn Ilmari Mannsåker jcamacho: Juan Camacho -jester: Jesse Sheidlower `jester@panix.com` +jester: Jesse Sheidlower jhannah: Jay Hannah @@ -2088,16 +2187,14 @@ Johan Lindstrom jon: Jon Schutz -Jonathan Rockway `` +Jonathan Rockway -Kieren Diment `kd@totaldatasolution.com` +Kieren Diment konobi: Scott McWhirter marcus: Marcus Ramberg -Mischa Spiegelmock - miyagawa: Tatsuhiko Miyagawa mgrimes: Mark Grimes @@ -2128,7 +2225,9 @@ rafl: Florian Ragwitz random: Roland Lammel -Robert Sedlacek `` +revmischa: Mischa Spiegelmock + +Robert Sedlacek SpiceMan: Marcel Montes @@ -2142,17 +2241,17 @@ Ulf Edvinsson vanstyn: Henry Van Styn -Viljo Marrandi `vilts@yahoo.com` +Viljo Marrandi -Will Hawes `info@whawes.co.uk` +Will Hawes willert: Sebastian Willert wreis: Wallace Reis -Yuval Kogman, `nothingmuch@woobling.org` +Yuval Kogman -rainboxx: Matthias Dietrich, `perl@rainboxx.de` +rainboxx: Matthias Dietrich dd070: Dhaval Dhanani