use double bracketed formatting codes so < and > don't need to be escaped
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / CatalystAndMoose.pod
8a101890 1=head1 NAME
3Catalyst::Manual::CatalystAndMoose - How Catalyst 5.8+ and Moose relate
8a101890 5=head1 DESCRIPTION
46a5f2f5 7Since version 5.8, the core of Catalyst is based on L<Moose>. Although
b1a08fe1 8the developers went through great lengths to allow for a seamless
9transition, there are still a few things to keep in mind when trying
8a101890 10to exploit the power of L<Moose> in your Catalyst application.
b1a08fe1 12This document provides you with a short overview of common caveats and
46a5f2f5 13best practices for using L<Moose>-based classes within Catalyst.
8a101890 14
8a101890 15=head1 THE CONTEXT CLASS
17A Moose-ified version of the context class should look like this:
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';
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)
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 }
429d1caf 41You should also be aware that roles in C<< $c->setup >> are applied
b1a08fe1 42after the last plugin with all the benefits of using a single
ad60b48b 43L<with()|Moose/"with (@roles)"> statement in an ordinary L<Moose> class.
4d719c7e 44
b1a08fe1 45Your class is automatically made immutable at the end of the current file.
8a101890 46
429d1caf 47CAVEAT: Using roles in C<< $c->setup >> was implemented in Catalyst
8a101890 48version 5.80004. In prior versions you might get away with
50 after 'setup_plugins' => sub{ with(
51 # your roles
52 )};
b1a08fe1 53
8a101890 54 $app->setup(
55 # your plugins
56 );
b1a08fe1 58but this is discouraged and you should upgrade to 5.80004 anyway,
59because it fixes a few important regressions against 5.71
8a101890 60
429d1caf 61CAVEAT: Using roles in C<< $c->setup >> will not currently allow
4d719c7e 62you to pass parameters to roles, or perform conflict resolution.
63Conflict detection still works as expected.
8a101890 64
65=head2 ACCESSORS
429d1caf 67Most of the request-specific attributes like C<< $c->stash >>,
68C<< $c->request >> and C<< $c->response >> have been converted to
b1a08fe1 69L<Moose> attributes but without type constraints, attribute helpers or
70builder methods. This ensures that Catalyst 5.8 is fully backwards
71compatible to applications using the published API of Catalyst 5.7 but
72slightly limits the gains that could be had by wielding the full power
8a101890 73of L<Moose> attributes.
e91e320b 75Most of the accessors to information gathered during compile time (such
7ce05098 76as configuration) are managed by C<Catalyst::ClassData>, which is a
e91e320b 77L<Moose>-aware version of L<Class::Data::Inheritable> but not compatible
78with L<MooseX::ClassAttribute>.
8a101890 79
b1a08fe1 82Since the release of Catalyst version 5.8, the only reason for creating
83a Catalyst extension as a plugin is to provide backward compatibility
4d719c7e 84to applications still using version 5.7.
8a101890 85
b1a08fe1 86If backward compatibility is of no concern to you, you could as easily
87rewrite your plugins as roles and enjoy all the benefits of automatic
88method re-dispatching of C<< before >> and C<< after >> method
e91e320b 89modifiers, naming conflict detection and generally cleaner code.
91=head3 NOTE
8a101890 92
93Plugins and roles should never use
95 after 'setup' => sub { ... } # wrong
e91e320b 97(or any other method of hooking the setup method) but rely on
8a101890 98
99 after 'setup_finalize' => sub { ... } # this will work
b1a08fe1 101to run their own setup code if needed. If they need to influence the
102setup process itself, they can modify C<< setup_dispatcher() >>,
103C<< setup_engine() >>, C<< setup_stats() >>, C<< setup_components() >>
104and C<< setup_actions() >>, but this should be done with due
8a101890 105consideration and as late as possible.
8a101890 107=head1 CONTROLLERS
b1a08fe1 109To activate Catalyst's action attributes, Moose-ified controller
e91e320b 110classes need to extend L<Catalyst::Controller> at compile time, before
8a101890 111the actions themselves are declared:
113 package Catalyst::Controller::Root;
8a101890 114 use Moose;
4d719c7e 115 use namespace::autoclean;
117 BEGIN { extends 'Catalyst::Controller'; }
7ce05098 118
4d719c7e 119=head2 Controller Roles
121It is possible to use roles to apply method modifiers on controller actions
e91e320b 122from 5.80003 onwards, or use modifiers in your controller classes
123themselves. For example
9163f592 125 package MyApp::Controller::Foo;
126 use Moose;
127 use namespace::autoclean;
128 BEGIN { extends 'Catalyst::Controller' };
7ce05098 129
130 sub foo : Local {
9163f592 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 };
7ce05098 138
4d719c7e 139It is possible to have action methods with attributes inside Moose roles, using
2ad51a61 140L<MooseX::MethodAttributes>, example:
4d719c7e 141
142 package MyApp::ControllerRole;
5524259c 143 use MooseX::MethodAttributes::Role;
4d719c7e 144 use namespace::autoclean;
7ce05098 145
4d719c7e 146 sub foo : Local {
147 my ($self, $c) = @_;
148 ...
149 }
7ce05098 150
9163f592 151 package MyApp::Controller::Foo;
152 use Moose;
153 use namespace::autoclean;
154 BEGIN { extends 'Catalyst::Controller' };
7ce05098 155
9163f592 156 with 'MyApp::ControllerRole';
4d719c7e 157
bbddff00 158=head1 AUTHORS
e91e320b 159
bbddff00 160Catalyst Contributors, see
e91e320b 161
162=head1 COPYRIGHT
bbddff00 164This library is free software. You can redistribute it and/or modify it under
165the same terms as Perl itself.