X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FUpgrading.pod;h=773e24605bce5165486e98383438395e16219e0e;hb=0ea8962d9383c610ebfcd8f3f3b0095a63398640;hp=c639b16ccbc75ae2824a900cea14764a40b0d7c3;hpb=8f61d649008a9894aed05cb4aa418da44cf710c8;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Upgrading.pod b/lib/Catalyst/Upgrading.pod index c639b16..773e246 100644 --- a/lib/Catalyst/Upgrading.pod +++ b/lib/Catalyst/Upgrading.pod @@ -2,6 +2,123 @@ 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. + +XXX FIXME - note how to run Starman with different options. + +=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 - needs testing, should work? + Catalyst::Engine::XMPP2 + Catalyst::Engine::SCGI + Catalyst::Engine::Mojo + Catalyst::Engine::Zeus - broken for ages + Catalyst::Engine::JobQueue::POE - broken for ages + Catalyst::Engine::Wx + Catalyst::Engine::Stomp - fixed + 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 +149,19 @@ 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 + +The correct way to use Moose in a component in a both forward and backwards +compatible way is: + + package TestApp::Controller::Root; + use Moose; + BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever + +See L. =head1 Known backwards compatibility breakages @@ -104,21 +233,6 @@ with the C< BUILDARGS > method), will not work with Catalyst 5.80 as C inherits from C, and so C< @ISA > fails to linearize. -The fix for this is to not inherit directly from C -yourself. Having components which do not inherit their constructor from -C is B, and has never been recommended, -therefore you're on your own if you're using this technique. You'll need -to detect the version of Catalyst your application is running, and deal -with it appropriately. - -You will also see this issue if you do the following: - - package TestApp::Controller::Example; - use Moose; - use base 'Catalyst::Controller'; - -as C< use base > appends to @ISA. - The correct way to use Moose in a component in a both forward and backwards compatible way is: @@ -129,6 +243,13 @@ compatible way is: Note that the C< extends > declaration needs to occur in a begin block for L to operate correctly. +This way you do not inherit directly from C +yourself. Having components which do not inherit their constructor from +C is B, and has never been recommended, +therefore you're on your own if you're using this technique. You'll need +to detect the version of Catalyst your application is running, and deal +with it appropriately. + You also don't get the L constructor, and therefore attribute initialization will not work as normally expected. If you want to use Moose attributes, then they need to be made lazy to correctly initialize. @@ -140,6 +261,14 @@ attributes work as expected, and the BUILD method is called normally If you depend on Catalyst 5.8, then B Moose features work as expected. +You will also see this issue if you do the following: + + package TestApp::Controller::Example; + use Moose; + use base 'Catalyst::Controller'; + +as C< use base > appends to @ISA. + =head3 use Moose in MyApp Similar to the above, this will also fail: @@ -205,7 +334,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: @@ -293,6 +422,43 @@ COMPONENT method in your @ISA. =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). + +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 + +Having packages called MyApp::[MVC]::XX is deprecated and can no longer be generated +by catalyst.pl + +This is still supported, but it is recommended that you rename your application +components to Model/View/Controller. + +A warning will be issued at application startup if the ::[MVC]:: naming scheme is +in use. + =head2 Catalyst::Base Any code using L will now emit a warning; this @@ -352,7 +518,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.