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; |
24 | use Catalyst; |
25 | |
26 | $app->config( name => 'MyApp' ); |
27 | $app->setup( |
28 | # your roles and plugins |
29 | ); |
30 | |
31 | # method modifiers must be created after setup because otherwise they will |
32 | # conflict with plugin overrides |
33 | |
34 | after 'finalize' => sub{ |
35 | my $c = shift; |
36 | $c->log->info( 'done!' ); |
37 | } |
38 | |
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). |
44 | |
45 | CAVEAT: using roles in C<< $c->setup >> was implemented in Catalyst |
46 | version 5.80004. In prior versions you might get away with |
47 | |
48 | after 'setup_plugins' => sub{ with( |
49 | # your roles |
50 | )}; |
51 | |
52 | $app->setup( |
53 | # your plugins |
54 | ); |
55 | |
56 | but this is discouraged and you should upgrade to 5.80004 anyway, |
57 | because it fixes a few important regression against 5.71 |
58 | |
59 | [Q: COULD THIS BE USED TO RESOLVE CONFLICTS IN ROLES?]. |
60 | |
61 | |
62 | =head2 ACCESSORS |
63 | |
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. |
71 | |
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>. |
76 | |
77 | |
78 | =head2 ROLES AND METHOD MODIFIERS |
79 | |
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. |
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() >>, |
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. |
105 | |
106 | |
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; |
114 | |
115 | use Moose; |
116 | BEGIN{ |
117 | extends 'Catalyst::Controller'; |
118 | with( |
119 | # your controller roles |
120 | ); |
121 | } |
122 | |
123 | [MORE TO BE DONE!] |