Commit | Line | Data |
8a101890 |
1 | =head1 NAME |
2 | |
3 | Catalyst::Manual::CatalystAndMoose - How Catalyst 5.8+ and Moose relate |
4 | |
8a101890 |
5 | =head1 DESCRIPTION |
6 | |
46a5f2f5 |
7 | Since version 5.8, the core of Catalyst is based on L<Moose>. Although |
b1a08fe1 |
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 |
8a101890 |
10 | to exploit the power of L<Moose> in your Catalyst application. |
11 | |
b1a08fe1 |
12 | This document provides you with a short overview of common caveats and |
46a5f2f5 |
13 | best practices for using L<Moose>-based classes within Catalyst. |
8a101890 |
14 | |
8a101890 |
15 | =head1 THE CONTEXT CLASS |
16 | |
17 | A Moose-ified version of the context class should look like this: |
18 | |
19 | package MyApp; |
8a101890 |
20 | use Moose; |
4d719c7e |
21 | use namespace::autoclean; |
22 | use Catalyst ( |
8a101890 |
23 | # your roles and plugins |
24 | ); |
b1a08fe1 |
25 | extends 'Catalyst'; |
26 | |
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) |
29 | |
4d719c7e |
30 | $app->config( name => 'MyApp' ); |
31 | $app->setup; |
b1a08fe1 |
32 | |
33 | # method modifiers generally must be created after setup because otherwise they will |
8a101890 |
34 | # conflict with plugin overrides |
b1a08fe1 |
35 | |
e91e320b |
36 | after 'finalize' => sub { |
8a101890 |
37 | my $c = shift; |
38 | $c->log->info( 'done!' ); |
39 | } |
40 | |
e91e320b |
41 | You should also be aware that roles in C<< $c-E<gt>setup >> are applied |
b1a08fe1 |
42 | after the last plugin with all the benefits of using a single |
ad60b48b |
43 | L<with()|Moose/"with (@roles)"> statement in an ordinary L<Moose> class. |
4d719c7e |
44 | |
b1a08fe1 |
45 | Your class is automatically made immutable at the end of the current file. |
8a101890 |
46 | |
b1a08fe1 |
47 | CAVEAT: Using roles in C<< $c-E<gt>setup >> was implemented in Catalyst |
8a101890 |
48 | version 5.80004. In prior versions you might get away with |
49 | |
50 | after 'setup_plugins' => sub{ with( |
51 | # your roles |
52 | )}; |
b1a08fe1 |
53 | |
8a101890 |
54 | $app->setup( |
55 | # your plugins |
56 | ); |
57 | |
b1a08fe1 |
58 | but this is discouraged and you should upgrade to 5.80004 anyway, |
59 | because it fixes a few important regressions against 5.71 |
8a101890 |
60 | |
f68b710f |
61 | CAVEAT: Using roles in C<< $c-E<gt>setup >> will not currently allow |
4d719c7e |
62 | you to pass parameters to roles, or perform conflict resolution. |
63 | Conflict detection still works as expected. |
8a101890 |
64 | |
65 | =head2 ACCESSORS |
66 | |
b1a08fe1 |
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 |
8a101890 |
73 | of L<Moose> attributes. |
74 | |
e91e320b |
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>. |
8a101890 |
79 | |
8a101890 |
80 | =head2 ROLES AND METHOD MODIFIERS |
81 | |
b1a08fe1 |
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 |
4d719c7e |
84 | to applications still using version 5.7. |
8a101890 |
85 | |
b1a08fe1 |
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 |
e91e320b |
89 | modifiers, naming conflict detection and generally cleaner code. |
90 | |
91 | =head3 NOTE |
8a101890 |
92 | |
93 | Plugins and roles should never use |
94 | |
95 | after 'setup' => sub { ... } # wrong |
96 | |
e91e320b |
97 | (or any other method of hooking the setup method) but rely on |
8a101890 |
98 | |
99 | after 'setup_finalize' => sub { ... } # this will work |
100 | |
b1a08fe1 |
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 |
8a101890 |
105 | consideration and as late as possible. |
106 | |
8a101890 |
107 | =head1 CONTROLLERS |
108 | |
b1a08fe1 |
109 | To activate Catalyst's action attributes, Moose-ified controller |
e91e320b |
110 | classes need to extend L<Catalyst::Controller> at compile time, before |
8a101890 |
111 | the actions themselves are declared: |
112 | |
113 | package Catalyst::Controller::Root; |
8a101890 |
114 | use Moose; |
4d719c7e |
115 | use namespace::autoclean; |
116 | |
117 | BEGIN { extends 'Catalyst::Controller'; } |
e91e320b |
118 | |
4d719c7e |
119 | =head2 Controller Roles |
120 | |
121 | It is possible to use roles to apply method modifiers on controller actions |
e91e320b |
122 | from 5.80003 onwards, or use modifiers in your controller classes |
123 | themselves. For example |
124 | |
125 | package MyApp::Controller::Foo; |
126 | use Moose; |
127 | use namespace::autoclean; |
128 | BEGIN { extends 'Catalyst::Controller' }; |
129 | |
130 | sub foo : Local { |
131 | my ($self, $c) = @_; |
132 | $c->res->body('Hello '); |
133 | } |
134 | after foo => sub { |
135 | my ($self, $c) = @_; |
136 | $c->res->body($c->res->body . 'World'); |
137 | }; |
138 | |
4d719c7e |
139 | It is possible to have action methods with attributes inside Moose roles, using |
2ad51a61 |
140 | L<MooseX::MethodAttributes>, example: |
4d719c7e |
141 | |
142 | package MyApp::ControllerRole; |
2ad51a61 |
143 | use MooseX::MethodAttribute::Role; |
4d719c7e |
144 | use namespace::autoclean; |
145 | |
146 | sub foo : Local { |
147 | my ($self, $c) = @_; |
148 | ... |
149 | } |
150 | |
e91e320b |
151 | package MyApp::Controller::Foo; |
152 | use Moose; |
153 | use namespace::autoclean; |
154 | BEGIN { extends 'Catalyst::Controller' }; |
155 | |
156 | with 'MyApp::ControllerRole'; |
157 | |
bbddff00 |
158 | =head1 AUTHORS |
e91e320b |
159 | |
bbddff00 |
160 | Catalyst Contributors, see Catalyst.pm |
e91e320b |
161 | |
162 | =head1 COPYRIGHT |
163 | |
bbddff00 |
164 | This library is free software. You can redistribute it and/or modify it under |
165 | the same terms as Perl itself. |
166 | |
167 | =cut |
168 | |