X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=lib%2FCatalyst%2FUpgrading.pod;h=1c9de4977101631518d027beeb566254cf6af8b2;hp=e210bbb55bfbc13ea9b2030c5755112d037e38b3;hb=79fb8f95180a06c51de7f0fde227927b5d864a7f;hpb=6cf77e11ef210219fbbe19df5f5b7cd7c84f501c diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod index e210bbb..1c9de49 100644 --- a/lib/Catalyst/Upgrading.pod +++ b/lib/Catalyst/Upgrading.pod @@ -2,6 +2,156 @@ Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst +=head1 Upgrading to Catalyst 5.90100 + +We changed the way the middleware stash works so that it no longer localizes +the PSGI env hashref. This was done to fix bugs where people set PSGI ENV hash +keys and found them to disappear in certain cases. It also means that now if +a sub applications sets stash variables, that stash will now bubble up to the +parent application. This may be a breaking change for you since previous +versions of this code did not allow that. A workaround is to explicitly delete +stash keys in your sub application before returning control to the parent +application. + +=head1 Upgrading to Catalyst 5.90097 + +In older versions of Catalyst one could construct a L with a fragment (such as +https://localhost/foo/bar#fragment) by using a '#' in the path or final argument, for +example: + + $c->uri_for($action, 'foo#fragment'); + +This behavior was never documented and would break if using the Unicode plugin, or when +adding a query to the arguments: + + $c->uri_for($action, 'foo#fragment', +{ a=>1, b=>2}); + +would define a fragment like "#fragment?a=1&b=2". + +When we introduced UTF-8 encoding by default in Catalyst 5.9008x this side effect behavior +was broken since we started encoding the '#' when it was part of the URI path. + +In version 5.90095 and 5.90096 we attempted to fix this, but all we managed to do was break +people with URIs that included '#' as part of the path data, when it was not expected to +be a fragment delimiter. + +In general L prefers an explicit specification rather than relying on side effects +or domain specific mini languages. As a result we are now defining how to set a fragment +for a URI via ->uri_for: + + $c->uri_for($action_or_path, \@captures_or_args, @args, \$query, \$fragment); + +If you are relying on the previous side effect behavior your URLs will now encode the '#' +delimiter, which is going to be a breaking change for you. You need to alter your code +to match the new specification or modify uri_for for your local case. Patches to solve +this are very welcomed, as long as they don't break existing test cases. + +B If you are using the string form of the first argument: + + $c->uri_for('/foo/bar#baz') + +construction, we do not attempt to encode this and it will make a URL with a +fragment of 'baz'. + + +=head1 Upgrading to Catalyst 5.90095 + +The method C in L was actually returning the first error. This has +been fixed but there is a small chance it could be a breaking issue for you. If this gives +you trouble changing to C is the easiest workaround (although that does +modify the error stack so if you are relying on that not being changed you should try something +like @{$c->errors}[-1] instead. Since this method is relatively new and the cases when the +error stack actually has more than one error in it, we feel the exposure is very low, but bug +reports are very welcomed. + +=head1 Upgrading to Catalyst 5.90090 + +L has a new method 'inject_component' which works the same as the method of +the same name in L. You should start converting any +use of the non core method in your code as future changes to Catalyst will be +synchronized to the core method first. We reserve the right to cease support +of the non core version should we reach a point in time where it cannot be +properly supported as an external module. Luckily this should be a trivial +search and replace. Change all occurences of: + + CatalystX::InjectComponent->inject(...) + +Into + + Catalyst::Utils::inject_component(...) + +and we expect everything to work the same (we'd consider it not working the same +to be a bug, and please report it.) + +We also cored features from L to compose a role into the +request, response and stats classes. The main difference is that with L +you did: + + package MyApp; + + use Catalyst; + use CatalystX::RoleApplicator; + + __PACKAGE__->apply_request_class_roles( + qw/My::Request::Role Other::Request::Role/); + +Whereas now we have three class attributes, 'request_class_traits', 'response_class_traits' +and 'stats_class_traits', so you use like this (note this value is an ArrayRef) + + + package MyApp; + + use Catalyst; + + __PACKAGE__->request_class_traits([qw/ + My::Request::Role + Other::Request::Role/]); + +(And the same for response_class_traits and stats_class_traits. We left off the +traits for Engine, since that class does a lot less nowadays, and dispatcher. If you +used those and can share a use case, we'd be likely to support them. + +Lastly, we have some of the feature from L in +core. This should mostly work the same way in core, except for now the +core version does not create an automatic base wrapper class for your configured +components (it requires these to be catalyst components and injects them directly. +So if you make heavy use of custom base classes in L +you might need a bit of work to use the core version (although there is no reason +to stop using L since it should continue to work +fine and we'd consider issues with it to be bugs). Here's one way to map from +L to core: + +In L: + + MyApp->config( + 'Model::MyClass' => { + class => 'MyClass', + args => { %args }, + + }); + +and now in core: + + MyApp->config( + inject_components => { + 'Model::MyClass' => { from_component => 'My::Class' }, + }, + 'Model::MyClass' => { + %args + }, + ); + +Although the core behavior requires more code, it better separates concerns +as well as plays more into core Catalyst expectations of how configuration should +look. + +Also we added a new develop console mode only warning when you call a component +with arguments that don't expect or do anything meaningful with those args. Its +possible if you are logging debug mode in production (please don't...) this +could add verbosity to those logs if you also happen to be calling for components +and passing pointless arguments. We added this warning to help people not make this +error and to better understand the component resolution flow. + =head1 Upgrading to Catalyst 5.90085 In this version of Catalyst we made a small change to Chained Dispatching so @@ -68,16 +218,16 @@ that will revert you code to the previous behavior. =head2 More backwards compatibility options with UTF-8 changes -In order to give better backwards compatiblity with the 5.90080+ UTF-8 changes +In order to give better backwards compatibility with the 5.90080+ UTF-8 changes we've added several configuration options around control of how we try to decode your URL keywords / query parameters. C 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 L -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. @@ -88,7 +238,7 @@ C C 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.