Catalyst::Manual::CataUserAContributed PeCatalyst::Manual::CatalystAndMoose(3)NAMECatalyst::Manual::CatalystAndMoose - How Catalyst 5.8+ and Moose relate
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.
This document provides you with a short overview of common caveats and
best practices for using Moose-based classes within Catalyst.
THE CONTEXT CLASS
A Moose-ified version of the context class should look like this:
package MyApp;
use Moose;
use namespace::autoclean;
use Catalyst (
# your roles and plugins
);
extends 'Catalyst';
# 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 => 'MyApp' );
$app->setup;
# method modifiers generally must be created after setup because otherwise they will
# conflict with plugin overrides
after 'finalize' => sub {
my $c = shift;
$c->log->info( 'done!' );
}
You should also be aware that roles in "$c->setup" are applied after
the last plugin with all the benefits of using a single with()
statement in an ordinary Moose class.
Your class is automatically made immutable at the end of the current
file.
CAVEAT: Using roles in "$c->setup" was implemented in Catalyst version
5.80004. In prior versions you might get away with
after 'setup_plugins' => sub{ with(
# your roles
)};
$app->setup(
# your plugins
);
but this is discouraged and you should upgrade to 5.80004 anyway,
because it fixes a few important regressions against 5.71
CAVEAT: Using roles in "$c->setup" will not currently allow you to pass
parameters to roles, or perform conflict resolution. Conflict
detection still works as expected.
ACCESSORS
Most of the request-specific attributes like "$c->stash", "$c->request"
and "$c->response" 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 API of Catalyst 5.7 but slightly limits the gains that
could be had by wielding the full power of Moose attributes.
Most of the accessors to information gathered during compile time (such
as configuration) are managed by "Catalyst::ClassData", which is a
Moose-aware version of Class::Data::Inheritable but not compatible with
MooseX::ClassAttribute.
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.
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 "before" and "after" method modifiers, naming
conflict detection and generally cleaner code.
NOTE
Plugins and roles should never use
after 'setup' => sub { ... } # wrong
(or any other method of hooking the setup method) but rely on
after 'setup_finalize' => sub { ... } # this will work
to run their own setup code if needed. If they need to influence the
setup process itself, they can modify "setup_dispatcher()",
"setup_engine()", "setup_stats()", "setup_components()" and
"setup_actions()", but this should be done with due consideration and
as late as possible.
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:
package Catalyst::Controller::Root;
use Moose;
use namespace::autoclean;
BEGIN { extends 'Catalyst::Controller'; }
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
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 MooseX::MethodAttributes, example:
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 'Catalyst::Controller' };
with 'MyApp::ControllerRole';
AUTHORS
Catalyst Contributors, see Catalyst.pm
COPYRIGHT
This library is free software. You can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.22011-02Catalyst::Manual::CatalystAndMoose(3)
