Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
+=head1 Upgrading to Catalyst 5.90040
+
+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.
+
+ TDB: more on streaming, transfer encoding chunked, etc.
+
=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 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>.
to the test. This change standardizes behavior, so that local test
requests behave similarly to remote requests.
+=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.80
Most applications and plugins should run unaltered on Catalyst 5.80.
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
projects / catagits/Catalyst-Runtime.git / blobdiff