Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
+=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
+Catalyst maintainer group.
+
+=head2 basic async and event loop support
+
+This version of L<Catalyst> offers some support for using L<AnyEvent> and
+L<IO::Async> 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<Catalyst::Response\write_fh> 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<Catalyst::DispatchType::Regex>) has been deprecated.
+
+You are encouraged to move your application to Chained dispatch (L<Catalyst::DispatchType::Chained>).
+
+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<Plack>, a toolkit for using the L<PSGI>
-stack, now replaces most of the subclasses of L<Catalyst::Engine>. If
+specification, now replaces most of the subclasses of L<Catalyst::Engine>. If
you are using one of the standard subclasses of L<Catalyst::Engine> this
should be a straightforward upgrade for you. It was a design goal for
this release to preserve as much backwards compatibility as possible.
=head2 Upgrading the mod_perl / Apache Engines
The engines that are built upon the various iterations of mod_perl,
-L<Catalyst::Engine::Apache::MP13> and L<Catalyst::Engine::Apache2::MP20>,
-should be seamless upgrades and will work using using
-L<Plack::Handler::Apache1> or L<Plack::Handler::Apache2> as required.
+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 L<Plack::Handler::Apache1>
+or L<Plack::Handler::Apache2> as required.
L<Catalyst::Engine::Apache2::MP19>, however, is no longer supported, as
-Plack does not support mod_perl version 1.99
+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
If you were using L<Catalyst::Engine::CGI> there is no upgrade needed if your
myapp_cgi.pl script is already upgraded to use L<Catalyst::Script::CGI>.
-=head2 Upgrading the Preforking Engine
+=head2 Upgrading Catalyst::Engine::HTTP::Prefork
If you were using L<Catalyst::Engine::HTTP::Prefork> then L<Starman>
is automatically loaded. You should (at least) change your C<Makefile.PL>
becomes
- MyCatalystApp->setup_engine('PSGI');
my $app = MyCatalystApp->psgi_app(@_);
B<NOT>:
release, and will result in the development server starting, rather than
the expected test running.
+B<NOTE:> If you are directly accessing C<< $c->req->env >> to get the PSGI
+environment then this accessor is moved to C<< $c->engine->env >>,
+you will need to update your code.
+
=head2 Engines which are known to be broken
The following engines B<DO NOT> work as of Catalyst version 5.9. The
=back
-=head2 Specifying the engine in the call to ->setup
-
-XXX FIXME
-
=head2 Plack functionality
See L<Catalyst::PSGI>.
is using deprecated code, or relying on side effects, then you could have
issues upgrading to this release.
-Most issues found with pre-existing components have been easy to
+Most issues found with existing components have been easy to
solve. This document provides a complete description of behavior changes
which may cause compatibility issues, and of new Catalyst warnings which
might be unclear.
to resolve methods using C3, rather than the unpredictable dispatch
order of L<NEXT>.
-This issue is characterised by your application failing to start due to an
+This issue manifests itself by your application failing to start due to an
error message about having a non-linear @ISA.
The Catalyst plugin most often causing this is
use Test::More;
isnt(BaseClass->can('foo'), Child->can('foo'));
-=head2 Extending Catalyst::Request or other classes in an ad-hoc manner using mk_accessors
+=head2 Extending Catalyst::Request or other classes in an ad hoc manner using mk_accessors
Previously, it was possible to add additional accessors to Catalyst::Request
(or other classes) by calling the mk_accessors class method.
COMPONENT method you would like to inherit is the first (left-hand most)
COMPONENT method in your @ISA.
+=head2 Development server relying on environment variables
+
+Previously, the development server would allow propagation of system
+environment variables into the request environment, this has changed with the
+adoption of Plack. You can use L<Plack::Middleware::ForceEnv> to achieve the
+same effect.
+
=head1 WARNINGS
=head2 Actions in your application class
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