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 | |
b1a08fe1 |
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 |
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 |
8a101890 |
13 | best practices to use L<Moose>-based classes within Catalyst. |
14 | |
15 | |
16 | =head1 THE CONTEXT CLASS |
17 | |
18 | A Moose-ified version of the context class should look like this: |
19 | |
20 | package MyApp; |
b1a08fe1 |
21 | |
8a101890 |
22 | use Moose; |
4d719c7e |
23 | use namespace::autoclean; |
24 | use Catalyst ( |
8a101890 |
25 | # your roles and plugins |
26 | ); |
b1a08fe1 |
27 | extends 'Catalyst'; |
28 | |
29 | # If you want to use method modifiers to adjust the setup process, (e.g. setup_finalize) |
30 | # they must be here, before the call to setup (advanced users only) |
31 | |
4d719c7e |
32 | $app->config( name => 'MyApp' ); |
33 | $app->setup; |
b1a08fe1 |
34 | |
35 | # method modifiers generally must be created after setup because otherwise they will |
8a101890 |
36 | # conflict with plugin overrides |
b1a08fe1 |
37 | |
8a101890 |
38 | after 'finalize' => sub{ |
39 | my $c = shift; |
40 | $c->log->info( 'done!' ); |
41 | } |
42 | |
b1a08fe1 |
43 | You should also be aware, that roles in C<< $c-E<gt>setup >> are applied |
44 | after the last plugin with all the benefits of using a single |
f68b710f |
45 | C<< with() >> statement in an ordinary L<Moose> class. |
4d719c7e |
46 | |
b1a08fe1 |
47 | Your class is automatically made immutable at the end of the current file. |
8a101890 |
48 | |
b1a08fe1 |
49 | CAVEAT: Using roles in C<< $c-E<gt>setup >> was implemented in Catalyst |
8a101890 |
50 | version 5.80004. In prior versions you might get away with |
51 | |
52 | after 'setup_plugins' => sub{ with( |
53 | # your roles |
54 | )}; |
b1a08fe1 |
55 | |
8a101890 |
56 | $app->setup( |
57 | # your plugins |
58 | ); |
59 | |
b1a08fe1 |
60 | but this is discouraged and you should upgrade to 5.80004 anyway, |
61 | because it fixes a few important regressions against 5.71 |
8a101890 |
62 | |
f68b710f |
63 | CAVEAT: Using roles in C<< $c-E<gt>setup >> will not currently allow |
4d719c7e |
64 | you to pass parameters to roles, or perform conflict resolution. |
65 | Conflict detection still works as expected. |
8a101890 |
66 | |
f68b710f |
67 | |
8a101890 |
68 | =head2 ACCESSORS |
69 | |
b1a08fe1 |
70 | Most of the request-specific attributes like C<$c-E<gt>stash>, |
71 | C<$c-E<gt>request> and C<$c-E<gt>response> have been converted to |
72 | L<Moose> attributes but without type constraints, attribute helpers or |
73 | builder methods. This ensures that Catalyst 5.8 is fully backwards |
74 | compatible to applications using the published API of Catalyst 5.7 but |
75 | slightly limits the gains that could be had by wielding the full power |
8a101890 |
76 | of L<Moose> attributes. |
77 | |
b1a08fe1 |
78 | Most of the accessors to information gathered during compile time is |
79 | managed by C<Catalyst::ClassData>, which is a L<Moose>-aware version |
80 | of L<Class::Data::Inheritable> but not compatible with |
8a101890 |
81 | L<MooseX::ClassAttribute>. |
82 | |
8a101890 |
83 | =head2 ROLES AND METHOD MODIFIERS |
84 | |
b1a08fe1 |
85 | Since the release of Catalyst version 5.8, the only reason for creating |
86 | a Catalyst extension as a plugin is to provide backward compatibility |
4d719c7e |
87 | to applications still using version 5.7. |
8a101890 |
88 | |
b1a08fe1 |
89 | If backward compatibility is of no concern to you, you could as easily |
90 | rewrite your plugins as roles and enjoy all the benefits of automatic |
91 | method re-dispatching of C<< before >> and C<< after >> method |
8a101890 |
92 | modifiers, naming conflict detecting and generally cleaner code. |
93 | |
94 | Plugins and roles should never use |
95 | |
96 | after 'setup' => sub { ... } # wrong |
97 | |
98 | but rely on |
99 | |
100 | after 'setup_finalize' => sub { ... } # this will work |
101 | |
b1a08fe1 |
102 | to run their own setup code if needed. If they need to influence the |
103 | setup process itself, they can modify C<< setup_dispatcher() >>, |
104 | C<< setup_engine() >>, C<< setup_stats() >>, C<< setup_components() >> |
105 | and C<< setup_actions() >>, but this should be done with due |
8a101890 |
106 | consideration and as late as possible. |
107 | |
8a101890 |
108 | =head1 CONTROLLERS |
109 | |
b1a08fe1 |
110 | To activate Catalyst's action attributes, Moose-ified controller |
111 | classes need to extend L<Catalyst::Controller> at compile time before |
8a101890 |
112 | the actions themselves are declared: |
113 | |
114 | package Catalyst::Controller::Root; |
8a101890 |
115 | use Moose; |
4d719c7e |
116 | use namespace::autoclean; |
117 | |
118 | BEGIN { extends 'Catalyst::Controller'; } |
b1a08fe1 |
119 | with qw( |
8a101890 |
120 | # your controller roles |
121 | ); |
8a101890 |
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 | |