+=head1 NAME
+
+Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
+
=head1 Upgrading to Catalyst 5.80
Most applications and plugins should run unaltered on Catalyst 5.80.
If you think you have found an upgrade related issue which is not covered in
this document, then please email the Catalyst list to discuss the problem.
+=head1 Moose features
+
+=head2 Application class roles.
+
+You can only apply method modifiers after the applications C<< ->setup >>
+method has been called. This means that modifiers will not work with methods
+which run during the call to C<< ->setup >>.
+
+=head2 Controller actions in Moose roles
+
+Is known to not work.
+
=head1 Known backwards compatibility breakages.
+=head2 Applications in a single file.
+
+Applications must be in their own file, and loaded at compile time. This
+issue generally only affects the tests of cpan distributions. Defining an
+application inline in a block, and using plugins which supply a C< new >
+method, then using that application latter in tests, within the same file
+will cause your application to fail.
+
+This is due to the fact that Catalyst is inlining a new method on your
+application class allowing it to be compatible with Moose. The method used
+to do this changed in 5.80004 to avoid the possibility of reporting
+'Unknown Error' if your application failed to compile.
+
=head2 Issues with Class::C3
Catalyst 5.80 uses L<Algorithm::C3> method dispatch order. This is built into
with L<Class::C3::Adopt::NEXT>, forcing all components to resolve methods using
C3, rather than the unpredictable dispatch order of L<NEXT>.
-To be able to do this, however, entails that the graph of superclasses for each
-class must be linearizable using the C3 algorithm. Unfortunately, when
-superclasses are being used as mixins, it is easy to get this wrong.
+This issue is characterised 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
+L<Catalyst::Plugin::Session::Store::FastMmap> - if you are using this plugin
+and see issues, then please upgrade - and please try upgrading your plugins
+if you have this issue, as it has been fixed. Note that Makefile.PL in the
+distribution will warn about known incompatible components.
+
+This issue can, however, be found in your own application - the only solution is
+to go through each base class of the class the error was reported against, until
+you identify the ones in conflict, and resolve them.
+
+To be able to generate a linear @ISA, the list of superclasses for each
+class must be resolvable using the C3 algorithm. Unfortunately, when
+superclasses are being used as mixins (to add functionality used in your class),
+and with multiple inheritence, it is easy to get this wrong.
Most common is the case of:
package GoesBang;
use base qw/Component1 Component2/;
-And the Catalyst plugin most often causing this, is
-L<Catalyst::Plugin::Sesssion::Store::FastMMap> - if you are using this plugin
-and see issues, then please upgrade!
+Any situation like this will cause your application to fail to start.
-This can, however, be found in your own application - the only solution is to
-go through each base class of the class the error was reported against, until
-you identify the ones in conflict, and resolve them.
+Please see additional documentation about this issue, and how to resolve it in
+L<Class::C3::Adopt::NEXT>.
=head2 Components which inherit from Moose::Object before Catalyst::Component
to use the constructor provided by Moose, whilst working (if you do some hacks
with the C< BUILDARGS > method), will not work with Catalyst 5.80 as
C<Catalyst::Component> inherits from C<Moose::Object>, and so C< @ISA > fails
-to linearise.
+to linearize.
The fix for this is to not inherit directly from C<Moose::Object>
yourself. Having components which do not inherit their constructor from
Note that the C< extends > declaration needs to occur in a begin block for
L<attributes> to operate correctly.
-You also don't get the L<Moose::Object> constructor, and therefore attribute
-initialization will not work as normally expected. If you want to use Moose
+You also don't get the L<Moose::Object> 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.
Note that this only applies if your component needs to maintain component
backwards compatibility for Catalyst versions before 5.71001 - in 5.71001
attributes work as expected, and the BUILD method is called normally
-(although BUILDARGS is not).
+(although BUILDARGS is not).
If you depend on Catalyst 5.8, then B<all> Moose features work as expected.
package MyApp;
use Moose;
+ use Catalyst;
+
extends 'Catalyst';
+
+ __PACKAGE__->config( name => 'MyApp' );
__PACKAGE__->setup(qw/
ConfigLoader
/);
*$full_method_name = subname $full_method_name, sub { ... };
Additionally, you can take advantage of Catalysts use of L<Class::MOP> and
-install the closure using the appropriate metaclass. Example:
+install the closure using the appropriate meta class. Example:
use Class::MOP;
my $metaclass = Moose::Meta::Class->initialize($package_name);
=head2 Hooking into application setup
-To execute code during application startup the following snippet in MyApp.pm
+To execute code during application start-up the following snippet in MyApp.pm
used to work:
sub setup {
BaseClass->foo('base class');
Child->foo('sub class');
-
+
use Test::More;
isnt(BaseClass->can('foo'), Child->can('foo'));
adequately supports your use-case, please email the development list to
discuss what API features you need so that you can be appropriately supported.
-=head2 Class naming to packages defined does not correspond.
+=head2 Class files with names that don't correspond to the packages they define
In this version of Catalyst, if a component is loaded from disk, but no
symbols are defined in that component's name space after it is loaded, this
=head2 $c->plugin method
-Calling the plugin method is deprecated, and calling it at runtime is B<highly
+Calling the plugin method is deprecated, and calling it at run time is B<highly
deprecated>.
Instead you are recommended to use L< Catalyst::Model::Adaptor > or similar to