Commit | Line | Data |
8a101890 |
1 | =head1 NAME |
2 | |
3 | Catalyst::Manual::CatalystAndMoose - How Catalyst 5.8+ and Moose relate |
4 | |
5 | |
6 | =head1 DESCRIPTION |
7 | |
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. |
12 | |
13 | This document provides you with a short overview of common caveats and |
14 | best practices to use L<Moose>-based classes within Catalyst. |
15 | |
16 | |
17 | =head1 THE CONTEXT CLASS |
18 | |
19 | A Moose-ified version of the context class should look like this: |
20 | |
21 | package MyApp; |
22 | |
23 | use Moose; |
4d719c7e |
24 | use namespace::autoclean; |
25 | use Catalyst ( |
8a101890 |
26 | # your roles and plugins |
27 | ); |
28 | |
4d719c7e |
29 | $app->config( name => 'MyApp' ); |
30 | $app->setup; |
31 | |
8a101890 |
32 | # method modifiers must be created after setup because otherwise they will |
33 | # conflict with plugin overrides |
34 | |
35 | after 'finalize' => sub{ |
36 | my $c = shift; |
37 | $c->log->info( 'done!' ); |
38 | } |
39 | |
f68b710f |
40 | You should also be aware, that roles in C<< $c-E<gt>setup >> are applied |
41 | after the last plugin with all the benefits of using a single |
42 | C<< with() >> statement in an ordinary L<Moose> class. |
4d719c7e |
43 | |
44 | Your class is automatically made immutable at the end of the current file. |
8a101890 |
45 | |
f68b710f |
46 | CAVEAT: Using roles in C<< $c-E<gt>setup >> was implemented in Catalyst |
8a101890 |
47 | version 5.80004. In prior versions you might get away with |
48 | |
49 | after 'setup_plugins' => sub{ with( |
50 | # your roles |
51 | )}; |
52 | |
53 | $app->setup( |
54 | # your plugins |
55 | ); |
56 | |
57 | but this is discouraged and you should upgrade to 5.80004 anyway, |
58 | because it fixes a few important regression against 5.71 |
59 | |
f68b710f |
60 | CAVEAT: Using roles in C<< $c-E<gt>setup >> will not currently allow |
4d719c7e |
61 | you to pass parameters to roles, or perform conflict resolution. |
62 | Conflict detection still works as expected. |
8a101890 |
63 | |
f68b710f |
64 | |
8a101890 |
65 | =head2 ACCESSORS |
66 | |
f68b710f |
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 |
8a101890 |
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. |
74 | |
75 | Most of the accessors to information gathered during compile time is |
76 | managed by C<Catalyst::ClassData>, which is a L<Moose>-aware version |
77 | of L<Class::Data::Inheritable> but not compatible with |
78 | L<MooseX::ClassAttribute>. |
79 | |
80 | |
81 | =head2 ROLES AND METHOD MODIFIERS |
82 | |
83 | Since the release of Catalyst version 5.8 the only reason for creating |
84 | a Catalyst extension as a plugin is to provide backward compatibility |
4d719c7e |
85 | to applications still using version 5.7. |
8a101890 |
86 | |
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. |
91 | |
92 | Plugins and roles should never use |
93 | |
94 | after 'setup' => sub { ... } # wrong |
95 | |
96 | but rely on |
97 | |
98 | after 'setup_finalize' => sub { ... } # this will work |
99 | |
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() >>, |
f68b710f |
102 | C<< setup_engine() >>, C<< setup_stats() >>, C<< setup_components() >> |
8a101890 |
103 | and C<< setup_actions() >>, but this should be done with due |
104 | consideration and as late as possible. |
105 | |
f68b710f |
106 | |
8a101890 |
107 | =head1 CONTROLLERS |
108 | |
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: |
112 | |
113 | package Catalyst::Controller::Root; |
8a101890 |
114 | use Moose; |
4d719c7e |
115 | use namespace::autoclean; |
116 | |
117 | BEGIN { extends 'Catalyst::Controller'; } |
118 | with qw( |
8a101890 |
119 | # your controller roles |
120 | ); |
8a101890 |
121 | |
f68b710f |
122 | |
4d719c7e |
123 | =head2 Controller Roles |
124 | |
125 | It is possible to use roles to apply method modifiers on controller actions |
126 | from 5.80003 onwards, or use modifiers in actions in your controller classes |
127 | themselves. |
128 | |
129 | It is possible to have action methods with attributes inside Moose roles, using |
130 | the trait introduced in L<MooseX::MethodAttributes> version 0.12, example: |
131 | |
132 | package MyApp::ControllerRole; |
133 | use Moose::Role -traits => 'MethodAttributes'; |
134 | use namespace::autoclean; |
135 | |
136 | sub foo : Local { |
137 | my ($self, $c) = @_; |
138 | ... |
139 | } |
140 | |