lib/Catalyst/Manual/CatalystAndMoose.pod

   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-&gt;stash>,
  65 C<$c-&gt;request> and C<$c-&gt;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!]