[catagits/Catalyst-Runtime.git] / lib / Catalyst / RouteMatching.pod

=encoding UTF-8

=head1 Name

Catalyst::RouteMatching - How Catalyst maps an incoming URL to actions in controllers.

=head1 Description

This is a WIP document intended to help people understand the logic that L<Catalyst>
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>
type constraints to futher declare allowed matching for Args or CaptureArgs.  Here
is a simple example:

    package MyApp::Controller::User;

    use Moose;
    use MooseX::MethodAttributes;

    extends 'Catalyst::Controller';

    sub find :Path('') Args('Int') {
      my ($self, $c, $int) = @_;
    }

    __PACKAGE__->meta->make_immutable;

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 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.  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 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>:

    package MyApp::Controller::User;

    use Moose;
    use MooseX::MethodAttributes;
    use Types::Standard qw/StrMatch Int/;
    
    extends 'Catalyst::Controller';

    sub looks_like_a_date :Path('') Args(StrMatch[qr{\d\d-\d\d-\d\d}]) {
      my ($self, $c, $int) = @_;
    }

    __PACKAGE__->meta->make_immutable;

This would match URLs like "http://localhost/user/11-11-2015" for example.  If you've been
missing the old RegExp matching, this can emulate a good chunk of that ability, and more.

A tutorial on how to make custom type libraries is outside the scope of this document.  I'd
recommend looking at the copious documentation in L<Type::Tiny> or in L<MooseX::Types> if
you prefer that system.  The author recommends L<Type::Tiny> if you are unsure which to use.

=head3 Match order when more than one Action matches a path.

As previously described, L<Catalyst> will match 'the longest path', which generally means
that named path / path_parts will take precidence over Args or CaptureArgs.  However, what
will happen if two actions match the same path with equal args?  For example:

    sub an_int :Path(user) Args(Int) {
    }

    sub an_any :Path(user) Args(1) {
    }

In this case L<Catalyst> will check actions starting from the LAST one defined.  Generally
this means you should put your most specific action rules LAST and your 'catch-alls' first.
In the above example, since Args(1) will match any argument, you will find that that 'an_int'
action NEVER gets hit.  You would need to reverse the order:

    sub an_any :Path(user) Args(1) {
    }

    sub an_int :Path(user) Args(Int) {
    }

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 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 :GET Chained(chain_base) PathPart('') Args(1) {  }

    sub int_priority_chain :Chained(chain_base) PathPart('') Args(Int) {  }

    sub link_any :Chained(chain_base) PathPart('') CaptureArgs(1) { }

      sub any_priority_link_any :Chained(link_any) PathPart('') Args(1) {  }

      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 int_priority_link :Chained(link_int) PathPart('') Args(Int) {  }

    sub link_int_int :Chained(chain_base) PathPart('') CaptureArgs(Int,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)                      |
    |                                     | => 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>
will start with the last defined action and work upward.  For example the action C<int_priority_chain>
would be checked before C<any_priority_chain>.  The same applies for actions that are midway links
in a longer chain.  In this case C<link_int> would be checked before C<link_any>.  So as always we
recommend that you place you priority or most constrainted actions last and you least or catch-all
actions first.

Although this reverse order checking may seen counter intuitive it does have the added benefit that
when inheriting controllers any new actions added would take check precedence over those in your
parent controller or consumed role.

Please note that your declared type constraint names will now appear in the debug console.

=head1 Author

John Napiorkowski L<jjnapiork@cpan.org|email:jjnapiork@cpan.org>

=cut
Commit	Line	Data
480d94b5	1	=encoding UTF-8
	2
	3	=head1 Name
	4
	5	Catalyst::RouteMatching - How Catalyst maps an incoming URL to actions in controllers.
	6
	7	=head1 Description
	8
	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)
	11	in a controller.
	12
