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=56a525824d98adf0cdf7c5965ad49f14400382f3;hb=79fb8f95180a06c51de7f0fde227927b5d864a7f;hpb=24fd6115b56f34b5d91a1b9386c7864fba66ab4d diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod index 56a5258..1c9de49 100644 --- a/lib/Catalyst/Upgrading.pod +++ b/lib/Catalyst/Upgrading.pod @@ -2,50 +2,406 @@ Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst -=head1 Upgrading to Catalyst 5.90 - -The major change is that L now replaces most of the subclasses of -L. If you are using one of the standard subclasses of -L this should be a straightforward upgrade for you. It was -a design goal for this release to be as backwardly compatible as possible. -However since L is different from L it would be -possible that edge case differences would exist. Therefore we recommend care -be taken with this upgrade and that testing should be greater than would be -the case with a minor point update. - -It is highly recommended that you become familar with the L ecosystem +=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 +that when two or more actions all have the same path specification AND they +all have Args(0), we break the tie by choosing the last action defined, and +not the first one defined. This was done to normalize Chaining to following +the 'longest Path wins, and when several actions match the same Path specification +we choose the last defined.' rule. Previously Args(0) was hard coded to be a special +case such that the first action defined would match (which is not the case when +Args is not zero.) + +Its possible that this could be a breaking change for you, if you had used +action roles (custom or otherwise) to add additional matching rules to differentiate +between several Args(0) actions that share the same root action chain. For +example if you have code now like this: + + sub check_default :Chained(/) CaptureArgs(0) { ... } + + sub default_get :Chained('check_default') PathPart('') Args(0) GET { + pop->res->body('get3'); + } + + sub default_post :Chained('check_default') PathPart('') Args(0) POST { + pop->res->body('post3'); + } + + sub chain_default :Chained('check_default') PathPart('') Args(0) { + pop->res->body('chain_default'); + } + +The way that chaining will work previous is that when two or more equal actions can +match, the 'top' one wins. So if the request is "GET .../check_default" BOTH +actions 'default_get' AND 'chain_default' would match. To break the tie in +the case when Args is 0, we'd previous take the 'top' (or first defined) action. +Unfortunately this treatment of Args(0) is special case. In all other cases +we choose the 'last defined' action to break a tie. So this version of +Catalyst changed the dispatcher to make Args(0) no longer a special case for +breaking ties. This means that the above code must now become: + + sub check_default :Chained(/) CaptureArgs(0) { ... } + + sub chain_default :Chained('check_default') PathPart('') Args(0) { + pop->res->body('chain_default'); + } + + sub default_get :Chained('check_default') PathPart('') Args(0) GET { + pop->res->body('get3'); + } + + sub default_post :Chained('check_default') PathPart('') Args(0) POST { + pop->res->body('post3'); + } + +If we want it to work as expected (for example we we GET to match 'default_get' and +POST to match 'default_post' and any other http Method to match 'chain_default'). + +In other words Arg(0) and chained actions must now follow the normal rule where +in a tie the last defined action wins and you should place all your less defined +or 'catch all' actions first. + +If this causes you trouble and you can't fix your code to conform, you may set the +application configuration setting "use_chained_args_0_special_case" to true and +that will revert you code to the previous behavior. + +=head2 More backwards compatibility options with 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 relevant specifications +suggest these should be UTF-* encoded, which is the default that L +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 C and +C + +C + +By default we decode query and keywords in your request URL using UTF-8, which +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 C. + +C + +Setting this to true will default your query decoding to whatever your +general global encoding is (the default is UTF-8). + + +=head1 Upgrading to Catalyst 5.90080 + +UTF8 encoding is now default. For temporary backwards compatibility, if this +change is causing you trouble, you can disable it by setting the application +configuration option to undef: + + MyApp->config(encoding => undef); + +But please consider this a temporary measure since it is the intention that +UTF8 is enabled going forwards and the expectation is that other ecosystem +projects will assume this as well. At some point you application will not +correctly function without this setting. + +As of 5.90084 we've added two additional configuration flags for more selective +control over some encoding changes: 'skip_body_param_unicode_decoding' and +'skip_complex_post_part_handling'. You may use these to more selectively +disable new features while you are seeking a long term fix. Please review +CONFIGURATION in L. + +For further information, please see L + +A number of projects in the wider ecosystem required minor updates to be able +to work correctly. Here's the known list: + +L, L, L, +L, L + +You will need to update to modern versions in most cases, although quite a few +of these only needed minor test case and documentation changes so you will need +to review the changelog of each one that is relevant to you to determine your +true upgrade needs. + +=head1 Upgrading to Catalyst 5.90060 + +Starting in the v5.90059_001 development release, the regexp dispatch type is +no longer automatically included as a dependency. If you are still using this +dispatch type, you need to add L into your build +system. + +The standalone distribution of Regexp will be supported for the time being, but +should we find that supporting it prevents us from moving L forward +in necessary ways, we reserve the right to drop that support. It is highly +recommended that you use this last stage of deprecation to change your code. + +=head1 Upgrading to Catalyst 5.90040 + +=head2 Catalyst::Plugin::Unicode::Encoding is now core + +The previously stand alone Unicode support module L +has been brought into core as a default plugin. Going forward, all you need is +to add a configuration setting for the encoding type. For example: + + package Myapp::Web; + + use Catalyst; + + __PACKAGE__->config( encoding => 'UTF-8' ); + +Please note that this is different from the old stand alone plugin which applied +C encoding by default (that is, if you did not set an explicit +C configuration value, it assumed you wanted UTF-8). In order to +preserve backwards compatibility you will need to explicitly turn it on via the +configuration setting. THIS MIGHT CHANGE IN THE FUTURE, so please consider +starting to test your application with proper UTF-8 support and remove all those +crappy hacks you munged into the code because you didn't know the Plugin +existed :) + +For people that are using the Plugin, you will note a startup warning suggesting +that you can remove it from the plugin list. When you do so, please remember to +add the configuration setting, since you can no longer rely on the default being +UTF-8. We'll add it for you if you continue to use the stand alone plugin and +we detect this, but this backwards compatibility shim will likely be removed in +a few releases (trying to clean up the codebase after all). + +If you have trouble with any of this, please bring it to the attention of the +Catalyst maintainer group. + +=head2 basic async and event loop support + +This version of L offers some support for using L and +L event loops in your application. These changes should work +fine for most applications however if you are already trying to perform +some streaming, minor changes in this area of the code might affect your +functionality. Please see L for more and for a +basic example. + +We consider this feature experimental. We will try not to break it, but we +reserve the right to make necessary changes to fix major issues that people +run into when the use this functionality in the wild. + +=head1 Upgrading to Catalyst 5.90030 + +=head2 Regex dispatch type is deprecated. + +The Regex dispatchtype (L) has been deprecated. + +You are encouraged to move your application to Chained dispatch (L). + +If you cannot do so, please add a dependency to Catalyst::DispatchType::Regex to your application's +Makefile.PL + +=head1 Upgrading to Catalyst 5.9 + +The major change is that L, a toolkit for using the L +specification, now replaces most of the subclasses of L. If +you are using one of the standard subclasses of L this +should be a straightforward upgrade for you. It was a design goal for +this release to preserve as much backwards compatibility as possible. +However, since L is different from L, it is +possible that differences exist for edge cases. Therefore, we recommend +that care be taken with this upgrade and that testing should be greater +than would be the case with a minor point update. Please inform the +Catalyst developers of any problems so that we can fix them and +incorporate tests. + +It is highly recommended that you become familiar with the L ecosystem and documentation. Being able to take advantage of L development and middleware is a major bonus to this upgrade. Documentation about how to take advantage of L by writing your own C<< .psgi >> file is contained in L. -If you have created a custom subclass of L you will need to -convert it to be a subclass of L. +If you have created a custom subclass of L, you will +need to convert it to be a subclass of L. If you are using the L engine, L, this new -release supercedes that code. +release supersedes that code. -If you are using a subclass of L that is aimed at nonstandard -or internal / testing uses, such as L you should -still be able to continue using that engine. +If you are using a subclass of L that is aimed at +nonstandard or internal/testing uses, such as +L, you should still be able to continue +using that engine. Advice for specific subclasses of L follows: =head2 Upgrading the FastCGI Engine -No upgrade needed if your myapp_fastcgi.pl script is already upgraded -enough to use L. +No upgrade is needed if your myapp_fastcgi.pl script is already upgraded +to use L. =head2 Upgrading the mod_perl / Apache Engines -The engines that are build upon the various iterations of mod_perl, -L and -L should be seemless upgrades and will -work using using L or L -as required. +The engines that are built upon the various iterations of mod_perl, +L (for mod_perl 1, and Apache 1.x) and +L (for mod_perl 2, and Apache 2.x), +should be seamless upgrades and will work using L +or L as required. -L, is however no longer supported, as Plack -does not support mod_perl version 1.99 +L, however, is no longer supported, as +Plack does not support mod_perl version 1.99. This is unlikely to be a +problem for anyone, as 1.99 was a brief beta-test release for mod_perl +2, and all users of mod_perl 1.99 are encouraged to upgrade to a +supported release of Apache 2 and mod_perl 2. =head2 Upgrading the HTTP Engine @@ -56,34 +412,53 @@ script is upgraded to use L. =head2 Upgrading the CGI Engine If you were using L there is no upgrade needed if your -myapp_cgi.pl script is already upgraded enough to use L. +myapp_cgi.pl script is already upgraded to use L. -=head2 Upgrading the Preforking Engine +=head2 Upgrading Catalyst::Engine::HTTP::Prefork If you were using L then L -is automatically loaded. +is automatically loaded. You should (at least) change your C +to depend on Starman. -If you were customising your server script to pass opttions to the prefork engine, -then this is no longer supported. The recommended route to implement this functionality -is to write a simple .psgi file for your application, then use the L untility. +You can regenerate your C script with C +and implement a C class that looks like this: + + package MyApp::Script::Server; + use Moose; + use namespace::autoclean; + + extends 'CatalystX::Script::Server::Starman'; + + 1; + +This takes advantage of the new script system, and will add a number of +options to the standard server script as extra options are added by +Starman. + +More information about these options can be seen at +L. + +An alternate route to implement this functionality is to write a simple .psgi +file for your application, and then use the L utility to start the +server. =head2 Upgrading the PSGI Engine -If you were using L this new release supercedes this -engine in supporting L. By default the Engine is now always L. -As a result, you can stop depending on L in your -C. +If you were using L, this new release supersedes +this engine in supporting L. By default the Engine is now always +L. As a result, you can remove the dependency on +L in your C. Applications that were using L previously should entirely continue to work in this release with no changes. -However, if you have an C script, then you no longer -need to specify the PSGI engine. Instead, the L application class -now has a new method C which returns a L compatible coderef -which you can wrap in middleware of your choice. +However, if you have an C script, then you no longer need to +specify the PSGI engine. Instead, the L application class now +has a new method C which returns a L compatible coderef +which you can wrap in the middleware of your choice. Catalyst will use the .psgi for your application if it is located in the C -directory of the application +directory of the application. For example, if you were using L in the past, you will have written (or generated) a C