X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FUpgrading.pod;h=8ce8eec4fa27761c77837896ba748068dfebcc87;hb=1e5dad0099d51c919670c0e765615937b0fd4dae;hp=98f2d9d906c1b2434ad1038b63cacba96a4ab0f4;hpb=ac9279b0045ca8e9b6de84cddefd54661eece9fe;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod index 98f2d9d..8ce8eec 100644 --- a/lib/Catalyst/Upgrading.pod +++ b/lib/Catalyst/Upgrading.pod @@ -2,6 +2,121 @@ Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst +=head1 Upgrading to Catalyst 5.90 + +The major change is that L now replaces most of the subclasses of +L. If you are using one of the standard subclasses of +L 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 is different from L it would be +possible that edge case differences would 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. + +It is highly recommended that you become familar with the L ecosystem +and documentation. Being able to take advantage of L development and +middleware is a major bonus to this upgrade. + +If you have created a custom subclass of L you will need to +convert it to be a subclass of L. + +If you are using the L engine, L, this new +release supercedes that code. + +If you are using a subclass of L that is aimed at nonstandard +or internal / testing uses, such as L you should +still be able to continue using that engine. + +Advice for specific subclasses of L follows: + +=head2 Upgrading the FastCGI Engine + +No upgrade needed if your myapp_fastcgi.pl script is already upgraded +enough to use L. + +=head2 Upgrading the mod_perl / Apache Engines + +The engines that are build upon the various iterations of mod_perl, +L and +L should be seemless upgrades and will +work using using L or L +as required. + +L, is however no longer supported, as Plack +does not support mod_perl version 1.99??? FIXME - is this true? + +=head2 Upgrading the HTTP Engine + +The default development server that comes with the L distribution +should continue to work as expected with no changes as long as your C +script is upgraded to use L. + +=head2 Upgrading the CGI Engine + +If you were using L there is no upgrade needed if your +myapp_cgi.pl script is already upgraded enough to use L. + +=head2 Upgrading the Preforking Engine + +If you were using L then L +is automatically loaded. + +=head2 Upgrading the PSGI Engine + +If you were using L this new release supercedes this +engine in supporting L. By default the Engine is now always L. +As a result, you can stop depending on L in your +C. Additionally, if you have an C script you no longer +need to specify the PSGI engine. Instead, the L application class +now has a new method C which returns a L compatible coderef. + +For example, if you were using L in the past, you may +have written an C file similar to this one: + + use Plack::Builder; + use MyCatalytApp; + + MyCatalystApp->setup_engine('PSGI'); + + builder { + enable ... # enable your desired middleware + sub { MyCatalystApp->run(@_) }; + }; + +Instead, you now just do + + use Plack::Builder; + use MyCatalystApp; + + builder { + enable ... #enable your desired middleware + MyCatalystApp->psgi_app; + }; + +=head2 Engines with unknown status + +The following engines have untested or unknown compatibility. Reports are +highly welcomed: + + Catalyst::Engine::Embeddable + Catalyst::Engine::XMPP2 + Catalyst::Engine::SCGI + Catalyst::Engine::Mojo + Catalyst::Engine::Zeus + Catalyst::Engine::JobQueue::POE + Catalyst::Engine::Wx + Catalyst::Engine::Stomp + Catalyst::Engine::Server (Marked as Deprecated) + Catalyst::Engine::HTTP::POE (Marked as Deprecated) + +=head2 Using middleware + +XXX Should this be here or elsewhere? + +=head2 Making an app.psgi file + +=head2 Running with plackup? + =head1 Upgrading to Catalyst 5.80 Most applications and plugins should run unaltered on Catalyst 5.80. @@ -32,7 +147,8 @@ L in your applications. =head2 Controller actions in Moose roles -Declaring actions in Roles is currently unsupported. +You can use L if you want to declare actions +inside Moose roles. =head2 Using Moose in Components @@ -216,7 +332,7 @@ been called, and will not call them again. Using this now causes infinite recursion between MyApp::setup and Catalyst::setup, due to other backwards compatibility issues related to how -plugin setup works. Moose method modifiers like C<< before|after|around 'setup +plugin setup works. Moose method modifiers like C<< before|after|around setup => sub { ... }; >> also will not operate correctly on the setup method. The right way to do it is this: @@ -309,7 +425,26 @@ COMPONENT method in your @ISA. 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: + + package MyTest::Controller::Root; + + use strict; + use warnings; + + use parent 'Catalyst::Controller'; + + __PACKAGE__->config(namespace => ''); + + sub action : Local { + my ( $self, $c ) = @_; + $c->do_something; + } + + 1; =head2 ::[MVC]:: naming scheme @@ -381,7 +516,7 @@ to B of the packages defined within that component. Calling the plugin method is deprecated, and calling it at run time is B. -Instead you are recommended to use L< Catalyst::Model::Adaptor > or similar to +Instead you are recommended to use L or similar to compose the functionality you need outside of the main application name space. Calling the plugin method will not be supported past Catalyst 5.81.