=item Use the C<CatalystX::*> namespace if you can!
-If your extension isn't a Model, View, Controller, Plugin, or Engine,
-it's best to leave it out of the C<Catalyst::> namespace. Use
-<CatalystX::> instead.
+If your extension isn't a Model, View, Controller, Plugin, Engine,
+or Log, it's best to leave it out of the C<Catalyst::> namespace.
+Use <CatalystX::> instead.
=item Don't make it a plugin unless you have to!
If your plugin doesn't really need to muck with the internals, make it a
base Controller or Model.
+Also, if you think you really need a plugin, please instead consider
+using a L<Moose::Role>.
+
=item There's a community. Use it!
There are many experienced developers in the Catalyst community,
in the C<Catalyst::*> namespace, the Catalyst core would like to ask
developers to use the C<CatalystX::*> namespace if possible.
+Please B<do not> invent components which are outside the well
+known C<Model>, C<View>, C<Controller> or C<Plugin> namespaces!
+
When you try to put a base class for a C<Model>, C<View> or
C<Controller> directly under your C<MyApp> directory as, for example,
C<MyApp::Controller::Foo>, you will have the problem that Catalyst
If you want the thinnest interface possible, take a look at
L<Catalyst::Model::Adaptor|Catalyst::Model::Adaptor>.
-=head2 Inheritance and overriding methods
+=head2 Using Moose roles to apply method modifiers
+
+Rather than having a complex set of base classes which you have to mixin
+via multiple inheritence, if your functionality is well structured, then
+it's possible to use the composability of L<Moose> roles, and method modifiers
+to hook onto to provide functionality.
-While Catalyst itself is still based on L<NEXT> (for multiple
-inheritance), extension developers are encouraged to use L<Class::C3>,
-which is what Catalyst will be switching to in some point in the
-future.
+For a simple example of this, see L<CatalystX::REPL>.
+
+=head2 Inheritance and overriding methods
When overriding a method, keep in mind that some day additionally
arguments may be provided to the method, if the last parameter is not
invocant off of C<@_> and assign the rest of the used arguments, so
you can pass your complete arguments to the original method via C<@_>:
- use Class::C3; ...
+ use MRO::Compat; ...
- sub foo { my $self = shift;
- my ($bar, $baz) = @_; # ... return
- $self->next::method(@_); }
+ sub foo {
+ my $self = shift;
+ my ($bar, $baz) = @_; # ... return
+ $self->next::method(@_);
+ }
If you would do the common
methods code. You can surround this by overriding the method in a
subclass:
- package Catalyst::Action::MyFoo; use strict;
+ package Catalyst::Action::MyFoo;
+ use strict;
- use Class::C3; use base 'Catalyst::Action';
+ use MRO::Compat;
+ use base 'Catalyst::Action';
sub execute {
my $self = shift;
}
1;
-We are using L<Class::C3> to re-dispatch to the original C<execute> method
-in the L<Catalyst::Action> class.
+We are using L<MRO::Compat> to ensure that you have the next::method
+call, from L<Class::C3> (in older perls), or natively (if you are using
+perl 5.10) to re-dispatch to the original C<execute> method in the
+L<Catalyst::Action> class.
The Catalyst dispatcher handles an incoming request and, depending
upon the dispatch type, will call the appropriate target or chain.
For example, the action class below will make the action only match on
Mondays:
- package Catalyst::Action::OnlyMondays; use strict;
+ package Catalyst::Action::OnlyMondays;
+ use strict;
- use Class::C3;
+ use MRO::Compat;
use base 'Catalyst::Action';
sub match {
When is a plugin suited to your task? Your code needs to be a
plugin to act upon or alter specific parts of Catalyst's request
-lifecycle. If your functionality needs to wrap some C<prepare_*> or
+lifecycle. If your functionality needs to change some C<prepare_*> or
C<finalize_*> stages, you won't get around a plugin.
+Note, if you just want to hook into such a stage, and run code before,
+or after it, then it is recommended that you use L<Moose>s method modifiers
+to do this.
+
Another valid target for a plugin architecture are things that
B<really> have to be globally available, like sessions or
authentication.
alter Catalyst's request lifecycle behaviour. Every method you
declare, every import in your package will be available as method on
the application and the context object. As an example, let's say you
-want Catalyst to warn you every time uri_for returned an undefined
-value, for example because you specified the wrong number of captures
-for the targeted action chain. You could do this with this simple
+want Catalyst to warn you every time uri_for was called without an action
+object as the first parameter, for example to test that all your chained
+uris are generated from actions (a recommended best practice).
+You could do this with this simple
implementation (excuse the lame class name, it's just an example):
package Catalyst::Plugin::UriforUndefWarning;
use strict;
- use Class::C3;
+ use Scalar::Util qw/blessed/;
+ use MRO::Compat;
sub uri_for {
my $c = shift;
my $uri = $c->next::method(@_);
- $c->log->warn( 'uri_for returned undef for:', join(', ', @_), );
+ $c->log->warn( 'uri_for with non action: ', join(', ', @_), )
+ if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action'));
return $uri;
}
1;
This would override Catalyst's C<uri_for> method and emit a C<warn>
-log entry containing the arguments that led to the undefined return
-value.
+log entry containing the arguments to uri_for.
+
+Please note this is not a practical example, as string URLs are fine for
+static content etc.
+
+A simple example like this is actually better as a L<Moose> role, for example:
+
+ package CatalystX::UriforUndefWarning;
+ use Moose::Role;
+ use namespace::clean -except => 'meta';
+
+ after 'uri_for' => sub {
+ my ($c, $arg) = @_;
+ $c->log->warn( 'uri_for with non action: ', join(', ', @_), )
+ if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action'));
+ return $uri;
+ };
=head2 Factory components with COMPONENT()
class' C<new> method to return the component object.
You can override this method and do and return whatever you want.
-However, you should use L<Class::C3> to forward to the original
-C<COMPONENT> method to merge the configuration of your component.
+However, you should use L<Class::C3> (via L<MRO::Compat>) to forward
+to the original C<COMPONENT> method to merge the configuration of
+your component.
Here is a stub C<COMPONENT> method:
use strict;
use base 'Catalyst::Component';
- use Class::C3;
+ use MRO::Compat;
sub COMPONENT {
my $class = shift;
- my ($app_class, $config) = @_;
-
- # do things here before instantiation my
- $obj = $self->next::method(@_);
- # do things to object after instantiation
- return $object;
+ # Note: $app is like $c, but since the application isn't fully
+ # initialized, we don't want to call it $c yet. $config
+ # is a hashref of config options possibly set on this component.
+ my ($app, $config) = @_;
+
+ # Do things here before instantiation
+ $new = $class->next::method(@_);
+ # Do things to object after instantiation
+ return $new;
}
The arguments are the class name of the component, the class name of
component or really do anything compatible with Catalyst's
expectations on a component.
-For more information, please see L<Catalyst::Component/"COMPONENT($c,$arguments)">.
+For more information, please see
+L<Catalyst::Component/"COMPONENT($c,$arguments)">.
=head1 SEE ALSO
projects / catagits/Catalyst-Manual.git / blobdiff