2234c98a	13	=head2 Request to Controller/Action Matching
	14
	15	L<Catalyst> maps requests to action using a 'longest path wins' approach. That means
	16	that if the request is '/foo/bar/baz' That means the action 'baz' matches:
	17
	18	package MyApp::Controller::Foo;
	19
	20	use Moose;
	21	use MooseX::MethodAttributes
	22
	23	extends 'Catalyst::Controller';
	24
	25	sub bar :Path('bar') Args(1) { ...}
	26	sub baz :Path('bar/baz') Args(0) { ... }
	27
	28	Path length matches take precidence over all other types of matches (included HTTP
	29	Method, Scheme, etc.). The same holds true for Chained actions. Generally the
	30	chain that matches the most PathParts wins.
	31
	32	=head2 Args(N) versus Args
	33
	34	'Args' matches any number of args. Because this functions as a sort of catchall, we
	35	treat 'Args' as the lowest precedence of any Args(N) when N is 0 to infinity. An
	36	action with 'Args' always get the last chance to match.
	37
	38	=head2 When two or more actions match a given Path
	39
	40	Sometimes two or more actions match the same path and all have the same pathpart
	41	length. For example:
	42
	43	package MyApp::Controller::Root;
	44
	45	use Moose;
	46	use MooseX::MethodAttributes
	47
	48	extends 'Catalyst::Controller';
	49
	50	sub root :Chained(/) CaptureArgs(0) { }
	51
	52	sub one :Chained(root) PathPart('') Args(0) { }
	53	sub two :Chained(root) PathPart('') Args(0) { }
	54	sub three :Chained(root) PathPart('') Args(0) { }
	55
	56	__PACKAGE__->meta->make_immutable;
	57
	58	In this case the last defined action wins (for the example that is action 'three').
	59
	60	This is most common to happen when you are using action matching beyond paths, such as
	61	when using method matching:
	62
	63	package MyApp::Controller::Root;
	64
	65	use Moose;
	66	use MooseX::MethodAttributes
	67
	68	extends 'Catalyst::Controller';
	69
	70	sub root :Chained(/) CaptureArgs(0) { }
	71
	72	sub any :Chained(root) PathPart('') Args(0) { }
	73	sub get :GET Chained(root) PathPart('') Args(0) { }
	74
	75	__PACKAGE__->meta->make_immutable;
	76
77	In the above example GET /root could match both actions. In this case you should define
78	your 'catchall' actions higher in the controller.
79
480d94b5	80	=head2 Type Constraints in Args and Capture Args
	81
	82	Beginning in Version 5.90090+ you may use L<Moose>, L<MooseX::Types> or L<Type::Tiny>
	83	type constraints to futher declare allowed matching for Args or CaptureArgs. Here
	84	is a simple example:
	85
	86	package MyApp::Controller::User;
	87
	88	use Moose;
	89	use MooseX::MethodAttributes;
	90
	91	extends 'Catalyst::Controller';
	92
75ce30d0	93	sub find :Path('') Args('Int') {
480d94b5	94	my ($self, $c, $int) = @_;
	95	}
	96
	97	__PACKAGE__->meta->make_immutable;
	98
	99	In this case the incoming request "http://localhost:/user/100" would match the action
	100	C<find> but "http://localhost:/user/not_a_number" would not. You may find declaring
d249a614	101	constraints in this manner aids with debugging, automatic generation of documentation
	102	and reducing the amount of manual checking you might need to do in your actions. For
	103	example if the argument in the given action was going to be used to lookup a row
	104	in a database, if the matching field expected an integer, a string might cause a database
480d94b5	105	exception, prompting you to add additional checking of the argument prior to using it.
d249a614	106	In general it is hoped this feature can lead to reduced validation boilerplate and more
d249a614	107	easily understood and declarative actions.
480d94b5	108
	109	More than one argument may be added by comma separating your type constraint names, for
	110	example:
	111
75ce30d0	112	use Types::Standard qw/Int Str/;
75ce30d0	113
480d94b5	114	sub find :Path('') Args(Int,Int,Str) {
	115	my ($self, $c, $int1, $int2, $str) = @_;
	116	}
	117
75ce30d0	118	Would require three arguments, an integer, integer and a string. Note in this example we
	119	constrained the args using imported types via L<Types::Standard>. Although you may use
	120	stringy Moose types, we recommend imported types since this is less ambiguous to your readers.
	121	If you want to use Moose stringy types. you must quote them (either "Int" or 'Int' is fine).
	122
	123	Conversely, you should not quote types that are imported!
