=head1 DESCRIPTION
-Since version 5.8 the core of Catalyst is based on L<Moose>. Although
+Since version 5.8, the core of Catalyst is based on L<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 L<Moose> in your Catalyst application.
This document provides you with a short overview of common caveats and
-best practices to use L<Moose>-based classes within Catalyst.
-
+best practices for using L<Moose>-based classes within Catalyst.
=head1 THE CONTEXT CLASS
A Moose-ified version of the context class should look like this:
package MyApp;
-
use Moose;
use namespace::autoclean;
use Catalyst (
# method modifiers generally must be created after setup because otherwise they will
# conflict with plugin overrides
- after 'finalize' => sub{
+ after 'finalize' => sub {
my $c = shift;
$c->log->info( 'done!' );
}
-You should also be aware, that roles in C<< $c-E<gt>setup >> are applied
+You should also be aware that roles in C<< $c-E<gt>setup >> are applied
after the last plugin with all the benefits of using a single
-C<< with() >> statement in an ordinary L<Moose> class.
+L<with()|Moose/"with (@roles)"> statement in an ordinary L<Moose> class.
Your class is automatically made immutable at the end of the current file.
you to pass parameters to roles, or perform conflict resolution.
Conflict detection still works as expected.
-
=head2 ACCESSORS
Most of the request-specific attributes like C<$c-E<gt>stash>,
slightly limits the gains that could be had by wielding the full power
of L<Moose> attributes.
-Most of the accessors to information gathered during compile time is
-managed by C<Catalyst::ClassData>, which is a L<Moose>-aware version
-of L<Class::Data::Inheritable> but not compatible with
-L<MooseX::ClassAttribute>.
+Most of the accessors to information gathered during compile time (such
+as configuration) are managed by C<Catalyst::ClassData>, which is a
+L<Moose>-aware version of L<Class::Data::Inheritable> but not compatible
+with L<MooseX::ClassAttribute>.
=head2 ROLES AND METHOD MODIFIERS
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 C<< before >> and C<< after >> method
-modifiers, naming conflict detecting and generally cleaner code.
+modifiers, naming conflict detection and generally cleaner code.
+
+=head3 NOTE
Plugins and roles should never use
after 'setup' => sub { ... } # wrong
-but rely on
+(or any other method of hooking the setup method) but rely on
after 'setup_finalize' => sub { ... } # this will work
=head1 CONTROLLERS
To activate Catalyst's action attributes, Moose-ified controller
-classes need to extend L<Catalyst::Controller> at compile time before
+classes need to extend L<Catalyst::Controller> at compile time, before
the actions themselves are declared:
package Catalyst::Controller::Root;
use namespace::autoclean;
BEGIN { extends 'Catalyst::Controller'; }
- with qw(
- # your controller roles
- );
-
+
=head2 Controller Roles
It is possible to use roles to apply method modifiers on controller actions
-from 5.80003 onwards, or use modifiers in actions in your controller classes
-themselves.
+from 5.80003 onwards, or use modifiers in your controller classes
+themselves. For example
+ package MyApp::Controller::Foo;
+ use Moose;
+ use namespace::autoclean;
+ BEGIN { extends 'Catalyst::Controller' };
+
+ sub foo : Local {
+ my ($self, $c) = @_;
+ $c->res->body('Hello ');
+ }
+ after foo => sub {
+ my ($self, $c) = @_;
+ $c->res->body($c->res->body . 'World');
+ };
+
It is possible to have action methods with attributes inside Moose roles, using
-the trait introduced in L<MooseX::MethodAttributes> version 0.12, example:
+L<MooseX::MethodAttributes>, example:
package MyApp::ControllerRole;
- use Moose::Role -traits => 'MethodAttributes';
+ use MooseX::MethodAttributes::Role;
use namespace::autoclean;
-
+
sub foo : Local {
my ($self, $c) = @_;
...
}
+
+ package MyApp::Controller::Foo;
+ use Moose;
+ use namespace::autoclean;
+ BEGIN { extends 'Catalyst::Controller' };
+
+ with 'MyApp::ControllerRole';
+
+=head1 AUTHORS
+
+Catalyst Contributors, see Catalyst.pm
+
+=head1 COPYRIGHT
+
+This library is free software. You can redistribute it and/or modify it under
+the same terms as Perl itself.
+
+=cut