File Coverage

blib/lib/PlackX/Framework/Role/RouterEngine.pm
Criterion Covered Total %
statement 5 5 100.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 7 7 100.0


line stmt bran cond sub pod time code
1 7     7   4454 use v5.36;
  7         31  
2             package PlackX::Framework::Role::RouterEngine {
3 7     7   71 use Role::Tiny;
  7         16  
  7         48  
4             requires qw(new instance match add_route add_global_filter freeze);
5             }
6              
7             1;
8              
9             =pod
10              
11             =head1 NAME
12              
13             PlackX::Framework::Role::RouterEngine
14              
15              
16             =head1 SYNOPSIS
17              
18             package My::Router::Engine {
19             use Role::Tiny::With;
20             with 'PlackX::Framework::Role::RouterEngine';
21             sub new { ... }
22             sub instance { ... }
23             sub match { ... }
24             sub add_route { ... }
25             sub add_global_filter { ... }
26             }
27              
28              
29             =head1 DESCRIPTION
30              
31             This module defines a role which can be used to create a custom Router::Engine
32             class for PlackX::Framework.
33              
34             The Engine class shall be a singleton which returns one object instance per
35             subclass.
36              
37              
38             =head1 REQUIRED CLASS METHODS
39              
40             =over 4
41              
42             =item new, instance
43              
44             Return an instance of the class.
45              
46             =back
47              
48             =head1 REQUIRED OBJECT METHODS
49              
50             =over 4
51              
52             =item $engine->match($request)
53              
54             Use a PlackX::Framework::Request object to find a matching route. The return
55             value shall be undef or false if no match is found. If a match is found, a
56             hashref should be returned. The hashref should contain the following keys:
57              
58             =item route_parameters
59              
60             A hashref of route parameters that were collected during the route match. If
61             no parameters are applicable, it should be an empty hashref (not undef).
62              
63             =item action
64              
65             The subref to be called by PlackX::Framework::Handler to execute the route.
66              
67             =item prefilters, postfilters
68              
69             An arrayref of subrefs to be executed before or after the main action, to
70             include both local (package-scoped) and global filters. Filtes should be
71             in the same order in which they were added, except that global prefilters
72             should come before local prefilters, and global postfilters should come
73             after local postfilters.
74              
75             =item $engine->add_route(...)
76              
77             Add a route. Accepted parameters should be a list of key-value pairs with the
78             following keys:
79              
80             =over 4
81              
82             =item spec
83              
84             A route specification, which can be a string path, arrayref of paths, or a
85             hashref with a verb (HTTP request method) as the key(s) and the previously
86             described string or arrayref as the value(s). The engine should allow regex
87             matching and parameterization of path elements, as described in the default
88             engine base class for PlackX::Framework, Router::Boom.
89              
90             =item base
91              
92             An optional base uri path to be used as a prefix for the spec path uri(s).
93              
94             (A future version might eliminate this parameter, such that the Router.pm
95             package handles it before sending it to the engine.)
96              
97             =item prefilters
98              
99             An arrayref of local (package-scoped) prefilters.
100              
101             =item postfilters
102              
103             An arrayref of local (package-scoped) postfilters.
104              
105             =back
106              
107             =item $obj->add_global_filter(...)
108              
109             Add a global filter. Parameters should be a list of key-value pairs with the following
110             keys:
111              
112             =over 4
113              
114             =item when
115              
116             The string "before" or "after" for prefilters and postfilters, respectively.
117              
118             =item action
119              
120             A subref to be executed.
121              
122             =item pattern
123              
124             An optional path segment or pattern such that the filter will only apply if the
125             request path matches the pattern.
126              
127             The pattern may be one of:
128              
129             1. a string, in which case the global filter should match if the request
130             path_info STARTS WITH the string.
131              
132             2. a scalar reference to the string, in which case the global filter should
133             match if the request path_info is identical to the string.
134              
135             3. a reference to a regex, in which case the global filter should match if
136             the request path_info =~ the regex.
137              
138             =back
139              
140             =item $obj->freeze
141              
142             A method telling the router engine to compile itself and prevent more routes
143             from being added. This is required but may be implemented as a no-op.
144              
145             =back
146              
147             =head1 META
148              
149             For copyright and license, see PlackX::Framework.
150