+=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
+perl 5.10, and comes via L<Class::C3> for perl 5.8. This replaces L<NEXT>
+with L<Class::C3::Adopt::NEXT>, forcing all components to resolve methods using
+C3, rather than the unpredictable dispatch order of L<NEXT>.
+
+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 Component1; # Note, this is the common case
+ use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
+
+ package Component2; # Accidentally saying it this way round causes fail.
+ use base qw/Class::Data::Inheritable Class::Accessor::Fast/;
+
+ package GoesBang;
+ use base qw/Component1 Component2/;
+
+Any situation like this will cause your application to fail to start.
+
+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
Moose components which say:
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
BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
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 attributes, then they need to be made lazy
-to correctly initialize.
+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
+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).
+
+If you depend on Catalyst 5.8, then B<all> Moose features work as expected.
=head3 use Moose in MyApp
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 {
... # things to do after the actual setup
};
-The setup_finalize hook was introduced as a way to void this issue.
+The setup_finalize hook was introduced as a way to avoid this issue.
=head2 Components with a new method which returns false
BaseClass->foo('base class');
Child->foo('sub class');
-
+
use Test::More;
isnt(BaseClass->can('foo'), Child->can('foo'));
=head1 WARNINGS
+=head2 Catalyst::Base
+
+Any code using L<Catalyst::Base> will now warn, and this module will be removed
+in a future release.
+
=head2 Methods in Catalyst::Dispatcher
The following methods in Catalyst::Dispatcher are both an implementation
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
projects / catagits/Catalyst-Runtime.git / blobdiff