lib/Catalyst/Manual/CatalystAndMoose.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::CatalystAndMoose - How Catalyst 5.8+ and Moose relate
   4
   5 =head1 DESCRIPTION
   6
   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
  10 to exploit the power of L<Moose> in your Catalyst application.
  11
  12 This document provides you with a short overview of common caveats and
  13 best practices for using L<Moose>-based classes within Catalyst.
  14
  15 =head1 THE CONTEXT CLASS
  16
  17 A Moose-ified version of the context class should look like this:
  18
  19     package MyApp;
  20     use Moose;
  21     use namespace::autoclean;
  22     use Catalyst (
  23         # your roles and plugins
  24     );
  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
  30     $app->config( name => 'MyApp' );
  31     $app->setup;
  32
  33     # method modifiers generally must be created after setup because otherwise they will
  34     # conflict with plugin overrides
  35
  36     after 'finalize' => sub {
  37         my $c = shift;
  38         $c->log->info( 'done!' );
  39     }
  40
  41 You should also be aware that roles in C<< $c-E<gt>setup >> are applied
  42 after the last plugin with all the benefits of using a single
  43 L<with()|Moose/"with (@roles)"> statement in an ordinary L<Moose> class.
  44
  45 Your class is automatically made immutable at the end of the current file.
  46
  47 CAVEAT: Using roles in C<< $c-E<gt>setup >> was implemented in Catalyst
  48 version 5.80004. In prior versions you might get away with
  49
  50     after 'setup_plugins' => sub{ with(
  51         # your roles
  52     )};
  53
  54     $app->setup(
  55         # your plugins
  56     );
  57
  58 but this is discouraged and you should upgrade to 5.80004 anyway,
  59 because it fixes a few important regressions against 5.71
  60
  61 CAVEAT: Using roles in C<< $c-E<gt>setup >> will not currently allow
  62 you to pass parameters to roles, or perform conflict resolution.
  63 Conflict detection still works as expected.
  64
  65 =head2 ACCESSORS
  66
  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
  73 of L<Moose> attributes.
  74
  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>.
  79
  80 =head2 ROLES AND METHOD MODIFIERS
  81
  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
  84 to applications still using version 5.7.
  85
  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
  89 modifiers, naming conflict detection and generally cleaner code.
  90
  91 =head3 NOTE
  92
  93 Plugins and roles should never use
  94
  95     after 'setup' => sub { ... } # wrong
  96
  97 (or any other method of hooking the setup method) but rely on
  98
  99     after 'setup_finalize' => sub { ... } # this will work
 100
 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
 105 consideration and as late as possible.
 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       use Moose;
 115       use namespace::autoclean;
 116
 117       BEGIN { extends 'Catalyst::Controller'; }
 118
 119 =head2 Controller Roles
 120
 121 It is possible to use roles to apply method modifiers on controller actions
 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
 139 It is possible to have action methods with attributes inside Moose roles, using
 140 the trait introduced in L<MooseX::MethodAttributes> version 0.12, example:
 141
 142     package MyApp::ControllerRole;
 143     use Moose::Role -traits => 'MethodAttributes';
 144     use namespace::autoclean;
 145
 146     sub foo : Local {
 147         my ($self, $c) = @_;
 148         ...
 149     }
 150
 151         package MyApp::Controller::Foo;
 152         use Moose;
 153         use namespace::autoclean;
 154         BEGIN { extends 'Catalyst::Controller' };
 155
 156         with 'MyApp::ControllerRole';
 157
 158 =head1 AUTHORS
 159
 160 Catalyst Contributors, see Catalyst.pm
 161
 162 =head1 COPYRIGHT
 163
 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