1Catalyst::RouteMatchingU(s3e)r Contributed Perl DocumentaCtaitoanlyst::RouteMatching(3)
2
6 Catalyst::RouteMatching - How Catalyst maps an incoming URL to actions
7 in controllers.
8
10 This is a WIP document intended to help people understand the logic
11 that Catalyst uses to determine how to match in incoming request to an
12 action (or action chain) in a controller.
13 Request to Controller/Action Matching
15 Catalyst maps requests to action using a 'longest path wins' approach.
16 That means that if the request is '/foo/bar/baz' That means the action
17 'baz' matches:
18 package MyApp::Controller::Foo;
20 use Moose;
22 use MooseX::MethodAttributes
23 extends 'Catalyst::Controller';
25 sub bar :Path('bar') Args(1) { ...}
27 sub baz :Path('bar/baz') Args(0) { ... }
28 Path length matches take precedence over all other types of matches
30 (included HTTP Method, Scheme, etc.). The same holds true for Chained
31 actions. Generally the chain that matches the most PathParts wins.
32 Args(N) versus Args
34 'Args' matches any number of args. Because this functions as a sort of
35 catchall, we treat 'Args' as the lowest precedence of any Args(N) when
36 N is 0 to infinity. An action with 'Args' always get the last chance
37 to match.
38 When two or more actions match a given Path
40 Sometimes two or more actions match the same path and all have the same
41 PathPart length. For example:
42 package MyApp::Controller::Root;
44 use Moose;
46 use MooseX::MethodAttributes
47 extends 'Catalyst::Controller';
49 sub root :Chained(/) CaptureArgs(0) { }
51 sub one :Chained(root) PathPart('') Args(0) { }
53 sub two :Chained(root) PathPart('') Args(0) { }
54 sub three :Chained(root) PathPart('') Args(0) { }
55 __PACKAGE__->meta->make_immutable;
57 In this case the last defined action wins (for the example that is
59 action 'three').
60 This is most common to happen when you are using action matching beyond
62 paths, such as when using method matching:
63 package MyApp::Controller::Root;
65 use Moose;
67 use MooseX::MethodAttributes
68 extends 'Catalyst::Controller';
70 sub root :Chained(/) CaptureArgs(0) { }
72 sub any :Chained(root) PathPart('') Args(0) { }
74 sub get :GET Chained(root) PathPart('') Args(0) { }
75 __PACKAGE__->meta->make_immutable;
77 In the above example GET /root could match both actions. In this case
79 you should define your 'catchall' actions higher in the controller.
80 Type Constraints in Args and Capture Args
82 Beginning in Version 5.90090+ you may use Moose, MooseX::Types or
83 Type::Tiny type constraints to further declare allowed matching for
84 Args or CaptureArgs. Here is a simple example:
85 package MyApp::Controller::User;
87 use Moose;
89 use MooseX::MethodAttributes;
90 use MooseX::Types::Moose qw(Int);
91 extends 'Catalyst::Controller';
93 sub find :Path('') Args(Int) {
95 my ($self, $c, $int) = @_;
96 }
97 __PACKAGE__->meta->make_immutable;
99 In this case the incoming request "http://localhost:/user/100" would
101 match the action "find" but "http://localhost:/user/not_a_number" would
102 not. You may find declaring constraints in this manner aids with
103 debugging, automatic generation of documentation and reducing the
104 amount of manual checking you might need to do in your actions. For
105 example if the argument in the given action was going to be used to
106 lookup a row in a database, if the matching field expected an integer,
107 a string might cause a database exception, prompting you to add
108 additional checking of the argument prior to using it. In general it
109 is hoped this feature can lead to reduced validation boilerplate and
110 more easily understood and declarative actions.
111 More than one argument may be added by comma separating your type
113 constraint names, for example:
114 use Types::Standard qw/Int Str/;
116 sub find :Path('') Args(Int,Int,Str) {
118 my ($self, $c, $int1, $int2, $str) = @_;
119 }
120 Would require three arguments, an integer, integer and a string. Note
122 in this example we constrained the args using imported types via
123 Types::Standard. Although you may use stringy Moose types, we
124 recommend imported types since this is less ambiguous to your readers.
125 If you want to use Moose stringy types. you must quote them (either
126 "Int" or 'Int' is fine).
127 Conversely, you should not quote types that are imported!
129 Using type constraints in a controller
131 By default Catalyst allows all the standard, built-in, named type
133 constraints that come bundled with Moose. However it is trivial to
134 create your own Type constraint libraries and export them to a
135 controller that wishes to use them. We recommend using Type::Tiny or
136 MooseX::Types for this. Here is an example using some extended type
137 constraints via the Types::Standard library that is packaged with
138 Type::Tiny:
139 package MyApp::Controller::User;
141 use Moose;
143 use MooseX::MethodAttributes;
144 use Types::Standard qw/StrMatch Int/;
145 extends 'Catalyst::Controller';
147 sub looks_like_a_date :Path('') Args(StrMatch[qr{\d\d-\d\d-\d\d}]) {
149 my ($self, $c, $int) = @_;
150 }
151 __PACKAGE__->meta->make_immutable;
153 This would match URLs like "http://localhost/user/11-11-2015" for
155 example. If you've been missing the old RegExp matching, this can
156 emulate a good chunk of that ability, and more.
157 A tutorial on how to make custom type libraries is outside the scope of
159 this document. I'd recommend looking at the copious documentation in
160 Type::Tiny or in MooseX::Types if you prefer that system. The author
161 recommends Type::Tiny if you are unsure which to use.
162 Type constraint namespace.
164 By default we assume the namespace which defines the type constraint is
166 in the package which contains the action declaring the arg or capture
167 arg. However if you do not wish to import type constraints into you
168 package, you may use a fully qualified namespace for your type
169 constraint. If you do this you must install Type::Tiny which defines
170 the code used to lookup and normalize the various types of Type
171 constraint libraries.
172 Example:
174 package MyApp::Example;
176 use Moose;
178 use MooseX::MethodAttributes;
179 extends 'Catalyst::Controller';
181 sub an_int_ns :Local Args(MyApp::Types::Int) {
183 my ($self, $c, $int) = @_;
184 $c->res->body('an_int (withrole)');
185 }
186 Would basically work the same as:
188 package MyApp::Example;
190 use Moose;
192 use MooseX::MethodAttributes;
193 use MyApp::Types 'Int';
194 extends 'Catalyst::Controller';
196 sub an_int_ns :Local Args(Int) {
198 my ($self, $c, $int) = @_;
199 $c->res->body('an_int (withrole)');
200 }
201 namespace::autoclean
203 If you want to use namespace::autoclean in your controllers you must
205 'except' imported type constraints since the code that resolves type
206 constraints in args / capture args run after the cleaning. For
207 example:
208 package MyApp::Controller::Autoclean;
210 use Moose;
212 use MooseX::MethodAttributes;
213 use namespace::autoclean -except => 'Int';
214 use MyApp::Types qw/Int/;
215 extends 'Catalyst::Controller';
217 sub an_int :Local Args(Int) {
219 my ($self, $c, $int) = @_;
220 $c->res->body('an_int (autoclean)');
221 }
222 Using roles and base controller with type constraints
224 If your controller is using a base class or a role that has an action
226 with a type constraint you should declare your use of the type
227 constraint in that role or base controller in the same way as you do in
228 main controllers. Catalyst will try to find the package with declares
229 the type constraint first by looking in any roles and then in
230 superclasses. It will use the first package that defines the type
231 constraint. For example:
232 package MyApp::Role;
234 use Moose::Role;
236 use MooseX::MethodAttributes::Role;
237 use MyApp::Types qw/Int/;
238 sub an_int :Local Args(Int) {
240 my ($self, $c, $int) = @_;
241 $c->res->body('an_int (withrole)');
242 }
243 sub an_int_ns :Local Args(MyApp::Types::Int) {
245 my ($self, $c, $int) = @_;
246 $c->res->body('an_int (withrole)');
247 }
248 package MyApp::BaseController;
250 use Moose;
252 use MooseX::MethodAttributes;
253 use MyApp::Types qw/Int/;
254 extends 'Catalyst::Controller';
256 sub from_parent :Local Args(Int) {
258 my ($self, $c, $id) = @_;
259 $c->res->body('from_parent $id');
260 }
261 package MyApp::Controller::WithRole;
263 use Moose;
265 use MooseX::MethodAttributes;
266 extends 'MyApp::BaseController';
268 with 'MyApp::Role';
270 If you have complex controller hierarchy, we do not at this time
272 attempt to look for all packages with a match type constraint, but
273 instead take the first one found. In the future we may add code that
274 attempts to insure a sane use of subclasses with type constraints but
275 right now there are no clear use cases so report issues and interests.
276 Match order when more than one Action matches a path.
278 As previously described, Catalyst will match 'the longest path', which
280 generally means that named path / path_parts will take precedence over
281 Args or CaptureArgs. However, what will happen if two actions match
282 the same path with equal args? For example:
283 sub an_int :Path(user) Args(Int) {
285 }
286 sub an_any :Path(user) Args(1) {
288 }
289 In this case Catalyst will check actions starting from the LAST one
291 defined. Generally this means you should put your most specific action
292 rules LAST and your 'catch-alls' first. In the above example, since
293 Args(1) will match any argument, you will find that that 'an_int'
294 action NEVER gets hit. You would need to reverse the order:
295 sub an_any :Path(user) Args(1) {
297 }
298 sub an_int :Path(user) Args(Int) {
300 }
301 Now requests that match this path would first hit the 'an_int' action
303 and will check to see if the argument is an integer. If it is, then
304 the action will execute, otherwise it will pass and the dispatcher will
305 check the next matching action (in this case we fall through to the
306 'an_any' action).
307 Type Constraints and Chained Actions
309 Using type constraints in Chained actions works the same as it does for
311 Path and Local or Global actions. The only difference is that you may
312 declare type constraints on CaptureArgs as well as Args. For Example:
313 use Types::Standard qw/Int Tuple/;
315 sub chain_base :Chained(/) CaptureArgs(1) { }
317 sub any_priority_chain :GET Chained(chain_base) PathPart('') Args(1) { }
319 sub int_priority_chain :Chained(chain_base) PathPart('') Args(Int) { }
321 sub link_any :Chained(chain_base) PathPart('') CaptureArgs(1) { }
323 sub any_priority_link_any :Chained(link_any) PathPart('') Args(1) { }
325 sub int_priority_link_any :Chained(link_any) PathPart('') Args(Int) { }
327 sub link_int :Chained(chain_base) PathPart('') CaptureArgs(Int) { }
329 sub any_priority_link :Chained(link_int) PathPart('') Args(1) { }
331 sub int_priority_link :Chained(link_int) PathPart('') Args(Int) { }
333 sub link_int_int :Chained(chain_base) PathPart('') CaptureArgs(Int,Int) { }
335 sub any_priority_link2 :Chained(link_int_int) PathPart('') Args(1) { }
337 sub int_priority_link2 :Chained(link_int_int) PathPart('') Args(Int) { }
339 sub link_tuple :Chained(chain_base) PathPart('') CaptureArgs(Tuple[Int,Int,Int]) { }
341 sub any_priority_link3 :Chained(link_tuple) PathPart('') Args(1) { }
343 sub int_priority_link3 :Chained(link_tuple) PathPart('') Args(Int) { }
345 These chained actions might create match tables like the following:
347 [debug] Loaded Chained actions:
349 .-------------------------------------+--------------------------------------.
350 | Path Spec | Private |
351 +-------------------------------------+--------------------------------------+
352 | /chain_base/*/* | /chain_base (1) |
353 | | => GET /any_priority_chain (1) |
354 | /chain_base/*/*/* | /chain_base (1) |
355 | | -> /link_int (Int) |
356 | | => /any_priority_link (1) |
357 | /chain_base/*/*/*/* | /chain_base (1) |
358 | | -> /link_int_int (Int,Int) |
359 | | => /any_priority_link2 (1) |
360 | /chain_base/*/*/*/*/* | /chain_base (1) |
361 | | -> /link_tuple (Tuple[Int,Int,Int]) |
362 | | => /any_priority_link3 (1) |
363 | /chain_base/*/*/* | /chain_base (1) |
364 | | -> /link_any (1) |
365 | | => /any_priority_link_any (1) |
366 | /chain_base/*/*/*/*/*/* | /chain_base (1) |
367 | | -> /link_tuple (Tuple[Int,Int,Int]) |
368 | | -> /link2_int (UserId) |
369 | | => GET /finally (Int) |
370 | /chain_base/*/*/*/*/*/... | /chain_base (1) |
371 | | -> /link_tuple (Tuple[Int,Int,Int]) |
372 | | -> /link2_int (UserId) |
373 | | => GET /finally2 (...) |
374 | /chain_base/*/* | /chain_base (1) |
375 | | => /int_priority_chain (Int) |
376 | /chain_base/*/*/* | /chain_base (1) |
377 | | -> /link_int (Int) |
378 | | => /int_priority_link (Int) |
379 | /chain_base/*/*/*/* | /chain_base (1) |
380 | | -> /link_int_int (Int,Int) |
381 | | => /int_priority_link2 (Int) |
382 | /chain_base/*/*/*/*/* | /chain_base (1) |
383 | | -> /link_tuple (Tuple[Int,Int,Int]) |
384 | | => /int_priority_link3 (Int) |
385 | /chain_base/*/*/* | /chain_base (1) |
386 | | -> /link_any (1) |
387 | | => /int_priority_link_any (Int) |
388 '-------------------------------------+--------------------------------------'
389 As you can see the same general path could be matched by various action
391 chains. In this case the rule described in the previous section should
392 be followed, which is that Catalyst will start with the last defined
393 action and work upward. For example the action "int_priority_chain"
394 would be checked before "any_priority_chain". The same applies for
395 actions that are midway links in a longer chain. In this case
396 "link_int" would be checked before "link_any". So as always we
397 recommend that you place you priority or most constrained actions last
398 and you least or catch-all actions first.
399 Although this reverse order checking may seen counter intuitive it does
401 have the added benefit that when inheriting controllers any new actions
402 added would take check precedence over those in your parent controller
403 or consumed role.
404 Please note that your declared type constraint names will now appear in
406 the debug console.
407
409 John Napiorkowski jjnapiork@cpan.org <email:jjnapiork@cpan.org>
410perl v5.34.0 2021-07-22 Catalyst::RouteMatching(3)