3 Catalyst::Manual::CatalystAndMoose - How Catalyst 5.8+ and Moose relate
7 Since version 5.8, the core of Catalyst is based on L<Moose>. Although
8 the developers went through great lengths to allow for a seamless
9 transition, there are still a few things to keep in mind when trying
10 to exploit the power of L<Moose> in your Catalyst application.
12 This document provides you with a short overview of common caveats and
13 best practices for using L<Moose>-based classes within Catalyst.
15 =head1 THE CONTEXT CLASS
17 A Moose-ified version of the context class should look like this:
21 use namespace::autoclean;
23 # your roles and plugins
27 # If you want to use method modifiers to adjust the setup process, (e.g. setup_finalize)
28 # they must be here, before the call to setup (advanced users only)
30 $app->config( name => 'MyApp' );
33 # method modifiers generally must be created after setup because otherwise they will
34 # conflict with plugin overrides
36 after 'finalize' => sub {
38 $c->log->info( 'done!' );
41 You should also be aware that roles in C<< $c-E<gt>setup >> are applied
42 after the last plugin with all the benefits of using a single
43 L<with()|Moose/"with (@roles)"> statement in an ordinary L<Moose> class.
45 Your class is automatically made immutable at the end of the current file.
47 CAVEAT: Using roles in C<< $c-E<gt>setup >> was implemented in Catalyst
48 version 5.80004. In prior versions you might get away with
50 after 'setup_plugins' => sub{ with(
58 but this is discouraged and you should upgrade to 5.80004 anyway,
59 because it fixes a few important regressions against 5.71
61 CAVEAT: Using roles in C<< $c-E<gt>setup >> will not currently allow
62 you to pass parameters to roles, or perform conflict resolution.
63 Conflict detection still works as expected.
67 Most of the request-specific attributes like C<$c-E<gt>stash>,
68 C<$c-E<gt>request> and C<$c-E<gt>response> have been converted to
69 L<Moose> attributes but without type constraints, attribute helpers or
70 builder methods. This ensures that Catalyst 5.8 is fully backwards
71 compatible to applications using the published API of Catalyst 5.7 but
72 slightly limits the gains that could be had by wielding the full power
73 of L<Moose> attributes.
75 Most of the accessors to information gathered during compile time (such
76 as configuration) are managed by C<Catalyst::ClassData>, which is a
77 L<Moose>-aware version of L<Class::Data::Inheritable> but not compatible
78 with L<MooseX::ClassAttribute>.
80 =head2 ROLES AND METHOD MODIFIERS
82 Since the release of Catalyst version 5.8, the only reason for creating
83 a Catalyst extension as a plugin is to provide backward compatibility
84 to applications still using version 5.7.
86 If backward compatibility is of no concern to you, you could as easily
87 rewrite your plugins as roles and enjoy all the benefits of automatic
88 method re-dispatching of C<< before >> and C<< after >> method
89 modifiers, naming conflict detection and generally cleaner code.
93 Plugins and roles should never use
95 after 'setup' => sub { ... } # wrong
97 (or any other method of hooking the setup method) but rely on
99 after 'setup_finalize' => sub { ... } # this will work
101 to run their own setup code if needed. If they need to influence the
102 setup process itself, they can modify C<< setup_dispatcher() >>,
103 C<< setup_engine() >>, C<< setup_stats() >>, C<< setup_components() >>
104 and C<< setup_actions() >>, but this should be done with due
105 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;
115 use namespace::autoclean;
117 BEGIN { extends 'Catalyst::Controller'; }
119 =head2 Controller Roles
121 It is possible to use roles to apply method modifiers on controller actions
122 from 5.80003 onwards, or use modifiers in your controller classes
123 themselves. For example
125 package MyApp::Controller::Foo;
127 use namespace::autoclean;
128 BEGIN { extends 'Catalyst::Controller' };
132 $c->res->body('Hello ');
136 $c->res->body($c->res->body . 'World');
139 It is possible to have action methods with attributes inside Moose roles, using
140 L<MooseX::MethodAttributes>, example:
142 package MyApp::ControllerRole;
143 use MooseX::MethodAttributes::Role;
144 use namespace::autoclean;
151 package MyApp::Controller::Foo;
153 use namespace::autoclean;
154 BEGIN { extends 'Catalyst::Controller' };
156 with 'MyApp::ControllerRole';
160 Catalyst Contributors, see Catalyst.pm
164 This library is free software. You can redistribute it and/or modify it under
165 the same terms as Perl itself.