5 Catalyst::RouteMatching - How Catalyst maps an incoming URL to actions in controllers.
9 This is a WIP document intended to help people understand the logic that L<Catalyst>
10 uses to determine how to match in incoming request to an action (or action chain)
13 =head2 Type Constraints in Args and Capture Args
15 Beginning in Version 5.90090+ you may use L<Moose>, L<MooseX::Types> or L<Type::Tiny>
16 type constraints to futher declare allowed matching for Args or CaptureArgs. Here
19 package MyApp::Controller::User;
22 use MooseX::MethodAttributes;
24 extends 'Catalyst::Controller';
26 sub find :Path('') Args(Int) {
27 my ($self, $c, $int) = @_;
30 __PACKAGE__->meta->make_immutable;
32 In this case the incoming request "http://localhost:/user/100" would match the action
33 C<find> but "http://localhost:/user/not_a_number" would not. You may find declaring
34 constraints in this manner aids with debuggin, automatic generation of documentation
35 and reduces the amount of manual checking you might need to do in your actions. For
36 example if the argument in the example action was going to be used to lookup a row
37 in a database, if the matching field expected an integer a string might cause a database
38 exception, prompting you to add additional checking of the argument prior to using it.
40 More than one argument may be added by comma separating your type constraint names, for
43 sub find :Path('') Args(Int,Int,Str) {
44 my ($self, $c, $int1, $int2, $str) = @_;
47 Would require three arguments, an integer, integer and a string.
49 =head3 Using type constraints in a controller
51 By default L<Catalyst> allows all the standard, built-in, named type constraints that come
52 bundled with L<Moose>. However it is trivial to create your own Type constraint libraries
53 and export them to controller that wish to use them. We recommend using L<Type::Tiny> or
54 L<MooseX::Types> for this. Here is an example using some extended type constraints via
55 the L<Types::Standard> library that is packaged with L<Type::Tiny>:
57 package MyApp::Controller::User;
60 use MooseX::MethodAttributes;
61 use Types::Standard qw/StrMatch/;
63 extends 'Catalyst::Controller';
65 sub looks_like_a_date :Path('') Args(StrMatch[qr{\d\d-\d\d-\d\d}]) {
66 my ($self, $c, $int) = @_;
69 __PACKAGE__->meta->make_immutable;
71 This would match URLs like "http://localhost/user/11-11-2015" for example. If you've been
72 missing the old RegExp matching, this can emulate a good chunk of that ability, and more.
74 A tutorial on how to make custom type libraries is outside the scope of this document. I'd
75 recommend looking at the copious documentation in L<Type::Tiny> or in L<MooseX::Types> if
76 you prefer that system. The author recommends L<Type::Tiny> if you are unsure which to use.
78 =head3 Match order when more than one Action matches a path.
80 As previously described, L<Catalyst> will match 'the longest path', which generally means
81 that named path / path_parts will take precidence over Args or CaptureArgs. However, what
82 will happen if two actions match the same path with equal args? For example:
84 sub an_int :Path(user) Args(Int) {
87 sub an_any :Path(user) Args(1) {
90 In this case L<Catalyst> will check actions starting from the LAST one defined. Generally
91 this means you should put your most specific action rules LAST and your 'catch-alls' first.
92 In the above example, since Args(1) will match any argument, you will find that that 'an_int'
93 action NEVER gets hit. You would need to reverse the order:
95 sub an_any :Path(user) Args(1) {
98 sub an_int :Path(user) Args(Int) {
101 Now requests that match this path would first hit the 'an_int' action, and then the 'an_any'
102 action, which it likely what you are looking for!
104 =head3 Type Constraints and Chained Actions
106 Using type constraints in Chained actions works the same as it does for Path and Local or Global
107 actions. The only difference is that you maybe declare type constraints on CaptureArgs as
108 well as Args. For Example:
110 sub chain_base :Chained(/) CaptureArgs(1) { }
112 sub any_priority_chain :Chained(chain_base) PathPart('') Args(1) { }
114 sub int_priority_chain :Chained(chain_base) PathPart('') Args(Int) { }
116 sub link_any :Chained(chain_base) PathPart('') CaptureArgs(1) { }
118 sub any_priority_link_any :Chained(link_any) PathPart('') Args(1) { }
120 sub int_priority_link_any :Chained(link_any) PathPart('') Args(Int) { }
122 sub link_int :Chained(chain_base) PathPart('') CaptureArgs(Int) { }
124 sub any_priority_link :Chained(link_int) PathPart('') Args(1) { }
126 sub int_priority_link :Chained(link_int) PathPart('') Args(Int) { }
128 These chained actions migth create match tables like the following:
130 [debug] Loaded Chained actions:
131 .----------------------------------------------+----------------------------------------------.
132 | Path Spec | Private |
133 +----------------------------------------------+----------------------------------------------+
134 | /chain_base/*/* | /chain_base (1) |
135 | | => /any_priority_chain |
136 | /chain_base/*/*/* | /chain_base (1) |
137 | | -> /link_int (1) |
138 | | => /any_priority_link |
139 | /chain_base/*/*/* | /chain_base (1) |
140 | | -> /link_any (1) |
141 | | => /any_priority_link_any |
142 | /chain_base/*/* | /chain_base (1) |
143 | | => /int_priority_chain |
144 | /chain_base/*/*/* | /chain_base (1) |
145 | | -> /link_int (1) |
146 | | => /int_priority_link |
147 | /chain_base/*/*/* | /chain_base (1) |
148 | | -> /link_any (1) |
149 | | => /int_priority_link_any |
150 '----------------------------------------------+----------------------------------------------'
152 As you can see the same general path could be matched by various action chains. In this case
153 the rule described in the previous section should be followed, which is that L<Catalyst>
154 will start with the last defined action and work upward. For example the action C<int_priority_chain>
155 would be checked before C<any_priority_chain>. The same applies for actions that are midway links
156 in a longer chain. In this case C<link_int> would be checked before C<link_any>. So as always we
157 recommend that you place you priority or most constrainted actions last and you least or catch-all
160 Although this reverse order checking may seen counter intuitive it does have the added benefit that
161 when inheriting controllers any new actions added would take check precedence over those in your
162 parent controller or consumed role.
170 John Napiorkowski L<jjnapiork@cpan.org|email:jjnapiork@cpan.org>