.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Catalyst::Manual::CatalystAndMoose 3pm"
.TH Catalyst::Manual::CatalystAndMoose 3pm "2013-05-06" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catalyst::Manual::CatalystAndMoose \- How Catalyst 5.8+ and Moose relate
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Since version 5.8, the core of Catalyst is based on Moose. Although
the developers went through great lengths to allow for a seamless
transition, there are still a few things to keep in mind when trying
to exploit the power of Moose in your Catalyst application.
.PP
This document provides you with a short overview of common caveats and
best practices for using Moose\-based classes within Catalyst.
.SH "THE CONTEXT CLASS"
.IX Header "THE CONTEXT CLASS"
A Moose-ified version of the context class should look like this:
.PP
.Vb 7
\&    package MyApp;
\&    use Moose;
\&    use namespace::autoclean;
\&    use Catalyst (
\&        # your roles and plugins
\&    );
\&    extends \*(AqCatalyst\*(Aq;
\&
\&    # If you want to use method modifiers to adjust the setup process, (e.g. setup_finalize)
\&    # they must be here, before the call to setup (advanced users only)
\&
\&    $app\->config( name => \*(AqMyApp\*(Aq );
\&    $app\->setup;
\&
\&    # method modifiers generally must be created after setup because otherwise they will
\&    # conflict with plugin overrides
\&
\&    after \*(Aqfinalize\*(Aq => sub {
\&        my $c = shift;
\&        $c\->log\->info( \*(Aqdone!\*(Aq );
\&    }
.Ve
.PP
You should also be aware that roles in \f(CW\*(C`$c\->setup\*(C'\fR are applied
after the last plugin with all the benefits of using a single
\&\fIwith()\fR statement in an ordinary Moose class.
.PP
Your class is automatically made immutable at the end of the current file.
.PP
\&\s-1CAVEAT:\s0 Using roles in \f(CW\*(C`$c\->setup\*(C'\fR was implemented in Catalyst
version 5.80004. In prior versions you might get away with
.PP
.Vb 3
\&    after \*(Aqsetup_plugins\*(Aq => sub{ with(
\&        # your roles
\&    )};
\&
\&    $app\->setup(
\&        # your plugins
\&    );
.Ve
.PP
but this is discouraged and you should upgrade to 5.80004 anyway,
because it fixes a few important regressions against 5.71
.PP
\&\s-1CAVEAT:\s0 Using roles in \f(CW\*(C`$c\->setup\*(C'\fR will not currently allow
you to pass parameters to roles, or perform conflict resolution.
Conflict detection still works as expected.
.SS "\s-1ACCESSORS\s0"
.IX Subsection "ACCESSORS"
Most of the request-specific attributes like \f(CW\*(C`$c\->stash\*(C'\fR,
\&\f(CW\*(C`$c\->request\*(C'\fR and \f(CW\*(C`$c\->response\*(C'\fR have been converted to
Moose attributes but without type constraints, attribute helpers or
builder methods. This ensures that Catalyst 5.8 is fully backwards
compatible to applications using the published \s-1API\s0 of Catalyst 5.7 but
slightly limits the gains that could be had by wielding the full power
of Moose attributes.
.PP
Most of the accessors to information gathered during compile time (such
as configuration) are managed by \f(CW\*(C`Catalyst::ClassData\*(C'\fR, which is a 
Moose\-aware version of Class::Data::Inheritable but not compatible
with MooseX::ClassAttribute.
.SS "\s-1ROLES AND METHOD MODIFIERS\s0"
.IX Subsection "ROLES AND METHOD MODIFIERS"
Since the release of Catalyst version 5.8, the only reason for creating
a Catalyst extension as a plugin is to provide backward compatibility
to applications still using version 5.7.
.PP
If backward compatibility is of no concern to you, you could as easily
rewrite your plugins as roles and enjoy all the benefits of automatic
method re-dispatching of \f(CW\*(C`before\*(C'\fR and \f(CW\*(C`after\*(C'\fR method
modifiers, naming conflict detection and generally cleaner code.
.PP
\fI\s-1NOTE\s0\fR
.IX Subsection "NOTE"
.PP
Plugins and roles should never use
.PP
.Vb 1
\&    after \*(Aqsetup\*(Aq => sub { ... } # wrong
.Ve
.PP
(or any other method of hooking the setup method) but rely on
.PP
.Vb 1
\&    after \*(Aqsetup_finalize\*(Aq => sub { ... } # this will work
.Ve
.PP
to run their own setup code if needed. If they need to influence the
setup process itself, they can modify \f(CW\*(C`setup_dispatcher()\*(C'\fR,
\&\f(CW\*(C`setup_engine()\*(C'\fR, \f(CW\*(C`setup_stats()\*(C'\fR, \f(CW\*(C`setup_components()\*(C'\fR
and \f(CW\*(C`setup_actions()\*(C'\fR, but this should be done with due
consideration and as late as possible.
.SH "CONTROLLERS"
.IX Header "CONTROLLERS"
To activate Catalyst's action attributes, Moose-ified controller
classes need to extend Catalyst::Controller at compile time, before
the actions themselves are declared:
.PP
.Vb 3
\&      package Catalyst::Controller::Root;
\&      use Moose;
\&      use namespace::autoclean;
\&
\&      BEGIN { extends \*(AqCatalyst::Controller\*(Aq; }
.Ve
.SS "Controller Roles"
.IX Subsection "Controller Roles"
It is possible to use roles to apply method modifiers on controller actions
from 5.80003 onwards, or use modifiers in your controller classes
themselves. For example
.PP
.Vb 4
\&    package MyApp::Controller::Foo;
\&    use Moose;
\&    use namespace::autoclean;
\&    BEGIN { extends \*(AqCatalyst::Controller\*(Aq };
\&    
\&    sub foo : Local { 
\&        my ($self, $c) = @_;
\&        $c\->res\->body(\*(AqHello \*(Aq);
\&    }
\&    after foo => sub {
\&        my ($self, $c) = @_;
\&        $c\->res\->body($c\->res\->body . \*(AqWorld\*(Aq);
\&    };
.Ve
.PP
It is possible to have action methods with attributes inside Moose roles, using
MooseX::MethodAttributes, example:
.PP
.Vb 3
\&    package MyApp::ControllerRole;
\&    use MooseX::MethodAttributes::Role;
\&    use namespace::autoclean;
\&    
\&    sub foo : Local {
\&        my ($self, $c) = @_;
\&        ...
\&    }
\&    
\&    package MyApp::Controller::Foo;
\&    use Moose;
\&    use namespace::autoclean;
\&    BEGIN { extends \*(AqCatalyst::Controller\*(Aq };
\&    
\&    with \*(AqMyApp::ControllerRole\*(Aq;
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
Catalyst Contributors, see Catalyst.pm
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This library is free software. You can redistribute it and/or modify it under
the same terms as Perl itself.