480d94b5	124
	125	=head3 Using type constraints in a controller
	126
	127	By default L<Catalyst> allows all the standard, built-in, named type constraints that come
	128	bundled with L<Moose>. However it is trivial to create your own Type constraint libraries
d249a614	129	and export them to a controller that wishes to use them. We recommend using L<Type::Tiny> or
480d94b5	130	L<MooseX::Types> for this. Here is an example using some extended type constraints via
	131	the L<Types::Standard> library that is packaged with L<Type::Tiny>:
	132
	133	package MyApp::Controller::User;
	134
	135	use Moose;
	136	use MooseX::MethodAttributes;
75ce30d0	137	use Types::Standard qw/StrMatch Int/;
480d94b5	138
	139	extends 'Catalyst::Controller';
	140
	141	sub looks_like_a_date :Path('') Args(StrMatch[qr{\d\d-\d\d-\d\d}]) {
	142	my ($self, $c, $int) = @_;
	143	}
	144
	145	__PACKAGE__->meta->make_immutable;
	146
	147	This would match URLs like "http://localhost/user/11-11-2015" for example. If you've been
	148	missing the old RegExp matching, this can emulate a good chunk of that ability, and more.
	149
	150	A tutorial on how to make custom type libraries is outside the scope of this document. I'd
	151	recommend looking at the copious documentation in L<Type::Tiny> or in L<MooseX::Types> if
	152	you prefer that system. The author recommends L<Type::Tiny> if you are unsure which to use.
	153
	154	=head3 Match order when more than one Action matches a path.
	155
	156	As previously described, L<Catalyst> will match 'the longest path', which generally means
	157	that named path / path_parts will take precidence over Args or CaptureArgs. However, what
	158	will happen if two actions match the same path with equal args? For example:
	159
	160	sub an_int :Path(user) Args(Int) {
	161	}
	162
	163	sub an_any :Path(user) Args(1) {
	164	}
	165
	166	In this case L<Catalyst> will check actions starting from the LAST one defined. Generally
	167	this means you should put your most specific action rules LAST and your 'catch-alls' first.
	168	In the above example, since Args(1) will match any argument, you will find that that 'an_int'
	169	action NEVER gets hit. You would need to reverse the order:
	170
	171	sub an_any :Path(user) Args(1) {
	172	}
	173
	174	sub an_int :Path(user) Args(Int) {
	175	}
	176
d249a614	177	Now requests that match this path would first hit the 'an_int' action and will check to see if
	178	the argument is an integer. If it is, then the action will execute, otherwise it will pass and
	179	the dispatcher will check the next matching action (in this case we fall thru to the 'an_any'
	180	action).
480d94b5	181
	182	=head3 Type Constraints and Chained Actions
	183
	184	Using type constraints in Chained actions works the same as it does for Path and Local or Global
d249a614	185	actions. The only difference is that you may declare type constraints on CaptureArgs as
480d94b5	186	well as Args. For Example:
480d94b5	187
75ce30d0	188	use Types::Standard qw/Int Tuple/;
75ce30d0	189
480d94b5	190	sub chain_base :Chained(/) CaptureArgs(1) { }
480d94b5	191
9228a8ec	192	sub any_priority_chain :GET Chained(chain_base) PathPart('') Args(1) { }
480d94b5	193
	194	sub int_priority_chain :Chained(chain_base) PathPart('') Args(Int) { }
	195
	196	sub link_any :Chained(chain_base) PathPart('') CaptureArgs(1) { }
	197
	198	sub any_priority_link_any :Chained(link_any) PathPart('') Args(1) { }
	199
9228a8ec	200	sub int_priority_link_any :Chained(link_any) PathPart('') Args(Int) { }
480d94b5	201
	202	sub link_int :Chained(chain_base) PathPart('') CaptureArgs(Int) { }
	203
