view release on metacpan or  search on metacpan

lib/Catalyst/Upgrading.pod  view on Meta::CPAN

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<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 relevant specifications
suggest these should be UTF-* encoded, which is the default that L<Catalyst>
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<default_query_encoding> and
C<decode_query_using_global_encoding>

C<default_query_encoding>

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<decode_query_using_global_encoding>.

C<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).


=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

The previously stand alone Unicode support module L<Catalyst::Plugin::Unicode::Encoding>
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<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
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