uses to determine how to match in incoming request to an action (or action chain)
in a controller.
+=head2 Request to Controller/Action Matching
+
+L<Catalyst> maps requests to action using a 'longest path wins' approach. That means
+that if the request is '/foo/bar/baz' That means the action 'baz' matches:
+
+ package MyApp::Controller::Foo;
+
+ use Moose;
+ use MooseX::MethodAttributes
+
+ extends 'Catalyst::Controller';
+
+ sub bar :Path('bar') Args(1) { ...}
+ sub baz :Path('bar/baz') Args(0) { ... }
+
+Path length matches take precidence over all other types of matches (included HTTP
+Method, Scheme, etc.). The same holds true for Chained actions. Generally the
+chain that matches the most PathParts wins.
+
+=head2 Args(N) versus Args
+
+'Args' matches any number of args. Because this functions as a sort of catchall, we
+treat 'Args' as the lowest precedence of any Args(N) when N is 0 to infinity. An
+action with 'Args' always get the last chance to match.
+
+=head2 When two or more actions match a given Path
+
+Sometimes two or more actions match the same path and all have the same pathpart
+length. For example:
+
+ package MyApp::Controller::Root;
+
+ use Moose;
+ use MooseX::MethodAttributes
+
+ extends 'Catalyst::Controller';
+
+ sub root :Chained(/) CaptureArgs(0) { }
+
+ sub one :Chained(root) PathPart('') Args(0) { }
+ sub two :Chained(root) PathPart('') Args(0) { }
+ sub three :Chained(root) PathPart('') Args(0) { }
+
+ __PACKAGE__->meta->make_immutable;
+
+In this case the last defined action wins (for the example that is action 'three').
+
+This is most common to happen when you are using action matching beyond paths, such as
+when using method matching:
+
+ package MyApp::Controller::Root;
+
+ use Moose;
+ use MooseX::MethodAttributes
+
+ extends 'Catalyst::Controller';
+
+ sub root :Chained(/) CaptureArgs(0) { }
+
+ sub any :Chained(root) PathPart('') Args(0) { }
+ sub get :GET Chained(root) PathPart('') Args(0) { }
+
+ __PACKAGE__->meta->make_immutable;
+
+In the above example GET /root could match both actions. In this case you should define
+your 'catchall' actions higher in the controller.
+
=head2 Type Constraints in Args and Capture Args
Beginning in Version 5.90090+ you may use L<Moose>, L<MooseX::Types> or L<Type::Tiny>
use Moose;
use MooseX::MethodAttributes;
+ use MooseX::Types::Moose qw(Int);
extends 'Catalyst::Controller';
In this case the incoming request "http://localhost:/user/100" would match the action
C<find> but "http://localhost:/user/not_a_number" would not. You may find declaring
-constraints in this manner aids with debuggin, automatic generation of documentation
-and reduces the amount of manual checking you might need to do in your actions. For
-example if the argument in the example action was going to be used to lookup a row
-in a database, if the matching field expected an integer a string might cause a database
+constraints in this manner aids with debugging, automatic generation of documentation
+and reducing the amount of manual checking you might need to do in your actions. For
+example if the argument in the given action was going to be used to lookup a row
+in a database, if the matching field expected an integer, a string might cause a database
exception, prompting you to add additional checking of the argument prior to using it.
+In general it is hoped this feature can lead to reduced validation boilerplate and more
+easily understood and declarative actions.
More than one argument may be added by comma separating your type constraint names, for
example:
+ use Types::Standard qw/Int Str/;
+
sub find :Path('') Args(Int,Int,Str) {
my ($self, $c, $int1, $int2, $str) = @_;
}
-Would require three arguments, an integer, integer and a string.
+Would require three arguments, an integer, integer and a string. Note in this example we
+constrained the args using imported types via L<Types::Standard>. Although you may use
+stringy Moose types, we recommend imported types since this is less ambiguous to your readers.
+If you want to use Moose stringy types. you must quote them (either "Int" or 'Int' is fine).
+
+Conversely, you should not quote types that are imported!
=head3 Using type constraints in a controller
By default L<Catalyst> allows all the standard, built-in, named type constraints that come
bundled with L<Moose>. However it is trivial to create your own Type constraint libraries
-and export them to controller that wish to use them. We recommend using L<Type::Tiny> or
+and export them to a controller that wishes to use them. We recommend using L<Type::Tiny> or
L<MooseX::Types> for this. Here is an example using some extended type constraints via
the L<Types::Standard> library that is packaged with L<Type::Tiny>:
use Moose;
use MooseX::MethodAttributes;
- use Types::Standard qw/StrMatch/;
+ use Types::Standard qw/StrMatch Int/;
extends 'Catalyst::Controller';
sub an_int :Path(user) Args(Int) {
}
-Now requests that match this path would first hit the 'an_int' action, and then the 'an_any'
-action, which it likely what you are looking for!
+Now requests that match this path would first hit the 'an_int' action and will check to see if
+the argument is an integer. If it is, then the action will execute, otherwise it will pass and
+the dispatcher will check the next matching action (in this case we fall thru to the 'an_any'
+action).
=head3 Type Constraints and Chained Actions
Using type constraints in Chained actions works the same as it does for Path and Local or Global
-actions. The only difference is that you maybe declare type constraints on CaptureArgs as
+actions. The only difference is that you may declare type constraints on CaptureArgs as
well as Args. For Example:
+ use Types::Standard qw/Int Tuple/;
+
sub chain_base :Chained(/) CaptureArgs(1) { }
- sub any_priority_chain :Chained(chain_base) PathPart('') Args(1) { }
+ sub any_priority_chain :GET Chained(chain_base) PathPart('') Args(1) { }
sub int_priority_chain :Chained(chain_base) PathPart('') Args(Int) { }
sub any_priority_link_any :Chained(link_any) PathPart('') Args(1) { }
- sub int_priority_link_any :Chained(link_any) PathPart('') Args(Int) { }
+ sub int_priority_link_any :Chained(link_any) PathPart('') Args(Int) { }
sub link_int :Chained(chain_base) PathPart('') CaptureArgs(Int) { }
- sub any_priority_link :Chained(link_int) PathPart('') Args(1) { }
+ sub any_priority_link :Chained(link_int) PathPart('') Args(1) { }
+
+ sub int_priority_link :Chained(link_int) PathPart('') Args(Int) { }
+
+ sub link_int_int :Chained(chain_base) PathPart('') CaptureArgs(Int,Int) { }
- sub int_priority_link :Chained(link_int) PathPart('') Args(Int) { }
+ sub any_priority_link2 :Chained(link_int_int) PathPart('') Args(1) { }
+
+ sub int_priority_link2 :Chained(link_int_int) PathPart('') Args(Int) { }
+
+ sub link_tuple :Chained(chain_base) PathPart('') CaptureArgs(Tuple[Int,Int,Int]) { }
+
+ sub any_priority_link3 :Chained(link_tuple) PathPart('') Args(1) { }
+
+ sub int_priority_link3 :Chained(link_tuple) PathPart('') Args(Int) { }
These chained actions migth create match tables like the following:
[debug] Loaded Chained actions:
- .----------------------------------------------+----------------------------------------------.
- | Path Spec | Private |
- +----------------------------------------------+----------------------------------------------+
- | /chain_base/*/* | /chain_base (1) |
- | | => /any_priority_chain |
- | /chain_base/*/*/* | /chain_base (1) |
- | | -> /link_int (1) |
- | | => /any_priority_link |
- | /chain_base/*/*/* | /chain_base (1) |
- | | -> /link_any (1) |
- | | => /any_priority_link_any |
- | /chain_base/*/* | /chain_base (1) |
- | | => /int_priority_chain |
- | /chain_base/*/*/* | /chain_base (1) |
- | | -> /link_int (1) |
- | | => /int_priority_link |
- | /chain_base/*/*/* | /chain_base (1) |
- | | -> /link_any (1) |
- | | => /int_priority_link_any |
- '----------------------------------------------+----------------------------------------------'
+ .-------------------------------------+--------------------------------------.
+ | Path Spec | Private |
+ +-------------------------------------+--------------------------------------+
+ | /chain_base/*/* | /chain_base (1) |
+ | | => GET /any_priority_chain (1) |
+ | /chain_base/*/*/* | /chain_base (1) |
+ | | -> /link_int (Int) |
+ | | => /any_priority_link (1) |
+ | /chain_base/*/*/*/* | /chain_base (1) |
+ | | -> /link_int_int (Int,Int) |
+ | | => /any_priority_link2 (1) |
+ | /chain_base/*/*/*/*/* | /chain_base (1) |
+ | | -> /link_tuple (Tuple[Int,Int,Int]) |
+ | | => /any_priority_link3 (1) |
+ | /chain_base/*/*/* | /chain_base (1) |
+ | | -> /link_any (1) |
+ | | => /any_priority_link_any (1) |
+ | /chain_base/*/*/*/*/*/* | /chain_base (1) |
+ | | -> /link_tuple (Tuple[Int,Int,Int]) |
+ | | -> /link2_int (UserId) |
+ | | => GET /finally (Int) |
+ | /chain_base/*/*/*/*/*/... | /chain_base (1) |
+ | | -> /link_tuple (Tuple[Int,Int,Int]) |
+ | | -> /link2_int (UserId) |
+ | | => GET /finally2 (...) |
+ | /chain_base/*/* | /chain_base (1) |
+ | | => /int_priority_chain (Int) |
+ | /chain_base/*/*/* | /chain_base (1) |
+ | | -> /link_int (Int) |
+ | | => /int_priority_link (Int) |
+ | /chain_base/*/*/*/* | /chain_base (1) |
+ | | -> /link_int_int (Int,Int) |
+ | | => /int_priority_link2 (Int) |
+ | /chain_base/*/*/*/*/* | /chain_base (1) |
+ | | -> /link_tuple (Tuple[Int,Int,Int]) |
+ | | => /int_priority_link3 (Int) |
+ | /chain_base/*/*/* | /chain_base (1) |
+ | | -> /link_any (1) |
+ | | => /int_priority_link_any (Int) |
+ '-------------------------------------+--------------------------------------'
As you can see the same general path could be matched by various action chains. In this case
the rule described in the previous section should be followed, which is that L<Catalyst>
when inheriting controllers any new actions added would take check precedence over those in your
parent controller or consumed role.
-=head1 Conclusion
-
- TBD
+Please note that your declared type constraint names will now appear in the debug console.
=head1 Author
projects / catagits/Catalyst-Runtime.git / blobdiff