3 Catalyst::Manual::CatalystAndMoose - How Catalyst 5.8+ and Moose relate
8 Since version 5.8 the core of Catalyst is based on L<Moose>. Although
9 the developers went through great lengths to allow for a seamless
10 transition, there are still a few things to keep in mind when trying
11 to exploit the power of L<Moose> in your Catalyst application.
13 This document provides you with a short overview of common caveats and
14 best practices to use L<Moose>-based classes within Catalyst.
17 =head1 THE CONTEXT CLASS
19 A Moose-ified version of the context class should look like this:
26 $app->config( name => 'MyApp' );
28 # your roles and plugins
31 # method modifiers must be created after setup because otherwise they will
32 # conflict with plugin overrides
34 after 'finalize' => sub{
36 $c->log->info( 'done!' );
39 You should also be aware, that roles in C<< $c->setup >> are applied
40 after the last plugin with all the benefits of using a single C<<
41 with() >> statement in an ordinary L<Moose> class and that your class
42 is automatically made immutable for you after the call to setup
43 (method modifiers in your class will work, though).
45 CAVEAT: using roles in C<< $c->setup >> was implemented in Catalyst
46 version 5.80004. In prior versions you might get away with
48 after 'setup_plugins' => sub{ with(
56 but this is discouraged and you should upgrade to 5.80004 anyway,
57 because it fixes a few important regression against 5.71
59 [Q: COULD THIS BE USED TO RESOLVE CONFLICTS IN ROLES?].
64 Most of the request-specific attributes like C<$c->stash>,
65 C<$c->request> and C<$c->response> have been converted to
66 L<Moose> attributes but without type constraints, attribute helpers or
67 builder methods. This ensures that Catalyst 5.8 is fully backwards
68 compatible to applications using the published API of Catalyst 5.7 but
69 slightly limits the gains that could be had by wielding the full power
70 of L<Moose> attributes.
72 Most of the accessors to information gathered during compile time is
73 managed by C<Catalyst::ClassData>, which is a L<Moose>-aware version
74 of L<Class::Data::Inheritable> but not compatible with
75 L<MooseX::ClassAttribute>.
78 =head2 ROLES AND METHOD MODIFIERS
80 Since the release of Catalyst version 5.8 the only reason for creating
81 a Catalyst extension as a plugin is to provide backward compatibility
82 to applications still using version 5.7 but even then you should
83 consider building your plugin using L<Moose> and take advantage of
84 L<Moose::Manual::MethodModifiers|method modifiers> instead of
85 overriding methods to alter Catalyst's request lifecycle behavior.
87 If backward compatibility is of no concern to you, you could as easily
88 rewrite your plugins as roles and enjoy all the benefits of automatic
89 method re-dispatching of C<< before >> and C<< after >> method
90 modifiers, naming conflict detecting and generally cleaner code.
92 Plugins and roles should never use
94 after 'setup' => sub { ... } # wrong
98 after 'setup_finalize' => sub { ... } # this will work
100 to run their own setup code if needed. If they need to influence the
101 setup process itself, they can modify C<< setup_dispatcher() >>,
102 C<< setup_engine()>>, C<< setup_stats() >>, C<< setup_components() >>
103 and C<< setup_actions() >>, but this should be done with due
104 consideration and as late as possible.
109 To activate Catalyst's action attributes, Moose-ified controller
110 classes need to extend L<Catalyst::Controller> at compile time before
111 the actions themselves are declared:
113 package Catalyst::Controller::Root;
117 extends 'Catalyst::Controller';
119 # your controller roles