3 Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
5 =head1 Upgrading to Catalyst 5.9
7 The major change is that L<Plack> now replaces most of the subclasses of
8 L<Catalyst::Engine>. If you are using one of the standard subclasses of
9 L<Catalyst::Engine> this should be a straightforward upgrade for you. It was
10 a design goal for this release to be as backwardly compatible as possible.
11 However since L<Plack> is different from L<Catalyst::Engine> it is possible
12 that edge case differences exist. Therefore we recommend care be taken with
13 this upgrade and that testing should be greater than would be the case with a
16 It is highly recommended that you become familiar with the L<Plack> ecosystem
17 and documentation. Being able to take advantage of L<Plack> development and
18 middleware is a major bonus to this upgrade. Documentation about how to
19 take advantage of L<Plack::Middleware> by writing your own C<< .psgi >> file
20 is contained in L<Catalyst::PSGI>.
22 If you have created a custom subclass of L<Catalyst:Engine> you will need to
23 convert it to be a subclass of L<Plack::Handler>.
25 If you are using the L<Plack> engine, L<Catalyst::Engine::PSGI>, this new
26 release supersedes that code.
28 If you are using a subclass of L<Catalyst::Engine> that is aimed at nonstandard
29 or internal / testing uses, such as L<Catalyst::Engine::Embeddable> you should
30 still be able to continue using that engine.
32 Advice for specific subclasses of L<Catalyst::Engine> follows:
34 =head2 Upgrading the FastCGI Engine
36 No upgrade needed if your myapp_fastcgi.pl script is already upgraded
37 enough to use L<Catalyst::Script::FastCGI>.
39 =head2 Upgrading the mod_perl / Apache Engines
41 The engines that are build upon the various iterations of mod_perl,
42 L<Catalyst::Engine::Apache::MP13> (for mod_perl 1, and Apache 1.x) and
43 L<Catalyst::Engine::Apache2::MP20> (for mod_perl 2, and Apache 2.x)
44 should be seamless upgrades and will work using using L<Plack::Handler::Apache1>
45 or L<Plack::Handler::Apache2> as required.
47 L<Catalyst::Engine::Apache2::MP19>, is however no longer supported, as Plack
48 does not support mod_perl version 1.99. This is unlikely to be a problem
49 for anyone, as 1.99 was a brief beta-test release for mod_perl 2, and any users
50 are encouraged to upgrade to a supported release of Apache 2 and mod_perl 2.
52 =head2 Upgrading the HTTP Engine
54 The default development server that comes with the L<Catalyst> distribution
55 should continue to work as expected with no changes as long as your C<myapp_server>
56 script is upgraded to use L<Catalyst::Script::HTTP>.
58 =head2 Upgrading the CGI Engine
60 If you were using L<Catalyst::Engine::CGI> there is no upgrade needed if your
61 myapp_cgi.pl script is already upgraded enough to use L<Catalyst::Script::CGI>.
63 =head2 Upgrading the Preforking Engine
65 If you were using L<Catalyst::Engine::HTTP::Prefork> then L<Starman>
66 is automatically loaded. You should (at least) change your C<Makefile.PL>
69 You can regenerate your C<myapp_server.pl> script with C<catalyst.pl>
70 and implement a C<MyApp::Script::Server> class that looks like this:
72 package MyApp::Script::Server;
74 use namespace::autoclean;
76 extends 'CatalystX::Script::Server::Starman';
80 This takes advantage of the new script system, and adds a number of options to
81 the standard server script as extra options are added by Starman.
83 More information about these options can be seen at
84 L<CatalystX::Script::Server::Starman/SYNOPSIS>.
86 An alternate route to implement this functionality is to write a simple .psgi
87 file for your application, then use the L<plackup> utility to start the
90 =head2 Upgrading the PSGI Engine
92 If you were using L<Catalyst::Engine::PSGI> this new release supersedes this
93 engine in supporting L<Plack>. By default the Engine is now always L<Plack>.
94 As a result, you can stop depending on L<Catalyst::Engine::PSGI> in your
97 Applications that were using L<Catalyst::Engine::PSGI>
98 previously should entirely continue to work in this release with no changes.
100 However, if you have an C<app.psgi> script, then you no longer
101 need to specify the PSGI engine. Instead, the L<Catalyst> application class
102 now has a new method C<psgi_app> which returns a L<PSGI> compatible coderef
103 which you can wrap in middleware of your choice.
105 Catalyst will use the .psgi for your application if it is located in the C<home>
106 directory of the application
108 For example, if you were using L<Catalyst::Engine::PSGI> in the past, you will
109 have written (or generated) a C<script/myapp.psgi> file similar to this one:
114 MyCatalystApp->setup_engine('PSGI');
117 enable ... # enable your desired middleware
118 sub { MyCatalystApp->run(@_) };
121 Instead, you now say:
127 enable ... #enable your desired middleware
128 MyCatalystApp->psgi_app;
131 In the simplest case:
133 MyCatalystApp->setup_engine('PSGI');
134 my $app = sub { MyCatalystApp->run(@_) }
138 MyCatalystApp->setup_engine('PSGI');
139 my $app = MyCatalystApp->psgi_app(@_);
143 my $app = sub { MyCatalystApp->psgi_app(@_) };
144 # If you make ^^ this mistake, your app won't work, and will confuse the hell out of you!
146 You can now move C<< script/myapp.psgi >> to C<< myapp.psgi >> and the built-in
147 Catalyst scripts and your test suite will start using your .psgi file.
149 B<NOTE:> If you rename your .psgi file without these modifications, then any tests run via
150 L<Catalyst::Test> will not be compatible with the new release, and will result in
151 the development server starting, rather than the expected test running.
153 =head2 Engines which are known broken
155 The following engines B<DO NOT> work as of Catalyst version 5.9. The core
156 team is extremely happy to work with the developers and/or users of these
157 engines to help them port to the new Plack/Engine system, however applications
158 which are currently using these engines B<WILL NOT> run without modification
163 =item Catalyst::Engine::Wx
165 =item Catalyst::Engine::Zeus
167 =item Catalyst::Engine::JobQueue::POE
169 =item Catalyst::Engine::XMPP2
171 =item Catalyst::Engine::SCGI
175 =head2 Engines with unknown status
177 The following engines have untested or unknown compatibility. Reports are
182 =item Catalyst::Engine::Mojo
184 =item Catalyst::Engine::Server (Marked as Deprecated)
186 =item Catalyst::Engine::HTTP::POE (Marked as Deprecated)
190 =head2 Specifying the engine in the call to ->setup
194 =head2 Plack functionality
196 See L<Catalyst::PSGI>.
200 Tests should generally work the same in Catalyst 5.9, however there are some differences.
202 Previously, if using L<Catalyst::Test> and doing local requests (against a local server),
203 if the application threw an exception then this exception propagated into the test.
205 This behavior has been removed, and now a 500 response will be returned to the test.
206 This change unifies behavior, to make local test requests behave similarly to remote
209 =head1 Upgrading to Catalyst 5.80
211 Most applications and plugins should run unaltered on Catalyst 5.80.
213 However, a lot of refactoring work has taken place, and several changes have
214 been made which could cause incompatibilities. If your application or plugin
215 is using deprecated code, or relying on side effects, then you could have
216 issues upgrading to this release.
218 Most issues found with pre-existing components have been easy to
219 solve. This document provides a complete description of behavior changes
220 which may cause compatibility issues, and of new Catalyst warnings which
223 If you think you have found an upgrade-related issue which is not covered in
224 this document, please email the Catalyst list to discuss the problem.
226 =head1 Moose features
228 =head2 Application class roles
230 You can only apply method modifiers after the application's C<< ->setup >>
231 method has been called. This means that modifiers will not work with methods
232 run during the call to C<< ->setup >>.
234 See L<Catalyst::Manual::ExtendingCatalyst> for more information about using
235 L<Moose> in your applications.
237 =head2 Controller actions in Moose roles
239 You can use L<MooseX::MethodAttributes::Role> if you want to declare actions
242 =head2 Using Moose in Components
244 The correct way to use Moose in a component in a both forward and backwards
247 package TestApp::Controller::Root;
249 BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
251 See L<Components which inherit from Moose::Object before Catalyst::Component>.
253 =head1 Known backwards compatibility breakages
255 =head2 Applications in a single file
257 Applications must be in their own file, and loaded at compile time. This
258 issue generally only affects the tests of CPAN distributions. Your
259 application will fail if you try to define an application inline in a
260 block, and use plugins which supply a C< new > method, then use that
261 application latter in tests within the same file.
263 This is due to the fact that Catalyst is inlining a new method on your
264 application class allowing it to be compatible with Moose. The method
265 used to do this changed in 5.80004 to avoid the possibility of reporting
266 an 'Unknown Error' if your application failed to compile.
268 =head2 Issues with Class::C3
270 Catalyst 5.80 uses the L<Algorithm::C3> method dispatch order. This is
271 built into Perl 5.10, and comes via L<Class::C3> for Perl 5.8. This
272 replaces L<NEXT> with L<Class::C3::Adopt::NEXT>, forcing all components
273 to resolve methods using C3, rather than the unpredictable dispatch
276 This issue is characterised by your application failing to start due to an
277 error message about having a non-linear @ISA.
279 The Catalyst plugin most often causing this is
280 L<Catalyst::Plugin::Session::Store::FastMmap> - if you are using this
281 plugin and see issues, then please upgrade your plugins, as it has been
282 fixed. Note that Makefile.PL in the distribution will warn about known
283 incompatible components.
285 This issue can, however, be found in your own application - the only solution is
286 to go through each base class of the class the error was reported against, until
287 you identify the ones in conflict, and resolve them.
289 To be able to generate a linear @ISA, the list of superclasses for each
290 class must be resolvable using the C3 algorithm. Unfortunately, when
291 superclasses are being used as mixins (to add functionality used in your class),
292 and with multiple inheritance, it is easy to get this wrong.
294 Most common is the case of:
296 package Component1; # Note, this is the common case
297 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
299 package Component2; # Accidentally saying it this way causes a failure
300 use base qw/Class::Data::Inheritable Class::Accessor::Fast/;
303 use base qw/Component1 Component2/;
305 Any situation like this will cause your application to fail to start.
307 For additional documentation about this issue, and how to resolve it, see
308 L<Class::C3::Adopt::NEXT>.
310 =head2 Components which inherit from Moose::Object before Catalyst::Component
312 Moose components which say:
314 package TestApp::Controller::Example;
316 extends qw/Moose::Object Catalyst::Component/;
318 to use the constructor provided by Moose, while working (if you do some hacks
319 with the C< BUILDARGS > method), will not work with Catalyst 5.80 as
320 C<Catalyst::Component> inherits from C<Moose::Object>, and so C< @ISA > fails
323 The correct way to use Moose in a component in a both forward and backwards
326 package TestApp::Controller::Root;
328 BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
330 Note that the C< extends > declaration needs to occur in a begin block for
331 L<attributes> to operate correctly.
333 This way you do not inherit directly from C<Moose::Object>
334 yourself. Having components which do not inherit their constructor from
335 C<Catalyst::Component> is B<unsupported>, and has never been recommended,
336 therefore you're on your own if you're using this technique. You'll need
337 to detect the version of Catalyst your application is running, and deal
338 with it appropriately.
340 You also don't get the L<Moose::Object> constructor, and therefore attribute
341 initialization will not work as normally expected. If you want to use Moose
342 attributes, then they need to be made lazy to correctly initialize.
344 Note that this only applies if your component needs to maintain component
345 backwards compatibility for Catalyst versions before 5.71001 - in 5.71001
346 attributes work as expected, and the BUILD method is called normally
347 (although BUILDARGS is not).
349 If you depend on Catalyst 5.8, then B<all> Moose features work as expected.
351 You will also see this issue if you do the following:
353 package TestApp::Controller::Example;
355 use base 'Catalyst::Controller';
357 as C< use base > appends to @ISA.
359 =head3 use Moose in MyApp
361 Similar to the above, this will also fail:
370 If you need to use Moose in your application class (e.g. for method modifiers
371 etc.) then the correct technique is:
379 __PACKAGE__->config( name => 'MyApp' );
380 __PACKAGE__->setup(qw/
384 =head2 Anonymous closures installed directly into the symbol table
386 If you have any code which installs anonymous subroutine references directly
387 into the symbol table, you may encounter breakages. The simplest solution is
388 to use L<Sub::Name> to name the subroutine. Example:
390 # Original code, likely to break:
391 my $full_method_name = join('::', $package_name, $method_name);
392 *$full_method_name = sub { ... };
395 use Sub::Name 'subname';
396 my $full_method_name = join('::',$package_name, $method_name);
397 *$full_method_name = subname $full_method_name, sub { ... };
399 Additionally, you can take advantage of Catalyst's use of L<Class::MOP> and
400 install the closure using the appropriate metaclass. Example:
403 my $metaclass = Moose::Meta::Class->initialize($package_name);
404 $metaclass->add_method($method_name => sub { ... });
406 =head2 Hooking into application setup
408 To execute code during application start-up, the following snippet in MyApp.pm
412 my ($class, @args) = @_;
413 $class->NEXT::setup(@args);
414 ... # things to do after the actual setup
417 With Catalyst 5.80 this won't work anymore, because Catalyst no longer
418 uses NEXT.pm for method resolution. The functionality was only ever
419 originally operational as L<NEXT> remembers what methods have already
420 been called, and will not call them again.
422 Using this now causes infinite recursion between MyApp::setup and
423 Catalyst::setup, due to other backwards compatibility issues related to how
424 plugin setup works. Moose method modifiers like C<< before|after|around setup
425 => sub { ... }; >> also will not operate correctly on the setup method.
427 The right way to do it is this:
429 after setup_finalize => sub {
430 ... # things to do after the actual setup
433 The setup_finalize hook was introduced as a way to avoid this issue.
435 =head2 Components with a new method which returns false
437 Previously, if you had a component which inherited from Catalyst::COMPONENT,
438 but overrode the new method to return false, then your class's configuration
439 would be blessed into a hash on your behalf, and this would be returned from
440 the COMPONENT method.
442 This behavior makes no sense, and so has been removed. Implementing your own
443 C< new > method in components is B<highly> discouraged. Instead, you should
444 inherit the new method from Catalyst::Component, and use Moose's BUILD
445 functionality and/or Moose attributes to perform any construction work
446 necessary for your class.
448 =head2 __PACKAGE__->mk_accessor('meta');
450 Won't work due to a limitation of L<Moose>. This is currently being fixed
453 =head2 Class::Data::Inheritable side effects
455 Previously, writing to a class data accessor would copy the accessor method
456 down into your package.
458 This behavior has been removed. While the class data is still stored
459 per-class, it is stored on the metaclass of the class defining the accessor.
461 Therefore anything relying on the side effect of the accessor being copied down
464 The following test demonstrates the problem:
468 use base qw/Class::Data::Inheritable/;
469 __PACKAGE__->mk_classdata('foo');
474 use base qw/BaseClass/;
477 BaseClass->foo('base class');
478 Child->foo('sub class');
481 isnt(BaseClass->can('foo'), Child->can('foo'));
483 =head2 Extending Catalyst::Request or other classes in an ad-hoc manner using mk_accessors
485 Previously, it was possible to add additional accessors to Catalyst::Request
486 (or other classes) by calling the mk_accessors class method.
488 This is no longer supported - users should make a subclass of the class whose
489 behavior they would like to change, rather than globally polluting the
492 =head2 Confused multiple inheritance with Catalyst::Component::COMPONENT
494 Previously, Catalyst's COMPONENT method would delegate to the method on
495 the right hand side, which could then delegate back again with
496 NEXT. This is poor practice, and in addition, makes no sense with C3
497 method dispatch order, and is therefore no longer supported.
499 If a COMPONENT method is detected in the inheritance hierarchy to the right
500 hand side of Catalyst::Component::COMPONENT, then the following warning
501 message will be emitted:
503 There is a COMPONENT method resolving after Catalyst::Component
506 The correct fix is to re-arrange your class's inheritance hierarchy so that the
507 COMPONENT method you would like to inherit is the first (left-hand most)
508 COMPONENT method in your @ISA.
512 =head2 Actions in your application class
514 Having actions in your application class will now emit a warning at application
515 startup as this is deprecated. It is highly recommended that these actions are moved
516 into a MyApp::Controller::Root (as demonstrated by the scaffold application
517 generated by catalyst.pl).
519 This warning, also affects tests. You should move actions in your test,
520 creating a myTest::Controller::Root, like the following example:
522 package MyTest::Controller::Root;
527 use parent 'Catalyst::Controller';
529 __PACKAGE__->config(namespace => '');
532 my ( $self, $c ) = @_;
538 =head2 ::[MVC]:: naming scheme
540 Having packages called MyApp::[MVC]::XX is deprecated and can no longer be generated
543 This is still supported, but it is recommended that you rename your application
544 components to Model/View/Controller.
546 A warning will be issued at application startup if the ::[MVC]:: naming scheme is
549 =head2 Catalyst::Base
551 Any code using L<Catalyst::Base> will now emit a warning; this
552 module will be removed in a future release.
554 =head2 Methods in Catalyst::Dispatcher
556 The following methods in Catalyst::Dispatcher are implementation
557 details, which may change in the 5.8X release series, and therefore their use
558 is highly deprecated.
566 =item registered_dispatch_types
568 =item method_action_class
576 The first time one of these methods is called, a warning will be emitted:
578 Class $class is calling the deprecated method Catalyst::Dispatcher::$public_method_name,
579 this will be removed in Catalyst 5.9
581 You should B<NEVER> be calling any of these methods from application code.
583 Plugin authors and maintainers whose plugins currently call these methods
584 should change to using the public API, or, if you do not feel the public API
585 adequately supports your use case, please email the development list to
586 discuss what API features you need so that you can be appropriately supported.
588 =head2 Class files with names that don't correspond to the packages they define
590 In this version of Catalyst, if a component is loaded from disk, but no
591 symbols are defined in that component's name space after it is loaded, this
592 warning will be issued:
594 require $class was successful but the package is not defined.
596 This is to protect against confusing bugs caused by mistyping package names,
597 and will become a fatal error in a future version.
599 Please note that 'inner packages' (via L<Devel::InnerPackage>) are still fully
600 supported; this warning is only issued when component file naming does not map
601 to B<any> of the packages defined within that component.
603 =head2 $c->plugin method
605 Calling the plugin method is deprecated, and calling it at run time is B<highly
608 Instead you are recommended to use L<Catalyst::Model::Adaptor> or similar to
609 compose the functionality you need outside of the main application name space.
611 Calling the plugin method will not be supported past Catalyst 5.81.