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 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;
  21
  22     use Moose;
  23     use namespace::autoclean;
  24     use Catalyst (
  25         # your roles and plugins
  26     );
  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
  32     $app->config( name => 'MyApp' );
  33     $app->setup;
  34
  35     # method modifiers generally must be created after setup because otherwise they will
  36     # conflict with plugin overrides
  37
  38     after 'finalize' => sub{
  39         my $c = shift;
  40         $c->log->info( 'done!' );
  41     }
  42
  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
  45 L<with()|Moose/"with (@roles)"> statement in an ordinary L<Moose> class.
  46
  47 Your class is automatically made immutable at the end of the current file.
  48
  49 CAVEAT: Using roles in C<< $c-E<gt>setup >> was implemented in Catalyst
  50 version 5.80004. In prior versions you might get away with
  51
  52     after 'setup_plugins' => sub{ with(
  53         # your roles
  54     )};
  55
  56     $app->setup(
  57         # your plugins
  58     );
  59
  60 but this is discouraged and you should upgrade to 5.80004 anyway,
  61 because it fixes a few important regressions against 5.71
  62
  63 CAVEAT: Using roles in C<< $c-E<gt>setup >> will not currently allow
  64 you to pass parameters to roles, or perform conflict resolution.
  65 Conflict detection still works as expected.
  66
  67
  68 =head2 ACCESSORS
  69
  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
  76 of L<Moose> attributes.
  77
  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
  81 L<MooseX::ClassAttribute>.
  82
  83 =head2 ROLES AND METHOD MODIFIERS
  84
  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
  87 to applications still using version 5.7.
  88
  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
  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
 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
 106 consideration and as late as possible.
 107
 108 =head1 CONTROLLERS
 109
 110 To activate Catalyst's action attributes, Moose-ified controller
 111 classes need to extend L<Catalyst::Controller> at compile time before
 112 the actions themselves are declared:
 113
 114       package Catalyst::Controller::Root;
 115       use Moose;
 116       use namespace::autoclean;
 117
 118       BEGIN { extends 'Catalyst::Controller'; }
 119       with qw(
 120                 # your controller roles
 121             );
 122
 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