Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
-=head1 Upgrading to Catalyst 5.90
-
-The major change is that L<Plack> 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 be as backwardly compatible as possible.
-However since L<Plack> is different from L<Catalyst::Engine> it is possible
-that edge case differences 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.
+=head1 Upgrading to Catalyst 5.9
+
+The major change is that L<Plack>, a toolkit for using the L<PSGI>
+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.
+However, since L<Plack> is different from L<Catalyst::Engine>, 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<Plack> ecosystem
and documentation. Being able to take advantage of L<Plack> development and
take advantage of L<Plack::Middleware> by writing your own C<< .psgi >> file
is contained in L<Catalyst::PSGI>.
-If you have created a custom subclass of L<Catalyst:Engine> you will need to
-convert it to be a subclass of L<Plack::Handler>.
+If you have created a custom subclass of L<Catalyst:Engine>, you will
+need to convert it to be a subclass of L<Plack::Handler>.
If you are using the L<Plack> engine, L<Catalyst::Engine::PSGI>, this new
release supersedes that code.
-If you are using a subclass of L<Catalyst::Engine> that is aimed at nonstandard
-or internal / testing uses, such as L<Catalyst::Engine::Embeddable> you should
-still be able to continue using that engine.
+If you are using a subclass of L<Catalyst::Engine> that is aimed at
+nonstandard or internal/testing uses, such as
+L<Catalyst::Engine::Embeddable>, you should still be able to continue
+using that engine.
Advice for specific subclasses of L<Catalyst::Engine> follows:
=head2 Upgrading the FastCGI Engine
-No upgrade needed if your myapp_fastcgi.pl script is already upgraded
-enough to use L<Catalyst::Script::FastCGI>.
+No upgrade is needed if your myapp_fastcgi.pl script is already upgraded
+to use L<Catalyst::Script::FastCGI>.
=head2 Upgrading the mod_perl / Apache Engines
-The engines that are build 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.
+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>
+or L<Plack::Handler::Apache2> as required.
-L<Catalyst::Engine::Apache2::MP19>, is however no longer supported, as Plack
-does not support mod_perl version 1.99
+L<Catalyst::Engine::Apache2::MP19>, 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
=head2 Upgrading the CGI Engine
If you were using L<Catalyst::Engine::CGI> there is no upgrade needed if your
-myapp_cgi.pl script is already upgraded enough to use L<Catalyst::Script::CGI>.
+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.
+is automatically loaded. You should (at least) change your C<Makefile.PL>
+to depend on Starman.
+
+You can regenerate your C<myapp_server.pl> script with C<catalyst.pl>
+and implement a C<MyApp::Script::Server> 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.
-If you were customising your server script to pass options 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<plackup> utility.
+More information about these options can be seen at
+L<CatalystX::Script::Server::Starman/SYNOPSIS>.
+
+An alternate route to implement this functionality is to write a simple .psgi
+file for your application, and then use the L<plackup> utility to start the
+server.
=head2 Upgrading the PSGI Engine
-If you were using L<Catalyst::Engine::PSGI> this new release supersedes this
-engine in supporting L<Plack>. By default the Engine is now always L<Plack>.
-As a result, you can stop depending on L<Catalyst::Engine::PSGI> in your
-C<Makefile.PL>.
+If you were using L<Catalyst::Engine::PSGI>, this new release supersedes
+this engine in supporting L<Plack>. By default the Engine is now always
+L<Plack>. As a result, you can remove the dependency on
+L<Catalyst::Engine::PSGI> in your C<Makefile.PL>.
Applications that were using L<Catalyst::Engine::PSGI>
previously should entirely continue to work in this release with no changes.
-However, if you have an C<app.psgi> script, then you no longer
-need to specify the PSGI engine. Instead, the L<Catalyst> application class
-now has a new method C<psgi_app> which returns a L<PSGI> compatible coderef
-which you can wrap in middleware of your choice.
+However, if you have an C<app.psgi> script, then you no longer need to
+specify the PSGI engine. Instead, the L<Catalyst> application class now
+has a new method C<psgi_app> which returns a L<PSGI> 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<home>
-directory of the application
+directory of the application.
For example, if you were using L<Catalyst::Engine::PSGI> in the past, you will
have written (or generated) a C<script/myapp.psgi> file similar to this one:
becomes
- MyCatalystApp->setup_engine('PSGI');
my $app = MyCatalystApp->psgi_app(@_);
B<NOT>:
my $app = sub { MyCatalystApp->psgi_app(@_) };
# If you make ^^ this mistake, your app won't work, and will confuse the hell out of you!
-You can now move C<< script/myapp.psgi >> to C<< myapp.psgi >> and the built-in
+You can now move C<< script/myapp.psgi >> to C<< myapp.psgi >>, and the built-in
Catalyst scripts and your test suite will start using your .psgi file.
-B<NOTE:> If you rename your .psgi file without these modifications, then any tests run via
-L<Catalyst::Test> will not be compatible with the new release, and will result in
-the development server starting, rather than the expected test running.
+B<NOTE:> If you rename your .psgi file without these modifications, then
+any tests run via L<Catalyst::Test> will not be compatible with the new
+release, and will result in the development server starting, rather than
+the expected test running.
-=head2 Engines which are known broken
+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.
-The following engines B<DO NOT> work as of Catalyst version 5.90. The core
-team is extremely happy to work with the developers and/or users of these
-engines to help them port to the new Plack/Engine system, however applications
-which are currently using these engines B<WILL NOT> run without modification
-to the engine code.
+=head2 Engines which are known to be broken
+
+The following engines B<DO NOT> work as of Catalyst version 5.9. The
+core team will be happy to work with the developers and/or users of
+these engines to help them port to the new Plack/Engine system, but for
+now, applications which are currently using these engines B<WILL NOT>
+run without modification to the engine code.
=over
=head2 Engines with unknown status
-The following engines have untested or unknown compatibility. Reports are
-highly welcomed:
+The following engines are untested or have unknown compatibility.
+Reports are highly encouraged:
=over
=item Catalyst::Engine::Mojo
-=item Catalyst::Engine::Server (Marked as Deprecated)
+=item Catalyst::Engine::Server (marked as Deprecated)
-=item Catalyst::Engine::HTTP::POE (Marked as Deprecated)
+=item Catalyst::Engine::HTTP::POE (marked as Deprecated)
=back
-=head2 Specifying the engine in the call to ->setup
-
-XXX FIXME
-
=head2 Plack functionality
See L<Catalyst::PSGI>.
-=head2 Tests in 5.89
+=head2 Tests in 5.9
-Tests should generally work the same in Catalyst 5.89, however there are some differences.
+Tests should generally work the same in Catalyst 5.9, but there are
+some differences.
-Previously, if using L<Catalyst::Test> and doing local requests (against a local server),
-if the application threw an exception then this exception propagated into the test.
+Previously, if using L<Catalyst::Test> and doing local requests (against
+a local server), if the application threw an exception then this
+exception propagated into the test.
-This behavior has been removed, and now a 500 response will be returned to the test.
-This change unifies behavior, to make local test requests behave similarly to remote
-requests.
+This behavior has been removed, and now a 500 response will be returned
+to the test. This change standardizes behavior, so that local test
+requests behave similarly to remote requests.
=head1 Upgrading to 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
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
The first time one of these methods is called, a warning will be emitted:
Class $class is calling the deprecated method Catalyst::Dispatcher::$public_method_name,
- this will be removed in Catalyst 5.9X
+ this will be removed in Catalyst 5.9
You should B<NEVER> be calling any of these methods from application code.