1Catalyst::Controller(3)User Contributed Perl DocumentatioCnatalyst::Controller(3)
2
6 Catalyst::Controller - Catalyst Controller base class
7
9 package MyApp::Controller::Search
10 use base qw/Catalyst::Controller/;
11 sub foo : Local {
13 my ($self,$c,@args) = @_;
14 ...
15 } # Dispatches to /search/foo
16
18 Controllers are where the actions in the Catalyst framework reside.
19 Each action is represented by a function with an attribute to identify
20 what kind of action it is. See the Catalyst::Dispatcher for more info
21 about how Catalyst dispatches to actions.
22
24 Like any other Catalyst::Component, controllers have a config hash,
25 accessible through $self->config from the controller actions. Some
26 settings are in use by the Catalyst framework:
27 namespace
29 This specifies the internal namespace the controller should be bound
30 to. By default the controller is bound to the URI version of the
31 controller name. For instance controller 'MyApp::Controller::Foo::Bar'
32 will be bound to 'foo/bar'. The default Root controller is an example
33 of setting namespace to '' (the null string).
34 path
36 Sets 'path_prefix', as described below.
37 action
39 Allows you to set the attributes that the dispatcher creates actions
40 out of. This allows you to do 'rails style routes', or override some
41 of the attribute definitions of actions composed from Roles. You can
42 set arguments globally (for all actions of the controller) and
43 specifically (for a single action).
44 __PACKAGE__->config(
46 action => {
47 '*' => { Chained => 'base', Args => 0 },
48 base => { Chained => '/', PathPart => '', CaptureArgs => 0 },
49 },
50 );
51 In the case above every sub in the package would be made into a Chain
53 endpoint with a URI the same as the sub name for each sub, chained to
54 the sub named "base". Ergo dispatch to "/example" would call the "base"
55 method, then the "example" method.
56 action_args
58 Allows you to set constructor arguments on your actions. You can set
59 arguments globally and specifically (as above). This is particularly
60 useful when using "ActionRole"s (Catalyst::Controller::ActionRole) and
61 custom "ActionClass"es.
62 __PACKAGE__->config(
64 action_args => {
65 '*' => { globalarg1 => 'hello', globalarg2 => 'goodbye' },
66 'specific_action' => { customarg => 'arg1' },
67 },
68 );
69 In the case above the action class associated with "specific_action"
71 would get passed the following arguments, in addition to the normal
72 action constructor arguments, when it is instantiated:
73 (globalarg1 => 'hello', globalarg2 => 'goodbye', customarg => 'arg1')
75
77 BUILDARGS ($app, @args)
78 From Catalyst::Component::ApplicationAttribute, stashes the application
79 instance as $self->_application.
80 $self->action_for($action_name)
82 Returns the Catalyst::Action object (if any) for a given action in this
83 controller or relative to it. You may refer to actions in controllers
84 nested under the current controllers namespace, or in controllers 'up'
85 from the current controller namespace. For example:
86 package MyApp::Controller::One::Two;
88 use base 'Catalyst::Controller';
89 sub foo :Local {
91 my ($self, $c) = @_;
92 $self->action_for('foo'); # action 'foo' in Controller 'One::Two'
93 $self->action_for('three/bar'); # action 'bar' in Controller 'One::Two::Three'
94 $self->action_for('../boo'); # action 'boo' in Controller 'One'
95 }
96 This returns 'undef' if there is no action matching the requested
98 action name (after any path normalization) so you should check for this
99 as needed.
100 $self->action_namespace($c)
102 Returns the private namespace for actions in this component. Defaults
103 to a value from the controller name (for e.g.
104 MyApp::Controller::Foo::Bar becomes "foo/bar") or can be overridden
105 from the "namespace" config key.
106 $self->path_prefix($c)
108 Returns the default path prefix for :PathPrefix, :Local and relative
109 :Path actions in this component. Defaults to the action_namespace or
110 can be overridden from the "path" config key.
111 $self->register_actions($c)
113 Finds all applicable actions for this component, creates
114 Catalyst::Action objects (using $self->create_action) for them and
115 registers them with $c->dispatcher.
116 $self->get_action_methods()
118 Returns a list of Moose::Meta::Method objects, doing the
119 MooseX::MethodAttributes::Role::Meta::Method role, which are the set of
120 action methods for this package.
121 $self->register_action_methods($c, @methods)
123 Creates action objects for a set of action methods using "
124 create_action ", and registers them with the dispatcher.
125 $self->action_class(%args)
127 Used when a controller is creating an action to determine the correct
128 base action class to use.
129 $self->create_action(%args)
131 Called with a hash of data to be use for construction of a new
132 Catalyst::Action (or appropriate sub/alternative class) object.
133 $self->gather_action_roles(\%action_args)
135 Gathers the list of roles to apply to an action with the given
136 %action_args.
137 $self->gather_default_action_roles(\%action_args)
139 returns a list of action roles to be applied based on core, builtin
140 rules. Currently only the Catalyst::ActionRole::HTTPMethods role is
141 applied this way.
142 $self->_application
144 $self->_app
145 Returns the application instance stored by "new()"
146
148 Please see Catalyst::Manual::Intro for more details
149 Think of action attributes as a sort of way to record metadata about an
151 action, similar to how annotations work in other languages you might
152 have heard of. Generally Catalyst uses these to influence how the
153 dispatcher sees your action and when it will run it in response to an
154 incoming request. They can also be used for other things. Here's a
155 summary, but you should refer to the linked manual page for additional
156 help.
157 Global
159 sub homepage :Global { ... }
160 A global action defined in any controller always runs relative to your
162 root. So the above is the same as:
163 sub myaction :Path("/homepage") { ... }
165 Absolute
167 Status: Deprecated alias to "Global".
168 Local
170 Alias to "Path("$action_name"). The following two actions are the
171 same:
172 sub myaction :Local { ... }
174 sub myaction :Path('myaction') { ... }
175 Relative
177 Status: Deprecated alias to "Local"
178 Path
180 Handle various types of paths:
181 package MyApp::Controller::Baz {
183 ...
185 sub myaction1 :Path { ... } # -> /baz
187 sub myaction2 :Path('foo') { ... } # -> /baz/foo
188 sub myaction2 :Path('/bar') { ... } # -> /bar
189 }
190 This is a general toolbox for attaching your action to a given path.
192 Regex
194 Regexp
195 Status: Deprecated. Use Chained methods or other techniques. If you
196 really depend on this, install the standalone
197 Catalyst::DispatchType::Regex distribution.
198 A global way to match a give regular expression in the incoming request
200 path.
201 LocalRegex
203 LocalRegexp
204 Status: Deprecated. Use Chained methods or other techniques. If you
205 really depend on this, install the standalone
206 Catalyst::DispatchType::Regex distribution.
207 Like "Regex" but scoped under the namespace of the containing
209 controller
210 Chained
212 ChainedParent
213 PathPrefix
214 PathPart
215 CaptureArgs
216 Allowed values for CaptureArgs is a single integer (CaptureArgs(2),
217 meaning two allowed) or you can declare a Moose, MooseX::Types or
218 Type::Tiny named constraint such as CaptureArgs(Int,Str) would require
219 two args with the first being a Integer and the second a string. You
220 may declare your own custom type constraints and import them into the
221 controller namespace:
222 package MyApp::Controller::Root;
224 use Moose;
226 use MooseX::MethodAttributes;
227 use MyApp::Types qw/Int/;
228 extends 'Catalyst::Controller';
230 sub chain_base :Chained(/) CaptureArgs(1) { }
232 sub any_priority_chain :Chained(chain_base) PathPart('') Args(1) { }
234 sub int_priority_chain :Chained(chain_base) PathPart('') Args(Int) { }
236 See Catalyst::RouteMatching for more.
238 Please see Catalyst::DispatchType::Chained for more.
240 ActionClass
242 Set the base class for the action, defaults to "Catalyst::Action". It
243 is now preferred to use "Does".
244 MyAction
246 Set the ActionClass using a custom Action in your project namespace.
247 The following is exactly the same:
249 sub foo_action1 : Local ActionClass('+MyApp::Action::Bar') { ... }
251 sub foo_action2 : Local MyAction('Bar') { ... }
252 Does
254 package MyApp::Controller::Zoo;
255 sub foo : Local Does('Buzz') { ... } # Catalyst::ActionRole::
257 sub bar : Local Does('~Buzz') { ... } # MyApp::ActionRole::Buzz
258 sub baz : Local Does('+MyApp::ActionRole::Buzz') { ... }
259 GET
261 POST
262 PUT
263 DELETE
264 OPTION
265 HEAD
266 PATCH
267 Method('...')
268 Sets the give action path to match the specified HTTP method, or via
269 one of the broadly accepted methods of overriding the 'true' method
270 (see Catalyst::ActionRole::HTTPMethods).
271 Args
273 When used with "Path" indicates the number of arguments expected in the
274 path. However if no Args value is set, assumed to 'slurp' all
275 remaining path pars under this namespace.
276 Allowed values for Args is a single integer (Args(2), meaning two
278 allowed) or you can declare a Moose, MooseX::Types or Type::Tiny named
279 constraint such as Args(Int,Str) would require two args with the first
280 being a Integer and the second a string. You may declare your own
281 custom type constraints and import them into the controller namespace:
282 package MyApp::Controller::Root;
284 use Moose;
286 use MooseX::MethodAttributes;
287 use MyApp::Types qw/Tuple Int Str StrMatch UserId/;
288 extends 'Catalyst::Controller';
290 sub user :Local Args(UserId) {
292 my ($self, $c, $int) = @_;
293 }
294 sub an_int :Local Args(Int) {
296 my ($self, $c, $int) = @_;
297 }
298 sub many_ints :Local Args(ArrayRef[Int]) {
300 my ($self, $c, @ints) = @_;
301 }
302 sub match :Local Args(StrMatch[qr{\d\d-\d\d-\d\d}]) {
304 my ($self, $c, $int) = @_;
305 }
306 If you choose not to use imported type constraints (like Type::Tiny, or
308 <MooseX::Types> you may use Moose 'stringy' types however just like
309 when you use these types in your declared attributes you must quote
310 them:
311 sub my_moose_type :Local Args('Int') { ... }
313 If you use 'reference' type constraints (such as ArrayRef[Int]) that
315 have an unknown number of allowed matches, we set this the same way
316 "Args" is. Please keep in mind that actions with an undetermined
317 number of args match at lower precedence than those with a fixed
318 number. You may use reference types such as Tuple from Types::Standard
319 that allows you to fix the number of allowed args. For example
320 Args(Tuple[Int,Int]) would be determined to be two args (or really the
321 same as Args(Int,Int).) You may find this useful for creating custom
322 subtypes with complex matching rules that you wish to reuse over many
323 actions.
324 See Catalyst::RouteMatching for more.
326 Note: It is highly recommended to use Type::Tiny for your type
328 constraints over other options. Type::Tiny exposed a better meta data
329 interface which allows us to do more and better types of introspection
330 driving tests and debugging.
331 Consumes('...')
333 Matches the current action against the content-type of the request.
334 Typically this is used when the request is a POST or PUT and you want
335 to restrict the submitted content type. For example, you might have an
336 HTML for that either returns classic url encoded form data, or JSON
337 when Javascript is enabled. In this case you may wish to match either
338 incoming type to one of two different actions, for properly processing.
339 Examples:
341 sub is_json : Chained('start') Consumes('application/json') { ... }
343 sub is_urlencoded : Chained('start') Consumes('application/x-www-form-urlencoded') { ... }
344 sub is_multipart : Chained('start') Consumes('multipart/form-data') { ... }
345 To reduce boilerplate, we include the following content type shortcuts:
347 Examples
349 sub is_json : Chained('start') Consume(JSON) { ... }
351 sub is_urlencoded : Chained('start') Consumes(UrlEncoded) { ... }
352 sub is_multipart : Chained('start') Consumes(Multipart) { ... }
353 You may specify more than one match:
355 sub is_more_than_one
357 : Chained('start')
358 : Consumes('application/x-www-form-urlencoded')
359 : Consumes('multipart/form-data')
360 sub is_more_than_one
362 : Chained('start')
363 : Consumes(UrlEncoded)
364 : Consumes(Multipart)
365 Since it is a common case the shortcut "HTMLForm" matches both
367 'application/x-www-form-urlencoded' and 'multipart/form-data'. Here's
368 the full list of available shortcuts:
369 JSON => 'application/json',
371 JS => 'application/javascript',
372 PERL => 'application/perl',
373 HTML => 'text/html',
374 XML => 'text/XML',
375 Plain => 'text/plain',
376 UrlEncoded => 'application/x-www-form-urlencoded',
377 Multipart => 'multipart/form-data',
378 HTMLForm => ['application/x-www-form-urlencoded','multipart/form-data'],
379 Please keep in mind that when dispatching, Catalyst will match the
381 first most relevant case, so if you use the "Consumes" attribute, you
382 should place your most accurate matches early in the Chain, and your
383 'catchall' actions last.
384 See Catalyst::ActionRole::ConsumesContent for more.
386 Scheme(...)
388 Allows you to specify a URI scheme for the action or action chain. For
389 example you can required that a given path be "https" or that it is a
390 websocket endpoint "ws" or "wss". For an action chain you may
391 currently only have one defined Scheme.
392 package MyApp::Controller::Root;
394 use base 'Catalyst::Controller';
396 sub is_http :Path(scheme) Scheme(http) Args(0) {
398 my ($self, $c) = @_;
399 $c->response->body("is_http");
400 }
401 sub is_https :Path(scheme) Scheme(https) Args(0) {
403 my ($self, $c) = @_;
404 $c->response->body("is_https");
405 }
406 In the above example http://localhost/root/scheme would match the first
408 action (is_http) but https://localhost/root/scheme would match the
409 second.
410 As an added benefit, if an action or action chain defines a Scheme,
412 when using $c->uri_for the scheme of the generated URL will use what
413 you define in the action or action chain (the current behavior is to
414 set the scheme based on the current incoming request). This makes it
415 easier to use uri_for on websites where some paths are secure and
416 others are not. You may also use this to other schemes like
417 websockets.
418 See Catalyst::ActionRole::Scheme for more.
420
422 _parse_[$name]_attr
423 Allows you to customize parsing of subroutine attributes.
424 sub myaction1 :Path TwoArgs { ... }
426 sub _parse_TwoArgs_attr {
428 my ( $self, $c, $name, $value ) = @_;
429 # $self -> controller instance
430 #
431 return(Args => 2);
432 }
433 Please note that this feature does not let you actually assign new
435 functions to actions via subroutine attributes, but is really more for
436 creating useful aliases to existing core and extended attributes, and
437 transforms based on existing information (like from configuration).
438 Code for actually doing something meaningful with the subroutine
439 attributes will be located in the Catalyst::Action classes (or your
440 subclasses), Catalyst::Dispatcher and in subclasses of
441 Catalyst::DispatchType. Remember these methods only get called
442 basically once when the application is starting, not per request!
443
445 Catalyst Contributors, see Catalyst.pm
446
448 This library is free software. You can redistribute it and/or modify it
449 under the same terms as Perl itself.
450perl v5.34.0 2021-07-22 Catalyst::Controller(3)