X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=README.mkdn;h=203d418278cd5b204d0e18636e4fa1fb50940a11;hp=f30025cae2efee41b0a6962a850e3e03a809d512;hb=807303a1658f895c41417beba24d24ff9b71c194;hpb=9e7f288e0bd785c69c8e54c77d951b2e878f5b8f diff --git a/README.mkdn b/README.mkdn index f30025c..203d418 100644 --- a/README.mkdn +++ b/README.mkdn @@ -2,13 +2,6 @@ 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 @@ -291,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 @@ -357,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 @@ -373,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 @@ -632,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. @@ -654,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 @@ -971,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 @@ -983,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 @@ -1186,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 @@ -1360,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 @@ -1464,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. - use like: + 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. - __PACKAGE__->config(abort_chain_on_error_fix => 1); + 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. - In the future this might become the default behavior. + __PACKAGE__->config(abort_chain_on_error_fix => 0); + + 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` @@ -1497,7 +1597,7 @@ This has been done since not all people need this feature and we wish to restric - `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 @@ -1515,30 +1615,29 @@ This has been done since not all people need this feature and we wish to restric - `do_not_decode_query` If true, then do not try to character decode any wide characters in your - request URL query or keywords. Most readings of the relevent specifications + 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 @@ -1553,15 +1652,15 @@ This has been done since not all people need this feature and we wish to restric - `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` @@ -1899,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: @@ -2009,7 +2113,7 @@ acme: Leon Brocard abraxxa: Alexander Hartmaier -andrewalker: André Walker +andrewalker: André Walker Andrew Bramble @@ -2027,6 +2131,8 @@ Caelum: Rafael Kitover chansen: Christian Hansen +Chase Venters `chase.venters@gmail.com` + chicks: Christopher Hicks Chisel Wright `pause@herlpacker.co.uk` @@ -2067,7 +2173,7 @@ groditi: Guillermo Roditi hobbs: Andrew Rodland -ilmari: Dagfinn Ilmari Mannsåker +ilmari: Dagfinn Ilmari MannsÃ¥ker jcamacho: Juan Camacho