Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
+=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.
+
+=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<Catalyst>.
+
+For further information, please see L<Catalyst::UTF8>
+
+A number of projects in the wider ecosystem required minor updates to be able
+to work correctly. Here's the known list:
+
+L<Catalyst::View::TT>, L<Catalyst::View::Mason>, L<Catalyst::View::HTML::Mason>,
+L<Catalyst::View::Xslate>, L<Test::WWW::Mechanize::Catalyst>
+
+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<Catalyst::DispatchType::Regex> 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<Catalyst> 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
Please note that this is different from the old stand alone plugin which applied
C<UTF-8> encoding by default (that is, if you did not set an explicit
-C<encoding> configuration value, it assumed you wanted UTF-8). In order to
+C<encoding> 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
we detect this, but this backwards compatibility shim will likely be removed in
a few releases (trying to clean up the codebase after all).
-B<NOTE>: One other difference between the cored plugin and the stand alone one
-is that in core we no longer throw an exception when there's a decode failure
-but instead log a warning. If you rely on exceptions for control flow, you
-will need to override method C<handle_unicode_encoding_exception> to die instead
-of warning. Please let the dev team know if this is a problem for you.
-
If you have trouble with any of this, please bring it to the attention of the
Catalyst maintainer group.
The engines that are built upon the various iterations of mod_perl,
L<Catalyst::Engine::Apache::MP13> (for mod_perl 1, and Apache 1.x) and
L<Catalyst::Engine::Apache2::MP20> (for mod_perl 2, and Apache 2.x),
-should be seamless upgrades and will work using using L<Plack::Handler::Apache1>
+should be seamless upgrades and will work using L<Plack::Handler::Apache1>
or L<Plack::Handler::Apache2> as required.
L<Catalyst::Engine::Apache2::MP19>, however, is no longer supported, as
Having actions in your application class will now emit a warning at application
startup as this is deprecated. It is highly recommended that these actions are moved
into a MyApp::Controller::Root (as demonstrated by the scaffold application
-generated by catalyst.pl).
+generated by catalyst.pl).
This warning, also affects tests. You should move actions in your test,
creating a myTest::Controller::Root, like the following example:
sub action : Local {
my ( $self, $c ) = @_;
- $c->do_something;
+ $c->do_something;
}
1;
projects / catagits/Catalyst-Runtime.git / blobdiff