9228a8ec	204	sub any_priority_link :Chained(link_int) PathPart('') Args(1) { }
480d94b5	205
9228a8ec	206	sub int_priority_link :Chained(link_int) PathPart('') Args(Int) { }
	207
	208	sub link_int_int :Chained(chain_base) PathPart('') CaptureArgs(Int,Int) { }
	209
	210	sub any_priority_link2 :Chained(link_int_int) PathPart('') Args(1) { }
	211
	212	sub int_priority_link2 :Chained(link_int_int) PathPart('') Args(Int) { }
	213
	214	sub link_tuple :Chained(chain_base) PathPart('') CaptureArgs(Tuple[Int,Int,Int]) { }
	215
	216	sub any_priority_link3 :Chained(link_tuple) PathPart('') Args(1) { }
	217
	218	sub int_priority_link3 :Chained(link_tuple) PathPart('') Args(Int) { }
480d94b5	219
	220	These chained actions migth create match tables like the following:
	221
	222	[debug] Loaded Chained actions:
9228a8ec	223	.-------------------------------------+--------------------------------------.
	224	\| Path Spec \| Private \|
	225	+-------------------------------------+--------------------------------------+
	226	\| /chain_base// \| /chain_base (1) \|
	227	\| \| => GET /any_priority_chain (1) \|
	228	\| /chain_base///* \| /chain_base (1) \|
	229	\| \| -> /link_int (Int) \|
	230	\| \| => /any_priority_link (1) \|
	231	\| /chain_base//// \| /chain_base (1) \|
	232	\| \| -> /link_int_int (Int,Int) \|
	233	\| \| => /any_priority_link2 (1) \|
	234	\| /chain_base/////* \| /chain_base (1) \|
	235	\| \| -> /link_tuple (Tuple[Int,Int,Int]) \|
	236	\| \| => /any_priority_link3 (1) \|
	237	\| /chain_base///* \| /chain_base (1) \|
	238	\| \| -> /link_any (1) \|
	239	\| \| => /any_priority_link_any (1) \|
	240	\| /chain_base////// \| /chain_base (1) \|
	241	\| \| -> /link_tuple (Tuple[Int,Int,Int]) \|
	242	\| \| -> /link2_int (UserId) \|
	243	\| \| => GET /finally (Int) \|
	244	\| /chain_base/////*/... \| /chain_base (1) \|
	245	\| \| -> /link_tuple (Tuple[Int,Int,Int]) \|
	246	\| \| -> /link2_int (UserId) \|
	247	\| \| => GET /finally2 (...) \|
	248	\| /chain_base// \| /chain_base (1) \|
	249	\| \| => /int_priority_chain (Int) \|
	250	\| /chain_base///* \| /chain_base (1) \|
	251	\| \| -> /link_int (Int) \|
	252	\| \| => /int_priority_link (Int) \|
	253	\| /chain_base//// \| /chain_base (1) \|
	254	\| \| -> /link_int_int (Int,Int) \|
	255	\| \| => /int_priority_link2 (Int) \|
	256	\| /chain_base/////* \| /chain_base (1) \|
	257	\| \| -> /link_tuple (Tuple[Int,Int,Int]) \|
	258	\| \| => /int_priority_link3 (Int) \|
	259	\| /chain_base///* \| /chain_base (1) \|
	260	\| \| -> /link_any (1) \|
	261	\| \| => /int_priority_link_any (Int) \|
	262	'-------------------------------------+--------------------------------------'
480d94b5	263
	264	As you can see the same general path could be matched by various action chains. In this case
	265	the rule described in the previous section should be followed, which is that L<Catalyst>
	266	will start with the last defined action and work upward. For example the action C<int_priority_chain>
	267	would be checked before C<any_priority_chain>. The same applies for actions that are midway links
	268	in a longer chain. In this case C<link_int> would be checked before C<link_any>. So as always we
	269	recommend that you place you priority or most constrainted actions last and you least or catch-all
	270	actions first.
	271
	272	Although this reverse order checking may seen counter intuitive it does have the added benefit that
	273	when inheriting controllers any new actions added would take check precedence over those in your
	274	parent controller or consumed role.
	275
9228a8ec	276	Please note that your declared type constraint names will now appear in the debug console.
9228a8ec	277
480d94b5	278	=head1 Author
	279
	280	John Napiorkowski L<jjnapiork@cpan.org\|email:jjnapiork@cpan.org>
	281
	282	=cut
	283