view release on metacpan or  search on metacpan

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

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>
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
middleware is a major bonus to this upgrade. Documentation about how to
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 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.

Advice for specific subclasses of L<Catalyst::Engine> follows:

=head2 Upgrading the FastCGI Engine

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

The default development server that comes with the L<Catalyst> distribution
should continue to work as expected with no changes as long as your C<myapp_server>
script is upgraded to use L<Catalyst::Script::HTTP>.

=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 to use L<Catalyst::Script::CGI>.

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

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