4 use Moose::Meta::Class ();
5 extends 'Catalyst::Component';
6 use Moose::Util qw/find_meta/;
7 use namespace::clean -except => 'meta';
8 use Catalyst::Exception;
9 use Catalyst::Exception::Detach;
10 use Catalyst::Exception::Go;
12 use Catalyst::Request;
13 use Catalyst::Request::Upload;
14 use Catalyst::Response;
16 use Catalyst::Controller;
18 use Devel::InnerPackage ();
19 use Module::Pluggable::Object ();
20 use Text::SimpleTable ();
21 use Path::Class::Dir ();
22 use Path::Class::File ();
27 use Tree::Simple qw/use_weak_refs/;
28 use Tree::Simple::Visitor::FindByUID;
29 use Class::C3::Adopt::NEXT;
30 use List::MoreUtils qw/uniq/;
32 use String::RewritePrefix;
33 use Catalyst::EngineLoader;
35 use Carp qw/croak carp shortmess/;
38 use Moose::Util 'find_meta';
39 use Plack::Middleware::Conditional;
40 use Plack::Middleware::ReverseProxy;
41 use Plack::Middleware::IIS6ScriptNameFix;
42 use Plack::Middleware::IIS7KeepAliveFix;
43 use Plack::Middleware::LighttpdScriptNameFix;
44 use Plack::Middleware::ContentLength;
45 use Plack::Middleware::Head;
46 use Plack::Middleware::HTTPExceptions;
47 use Plack::Middleware::FixMissingBodyInRedirect;
48 use Plack::Middleware::MethodOverride;
49 use Plack::Middleware::RemoveRedundantBody;
50 use Catalyst::Middleware::Stash;
52 use Class::Load 'load_class';
53 use Encode 2.21 'decode_utf8', 'encode_utf8';
55 BEGIN { require 5.008003; }
57 has stack => (is => 'ro', default => sub { [] });
58 has state => (is => 'rw', default => 0);
59 has stats => (is => 'rw');
60 has action => (is => 'rw');
61 has counter => (is => 'rw', default => sub { {} });
66 my $class = ref $self;
67 my $composed_request_class = $class->composed_request_class;
68 return $composed_request_class->new( $self->_build_request_constructor_args);
72 sub _build_request_constructor_args {
74 my %p = ( _log => $self->log );
75 $p{_uploadtmp} = $self->_uploadtmp if $self->_has_uploadtmp;
76 $p{data_handlers} = {$self->registered_data_handlers};
77 $p{_use_hash_multivalue} = $self->config->{use_hash_multivalue_in_request}
78 if $self->config->{use_hash_multivalue_in_request};
82 sub composed_request_class {
84 return $class->_composed_request_class if $class->_composed_request_class;
86 my @traits = (@{$class->request_class_traits||[]}, @{$class->config->{request_class_traits}||[]});
88 # For each trait listed, figure out what the namespace is. First we try the $trait
89 # as it is in the config. Then try $MyApp::TraitFor::Request:$trait. Last we try
90 # Catalyst::TraitFor::Request::$trait. If none load, throw error.
92 my $trait_ns = 'TraitFor::Request';
93 my @normalized_traits = map {
94 Class::Load::load_first_existing_class($_, $class.'::'.$trait_ns.'::'. $_, 'Catalyst::'.$trait_ns.'::'.$_)
97 if ($class->debug && scalar(@normalized_traits)) {
98 my $column_width = Catalyst::Utils::term_width() - 6;
99 my $t = Text::SimpleTable->new($column_width);
100 $t->row($_) for @normalized_traits;
101 $class->log->debug( "Composed Request Class Traits:\n" . $t->draw . "\n" );
104 return $class->_composed_request_class(Moose::Util::with_traits($class->request_class, @normalized_traits));
111 my $class = ref $self;
112 my $composed_response_class = $class->composed_response_class;
113 return $composed_response_class->new( $self->_build_response_constructor_args);
117 sub _build_response_constructor_args {
120 encoding => $_[0]->encoding,
124 sub composed_response_class {
126 return $class->_composed_response_class if $class->_composed_response_class;
128 my @traits = (@{$class->response_class_traits||[]}, @{$class->config->{response_class_traits}||[]});
130 my $trait_ns = 'TraitFor::Response';
131 my @normalized_traits = map {
132 Class::Load::load_first_existing_class($_, $class.'::'.$trait_ns.'::'. $_, 'Catalyst::'.$trait_ns.'::'.$_)
135 if ($class->debug && scalar(@normalized_traits)) {
136 my $column_width = Catalyst::Utils::term_width() - 6;
137 my $t = Text::SimpleTable->new($column_width);
138 $t->row($_) for @normalized_traits;
139 $class->log->debug( "Composed Response Class Traits:\n" . $t->draw . "\n" );
142 return $class->_composed_response_class(Moose::Util::with_traits($class->response_class, @normalized_traits));
145 has namespace => (is => 'rw');
147 sub depth { scalar @{ shift->stack || [] }; }
148 sub comp { shift->component(@_) }
151 my $self = shift; return $self->request(@_);
154 my $self = shift; return $self->response(@_);
157 # For backwards compatibility
158 sub finalize_output { shift->finalize_body(@_) };
163 our $RECURSION = 1000;
164 our $DETACH = Catalyst::Exception::Detach->new;
165 our $GO = Catalyst::Exception::Go->new;
167 #I imagine that very few of these really
168 #need to be class variables. if any.
169 #maybe we should just make them attributes with a default?
170 __PACKAGE__->mk_classdata($_)
171 for qw/components arguments dispatcher engine log dispatcher_class
172 engine_loader context_class request_class response_class stats_class
173 setup_finished _psgi_app loading_psgi_file run_options _psgi_middleware
174 _data_handlers _encoding _encode_check finalized_default_middleware
175 request_class_traits response_class_traits stats_class_traits
176 _composed_request_class _composed_response_class _composed_stats_class/;
178 __PACKAGE__->dispatcher_class('Catalyst::Dispatcher');
179 __PACKAGE__->request_class('Catalyst::Request');
180 __PACKAGE__->response_class('Catalyst::Response');
181 __PACKAGE__->stats_class('Catalyst::Stats');
183 sub composed_stats_class {
185 return $class->_composed_stats_class if $class->_composed_stats_class;
187 my @traits = (@{$class->stats_class_traits||[]}, @{$class->config->{stats_class_traits}||[]});
189 my $trait_ns = 'TraitFor::Stats';
190 my @normalized_traits = map {
191 Class::Load::load_first_existing_class($_, $class.'::'.$trait_ns.'::'. $_, 'Catalyst::'.$trait_ns.'::'.$_)
194 if ($class->debug && scalar(@normalized_traits)) {
195 my $column_width = Catalyst::Utils::term_width() - 6;
196 my $t = Text::SimpleTable->new($column_width);
197 $t->row($_) for @normalized_traits;
198 $class->log->debug( "Composed Stats Class Traits:\n" . $t->draw . "\n" );
201 return $class->_composed_stats_class(Moose::Util::with_traits($class->stats_class, @normalized_traits));
204 __PACKAGE__->_encode_check(Encode::FB_CROAK | Encode::LEAVE_SRC);
206 # Remember to update this in Catalyst::Runtime as well!
207 our $VERSION = '5.90106';
208 $VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
211 my ( $class, @arguments ) = @_;
213 # We have to limit $class to Catalyst to avoid pushing Catalyst upon every
215 return unless $class eq 'Catalyst';
217 my $caller = caller();
218 return if $caller eq 'main';
220 my $meta = Moose::Meta::Class->initialize($caller);
221 unless ( $caller->isa('Catalyst') ) {
222 my @superclasses = ($meta->superclasses, $class, 'Catalyst::Controller');
223 $meta->superclasses(@superclasses);
225 # Avoid possible C3 issues if 'Moose::Object' is already on RHS of MyApp
226 $meta->superclasses(grep { $_ ne 'Moose::Object' } $meta->superclasses);
228 unless( $meta->has_method('meta') ){
229 if ($Moose::VERSION >= 1.15) {
230 $meta->_add_meta_method('meta');
233 $meta->add_method(meta => sub { Moose::Meta::Class->initialize("${caller}") } );
237 $caller->arguments( [@arguments] );
241 sub _application { $_[0] }
247 Catalyst - The Elegant MVC Web Application Framework
250 <a href="https://badge.fury.io/pl/Catalyst-Runtime"><img src="https://badge.fury.io/pl/Catalyst-Runtime.svg" alt="CPAN version" height="18"></a>
251 <a href="https://travis-ci.org/perl-catalyst/catalyst-runtime/"><img src="https://api.travis-ci.org/perl-catalyst/catalyst-runtime.png" alt="Catalyst></a>
252 <a href="http://cpants.cpanauthors.org/dist/Catalyst-Runtime"><img src="http://cpants.cpanauthors.org/dist/Catalyst-Runtime.png" alt='Kwalitee Score' /></a>
256 See the L<Catalyst::Manual> distribution for comprehensive
257 documentation and tutorials.
259 # Install Catalyst::Devel for helpers and other development tools
260 # use the helper to create a new application
263 # add models, views, controllers
264 script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
265 script/myapp_create.pl view MyTemplate TT
266 script/myapp_create.pl controller Search
268 # built in testserver -- use -r to restart automatically on changes
269 # --help to see all available options
270 script/myapp_server.pl
272 # command line testing interface
273 script/myapp_test.pl /yada
276 use Catalyst qw/-Debug/; # include plugins here as well
278 ### In lib/MyApp/Controller/Root.pm (autocreated)
279 sub foo : Chained('/') Args() { # called for /foo, /foo/1, /foo/1/2, etc.
280 my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
281 $c->stash->{template} = 'foo.tt'; # set the template
282 # lookup something from db -- stash vars are passed to TT
284 $c->model('Database::Foo')->search( { country => $args[0] } );
285 if ( $c->req->params->{bar} ) { # access GET or POST parameters
286 $c->forward( 'bar' ); # process another action
287 # do something else after forward returns
291 # The foo.tt TT template can use the stash data from the database
292 [% WHILE (item = data.next) %]
296 # called for /bar/of/soap, /bar/of/soap/10, etc.
297 sub bar : Chained('/') PathPart('/bar/of/soap') Args() { ... }
299 # called after all actions are finished
301 my ( $self, $c ) = @_;
302 if ( scalar @{ $c->error } ) { ... } # handle errors
303 return if $c->res->body; # already have a response
304 $c->forward( 'MyApp::View::TT' ); # render template
307 See L<Catalyst::Manual::Intro> for additional information.
311 Catalyst is a modern framework for making web applications without the
312 pain usually associated with this process. This document is a reference
313 to the main Catalyst application. If you are a new user, we suggest you
314 start with L<Catalyst::Manual::Tutorial> or L<Catalyst::Manual::Intro>.
316 See L<Catalyst::Manual> for more documentation.
318 Catalyst plugins can be loaded by naming them as arguments to the "use
319 Catalyst" statement. Omit the C<Catalyst::Plugin::> prefix from the
320 plugin name, i.e., C<Catalyst::Plugin::My::Module> becomes
323 use Catalyst qw/My::Module/;
325 If your plugin starts with a name other than C<Catalyst::Plugin::>, you can
326 fully qualify the name by using a unary plus:
330 +Fully::Qualified::Plugin::Name
333 Special flags like C<-Debug> can also be specified as
334 arguments when Catalyst is loaded:
336 use Catalyst qw/-Debug My::Module/;
338 The position of plugins and flags in the chain is important, because
339 they are loaded in the order in which they appear.
341 The following flags are supported:
345 Enables debug output. You can also force this setting from the system
346 environment with CATALYST_DEBUG or <MYAPP>_DEBUG. The environment
347 settings override the application, with <MYAPP>_DEBUG having the highest
350 This sets the log level to 'debug' and enables full debug output on the
351 error screen. If you only want the latter, see L<< $c->debug >>.
355 Forces Catalyst to use a specific home directory, e.g.:
357 use Catalyst qw[-Home=/usr/mst];
359 This can also be done in the shell environment by setting either the
360 C<CATALYST_HOME> environment variable or C<MYAPP_HOME>; where C<MYAPP>
361 is replaced with the uppercased name of your application, any "::" in
362 the name will be replaced with underscores, e.g. MyApp::Web should use
363 MYAPP_WEB_HOME. If both variables are set, the MYAPP_HOME one will be used.
365 If none of these are set, Catalyst will attempt to automatically detect the
366 home directory. If you are working in a development environment, Catalyst
367 will try and find the directory containing either Makefile.PL, Build.PL,
368 dist.ini, or cpanfile. If the application has been installed into the system
369 (i.e. you have done C<make install>), then Catalyst will use the path to your
370 application module, without the .pm extension (e.g., /foo/MyApp if your
371 application was installed at /foo/MyApp.pm)
375 use Catalyst '-Log=warn,fatal,error';
377 Specifies a comma-delimited list of log levels.
381 Enables statistics collection and reporting.
383 use Catalyst qw/-Stats=1/;
385 You can also force this setting from the system environment with CATALYST_STATS
386 or <MYAPP>_STATS. The environment settings override the application, with
387 <MYAPP>_STATS having the highest priority.
389 Stats are also enabled if L<< debugging |/"-Debug" >> is enabled.
393 =head2 INFORMATION ABOUT THE CURRENT REQUEST
397 Returns a L<Catalyst::Action> object for the current action, which
398 stringifies to the action name. See L<Catalyst::Action>.
402 Returns the namespace of the current action, i.e., the URI prefix
403 corresponding to the controller of the current action. For example:
405 # in Controller::Foo::Bar
406 $c->namespace; # returns 'foo/bar';
412 Returns the current L<Catalyst::Request> object, giving access to
413 information about the current client request (including parameters,
414 cookies, HTTP headers, etc.). See L<Catalyst::Request>.
416 =head2 REQUEST FLOW HANDLING
418 =head2 $c->forward( $action [, \@arguments ] )
420 =head2 $c->forward( $class, $method, [, \@arguments ] )
422 This is one way of calling another action (method) in the same or
423 a different controller. You can also use C<< $self->my_method($c, @args) >>
424 in the same controller or C<< $c->controller('MyController')->my_method($c, @args) >>
425 in a different controller.
426 The main difference is that 'forward' uses some of the Catalyst request
427 cycle overhead, including debugging, which may be useful to you. On the
428 other hand, there are some complications to using 'forward', restrictions
429 on values returned from 'forward', and it may not handle errors as you prefer.
430 Whether you use 'forward' or not is up to you; it is not considered superior to
431 the other ways to call a method.
433 'forward' calls another action, by its private name. If you give a
434 class name but no method, C<process()> is called. You may also optionally
435 pass arguments in an arrayref. The action will receive the arguments in
436 C<@_> and C<< $c->req->args >>. Upon returning from the function,
437 C<< $c->req->args >> will be restored to the previous values.
439 Any data C<return>ed from the action forwarded to, will be returned by the
442 my $foodata = $c->forward('/foo');
443 $c->forward('index');
444 $c->forward(qw/Model::DBIC::Foo do_stuff/);
445 $c->forward('View::TT');
447 Note that L<< forward|/"$c->forward( $action [, \@arguments ] )" >> implies
448 an C<< eval { } >> around the call (actually
449 L<< execute|/"$c->execute( $class, $coderef )" >> does), thus rendering all
450 exceptions thrown by the called action non-fatal and pushing them onto
451 $c->error instead. If you want C<die> to propagate you need to do something
455 die join "\n", @{ $c->error } if @{ $c->error };
457 Or make sure to always return true values from your actions and write
460 $c->forward('foo') || return;
462 Another note is that C<< $c->forward >> always returns a scalar because it
463 actually returns $c->state which operates in a scalar context.
464 Thus, something like:
468 in an action that is forwarded to is going to return a scalar,
469 i.e. how many items are in that array, which is probably not what you want.
470 If you need to return an array then return a reference to it,
473 $c->stash->{array} = \@array;
475 and access it from the stash.
477 Keep in mind that the C<end> method used is that of the caller action. So a C<$c-E<gt>detach> inside a forwarded action would run the C<end> method from the original action requested.
481 sub forward { my $c = shift; no warnings 'recursion'; $c->dispatcher->forward( $c, @_ ) }
483 =head2 $c->detach( $action [, \@arguments ] )
485 =head2 $c->detach( $class, $method, [, \@arguments ] )
489 The same as L<< forward|/"$c->forward( $action [, \@arguments ] )" >>, but
490 doesn't return to the previous action when processing is finished.
492 When called with no arguments it escapes the processing chain entirely.
496 sub detach { my $c = shift; $c->dispatcher->detach( $c, @_ ) }
498 =head2 $c->visit( $action [, \@arguments ] )
500 =head2 $c->visit( $action [, \@captures, \@arguments ] )
502 =head2 $c->visit( $class, $method, [, \@arguments ] )
504 =head2 $c->visit( $class, $method, [, \@captures, \@arguments ] )
506 Almost the same as L<< forward|/"$c->forward( $action [, \@arguments ] )" >>,
507 but does a full dispatch, instead of just calling the new C<$action> /
508 C<< $class->$method >>. This means that C<begin>, C<auto> and the method
509 you go to are called, just like a new request.
511 In addition both C<< $c->action >> and C<< $c->namespace >> are localized.
512 This means, for example, that C<< $c->action >> methods such as
513 L<name|Catalyst::Action/name>, L<class|Catalyst::Action/class> and
514 L<reverse|Catalyst::Action/reverse> return information for the visited action
515 when they are invoked within the visited action. This is different from the
516 behavior of L<< forward|/"$c->forward( $action [, \@arguments ] )" >>, which
517 continues to use the $c->action object from the caller action even when
518 invoked from the called action.
520 C<< $c->stash >> is kept unchanged.
522 In effect, L<< visit|/"$c->visit( $action [, \@captures, \@arguments ] )" >>
523 allows you to "wrap" another action, just as it would have been called by
524 dispatching from a URL, while the analogous
525 L<< go|/"$c->go( $action [, \@captures, \@arguments ] )" >> allows you to
526 transfer control to another action as if it had been reached directly from a URL.
530 sub visit { my $c = shift; $c->dispatcher->visit( $c, @_ ) }
532 =head2 $c->go( $action [, \@arguments ] )
534 =head2 $c->go( $action [, \@captures, \@arguments ] )
536 =head2 $c->go( $class, $method, [, \@arguments ] )
538 =head2 $c->go( $class, $method, [, \@captures, \@arguments ] )
540 The relationship between C<go> and
541 L<< visit|/"$c->visit( $action [, \@captures, \@arguments ] )" >> is the same as
542 the relationship between
543 L<< forward|/"$c->forward( $class, $method, [, \@arguments ] )" >> and
544 L<< detach|/"$c->detach( $action [, \@arguments ] )" >>. Like C<< $c->visit >>,
545 C<< $c->go >> will perform a full dispatch on the specified action or method,
546 with localized C<< $c->action >> and C<< $c->namespace >>. Like C<detach>,
547 C<go> escapes the processing of the current request chain on completion, and
548 does not return to its caller.
550 @arguments are arguments to the final destination of $action. @captures are
551 arguments to the intermediate steps, if any, on the way to the final sub of
556 sub go { my $c = shift; $c->dispatcher->go( $c, @_ ) }
562 Returns the current L<Catalyst::Response> object, see there for details.
566 Returns a hashref to the stash, which may be used to store data and pass
567 it between components during a request. You can also set hash keys by
568 passing arguments. The stash is automatically sent to the view. The
569 stash is cleared at the end of a request; it cannot be used for
570 persistent storage (for this you must use a session; see
571 L<Catalyst::Plugin::Session> for a complete system integrated with
574 $c->stash->{foo} = $bar;
575 $c->stash( { moose => 'majestic', qux => 0 } );
576 $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
578 # stash is automatically passed to the view for use in a template
579 $c->forward( 'MyApp::View::TT' );
581 The stash hash is currently stored in the PSGI C<$env> and is managed by
582 L<Catalyst::Middleware::Stash>. Since it's part of the C<$env> items in
583 the stash can be accessed in sub applications mounted under your main
584 L<Catalyst> application. For example if you delegate the response of an
585 action to another L<Catalyst> application, that sub application will have
586 access to all the stash keys of the main one, and if can of course add
587 more keys of its own. However those new keys will not 'bubble' back up
588 to the main application.
590 For more information the best thing to do is to review the test case:
591 t/middleware-stash.t in the distribution /t directory.
597 $c->log->error("You are requesting the stash but you don't have a context") unless blessed $c;
598 return Catalyst::Middleware::Stash::get_stash($c->req->env)->(@_);
603 =head2 $c->error($error, ...)
605 =head2 $c->error($arrayref)
607 Returns an arrayref containing error messages. If Catalyst encounters an
608 error while processing a request, it stores the error in $c->error. This
609 method should only be used to store fatal error messages.
611 my @error = @{ $c->error };
615 $c->error('Something bad happened');
617 Calling this will always return an arrayref (if there are no errors it
618 will be an empty arrayref.
625 my $error = ref $_[0] eq 'ARRAY' ? $_[0] : [@_];
626 croak @$error unless ref $c;
627 push @{ $c->{error} }, @$error;
629 elsif ( defined $_[0] ) { $c->{error} = undef }
630 return $c->{error} || [];
635 Contains the return value of the last executed action.
636 Note that << $c->state >> operates in a scalar context which means that all
637 values it returns are scalar.
639 Please note that if an action throws an exception, the value of state
640 should no longer be considered the return if the last action. It is generally
641 going to be 0, which indicates an error state. Examine $c->error for error
644 =head2 $c->clear_errors
646 Clear errors. You probably don't want to clear the errors unless you are
647 implementing a custom error screen.
649 This is equivalent to running
660 =head2 $c->has_errors
662 Returns true if you have errors
666 sub has_errors { scalar(@{shift->error}) ? 1:0 }
668 =head2 $c->last_error
670 Returns the most recent error in the stack (the one most recently added...)
671 or nothing if there are no errors. This does not modify the contents of the
677 my (@errs) = @{shift->error};
678 return scalar(@errs) ? $errs[-1]: undef;
683 shifts the most recently added error off the error stack and returns it. Returns
684 nothing if there are no more errors.
690 my @errors = @{$self->error};
691 my $err = shift(@errors);
692 $self->{error} = \@errors;
698 pops the most recently added error off the error stack and returns it. Returns
699 nothing if there are no more errors.
705 my @errors = @{$self->error};
706 my $err = pop(@errors);
707 $self->{error} = \@errors;
711 sub _comp_search_prefixes {
713 return map $c->components->{ $_ }, $c->_comp_names_search_prefixes(@_);
716 # search components given a name and some prefixes
717 sub _comp_names_search_prefixes {
718 my ( $c, $name, @prefixes ) = @_;
719 my $appclass = ref $c || $c;
720 my $filter = "^${appclass}::(" . join( '|', @prefixes ) . ')::';
721 $filter = qr/$filter/; # Compile regex now rather than once per loop
723 # map the original component name to the sub part that we will search against
724 my %eligible = map { my $n = $_; $n =~ s{^$appclass\::[^:]+::}{}; $_ => $n; }
725 grep { /$filter/ } keys %{ $c->components };
727 # undef for a name will return all
728 return keys %eligible if !defined $name;
730 my $query = $name->$_isa('Regexp') ? $name : qr/^$name$/i;
731 my @result = grep { $eligible{$_} =~ m{$query} } keys %eligible;
733 return @result if @result;
735 # if we were given a regexp to search against, we're done.
736 return if $name->$_isa('Regexp');
738 # skip regexp fallback if configured
740 if $appclass->config->{disable_component_resolution_regex_fallback};
744 @result = grep { $eligible{ $_ } =~ m{$query} } keys %eligible;
746 # no results? try against full names
748 @result = grep { m{$query} } keys %eligible;
751 # don't warn if we didn't find any results, it just might not exist
753 # Disgusting hack to work out correct method name
754 my $warn_for = lc $prefixes[0];
755 my $msg = "Used regexp fallback for \$c->${warn_for}('${name}'), which found '" .
756 (join '", "', @result) . "'. Relying on regexp fallback behavior for " .
757 "component resolution is unreliable and unsafe.";
758 my $short = $result[0];
759 # remove the component namespace prefix
760 $short =~ s/.*?(Model|Controller|View):://;
761 my $shortmess = Carp::shortmess('');
762 if ($shortmess =~ m#Catalyst/Plugin#) {
763 $msg .= " You probably need to set '$short' instead of '${name}' in this " .
765 } elsif ($shortmess =~ m#Catalyst/lib/(View|Controller)#) {
766 $msg .= " You probably need to set '$short' instead of '${name}' in this " .
767 "component's config";
769 $msg .= " You probably meant \$c->${warn_for}('$short') instead of \$c->${warn_for}('${name}'), " .
770 "but if you really wanted to search, pass in a regexp as the argument " .
771 "like so: \$c->${warn_for}(qr/${name}/)";
773 $c->log->warn( "${msg}$shortmess" );
779 # Find possible names for a prefix
781 my ( $c, @prefixes ) = @_;
782 my $appclass = ref $c || $c;
784 my $filter = "^${appclass}::(" . join( '|', @prefixes ) . ')::';
786 my @names = map { s{$filter}{}; $_; }
787 $c->_comp_names_search_prefixes( undef, @prefixes );
792 # Filter a component before returning by calling ACCEPT_CONTEXT if available
794 sub _filter_component {
795 my ( $c, $comp, @args ) = @_;
797 if(ref $comp eq 'CODE') {
801 if ( eval { $comp->can('ACCEPT_CONTEXT'); } ) {
802 return $comp->ACCEPT_CONTEXT( $c, @args );
805 $c->log->warn("You called component '${\$comp->catalyst_component_name}' with arguments [@args], but this component does not ACCEPT_CONTEXT, so args are ignored.") if scalar(@args) && $c->debug;
810 =head2 COMPONENT ACCESSORS
812 =head2 $c->controller($name)
814 Gets a L<Catalyst::Controller> instance by name.
816 $c->controller('Foo')->do_stuff;
818 If the name is omitted, will return the controller for the dispatched
821 If you want to search for controllers, pass in a regexp as the argument.
823 # find all controllers that start with Foo
824 my @foo_controllers = $c->controller(qr{^Foo});
830 my ( $c, $name, @args ) = @_;
832 my $appclass = ref($c) || $c;
834 unless ( $name->$_isa('Regexp') ) { # Direct component hash lookup to avoid costly regexps
835 my $comps = $c->components;
836 my $check = $appclass."::Controller::".$name;
837 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
838 foreach my $path (@{$appclass->config->{ setup_components }->{ search_extra }}) {
839 next unless $path =~ /.*::Controller/;
840 $check = $path."::".$name;
841 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
844 my @result = $c->_comp_search_prefixes( $name, qw/Controller C/ );
845 return map { $c->_filter_component( $_, @args ) } @result if ref $name;
846 return $c->_filter_component( $result[ 0 ], @args );
849 return $c->component( $c->action->class );
852 =head2 $c->model($name)
854 Gets a L<Catalyst::Model> instance by name.
856 $c->model('Foo')->do_stuff;
858 Any extra arguments are directly passed to ACCEPT_CONTEXT, if the model
859 defines ACCEPT_CONTEXT. If it does not, the args are discarded.
861 If the name is omitted, it will look for
862 - a model object in $c->stash->{current_model_instance}, then
863 - a model name in $c->stash->{current_model}, then
864 - a config setting 'default_model', or
865 - check if there is only one model, and return it if that's the case.
867 If you want to search for models, pass in a regexp as the argument.
869 # find all models that start with Foo
870 my @foo_models = $c->model(qr{^Foo});
875 my ( $c, $name, @args ) = @_;
876 my $appclass = ref($c) || $c;
878 unless ( $name->$_isa('Regexp') ) { # Direct component hash lookup to avoid costly regexps
879 my $comps = $c->components;
880 my $check = $appclass."::Model::".$name;
881 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
882 foreach my $path (@{$appclass->config->{ setup_components }->{ search_extra }}) {
883 next unless $path =~ /.*::Model/;
884 $check = $path."::".$name;
885 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
888 my @result = $c->_comp_search_prefixes( $name, qw/Model M/ );
889 return map { $c->_filter_component( $_, @args ) } @result if ref $name;
890 return $c->_filter_component( $result[ 0 ], @args );
894 return $c->stash->{current_model_instance}
895 if $c->stash->{current_model_instance};
896 return $c->model( $c->stash->{current_model} )
897 if $c->stash->{current_model};
899 return $c->model( $appclass->config->{default_model} )
900 if $appclass->config->{default_model};
902 my( $comp, $rest ) = $c->_comp_search_prefixes( undef, qw/Model M/);
905 $c->log->warn( Carp::shortmess('Calling $c->model() will return a random model unless you specify one of:') );
906 $c->log->warn( '* $c->config(default_model => "the name of the default model to use")' );
907 $c->log->warn( '* $c->stash->{current_model} # the name of the model to use for this request' );
908 $c->log->warn( '* $c->stash->{current_model_instance} # the instance of the model to use for this request' );
909 $c->log->warn( 'NB: in version 5.81, the "random" behavior will not work at all.' );
912 return $c->_filter_component( $comp );
916 =head2 $c->view($name)
918 Gets a L<Catalyst::View> instance by name.
920 $c->view('Foo')->do_stuff;
922 Any extra arguments are directly passed to ACCEPT_CONTEXT.
924 If the name is omitted, it will look for
925 - a view object in $c->stash->{current_view_instance}, then
926 - a view name in $c->stash->{current_view}, then
927 - a config setting 'default_view', or
928 - check if there is only one view, and return it if that's the case.
930 If you want to search for views, pass in a regexp as the argument.
932 # find all views that start with Foo
933 my @foo_views = $c->view(qr{^Foo});
938 my ( $c, $name, @args ) = @_;
940 my $appclass = ref($c) || $c;
942 unless ( $name->$_isa('Regexp') ) { # Direct component hash lookup to avoid costly regexps
943 my $comps = $c->components;
944 my $check = $appclass."::View::".$name;
945 if( exists $comps->{$check} ) {
946 return $c->_filter_component( $comps->{$check}, @args );
949 $c->log->warn( "Attempted to use view '$check', but does not exist" );
951 foreach my $path (@{$appclass->config->{ setup_components }->{ search_extra }}) {
952 next unless $path =~ /.*::View/;
953 $check = $path."::".$name;
954 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
957 my @result = $c->_comp_search_prefixes( $name, qw/View V/ );
958 return map { $c->_filter_component( $_, @args ) } @result if ref $name;
959 return $c->_filter_component( $result[ 0 ], @args );
963 return $c->stash->{current_view_instance}
964 if $c->stash->{current_view_instance};
965 return $c->view( $c->stash->{current_view} )
966 if $c->stash->{current_view};
968 return $c->view( $appclass->config->{default_view} )
969 if $appclass->config->{default_view};
971 my( $comp, $rest ) = $c->_comp_search_prefixes( undef, qw/View V/);
974 $c->log->warn( 'Calling $c->view() will return a random view unless you specify one of:' );
975 $c->log->warn( '* $c->config(default_view => "the name of the default view to use")' );
976 $c->log->warn( '* $c->stash->{current_view} # the name of the view to use for this request' );
977 $c->log->warn( '* $c->stash->{current_view_instance} # the instance of the view to use for this request' );
978 $c->log->warn( 'NB: in version 5.81, the "random" behavior will not work at all.' );
981 return $c->_filter_component( $comp );
984 =head2 $c->controllers
986 Returns the available names which can be passed to $c->controller
992 return $c->_comp_names(qw/Controller C/);
997 Returns the available names which can be passed to $c->model
1003 return $c->_comp_names(qw/Model M/);
1009 Returns the available names which can be passed to $c->view
1015 return $c->_comp_names(qw/View V/);
1018 =head2 $c->comp($name)
1020 =head2 $c->component($name)
1022 Gets a component object by name. This method is not recommended,
1023 unless you want to get a specific component by full
1024 class. C<< $c->controller >>, C<< $c->model >>, and C<< $c->view >>
1025 should be used instead.
1027 If C<$name> is a regexp, a list of components matched against the full
1028 component name will be returned.
1030 If Catalyst can't find a component by name, it will fallback to regex
1031 matching by default. To disable this behaviour set
1032 disable_component_resolution_regex_fallback to a true value.
1034 __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );
1039 my ( $c, $name, @args ) = @_;
1042 my $comps = $c->components;
1045 # is it the exact name?
1046 return $c->_filter_component( $comps->{ $name }, @args )
1047 if exists $comps->{ $name };
1049 # perhaps we just omitted "MyApp"?
1050 my $composed = ( ref $c || $c ) . "::${name}";
1051 return $c->_filter_component( $comps->{ $composed }, @args )
1052 if exists $comps->{ $composed };
1054 # search all of the models, views and controllers
1055 my( $comp ) = $c->_comp_search_prefixes( $name, qw/Model M Controller C View V/ );
1056 return $c->_filter_component( $comp, @args ) if $comp;
1060 if $c->config->{disable_component_resolution_regex_fallback};
1062 # This is here so $c->comp( '::M::' ) works
1063 my $query = ref $name ? $name : qr{$name}i;
1065 my @result = grep { m{$query} } keys %{ $c->components };
1066 return map { $c->_filter_component( $_, @args ) } @result if ref $name;
1068 if( $result[ 0 ] ) {
1069 $c->log->warn( Carp::shortmess(qq(Found results for "${name}" using regexp fallback)) );
1070 $c->log->warn( 'Relying on the regexp fallback behavior for component resolution' );
1071 $c->log->warn( 'is unreliable and unsafe. You have been warned' );
1072 return $c->_filter_component( $result[ 0 ], @args );
1075 # I would expect to return an empty list here, but that breaks back-compat
1079 return sort keys %{ $c->components };
1082 =head2 CLASS DATA AND HELPER CLASSES
1086 Returns or takes a hashref containing the application's configuration.
1088 __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
1090 You can also use a C<YAML>, C<XML> or L<Config::General> config file
1091 like C<myapp.conf> in your applications home directory. See
1092 L<Catalyst::Plugin::ConfigLoader>.
1094 =head3 Cascading configuration
1096 The config method is present on all Catalyst components, and configuration
1097 will be merged when an application is started. Configuration loaded with
1098 L<Catalyst::Plugin::ConfigLoader> takes precedence over other configuration,
1099 followed by configuration in your top level C<MyApp> class. These two
1100 configurations are merged, and then configuration data whose hash key matches a
1101 component name is merged with configuration for that component.
1103 The configuration for a component is then passed to the C<new> method when a
1104 component is constructed.
1108 MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
1109 MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });
1111 will mean that C<MyApp::Model::Foo> receives the following data when
1114 MyApp::Model::Foo->new({
1120 It's common practice to use a Moose attribute
1121 on the receiving component to access the config value.
1123 package MyApp::Model::Foo;
1127 # this attr will receive 'baz' at construction time
1133 You can then get the value 'baz' by calling $c->model('Foo')->bar
1134 (or $self->bar inside code in the model).
1136 B<NOTE:> you MUST NOT call C<< $self->config >> or C<< __PACKAGE__->config >>
1137 as a way of reading config within your code, as this B<will not> give you the
1138 correctly merged config back. You B<MUST> take the config values supplied to
1139 the constructor and use those instead.
1143 around config => sub {
1147 croak('Setting config after setup has been run is not allowed.')
1148 if ( @_ and $c->setup_finished );
1155 Returns the logging object instance. Unless it is already set, Catalyst
1156 sets this up with a L<Catalyst::Log> object. To use your own log class,
1157 set the logger with the C<< __PACKAGE__->log >> method prior to calling
1158 C<< __PACKAGE__->setup >>.
1160 __PACKAGE__->log( MyLogger->new );
1165 $c->log->info( 'Now logging with my own logger!' );
1167 Your log class should implement the methods described in
1172 Returned True if there's a valid encoding
1174 =head2 clear_encoding
1176 Clears the encoding for the current context
1180 Sets or gets the application encoding. Setting encoding takes either an
1181 Encoding object or a string that we try to resolve via L<Encode::find_encoding>.
1183 You would expect to get the encoding object back if you attempt to set it. If
1184 there is a failure you will get undef returned and an error message in the log.
1188 sub has_encoding { shift->encoding ? 1:0 }
1190 sub clear_encoding {
1193 $c->encoding(undef);
1195 $c->log->error("You can't clear encoding on the application");
1205 # Don't let one change this once we are too far into the response
1206 if(blessed $c && $c->res->finalized_headers) {
1207 Carp::croak("You may not change the encoding once the headers are finalized");
1211 # Let it be set to undef
1212 if (my $wanted = shift) {
1213 $encoding = Encode::find_encoding($wanted)
1214 or Carp::croak( qq/Unknown encoding '$wanted'/ );
1215 binmode(STDERR, ':encoding(' . $encoding->name . ')');
1222 ? $c->{encoding} = $encoding
1223 : $c->_encoding($encoding);
1225 $encoding = ref $c && exists $c->{encoding}
1235 Returns 1 if debug mode is enabled, 0 otherwise.
1237 You can enable debug mode in several ways:
1241 =item By calling myapp_server.pl with the -d flag
1243 =item With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG
1245 =item The -Debug option in your MyApp.pm
1247 =item By declaring C<sub debug { 1 }> in your MyApp.pm.
1251 The first three also set the log level to 'debug'.
1253 Calling C<< $c->debug(1) >> has no effect.
1259 =head2 $c->dispatcher
1261 Returns the dispatcher instance. See L<Catalyst::Dispatcher>.
1265 Returns the engine instance. See L<Catalyst::Engine>.
1268 =head2 UTILITY METHODS
1270 =head2 $c->path_to(@path)
1272 Merges C<@path> with C<< $c->config->{home} >> and returns a
1273 L<Path::Class::Dir> object. Note you can usually use this object as
1274 a filename, but sometimes you will have to explicitly stringify it
1275 yourself by calling the C<< ->stringify >> method.
1279 $c->path_to( 'db', 'sqlite.db' );
1284 my ( $c, @path ) = @_;
1285 my $path = Path::Class::Dir->new( $c->config->{home}, @path );
1286 if ( -d $path ) { return $path }
1287 else { return Path::Class::File->new( $c->config->{home}, @path ) }
1291 my ( $class, $name, $plugin, @args ) = @_;
1293 # See block comment in t/unit_core_plugin.t
1294 $class->log->warn(qq/Adding plugin using the ->plugin method is deprecated, and will be removed in a future release/);
1296 $class->_register_plugin( $plugin, 1 );
1298 eval { $plugin->import };
1299 $class->mk_classdata($name);
1301 eval { $obj = $plugin->new(@args) };
1304 Catalyst::Exception->throw( message =>
1305 qq/Couldn't instantiate instant plugin "$plugin", "$@"/ );
1308 $class->$name($obj);
1309 $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
1315 Initializes the dispatcher and engine, loads any plugins, and loads the
1316 model, view, and controller components. You may also specify an array
1317 of plugins to load here, if you choose to not load them in the C<use
1321 MyApp->setup( qw/-Debug/ );
1323 B<Note:> You B<should not> wrap this method with method modifiers
1324 or bad things will happen - wrap the C<setup_finalize> method instead.
1326 B<Note:> You can create a custom setup stage that will execute when the
1327 application is starting. Use this to customize setup.
1329 MyApp->setup(-Custom=value);
1332 my ($class, $value) = @_;
1335 Can be handy if you want to hook into the setup phase.
1340 my ( $class, @arguments ) = @_;
1341 croak('Running setup more than once')
1342 if ( $class->setup_finished );
1344 unless ( $class->isa('Catalyst') ) {
1346 Catalyst::Exception->throw(
1347 message => qq/'$class' does not inherit from Catalyst/ );
1350 if ( $class->arguments ) {
1351 @arguments = ( @arguments, @{ $class->arguments } );
1357 foreach (@arguments) {
1361 ( $flags->{log} ) ? 'debug,' . $flags->{log} : 'debug';
1363 elsif (/^-(\w+)=?(.*)$/) {
1364 $flags->{ lc $1 } = $2;
1367 push @{ $flags->{plugins} }, $_;
1371 $class->setup_home( delete $flags->{home} );
1373 $class->setup_log( delete $flags->{log} );
1374 $class->setup_plugins( delete $flags->{plugins} );
1376 $class->setup_data_handlers();
1377 $class->setup_dispatcher( delete $flags->{dispatcher} );
1378 if (my $engine = delete $flags->{engine}) {
1379 $class->log->warn("Specifying the engine in ->setup is no longer supported, see Catalyst::Upgrading");
1381 $class->setup_engine();
1382 $class->setup_stats( delete $flags->{stats} );
1384 for my $flag ( sort keys %{$flags} ) {
1386 if ( my $code = $class->can( 'setup_' . $flag ) ) {
1387 &$code( $class, delete $flags->{$flag} );
1390 $class->log->warn(qq/Unknown flag "$flag"/);
1394 eval { require Catalyst::Devel; };
1395 if( !$@ && $ENV{CATALYST_SCRIPT_GEN} && ( $ENV{CATALYST_SCRIPT_GEN} < $Catalyst::Devel::CATALYST_SCRIPT_GEN ) ) {
1396 $class->log->warn(<<"EOF");
1397 You are running an old script!
1399 Please update by running (this will overwrite existing files):
1400 catalyst.pl -force -scripts $class
1402 or (this will not overwrite existing files):
1403 catalyst.pl -scripts $class
1408 # Call plugins setup, this is stupid and evil.
1409 # Also screws C3 badly on 5.10, hack to avoid.
1411 no warnings qw/redefine/;
1412 local *setup = sub { };
1413 $class->setup unless $Catalyst::__AM_RESTARTING;
1416 # If you are expecting configuration info as part of your setup, it needs
1417 # to get called here and below, since we need the above line to support
1418 # ConfigLoader based configs.
1420 $class->setup_encoding();
1421 $class->setup_middleware();
1423 # Initialize our data structure
1424 $class->components( {} );
1426 $class->setup_components;
1428 if ( $class->debug ) {
1429 my @plugins = map { "$_ " . ( $_->VERSION || '' ) } $class->registered_plugins;
1432 my $column_width = Catalyst::Utils::term_width() - 6;
1433 my $t = Text::SimpleTable->new($column_width);
1434 $t->row($_) for @plugins;
1435 $class->log->debug( "Loaded plugins:\n" . $t->draw . "\n" );
1438 my @middleware = map {
1441 (ref($_) .' '. ($_->can('VERSION') ? $_->VERSION || '' : '')
1442 || '') } $class->registered_middlewares;
1445 my $column_width = Catalyst::Utils::term_width() - 6;
1446 my $t = Text::SimpleTable->new($column_width);
1447 $t->row($_) for @middleware;
1448 $class->log->debug( "Loaded PSGI Middleware:\n" . $t->draw . "\n" );
1451 my %dh = $class->registered_data_handlers;
1452 if (my @data_handlers = keys %dh) {
1453 my $column_width = Catalyst::Utils::term_width() - 6;
1454 my $t = Text::SimpleTable->new($column_width);
1455 $t->row($_) for @data_handlers;
1456 $class->log->debug( "Loaded Request Data Handlers:\n" . $t->draw . "\n" );
1459 my $dispatcher = $class->dispatcher;
1460 my $engine = $class->engine;
1461 my $home = $class->config->{home};
1463 $class->log->debug(sprintf(q/Loaded dispatcher "%s"/, blessed($dispatcher)));
1464 $class->log->debug(sprintf(q/Loaded engine "%s"/, blessed($engine)));
1468 ? $class->log->debug(qq/Found home "$home"/)
1469 : $class->log->debug(qq/Home "$home" doesn't exist/)
1470 : $class->log->debug(q/Couldn't find home/);
1472 my $column_width = Catalyst::Utils::term_width() - 8 - 9;
1474 my $t = Text::SimpleTable->new( [ $column_width, 'Class' ], [ 8, 'Type' ] );
1475 for my $comp ( sort keys %{ $class->components } ) {
1476 my $type = ref $class->components->{$comp} ? 'instance' : 'class';
1477 $t->row( $comp, $type );
1479 $class->log->debug( "Loaded components:\n" . $t->draw . "\n" )
1480 if ( keys %{ $class->components } );
1483 # Add our self to components, since we are also a component
1484 if( $class->isa('Catalyst::Controller') ){
1485 $class->components->{$class} = $class;
1488 $class->setup_actions;
1490 if ( $class->debug ) {
1491 my $name = $class->config->{name} || 'Application';
1492 $class->log->info("$name powered by Catalyst $Catalyst::VERSION");
1495 if ($class->config->{case_sensitive}) {
1496 $class->log->warn($class . "->config->{case_sensitive} is set.");
1497 $class->log->warn("This setting is deprecated and planned to be removed in Catalyst 5.81.");
1500 # call these so we pre setup the composed classes
1501 $class->composed_request_class;
1502 $class->composed_response_class;
1503 $class->composed_stats_class;
1505 $class->setup_finalize;
1507 # Flush the log for good measure (in case something turned off 'autoflush' early)
1508 $class->log->_flush() if $class->log->can('_flush');
1510 return $class || 1; # Just in case someone named their Application 0...
1513 =head2 $app->setup_finalize
1515 A hook to attach modifiers to. This method does not do anything except set the
1516 C<setup_finished> accessor.
1518 Applying method modifiers to the C<setup> method doesn't work, because of quirky things done for plugin setup.
1522 after setup_finalize => sub {
1530 sub setup_finalize {
1532 $class->setup_finished(1);
1535 =head2 $c->uri_for( $path?, @args?, \%query_values?, \$fragment? )
1537 =head2 $c->uri_for( $action, \@captures?, @args?, \%query_values?, \$fragment? )
1539 =head2 $c->uri_for( $action, [@captures, @args], \%query_values?, \$fragment? )
1541 Constructs an absolute L<URI> object based on the application root, the
1542 provided path, and the additional arguments and query parameters provided.
1543 When used as a string, provides a textual URI. If you need more flexibility
1544 than this (i.e. the option to provide relative URIs etc.) see
1545 L<Catalyst::Plugin::SmartURI>.
1547 If no arguments are provided, the URI for the current action is returned.
1548 To return the current action and also provide @args, use
1549 C<< $c->uri_for( $c->action, @args ) >>.
1551 If the first argument is a string, it is taken as a public URI path relative
1552 to C<< $c->namespace >> (if it doesn't begin with a forward slash) or
1553 relative to the application root (if it does). It is then merged with
1554 C<< $c->request->base >>; any C<@args> are appended as additional path
1555 components; and any C<%query_values> are appended as C<?foo=bar> parameters.
1557 B<NOTE> If you are using this 'stringy' first argument, we skip encoding and
1558 allow you to declare something like:
1560 $c->uri_for('/foo/bar#baz')
1562 Where 'baz' is a URI fragment. We consider this first argument string to be
1563 'expert' mode where you are expected to create a valid URL and we for the most
1564 part just pass it through without a lot of internal effort to escape and encode.
1566 If the first argument is a L<Catalyst::Action> it represents an action which
1567 will have its path resolved using C<< $c->dispatcher->uri_for_action >>. The
1568 optional C<\@captures> argument (an arrayref) allows passing the captured
1569 variables that are needed to fill in the paths of Chained and Regex actions;
1570 once the path is resolved, C<uri_for> continues as though a path was
1571 provided, appending any arguments or parameters and creating an absolute
1574 The captures for the current request can be found in
1575 C<< $c->request->captures >>, and actions can be resolved using
1576 C<< Catalyst::Controller->action_for($name) >>. If you have a private action
1577 path, use C<< $c->uri_for_action >> instead.
1579 # Equivalent to $c->req->uri
1580 $c->uri_for($c->action, $c->req->captures,
1581 @{ $c->req->args }, $c->req->params);
1583 # For the Foo action in the Bar controller
1584 $c->uri_for($c->controller('Bar')->action_for('Foo'));
1586 # Path to a static resource
1587 $c->uri_for('/static/images/logo.png');
1589 In general the scheme of the generated URI object will follow the incoming request
1590 however if your targeted action or action chain has the Scheme attribute it will
1593 Also, if the targeted Action or Action chain declares Args/CaptureArgs that have
1594 type constraints, we will require that your proposed URL verify on those declared
1600 my ( $c, $path, @args ) = @_;
1602 if ( $path->$_isa('Catalyst::Controller') ) {
1603 $path = $path->path_prefix;
1608 my $fragment = ((scalar(@args) && ref($args[-1]) eq 'SCALAR') ? pop @args : undef );
1610 unless(blessed $path) {
1611 if (defined($path) and $path =~ s/#(.+)$//) {
1612 if(defined($1) and $fragment) {
1613 carp "Abiguious fragment declaration: You cannot define a fragment in '$path' and as an argument '$fragment'";
1622 ( scalar @args && ref $args[$#args] eq 'HASH' ? pop @args : {} );
1624 undef($path) if (defined $path && $path eq '');
1626 carp "uri_for called with undef argument" if grep { ! defined $_ } @args;
1628 my $target_action = $path->$_isa('Catalyst::Action') ? $path : undef;
1629 if ( $path->$_isa('Catalyst::Action') ) { # action object
1630 s|/|%2F|g for @args;
1631 my $captures = [ map { s|/|%2F|g; $_; }
1632 ( scalar @args && ref $args[0] eq 'ARRAY'
1637 my $expanded_action = $c->dispatcher->expand_action( $action );
1638 my $num_captures = $expanded_action->number_of_captures;
1640 # ->uri_for( $action, \@captures_and_args, \%query_values? )
1641 if( !@args && $action->number_of_args ) {
1642 unshift @args, splice @$captures, $num_captures;
1646 unless($expanded_action->match_captures_constraints($c, $captures)) {
1647 carp "captures [@{$captures}] do not match the type constraints in actionchain ending with '$expanded_action'";
1652 $path = $c->dispatcher->uri_for_action($action, $captures);
1653 if (not defined $path) {
1654 $c->log->debug(qq/Can't find uri_for action '$action' @$captures/)
1658 $path = '/' if $path eq '';
1660 # At this point @encoded_args is the remaining Args (all captures removed).
1661 if($expanded_action->has_args_constraints) {
1662 unless($expanded_action->match_args($c,\@args)) {
1663 carp "args [@args] do not match the type constraints in action '$expanded_action'";
1669 unshift(@args, $path);
1671 unless (defined $path && $path =~ s!^/!!) { # in-place strip
1672 my $namespace = $c->namespace;
1673 if (defined $path) { # cheesy hack to handle path '../foo'
1674 $namespace =~ s{(?:^|/)[^/]+$}{} while $args[0] =~ s{^\.\./}{};
1676 unshift(@args, $namespace || '');
1679 # join args with '/', or a blank string
1680 my $args = join('/', grep { defined($_) } @args);
1681 $args =~ s/\?/%3F/g; # STUPID STUPID SPECIAL CASE
1684 my ($base, $class) = ('/', 'URI::_generic');
1686 $base = $c->req->base;
1687 if($target_action) {
1688 $target_action = $c->dispatcher->expand_action($target_action);
1689 if(my $s = $target_action->scheme) {
1694 $class = ref($base);
1697 $class = ref($base);
1700 $base =~ s{(?<!/)$}{/};
1704 if (my @keys = keys %$params) {
1705 # somewhat lifted from URI::_query's query_form
1706 $query = '?'.join('&', map {
1707 my $val = $params->{$_};
1708 #s/([;\/?:@&=+,\$\[\]%])/$URI::Escape::escapes{$1}/go; ## Commented out because seems to lead to double encoding - JNAP
1711 $val = '' unless defined $val;
1714 $param = encode_utf8($param);
1715 # using the URI::Escape pattern here so utf8 chars survive
1716 $param =~ s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
1719 $key = encode_utf8($key);
1720 # using the URI::Escape pattern here so utf8 chars survive
1721 $key =~ s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
1724 "${key}=$param"; } ( ref $val eq 'ARRAY' ? @$val : $val ));
1728 $base = encode_utf8 $base;
1729 $base =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1730 $args = encode_utf8 $args;
1731 $args =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1733 if(defined $fragment) {
1735 $fragment = encode_utf8(${$fragment});
1736 $fragment =~ s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
1737 $fragment =~ s/ /+/g;
1739 $query .= "#$fragment";
1742 my $res = bless(\"${base}${args}${query}", $class);
1746 =head2 $c->uri_for_action( $path, \@captures_and_args?, @args?, \%query_values? )
1748 =head2 $c->uri_for_action( $action, \@captures_and_args?, @args?, \%query_values? )
1754 A private path to the Catalyst action you want to create a URI for.
1756 This is a shortcut for calling C<< $c->dispatcher->get_action_by_path($path)
1757 >> and passing the resulting C<$action> and the remaining arguments to C<<
1760 You can also pass in a Catalyst::Action object, in which case it is passed to
1763 Note that although the path looks like a URI that dispatches to the wanted action, it is not a URI, but an internal path to that action.
1765 For example, if the action looks like:
1767 package MyApp::Controller::Users;
1769 sub lst : Path('the-list') {}
1773 $c->uri_for_action('/users/lst')
1775 and it will create the URI /users/the-list.
1777 =item \@captures_and_args?
1779 Optional array reference of Captures (i.e. C<<CaptureArgs or $c->req->captures>)
1780 and arguments to the request. Usually used with L<Catalyst::DispatchType::Chained>
1781 to interpolate all the parameters in the URI.
1785 Optional list of extra arguments - can be supplied in the
1786 C<< \@captures_and_args? >> array ref, or here - whichever is easier for your
1789 Your action can have zero, a fixed or a variable number of args (e.g.
1790 C<< Args(1) >> for a fixed number or C<< Args() >> for a variable number)..
1792 =item \%query_values?
1794 Optional array reference of query parameters to append. E.g.
1800 /rest/of/your/uri?foo=bar
1806 sub uri_for_action {
1807 my ( $c, $path, @args ) = @_;
1808 my $action = blessed($path)
1810 : $c->dispatcher->get_action_by_path($path);
1811 unless (defined $action) {
1812 croak "Can't find action for path '$path'";
1814 return $c->uri_for( $action, @args );
1817 =head2 $c->welcome_message
1819 Returns the Catalyst welcome HTML page.
1823 sub welcome_message {
1825 my $name = $c->config->{name};
1826 my $logo = $c->uri_for('/static/images/catalyst_logo.png');
1827 my $prefix = Catalyst::Utils::appprefix( ref $c );
1828 $c->response->content_type('text/html; charset=utf-8');
1830 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1831 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1832 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
1834 <meta http-equiv="Content-Language" content="en" />
1835 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
1836 <title>$name on Catalyst $VERSION</title>
1837 <style type="text/css">
1840 background-color: #eee;
1847 margin-bottom: 10px;
1849 background-color: #ccc;
1850 border: 1px solid #aaa;
1855 font-family: verdana, tahoma, sans-serif;
1858 font-family: verdana, tahoma, sans-serif;
1861 text-decoration: none;
1863 border-bottom: 1px dotted #bbb;
1865 :link:hover, :visited:hover {
1878 background-color: #fff;
1879 border: 1px solid #aaa;
1883 font-weight: normal;
1905 <h1><span id="appname">$name</span> on <a href="http://catalyst.perl.org">Catalyst</a>
1910 <img src="$logo" alt="Catalyst Logo" />
1912 <p>Welcome to the world of Catalyst.
1913 This <a href="http://en.wikipedia.org/wiki/MVC">MVC</a>
1914 framework will make web development something you had
1915 never expected it to be: Fun, rewarding, and quick.</p>
1916 <h2>What to do now?</h2>
1917 <p>That really depends on what <b>you</b> want to do.
1918 We do, however, provide you with a few starting points.</p>
1919 <p>If you want to jump right into web development with Catalyst
1920 you might want to start with a tutorial.</p>
1921 <pre>perldoc <a href="https://metacpan.org/module/Catalyst::Manual::Tutorial">Catalyst::Manual::Tutorial</a></code>
1923 <p>Afterwards you can go on to check out a more complete look at our features.</p>
1925 <code>perldoc <a href="https://metacpan.org/module/Catalyst::Manual::Intro">Catalyst::Manual::Intro</a>
1926 <!-- Something else should go here, but the Catalyst::Manual link seems unhelpful -->
1928 <h2>What to do next?</h2>
1929 <p>Next it's time to write an actual application. Use the
1930 helper scripts to generate <a href="https://metacpan.org/search?q=Catalyst%3A%3AController">controllers</a>,
1931 <a href="https://metacpan.org/search?q=Catalyst%3A%3AModel">models</a>, and
1932 <a href="https://metacpan.org/search?q=Catalyst%3A%3AView">views</a>;
1933 they can save you a lot of work.</p>
1934 <pre><code>script/${prefix}_create.pl --help</code></pre>
1935 <p>Also, be sure to check out the vast and growing
1936 collection of <a href="http://search.cpan.org/search?query=Catalyst">plugins for Catalyst on CPAN</a>;
1937 you are likely to find what you need there.
1941 <p>Catalyst has a very active community. Here are the main places to
1942 get in touch with us.</p>
1945 <a href="http://dev.catalyst.perl.org">Wiki</a>
1948 <a href="http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst">Mailing-List</a>
1951 <a href="irc://irc.perl.org/catalyst">IRC channel #catalyst on irc.perl.org</a>
1954 <h2>In conclusion</h2>
1955 <p>The Catalyst team hopes you will enjoy using Catalyst as much
1956 as we enjoyed making it. Please contact us if you have ideas
1957 for improvement or other feedback.</p>
1967 Contains a hash of options passed from the application script, including
1968 the original ARGV the script received, the processed values from that
1969 ARGV and any extra arguments to the script which were not processed.
1971 This can be used to add custom options to your application's scripts
1972 and setup your application differently depending on the values of these
1975 =head1 INTERNAL METHODS
1977 These methods are not meant to be used by end users.
1979 =head2 $c->components
1981 Returns a hash of components.
1983 =head2 $c->context_class
1985 Returns or sets the context class.
1989 Returns a hashref containing coderefs and execution counts (needed for
1990 deep recursion detection).
1994 Returns the number of actions on the current internal execution stack.
1998 Dispatches a request to actions.
2002 sub dispatch { my $c = shift; $c->dispatcher->dispatch( $c, @_ ) }
2004 =head2 $c->dispatcher_class
2006 Returns or sets the dispatcher class.
2008 =head2 $c->dump_these
2010 Returns a list of 2-element array references (name, structure) pairs
2011 that will be dumped on the error page in debug mode.
2017 [ Request => $c->req ],
2018 [ Response => $c->res ],
2019 [ Stash => $c->stash ],
2020 [ Config => $c->config ];
2023 =head2 $c->engine_class
2025 Returns or sets the engine class.
2027 =head2 $c->execute( $class, $coderef )
2029 Execute a coderef in given class and catch exceptions. Errors are available
2035 my ( $c, $class, $code ) = @_;
2036 $class = $c->component($class) || $class;
2039 if ( $c->depth >= $RECURSION ) {
2040 my $action = $code->reverse();
2041 $action = "/$action" unless $action =~ /->/;
2042 my $error = qq/Deep recursion detected calling "${action}"/;
2043 $c->log->error($error);
2049 my $stats_info = $c->_stats_start_execute( $code ) if $c->use_stats;
2051 push( @{ $c->stack }, $code );
2053 no warnings 'recursion';
2054 # N.B. This used to be combined, but I have seen $c get clobbered if so, and
2055 # I have no idea how, ergo $ret (which appears to fix the issue)
2056 eval { my $ret = $code->execute( $class, $c, @{ $c->req->args } ) || 0; $c->state( $ret ) };
2058 $c->_stats_finish_execute( $stats_info ) if $c->use_stats and $stats_info;
2060 my $last = pop( @{ $c->stack } );
2062 if ( my $error = $@ ) {
2063 #rethow if this can be handled by middleware
2064 if ( $c->_handle_http_exception($error) ) {
2065 foreach my $err (@{$c->error}) {
2066 $c->log->error($err);
2069 $c->log->_flush if $c->log->can('_flush');
2071 $error->can('rethrow') ? $error->rethrow : croak $error;
2073 if ( blessed($error) and $error->isa('Catalyst::Exception::Detach') ) {
2074 $error->rethrow if $c->depth > 1;
2076 elsif ( blessed($error) and $error->isa('Catalyst::Exception::Go') ) {
2077 $error->rethrow if $c->depth > 0;
2080 unless ( ref $error ) {
2081 no warnings 'uninitialized';
2083 my $class = $last->class;
2084 my $name = $last->name;
2085 $error = qq/Caught exception in $class->$name "$error"/;
2094 sub _stats_start_execute {
2095 my ( $c, $code ) = @_;
2096 my $appclass = ref($c) || $c;
2097 return if ( ( $code->name =~ /^_.*/ )
2098 && ( !$appclass->config->{show_internal_actions} ) );
2100 my $action_name = $code->reverse();
2101 $c->counter->{$action_name}++;
2103 my $action = $action_name;
2104 $action = "/$action" unless $action =~ /->/;
2106 # determine if the call was the result of a forward
2107 # this is done by walking up the call stack and looking for a calling
2108 # sub of Catalyst::forward before the eval
2110 for my $index ( 2 .. 11 ) {
2112 if ( ( caller($index) )[0] eq 'Catalyst'
2113 && ( caller($index) )[3] eq '(eval)' );
2115 if ( ( caller($index) )[3] =~ /forward$/ ) {
2116 $callsub = ( caller($index) )[3];
2117 $action = "-> $action";
2122 my $uid = $action_name . $c->counter->{$action_name};
2124 # is this a root-level call or a forwarded call?
2125 if ( $callsub =~ /forward$/ ) {
2126 my $parent = $c->stack->[-1];
2128 # forward, locate the caller
2129 if ( defined $parent && exists $c->counter->{"$parent"} ) {
2132 parent => "$parent" . $c->counter->{"$parent"},
2138 # forward with no caller may come from a plugin
2157 sub _stats_finish_execute {
2158 my ( $c, $info ) = @_;
2159 $c->stats->profile( end => $info );
2164 Finalizes the request.
2171 for my $error ( @{ $c->error } ) {
2172 $c->log->error($error);
2175 # Support skipping finalize for psgix.io style 'jailbreak'. Used to support
2176 # stuff like cometd and websockets
2178 if($c->request->_has_io_fh) {
2183 # Allow engine to handle finalize flow (for POE)
2184 my $engine = $c->engine;
2185 if ( my $code = $engine->can('finalize') ) {
2190 $c->finalize_uploads;
2193 if ( $#{ $c->error } >= 0 ) {
2197 $c->finalize_encoding;
2198 $c->finalize_headers unless $c->response->finalized_headers;
2204 if ($c->use_stats) {
2205 my $elapsed = $c->stats->elapsed;
2206 my $av = $elapsed == 0 ? '??' : sprintf '%.3f', 1 / $elapsed;
2208 "Request took ${elapsed}s ($av/s)\n" . $c->stats->report . "\n" );
2211 return $c->response->status;
2214 =head2 $c->finalize_body
2220 sub finalize_body { my $c = shift; $c->engine->finalize_body( $c, @_ ) }
2222 =head2 $c->finalize_cookies
2228 sub finalize_cookies { my $c = shift; $c->engine->finalize_cookies( $c, @_ ) }
2230 =head2 $c->finalize_error
2232 Finalizes error. If there is only one error in L</error> and it is an object that
2233 does C<as_psgi> or C<code> we rethrow the error and presume it caught by middleware
2234 up the ladder. Otherwise we return the debugging error page (in debug mode) or we
2235 return the default error page (production mode).
2239 sub finalize_error {
2241 if($#{$c->error} > 0) {
2242 $c->engine->finalize_error( $c, @_ );
2244 my ($error) = @{$c->error};
2245 if ( $c->_handle_http_exception($error) ) {
2246 # In the case where the error 'knows what it wants', becauses its PSGI
2247 # aware, just rethow and let middleware catch it
2248 $error->can('rethrow') ? $error->rethrow : croak $error;
2250 $c->engine->finalize_error( $c, @_ )
2255 =head2 $c->finalize_headers
2261 sub finalize_headers {
2264 my $response = $c->response; #accessor calls can add up?
2266 # Check if we already finalized headers
2267 return if $response->finalized_headers;
2270 if ( my $location = $response->redirect ) {
2271 $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
2272 $response->header( Location => $location );
2275 # Remove incorrectly added body and content related meta data when returning
2276 # an information response, or a response the is required to not include a body
2278 $c->finalize_cookies;
2280 # This currently is a NOOP but I don't want to remove it since I guess people
2281 # might have Response subclasses that use it for something... (JNAP)
2282 $c->response->finalize_headers();
2285 $response->finalized_headers(1);
2288 =head2 $c->finalize_encoding
2290 Make sure your body is encoded properly IF you set an encoding. By
2291 default the encoding is UTF-8 but you can disable it by explicitly setting the
2292 encoding configuration value to undef.
2294 We can only encode when the body is a scalar. Methods for encoding via the
2295 streaming interfaces (such as C<write> and C<write_fh> on L<Catalyst::Response>
2302 sub finalize_encoding {
2304 my $res = $c->res || return;
2306 # Warn if the set charset is different from the one you put into encoding. We need
2307 # to do this early since encodable_response is false for this condition and we need
2308 # to match the debug output for backcompat (there's a test for this...) -JNAP
2310 $res->content_type_charset and $c->encoding and
2311 (uc($c->encoding->mime_name) ne uc($res->content_type_charset))
2313 my $ct = lc($res->content_type_charset);
2314 $c->log->debug("Catalyst encoding config is set to encode in '" .
2315 $c->encoding->mime_name .
2316 "', content type is '$ct', not encoding ");
2320 ($res->encodable_response) and
2321 (defined($res->body)) and
2322 (ref(\$res->body) eq 'SCALAR')
2324 $c->res->body( $c->encoding->encode( $c->res->body, $c->_encode_check ) );
2326 # Set the charset if necessary. This might be a bit bonkers since encodable response
2327 # is false when the set charset is not the same as the encoding mimetype (maybe
2328 # confusing action at a distance here..
2329 # Don't try to set the charset if one already exists or if headers are already finalized
2330 $c->res->content_type($c->res->content_type . "; charset=" . $c->encoding->mime_name)
2331 unless($c->res->content_type_charset ||
2332 ($c->res->_context && $c->res->finalized_headers && !$c->res->_has_response_cb));
2336 =head2 $c->finalize_output
2338 An alias for finalize_body.
2340 =head2 $c->finalize_read
2342 Finalizes the input after reading is complete.
2346 sub finalize_read { my $c = shift; $c->engine->finalize_read( $c, @_ ) }
2348 =head2 $c->finalize_uploads
2350 Finalizes uploads. Cleans up any temporary files.
2354 sub finalize_uploads { my $c = shift; $c->engine->finalize_uploads( $c, @_ ) }
2356 =head2 $c->get_action( $action, $namespace )
2358 Gets an action in a given namespace.
2362 sub get_action { my $c = shift; $c->dispatcher->get_action(@_) }
2364 =head2 $c->get_actions( $action, $namespace )
2366 Gets all actions of a given name in a namespace and all parent
2371 sub get_actions { my $c = shift; $c->dispatcher->get_actions( $c, @_ ) }
2373 =head2 $app->handle_request( @arguments )
2375 Called to handle each HTTP request.
2379 sub handle_request {
2380 my ( $class, @arguments ) = @_;
2382 # Always expect worst case!
2385 if ($class->debug) {
2386 my $secs = time - $START || 1;
2387 my $av = sprintf '%.3f', $COUNT / $secs;
2388 my $time = localtime time;
2389 $class->log->info("*** Request $COUNT ($av/s) [$$] [$time] ***");
2392 my $c = $class->prepare(@arguments);
2394 $status = $c->finalize;
2396 #rethow if this can be handled by middleware
2397 if ( $class->_handle_http_exception($_) ) {
2398 $_->can('rethrow') ? $_->rethrow : croak $_;
2400 chomp(my $error = $_);
2401 $class->log->error(qq/Caught exception in engine "$error"/);
2406 if(my $coderef = $class->log->can('_flush')){
2407 $class->log->$coderef();
2412 =head2 $class->prepare( @arguments )
2414 Creates a Catalyst context from an engine-specific request (Apache, CGI,
2421 predicate => '_has_uploadtmp',
2425 my ( $class, @arguments ) = @_;
2428 # After the app/ctxt split, this should become an attribute based on something passed
2429 # into the application.
2430 $class->context_class( ref $class || $class ) unless $class->context_class;
2432 my $uploadtmp = $class->config->{uploadtmp};
2433 my $c = $class->context_class->new({ $uploadtmp ? (_uploadtmp => $uploadtmp) : ()});
2435 $c->response->_context($c);
2436 $c->stats($class->stats_class->new)->enable($c->use_stats);
2438 if ( $c->debug || $c->config->{enable_catalyst_header} ) {
2439 $c->res->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
2443 # Allow engine to direct the prepare flow (for POE)
2444 if ( my $prepare = $c->engine->can('prepare') ) {
2445 $c->engine->$prepare( $c, @arguments );
2448 $c->prepare_request(@arguments);
2449 $c->prepare_connection;
2450 $c->prepare_query_parameters;
2451 $c->prepare_headers; # Just hooks, no longer needed - they just
2452 $c->prepare_cookies; # cause the lazy attribute on req to build
2455 # Prepare the body for reading, either by prepare_body
2456 # or the user, if they are using $c->read
2459 # Parse the body unless the user wants it on-demand
2460 unless ( ref($c)->config->{parse_on_demand} ) {
2466 # VERY ugly and probably shouldn't rely on ->finalize actually working
2468 # failed prepare is always due to an invalid request, right?
2469 # Note we call finalize and then die here, which escapes
2470 # finalize being called in the enclosing block..
2471 # It in fact couldn't be called, as we don't return $c..
2472 # This is a mess - but I'm unsure you can fix this without
2473 # breaking compat for people doing crazy things (we should set
2474 # the 400 and just return the ctx here IMO, letting finalize get called
2476 if ( $c->_handle_http_exception($_) ) {
2477 foreach my $err (@{$c->error}) {
2478 $c->log->error($err);
2481 $c->log->_flush if $c->log->can('_flush');
2482 $_->can('rethrow') ? $_->rethrow : croak $_;
2484 $c->response->status(400);
2485 $c->response->content_type('text/plain');
2486 $c->response->body('Bad Request');
2497 =head2 $c->prepare_action
2499 Prepares action. See L<Catalyst::Dispatcher>.
2503 sub prepare_action {
2505 my $ret = $c->dispatcher->prepare_action( $c, @_);
2508 foreach (@{$c->req->arguments}, @{$c->req->captures}) {
2509 $_ = $c->_handle_param_unicode_decoding($_);
2517 =head2 $c->prepare_body
2519 Prepares message body.
2526 return if $c->request->_has_body;
2528 # Initialize on-demand data
2529 $c->engine->prepare_body( $c, @_ );
2530 $c->prepare_parameters;
2531 $c->prepare_uploads;
2534 =head2 $c->prepare_body_chunk( $chunk )
2536 Prepares a chunk of data before sending it to L<HTTP::Body>.
2538 See L<Catalyst::Engine>.
2542 sub prepare_body_chunk {
2544 $c->engine->prepare_body_chunk( $c, @_ );
2547 =head2 $c->prepare_body_parameters
2549 Prepares body parameters.
2553 sub prepare_body_parameters {
2555 $c->request->prepare_body_parameters( $c, @_ );
2558 =head2 $c->prepare_connection
2560 Prepares connection.
2564 sub prepare_connection {
2566 $c->request->prepare_connection($c);
2569 =head2 $c->prepare_cookies
2571 Prepares cookies by ensuring that the attribute on the request
2572 object has been built.
2576 sub prepare_cookies { my $c = shift; $c->request->cookies }
2578 =head2 $c->prepare_headers
2580 Prepares request headers by ensuring that the attribute on the request
2581 object has been built.
2585 sub prepare_headers { my $c = shift; $c->request->headers }
2587 =head2 $c->prepare_parameters
2589 Prepares parameters.
2593 sub prepare_parameters {
2595 $c->prepare_body_parameters;
2596 $c->engine->prepare_parameters( $c, @_ );
2599 =head2 $c->prepare_path
2601 Prepares path and base.
2605 sub prepare_path { my $c = shift; $c->engine->prepare_path( $c, @_ ) }
2607 =head2 $c->prepare_query_parameters
2609 Prepares query parameters.
2613 sub prepare_query_parameters {
2616 $c->engine->prepare_query_parameters( $c, @_ );
2619 =head2 $c->log_request
2621 Writes information about the request to the debug logs. This includes:
2625 =item * Request method, path, and remote IP address
2627 =item * Query keywords (see L<Catalyst::Request/query_keywords>)
2629 =item * Request parameters
2631 =item * File uploads
2640 return unless $c->debug;
2642 my($dump) = grep {$_->[0] eq 'Request' } $c->dump_these;
2643 my $request = $dump->[1];
2645 my ( $method, $path, $address ) = ( $request->method, $request->path, $request->address );
2647 $path = '/' unless length $path;
2650 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
2651 $path = decode_utf8($path);
2653 $c->log->debug(qq/"$method" request for "$path" from "$address"/);
2655 $c->log_request_headers($request->headers);
2657 if ( my $keywords = $request->query_keywords ) {
2658 $c->log->debug("Query keywords are: $keywords");
2661 $c->log_request_parameters( query => $request->query_parameters, $request->_has_body ? (body => $request->body_parameters) : () );
2663 $c->log_request_uploads($request);
2666 =head2 $c->log_response
2668 Writes information about the response to the debug logs by calling
2669 C<< $c->log_response_status_line >> and C<< $c->log_response_headers >>.
2676 return unless $c->debug;
2678 my($dump) = grep {$_->[0] eq 'Response' } $c->dump_these;
2679 my $response = $dump->[1];
2681 $c->log_response_status_line($response);
2682 $c->log_response_headers($response->headers);
2685 =head2 $c->log_response_status_line($response)
2687 Writes one line of information about the response to the debug logs. This includes:
2691 =item * Response status code
2693 =item * Content-Type header (if present)
2695 =item * Content-Length header (if present)
2701 sub log_response_status_line {
2702 my ($c, $response) = @_;
2706 'Response Code: %s; Content-Type: %s; Content-Length: %s',
2707 $response->status || 'unknown',
2708 $response->headers->header('Content-Type') || 'unknown',
2709 $response->headers->header('Content-Length') || 'unknown'
2714 =head2 $c->log_response_headers($headers);
2716 Hook method which can be wrapped by plugins to log the response headers.
2717 No-op in the default implementation.
2721 sub log_response_headers {}
2723 =head2 $c->log_request_parameters( query => {}, body => {} )
2725 Logs request parameters to debug logs
2729 sub log_request_parameters {
2731 my %all_params = @_;
2733 return unless $c->debug;
2735 my $column_width = Catalyst::Utils::term_width() - 44;
2736 foreach my $type (qw(query body)) {
2737 my $params = $all_params{$type};
2738 next if ! keys %$params;
2739 my $t = Text::SimpleTable->new( [ 35, 'Parameter' ], [ $column_width, 'Value' ] );
2740 for my $key ( sort keys %$params ) {
2741 my $param = $params->{$key};
2742 my $value = defined($param) ? $param : '';
2743 $t->row( $key, ref $value eq 'ARRAY' ? ( join ', ', @$value ) : $value );
2745 $c->log->debug( ucfirst($type) . " Parameters are:\n" . $t->draw );
2749 =head2 $c->log_request_uploads
2751 Logs file uploads included in the request to the debug logs.
2752 The parameter name, filename, file type, and file size are all included in
2757 sub log_request_uploads {
2759 my $request = shift;
2760 return unless $c->debug;
2761 my $uploads = $request->uploads;
2762 if ( keys %$uploads ) {
2763 my $t = Text::SimpleTable->new(
2764 [ 12, 'Parameter' ],
2769 for my $key ( sort keys %$uploads ) {
2770 my $upload = $uploads->{$key};
2771 for my $u ( ref $upload eq 'ARRAY' ? @{$upload} : ($upload) ) {
2772 $t->row( $key, $u->filename, $u->type, $u->size );
2775 $c->log->debug( "File Uploads are:\n" . $t->draw );
2779 =head2 $c->log_request_headers($headers);
2781 Hook method which can be wrapped by plugins to log the request headers.
2782 No-op in the default implementation.
2786 sub log_request_headers {}
2788 =head2 $c->log_headers($type => $headers)
2790 Logs L<HTTP::Headers> (either request or response) to the debug logs.
2797 my $headers = shift; # an HTTP::Headers instance
2799 return unless $c->debug;
2801 my $column_width = Catalyst::Utils::term_width() - 28;
2802 my $t = Text::SimpleTable->new( [ 15, 'Header Name' ], [ $column_width, 'Value' ] );
2805 my ( $name, $value ) = @_;
2806 $t->row( $name, $value );
2809 $c->log->debug( ucfirst($type) . " Headers:\n" . $t->draw );
2813 =head2 $c->prepare_read
2815 Prepares the input for reading.
2819 sub prepare_read { my $c = shift; $c->engine->prepare_read( $c, @_ ) }
2821 =head2 $c->prepare_request
2823 Prepares the engine request.
2827 sub prepare_request { my $c = shift; $c->engine->prepare_request( $c, @_ ) }
2829 =head2 $c->prepare_uploads
2835 sub prepare_uploads {
2837 $c->engine->prepare_uploads( $c, @_ );
2840 =head2 $c->prepare_write
2842 Prepares the output for writing.
2846 sub prepare_write { my $c = shift; $c->engine->prepare_write( $c, @_ ) }
2848 =head2 $c->request_class
2850 Returns or sets the request class. Defaults to L<Catalyst::Request>.
2852 =head2 $app->request_class_traits
2854 An arrayref of L<Moose::Role>s which are applied to the request class. You can
2855 name the full namespace of the role, or a namespace suffix, which will then
2856 be tried against the following standard namespace prefixes.
2858 $MyApp::TraitFor::Request::$trait_suffix
2859 Catalyst::TraitFor::Request::$trait_suffix
2861 So for example if you set:
2863 MyApp->request_class_traits(['Foo']);
2865 We try each possible role in turn (and throw an error if none load)
2868 MyApp::TraitFor::Request::Foo
2869 Catalyst::TraitFor::Request::Foo
2871 The namespace part 'TraitFor::Request' was chosen to assist in backwards
2872 compatibility with L<CatalystX::RoleApplicator> which previously provided
2873 these features in a stand alone package.
2875 =head2 $app->composed_request_class
2877 This is the request class which has been composed with any request_class_traits.
2879 =head2 $c->response_class
2881 Returns or sets the response class. Defaults to L<Catalyst::Response>.
2883 =head2 $app->response_class_traits
2885 An arrayref of L<Moose::Role>s which are applied to the response class. You can
2886 name the full namespace of the role, or a namespace suffix, which will then
2887 be tried against the following standard namespace prefixes.
2889 $MyApp::TraitFor::Response::$trait_suffix
2890 Catalyst::TraitFor::Response::$trait_suffix
2892 So for example if you set:
2894 MyApp->response_class_traits(['Foo']);
2896 We try each possible role in turn (and throw an error if none load)
2899 MyApp::TraitFor::Response::Foo
2900 Catalyst::TraitFor::Responset::Foo
2902 The namespace part 'TraitFor::Response' was chosen to assist in backwards
2903 compatibility with L<CatalystX::RoleApplicator> which previously provided
2904 these features in a stand alone package.
2907 =head2 $app->composed_response_class
2909 This is the request class which has been composed with any response_class_traits.
2911 =head2 $c->read( [$maxlength] )
2913 Reads a chunk of data from the request body. This method is designed to
2914 be used in a while loop, reading C<$maxlength> bytes on every call.
2915 C<$maxlength> defaults to the size of the request if not specified.
2917 You have to set C<< MyApp->config(parse_on_demand => 1) >> to use this
2920 Warning: If you use read(), Catalyst will not process the body,
2921 so you will not be able to access POST parameters or file uploads via
2922 $c->request. You must handle all body parsing yourself.
2926 sub read { my $c = shift; return $c->request->read( @_ ) }
2936 $app->_make_immutable_if_needed;
2937 $app->engine_loader->needs_psgi_engine_compat_hack ?
2938 $app->engine->run($app, @_) :
2939 $app->engine->run( $app, $app->_finalized_psgi_app, @_ );
2942 sub _make_immutable_if_needed {
2944 my $meta = find_meta($class);
2945 my $isa_ca = $class->isa('Class::Accessor::Fast') || $class->isa('Class::Accessor');
2948 && ! { $meta->immutable_options }->{replace_constructor}
2951 warn("You made your application class ($class) immutable, "
2952 . "but did not inline the\nconstructor. "
2953 . "This will break catalyst, as your app \@ISA "
2954 . "Class::Accessor(::Fast)?\nPlease pass "
2955 . "(replace_constructor => 1)\nwhen making your class immutable.\n");
2957 unless ($meta->is_immutable) {
2958 # XXX - FIXME warning here as you should make your app immutable yourself.
2959 $meta->make_immutable(
2960 replace_constructor => 1,
2965 =head2 $c->set_action( $action, $code, $namespace, $attrs )
2967 Sets an action in a given namespace.
2971 sub set_action { my $c = shift; $c->dispatcher->set_action( $c, @_ ) }
2973 =head2 $c->setup_actions($component)
2975 Sets up actions for a component.
2979 sub setup_actions { my $c = shift; $c->dispatcher->setup_actions( $c, @_ ) }
2981 =head2 $c->setup_components
2983 This method is called internally to set up the application's components.
2985 It finds modules by calling the L<locate_components> method, expands them to
2986 package names with the L<expand_component_module> method, and then installs
2987 each component into the application.
2989 The C<setup_components> config option is passed to both of the above methods.
2991 Installation of each component is performed by the L<setup_component> method,
2996 sub setup_components {
2999 my $config = $class->config->{ setup_components };
3001 my @comps = $class->locate_components($config);
3002 my %comps = map { $_ => 1 } @comps;
3004 my $deprecatedcatalyst_component_names = grep { /::[CMV]::/ } @comps;
3005 $class->log->warn(qq{Your application is using the deprecated ::[MVC]:: type naming scheme.\n}.
3006 qq{Please switch your class names to ::Model::, ::View:: and ::Controller: as appropriate.\n}
3007 ) if $deprecatedcatalyst_component_names;
3009 for my $component ( @comps ) {
3011 # We pass ignore_loaded here so that overlay files for (e.g.)
3012 # Model::DBI::Schema sub-classes are loaded - if it's in @comps
3013 # we know M::P::O found a file on disk so this is safe
3015 Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
3018 for my $component (@comps) {
3019 my $instance = $class->components->{ $component } = $class->delayed_setup_component($component);
3022 # Inject a component or wrap a stand alone class in an adaptor. This makes a list
3023 # of named components in the configuration that are not actually existing (not a
3026 my @injected = $class->setup_injected_components;
3028 # All components are registered, now we need to 'init' them.
3029 foreach my $component_name (@comps, @injected) {
3030 $class->components->{$component_name} = $class->components->{$component_name}->() if
3031 (ref($class->components->{$component_name}) || '') eq 'CODE';
3035 =head2 $app->setup_injected_components
3037 Called by setup_compoents to setup components that are injected.
3041 sub setup_injected_components {
3043 my @injected_components = keys %{$class->config->{inject_components} ||+{}};
3045 foreach my $injected_comp_name(@injected_components) {
3046 $class->setup_injected_component(
3047 $injected_comp_name,
3048 $class->config->{inject_components}->{$injected_comp_name});
3051 return map { $class ."::" . $_ }
3052 @injected_components;
3055 =head2 $app->setup_injected_component( $injected_component_name, $config )
3057 Setup a given injected component.
3061 sub setup_injected_component {
3062 my ($class, $injected_comp_name, $config) = @_;
3063 if(my $component_class = $config->{from_component}) {
3064 my @roles = @{$config->{roles} ||[]};
3065 Catalyst::Utils::inject_component(
3067 component => $component_class,
3068 (scalar(@roles) ? (traits => \@roles) : ()),
3069 as => $injected_comp_name);
3073 =head2 $app->inject_component($MyApp_Component_name => \%args);
3075 Add a component that is injected at setup:
3077 MyApp->inject_component( 'Model::Foo' => { from_component => 'Common::Foo' } );
3079 Must be called before ->setup. Expects a component name for your
3080 current application and \%args where
3084 =item from_component
3086 The target component being injected into your application
3090 An arrayref of L<Moose::Role>s that are applied to your component.
3096 MyApp->inject_component(
3098 from_component => 'Common::Model::Foo',
3099 roles => ['Role1', 'Role2'],
3102 =head2 $app->inject_components
3104 Inject a list of components:
3106 MyApp->inject_components(
3107 'Model::FooOne' => {
3108 from_component => 'Common::Model::Foo',
3109 roles => ['Role1', 'Role2'],
3111 'Model::FooTwo' => {
3112 from_component => 'Common::Model::Foo',
3113 roles => ['Role1', 'Role2'],
3118 sub inject_component {
3119 my ($app, $name, $args) = @_;
3120 die "Component $name exists" if
3121 $app->config->{inject_components}->{$name};
3122 $app->config->{inject_components}->{$name} = $args;
3125 sub inject_components {
3128 $app->inject_component(shift, shift);
3132 =head2 $c->locate_components( $setup_component_config )
3134 This method is meant to provide a list of component modules that should be
3135 setup for the application. By default, it will use L<Module::Pluggable>.
3137 Specify a C<setup_components> config option to pass additional options directly
3138 to L<Module::Pluggable>. To add additional search paths, specify a key named
3139 C<search_extra> as an array reference. Items in the array beginning with C<::>
3140 will have the application class name prepended to them.
3144 sub locate_components {
3148 my @paths = qw( ::M ::Model ::V ::View ::C ::Controller );
3149 my $extra = $config->{ search_extra } || [];
3151 unshift @paths, @$extra;
3153 my @comps = map { sort { length($a) <=> length($b) } Module::Pluggable::Object->new(
3154 search_path => [ map { s/^(?=::)/$class/; $_; } ($_) ],
3156 )->plugins } @paths;
3161 =head2 $c->expand_component_module( $component, $setup_component_config )
3163 Components found by C<locate_components> will be passed to this method, which
3164 is expected to return a list of component (package) names to be set up.
3168 sub expand_component_module {
3169 my ($class, $module) = @_;
3170 return Devel::InnerPackage::list_packages( $module );
3173 =head2 $app->delayed_setup_component
3175 Returns a coderef that points to a setup_component instance. Used
3176 internally for when you want to delay setup until the first time
3177 the component is called.
3181 sub delayed_setup_component {
3182 my($class, $component, @more) = @_;
3184 return my $instance = $class->setup_component($component, @more);
3188 =head2 $c->setup_component
3192 sub setup_component {
3193 my( $class, $component ) = @_;
3195 unless ( $component->can( 'COMPONENT' ) ) {
3199 my $config = $class->config_for($component);
3200 # Stash catalyst_component_name in the config here, so that custom COMPONENT
3201 # methods also pass it. local to avoid pointlessly shitting in config
3202 # for the debug screen, as $component is already the key name.
3203 local $config->{catalyst_component_name} = $component;
3205 my $instance = eval {
3206 $component->COMPONENT( $class, $config );
3210 Catalyst::Exception->throw(
3211 message => qq/Couldn't instantiate component "$component", "$error"/
3215 unless (blessed $instance) {
3216 my $metaclass = Moose::Util::find_meta($component);
3217 my $method_meta = $metaclass->find_method_by_name('COMPONENT');
3218 my $component_method_from = $method_meta->associated_metaclass->name;
3219 my $value = defined($instance) ? $instance : 'undef';
3220 Catalyst::Exception->throw(
3222 qq/Couldn't instantiate component "$component", COMPONENT() method (from $component_method_from) didn't return an object-like value (value was $value)./
3226 my @expanded_components = $instance->can('expand_modules')
3227 ? $instance->expand_modules( $component, $config )
3228 : $class->expand_component_module( $component, $config );
3229 for my $component (@expanded_components) {
3230 next if $class->components->{ $component };
3231 $class->components->{ $component } = $class->setup_component($component);
3237 =head2 $app->config_for( $component_name )
3239 Return the application level configuration (which is not yet merged with any
3240 local component configuration, via $component_class->config) for the named
3241 component or component object. Example:
3244 'Model::Foo' => { a => 1, b => 2},
3247 my $config = MyApp->config_for('MyApp::Model::Foo');
3249 In this case $config is the hashref C< {a=>1, b=>2} >.
3251 This is also handy for looking up configuration for a plugin, to make sure you follow
3252 existing L<Catalyst> standards for where a plugin should put its configuration.
3257 my ($class, $component_name) = @_;
3258 my $component_suffix = Catalyst::Utils::class2classsuffix($component_name);
3259 my $config = $class->config->{ $component_suffix } || {};
3264 =head2 $c->setup_dispatcher
3270 sub setup_dispatcher {
3271 my ( $class, $dispatcher ) = @_;
3274 $dispatcher = 'Catalyst::Dispatcher::' . $dispatcher;
3277 if ( my $env = Catalyst::Utils::env_value( $class, 'DISPATCHER' ) ) {
3278 $dispatcher = 'Catalyst::Dispatcher::' . $env;
3281 unless ($dispatcher) {
3282 $dispatcher = $class->dispatcher_class;
3285 load_class($dispatcher);
3287 # dispatcher instance
3288 $class->dispatcher( $dispatcher->new );
3291 =head2 $c->setup_engine
3298 my ($class, $requested_engine) = @_;
3300 if (!$class->engine_loader || $requested_engine) {
3301 $class->engine_loader(
3302 Catalyst::EngineLoader->new({
3303 application_name => $class,
3304 (defined $requested_engine
3305 ? (catalyst_engine_class => $requested_engine) : ()),
3310 $class->engine_loader->catalyst_engine_class;
3314 my ($class, $requested_engine) = @_;
3317 my $loader = $class->engine_loader;
3319 if (!$loader || $requested_engine) {
3320 $loader = Catalyst::EngineLoader->new({
3321 application_name => $class,
3322 (defined $requested_engine
3323 ? (requested_engine => $requested_engine) : ()),
3326 $class->engine_loader($loader);
3329 $loader->catalyst_engine_class;
3332 # Don't really setup_engine -- see _setup_psgi_app for explanation.
3333 return if $class->loading_psgi_file;
3335 load_class($engine);
3337 if ($ENV{MOD_PERL}) {
3338 my $apache = $class->engine_loader->auto;
3340 my $meta = find_meta($class);
3341 my $was_immutable = $meta->is_immutable;
3342 my %immutable_options = $meta->immutable_options;
3343 $meta->make_mutable if $was_immutable;
3345 $meta->add_method(handler => sub {
3347 my $psgi_app = $class->_finalized_psgi_app;
3348 $apache->call_app($r, $psgi_app);
3351 $meta->make_immutable(%immutable_options) if $was_immutable;
3354 $class->engine( $engine->new );
3359 ## This exists just to supply a prebuild psgi app for mod_perl and for the
3360 ## build in server support (back compat support for pre psgi port behavior).
3361 ## This is so that we don't build a new psgi app for each request when using
3362 ## the mod_perl handler or the built in servers (http and fcgi, etc).
3364 sub _finalized_psgi_app {
3367 unless ($app->_psgi_app) {
3368 my $psgi_app = $app->_setup_psgi_app;
3369 $app->_psgi_app($psgi_app);
3372 return $app->_psgi_app;
3375 ## Look for a psgi file like 'myapp_web.psgi' (if the app is MyApp::Web) in the
3376 ## home directory and load that and return it (just assume it is doing the
3377 ## right thing :) ). If that does not exist, call $app->psgi_app, wrap that
3378 ## in default_middleware and return it ( this is for backward compatibility
3379 ## with pre psgi port behavior ).
3381 sub _setup_psgi_app {
3384 for my $home (Path::Class::Dir->new($app->config->{home})) {
3385 my $psgi_file = $home->file(
3386 Catalyst::Utils::appprefix($app) . '.psgi',
3389 next unless -e $psgi_file;
3391 # If $psgi_file calls ->setup_engine, it's doing so to load
3392 # Catalyst::Engine::PSGI. But if it does that, we're only going to
3393 # throw away the loaded PSGI-app and load the 5.9 Catalyst::Engine
3394 # anyway. So set a flag (ick) that tells setup_engine not to populate
3395 # $c->engine or do any other things we might regret.
3397 $app->loading_psgi_file(1);
3398 my $psgi_app = Plack::Util::load_psgi($psgi_file);
3399 $app->loading_psgi_file(0);
3402 unless $app->engine_loader->needs_psgi_engine_compat_hack;
3405 Found a legacy Catalyst::Engine::PSGI .psgi file at ${psgi_file}.
3407 Its content has been ignored. Please consult the Catalyst::Upgrading
3408 documentation on how to upgrade from Catalyst::Engine::PSGI.
3412 return $app->apply_default_middlewares($app->psgi_app);
3415 =head2 $c->apply_default_middlewares
3417 Adds the following L<Plack> middlewares to your application, since they are
3418 useful and commonly needed:
3420 L<Plack::Middleware::LighttpdScriptNameFix> (if you are using Lighttpd),
3421 L<Plack::Middleware::IIS6ScriptNameFix> (always applied since this middleware
3422 is smart enough to conditionally apply itself).
3424 We will also automatically add L<Plack::Middleware::ReverseProxy> if we notice
3425 that your HTTP $env variable C<REMOTE_ADDR> is '127.0.0.1'. This is usually
3426 an indication that your server is running behind a proxy frontend. However in
3427 2014 this is often not the case. We preserve this code for backwards compatibility
3428 however I B<highly> recommend that if you are running the server behind a front
3429 end proxy that you clearly indicate so with the C<using_frontend_proxy> configuration
3430 setting to true for your environment configurations that run behind a proxy. This
3431 way if you change your front end proxy address someday your code would inexplicably
3432 stop working as expected.
3434 Additionally if we detect we are using Nginx, we add a bit of custom middleware
3435 to solve some problems with the way that server handles $ENV{PATH_INFO} and
3438 Please B<NOTE> that if you do use C<using_frontend_proxy> the middleware is now
3439 adding via C<registered_middleware> rather than this method.
3441 If you are using Lighttpd or IIS6 you may wish to apply these middlewares. In
3442 general this is no longer a common case but we have this here for backward
3448 sub apply_default_middlewares {
3449 my ($app, $psgi_app) = @_;
3451 # Don't add this conditional IF we are explicitly saying we want the
3452 # frontend proxy support. We don't need it here since if that is the
3453 # case it will be always loaded in the default_middleware.
3455 unless($app->config->{using_frontend_proxy}) {
3456 $psgi_app = Plack::Middleware::Conditional->wrap(
3458 builder => sub { Plack::Middleware::ReverseProxy->wrap($_[0]) },
3461 return if $app->config->{ignore_frontend_proxy};
3462 return $env->{REMOTE_ADDR} eq '127.0.0.1';
3467 # If we're running under Lighttpd, swap PATH_INFO and SCRIPT_NAME
3468 # http://lists.scsys.co.uk/pipermail/catalyst/2006-June/008361.html
3469 $psgi_app = Plack::Middleware::Conditional->wrap(
3471 builder => sub { Plack::Middleware::LighttpdScriptNameFix->wrap($_[0]) },
3474 return unless $env->{SERVER_SOFTWARE} && $env->{SERVER_SOFTWARE} =~ m!lighttpd[-/]1\.(\d+\.\d+)!;
3475 return unless $1 < 4.23;
3480 # we're applying this unconditionally as the middleware itself already makes
3481 # sure it doesn't fuck things up if it's not running under one of the right
3483 $psgi_app = Plack::Middleware::IIS6ScriptNameFix->wrap($psgi_app);
3485 # And another IIS issue, this time with IIS7.
3486 $psgi_app = Plack::Middleware::Conditional->wrap(
3488 builder => sub { Plack::Middleware::IIS7KeepAliveFix->wrap($_[0]) },
3491 return $env->{SERVER_SOFTWARE} && $env->{SERVER_SOFTWARE} =~ m!IIS/7\.[0-9]!;
3498 =head2 App->psgi_app
3502 Returns a PSGI application code reference for the catalyst application
3503 C<$c>. This is the bare application created without the C<apply_default_middlewares>
3504 method called. We do however apply C<registered_middleware> since those are
3505 integral to how L<Catalyst> functions. Also, unlike starting your application
3506 with a generated server script (via L<Catalyst::Devel> and C<catalyst.pl>) we do
3507 not attempt to return a valid L<PSGI> application using any existing C<${myapp}.psgi>
3508 scripts in your $HOME directory.
3510 B<NOTE> C<apply_default_middlewares> was originally created when the first PSGI
3511 port was done for v5.90000. These are middlewares that are added to achieve
3512 backward compatibility with older applications. If you start your application
3513 using one of the supplied server scripts (generated with L<Catalyst::Devel> and
3514 the project skeleton script C<catalyst.pl>) we apply C<apply_default_middlewares>
3515 automatically. This was done so that pre and post PSGI port applications would
3518 This is what you want to be using to retrieve the PSGI application code
3519 reference of your Catalyst application for use in a custom F<.psgi> or in your
3520 own created server modules.
3524 *to_app = \&psgi_app;
3528 my $psgi = $app->engine->build_psgi_app($app);
3529 return $app->Catalyst::Utils::apply_registered_middleware($psgi);
3532 =head2 $c->setup_home
3534 Sets up the home directory.
3539 my ( $class, $home ) = @_;
3541 if ( my $env = Catalyst::Utils::env_value( $class, 'HOME' ) ) {
3545 $home ||= Catalyst::Utils::home($class);
3548 #I remember recently being scolded for assigning config values like this
3549 $class->config->{home} ||= $home;
3550 $class->config->{root} ||= Path::Class::Dir->new($home)->subdir('root');
3554 =head2 $c->setup_encoding
3556 Sets up the input/output encoding. See L<ENCODING>
3560 sub setup_encoding {
3562 if( exists($c->config->{encoding}) && !defined($c->config->{encoding}) ) {
3563 # Ok, so the user has explicitly said "I don't want encoding..."
3566 my $enc = defined($c->config->{encoding}) ?
3567 delete $c->config->{encoding} : 'UTF-8'; # not sure why we delete it... (JNAP)
3572 =head2 handle_unicode_encoding_exception
3574 Hook to let you customize how encoding errors are handled. By default
3575 we just throw an exception and the default error page will pick it up.
3576 Receives a hashref of debug information. Example of call:
3578 $c->handle_unicode_encoding_exception({
3579 param_value => $value,
3581 encoding_step => 'params',
3584 It expects to receive a decoded string.
3586 You can override this for custom handling of unicode errors. By
3587 default we just die. If you want a custom response here, one approach
3588 is to throw an HTTP style exception, instead of returning a decoded
3589 string or throwing a generic exception.
3591 sub handle_unicode_encoding_exception {
3592 my ($c, $params) = @_;
3593 HTTP::Exception::BAD_REQUEST->throw(status_message=>$params->{error_msg});
3596 Alternatively you can 'catch' the error, stash it and write handling code later
3597 in your application:
3599 sub handle_unicode_encoding_exception {
3600 my ($c, $params) = @_;
3601 $c->stash(BAD_UNICODE_DATA=>$params);
3602 # return a dummy string.
3606 <B>NOTE:</b> Please keep in mind that once an error like this occurs,
3607 the request setup is still ongoing, which means the state of C<$c> and
3608 related context parts like the request and response may not be setup
3609 up correctly (since we haven't finished the setup yet). If you throw
3610 an exception the setup is aborted.
3614 sub handle_unicode_encoding_exception {
3615 my ( $self, $exception_ctx ) = @_;
3616 die $exception_ctx->{error_msg};
3619 # Some unicode helpers cargo culted from the old plugin. These could likely
3622 sub _handle_unicode_decoding {
3623 my ( $self, $value ) = @_;
3625 return unless defined $value;
3627 ## I think this mess is to support the old nested
3628 if ( ref $value eq 'ARRAY' ) {
3629 foreach ( @$value ) {
3630 $_ = $self->_handle_unicode_decoding($_);
3634 elsif ( ref $value eq 'HASH' ) {
3635 foreach (keys %$value) {
3636 my $encoded_key = $self->_handle_param_unicode_decoding($_);
3637 $value->{$encoded_key} = $self->_handle_unicode_decoding($value->{$_});
3639 # If the key was encoded we now have two (the original and current so
3640 # delete the original.
3641 delete $value->{$_} if $_ ne $encoded_key;
3646 return $self->_handle_param_unicode_decoding($value);
3650 sub _handle_param_unicode_decoding {
3651 my ( $self, $value, $check ) = @_;
3652 return unless defined $value; # not in love with just ignoring undefs - jnap
3653 return $value if blessed($value); #don't decode when the value is an object.
3655 my $enc = $self->encoding;
3656 $check ||= $self->_encode_check;
3658 $enc->decode( $value, $check);
3661 return $self->handle_unicode_encoding_exception({
3662 param_value => $value,
3664 encoding_step => 'params',
3669 =head2 $c->setup_log
3671 Sets up log by instantiating a L<Catalyst::Log|Catalyst::Log> object and
3672 passing it to C<log()>. Pass in a comma-delimited list of levels to set the
3675 This method also installs a C<debug> method that returns a true value into the
3676 catalyst subclass if the "debug" level is passed in the comma-delimited list,
3677 or if the C<$CATALYST_DEBUG> environment variable is set to a true value.
3679 Note that if the log has already been setup, by either a previous call to
3680 C<setup_log> or by a call such as C<< __PACKAGE__->log( MyLogger->new ) >>,
3681 that this method won't actually set up the log object.
3686 my ( $class, $levels ) = @_;
3689 $levels =~ s/^\s+//;
3690 $levels =~ s/\s+$//;
3691 my %levels = map { $_ => 1 } split /\s*,\s*/, $levels;
3693 my $env_debug = Catalyst::Utils::env_value( $class, 'DEBUG' );
3694 if ( defined $env_debug ) {
3695 $levels{debug} = 1 if $env_debug; # Ugly!
3696 delete($levels{debug}) unless $env_debug;
3699 unless ( $class->log ) {
3700 $class->log( Catalyst::Log->new(keys %levels) );
3703 if ( $levels{debug} ) {
3704 Class::MOP::get_metaclass_by_name($class)->add_method('debug' => sub { 1 });
3705 $class->log->debug('Debug messages enabled');
3709 =head2 $c->setup_plugins
3715 =head2 $c->setup_stats
3717 Sets up timing statistics class.
3722 my ( $class, $stats ) = @_;
3724 Catalyst::Utils::ensure_class_loaded($class->stats_class);
3726 my $env = Catalyst::Utils::env_value( $class, 'STATS' );
3727 if ( defined($env) ? $env : ($stats || $class->debug ) ) {
3728 Class::MOP::get_metaclass_by_name($class)->add_method('use_stats' => sub { 1 });
3729 $class->log->debug('Statistics enabled');
3734 =head2 $c->registered_plugins
3736 Returns a sorted list of the plugins which have either been stated in the
3739 If passed a given plugin name, it will report a boolean value indicating
3740 whether or not that plugin is loaded. A fully qualified name is required if
3741 the plugin name does not begin with C<Catalyst::Plugin::>.
3743 if ($c->registered_plugins('Some::Plugin')) {
3751 sub registered_plugins {
3753 return sort keys %{ $proto->_plugins } unless @_;
3755 return 1 if exists $proto->_plugins->{$plugin};
3756 return exists $proto->_plugins->{"Catalyst::Plugin::$plugin"};
3759 sub _register_plugin {
3760 my ( $proto, $plugin, $instant ) = @_;
3761 my $class = ref $proto || $proto;
3763 load_class( $plugin );
3764 $class->log->warn( "$plugin inherits from 'Catalyst::Component' - this is deprecated and will not work in 5.81" )
3765 if $plugin->isa( 'Catalyst::Component' );
3766 my $plugin_meta = Moose::Meta::Class->create($plugin);
3767 if (!$plugin_meta->has_method('new')
3768 && ( $plugin->isa('Class::Accessor::Fast') || $plugin->isa('Class::Accessor') ) ) {
3769 $plugin_meta->add_method('new', Moose::Object->meta->get_method('new'))
3771 if (!$instant && !$proto->_plugins->{$plugin}) {
3772 my $meta = Class::MOP::get_metaclass_by_name($class);
3773 $meta->superclasses($plugin, $meta->superclasses);
3775 $proto->_plugins->{$plugin} = 1;
3779 sub _default_plugins { return qw() }
3782 my ( $class, $plugins ) = @_;
3784 $class->_plugins( {} ) unless $class->_plugins;
3786 m/Unicode::Encoding/ ? do {
3788 'Unicode::Encoding plugin is auto-applied,'
3789 . ' please remove this from your appclass'
3790 . ' and make sure to define "encoding" config'
3792 unless (exists $class->config->{'encoding'}) {
3793 $class->config->{'encoding'} = 'UTF-8';
3798 push @$plugins, $class->_default_plugins;
3799 $plugins = Data::OptList::mkopt($plugins || []);
3802 [ Catalyst::Utils::resolve_namespace(
3803 $class . '::Plugin',
3804 'Catalyst::Plugin', $_->[0]
3810 for my $plugin ( reverse @plugins ) {
3811 load_class($plugin->[0], $plugin->[1]);
3812 my $meta = find_meta($plugin->[0]);
3813 next if $meta && $meta->isa('Moose::Meta::Role');
3815 $class->_register_plugin($plugin->[0]);
3819 map { $_->[0]->name, $_->[1] }
3820 grep { blessed($_->[0]) && $_->[0]->isa('Moose::Meta::Role') }
3821 map { [find_meta($_->[0]), $_->[1]] }
3824 Moose::Util::apply_all_roles(
3830 =head2 default_middleware
3832 Returns a list of instantiated PSGI middleware objects which is the default
3833 middleware that is active for this application (taking any configuration
3834 options into account, excluding your custom added middleware via the C<psgi_middleware>
3835 configuration option). You can override this method if you wish to change
3836 the default middleware (although do so at risk since some middleware is vital
3837 to application function.)
3839 The current default middleware list is:
3841 Catalyst::Middleware::Stash
3842 Plack::Middleware::HTTPExceptions
3843 Plack::Middleware::RemoveRedundantBody
3844 Plack::Middleware::FixMissingBodyInRedirect
3845 Plack::Middleware::ContentLength
3846 Plack::Middleware::MethodOverride
3847 Plack::Middleware::Head
3849 If the configuration setting C<using_frontend_proxy> is true we add:
3851 Plack::Middleware::ReverseProxy
3853 If the configuration setting C<using_frontend_proxy_path> is true we add:
3855 Plack::Middleware::ReverseProxyPath
3857 But B<NOTE> that L<Plack::Middleware::ReverseProxyPath> is not a dependency of the
3858 L<Catalyst> distribution so if you want to use this option you should add it to
3859 your project distribution file.
3861 These middlewares will be added at L</setup_middleware> during the
3862 L</setup> phase of application startup.
3866 sub default_middleware {
3869 Catalyst::Middleware::Stash->new,
3870 Plack::Middleware::HTTPExceptions->new,
3871 Plack::Middleware::RemoveRedundantBody->new,
3872 Plack::Middleware::FixMissingBodyInRedirect->new,
3873 Plack::Middleware::ContentLength->new,
3874 Plack::Middleware::MethodOverride->new,
3875 Plack::Middleware::Head->new);
3877 if($class->config->{using_frontend_proxy}) {
3878 push @mw, Plack::Middleware::ReverseProxy->new;
3881 if($class->config->{using_frontend_proxy_path}) {
3882 if(Class::Load::try_load_class('Plack::Middleware::ReverseProxyPath')) {
3883 push @mw, Plack::Middleware::ReverseProxyPath->new;
3885 $class->log->error("Cannot use configuration 'using_frontend_proxy_path' because 'Plack::Middleware::ReverseProxyPath' is not installed");
3892 =head2 registered_middlewares
3894 Read only accessor that returns an array of all the middleware in the order
3895 that they were added (which is the REVERSE of the order they will be applied).
3897 The values returned will be either instances of L<Plack::Middleware> or of a
3898 compatible interface, or a coderef, which is assumed to be inlined middleware
3900 =head2 setup_middleware (?@middleware)
3902 Read configuration information stored in configuration key C<psgi_middleware> or
3905 See under L</CONFIGURATION> information regarding C<psgi_middleware> and how
3906 to use it to enable L<Plack::Middleware>
3908 This method is automatically called during 'setup' of your application, so
3909 you really don't need to invoke it. However you may do so if you find the idea
3910 of loading middleware via configuration weird :). For example:
3916 __PACKAGE__->setup_middleware('Head');
3919 When we read middleware definitions from configuration, we reverse the list
3920 which sounds odd but is likely how you expect it to work if you have prior
3921 experience with L<Plack::Builder> or if you previously used the plugin
3922 L<Catalyst::Plugin::EnableMiddleware> (which is now considered deprecated)
3924 So basically your middleware handles an incoming request from the first
3925 registered middleware, down and handles the response from the last middleware
3930 sub registered_middlewares {
3932 if(my $middleware = $class->_psgi_middleware) {
3933 my @mw = ($class->default_middleware, @$middleware);
3935 if($class->config->{using_frontend_proxy}) {
3936 push @mw, Plack::Middleware::ReverseProxy->new;
3941 die "You cannot call ->registered_middlewares until middleware has been setup";
3945 sub setup_middleware {
3947 my @middleware_definitions;
3949 # If someone calls this method you can add middleware with args. However if its
3950 # called without an arg we need to setup the configuration middleware.
3952 @middleware_definitions = reverse(@_);
3954 @middleware_definitions = reverse(@{$class->config->{'psgi_middleware'}||[]})
3955 unless $class->finalized_default_middleware;
3956 $class->finalized_default_middleware(1); # Only do this once, just in case some people call setup over and over...
3959 my @middleware = ();
3960 while(my $next = shift(@middleware_definitions)) {
3962 if(Scalar::Util::blessed $next && $next->can('wrap')) {
3963 push @middleware, $next;
3964 } elsif(ref $next eq 'CODE') {
3965 push @middleware, $next;
3966 } elsif(ref $next eq 'HASH') {
3967 my $namespace = shift @middleware_definitions;
3968 my $mw = $class->Catalyst::Utils::build_middleware($namespace, %$next);
3969 push @middleware, $mw;
3971 die "I can't handle middleware definition ${\ref $next}";
3974 my $mw = $class->Catalyst::Utils::build_middleware($next);
3975 push @middleware, $mw;
3979 my @existing = @{$class->_psgi_middleware || []};
3980 $class->_psgi_middleware([@middleware,@existing,]);
3983 =head2 registered_data_handlers
3985 A read only copy of registered Data Handlers returned as a Hash, where each key
3986 is a content type and each value is a subref that attempts to decode that content
3989 =head2 setup_data_handlers (?@data_handler)
3991 Read configuration information stored in configuration key C<data_handlers> or
3994 See under L</CONFIGURATION> information regarding C<data_handlers>.
3996 This method is automatically called during 'setup' of your application, so
3997 you really don't need to invoke it.
3999 =head2 default_data_handlers
4001 Default Data Handlers that come bundled with L<Catalyst>. Currently there are
4002 only two default data handlers, for 'application/json' and an alternative to
4003 'application/x-www-form-urlencoded' which supposed nested form parameters via
4004 L<CGI::Struct> or via L<CGI::Struct::XS> IF you've installed it.
4006 The 'application/json' data handler is used to parse incoming JSON into a Perl
4007 data structure. It used either L<JSON::MaybeXS> or L<JSON>, depending on which
4008 is installed. This allows you to fail back to L<JSON:PP>, which is a Pure Perl
4009 JSON decoder, and has the smallest dependency impact.
4011 Because we don't wish to add more dependencies to L<Catalyst>, if you wish to
4012 use this new feature we recommend installing L<JSON> or L<JSON::MaybeXS> in
4013 order to get the best performance. You should add either to your dependency
4014 list (Makefile.PL, dist.ini, cpanfile, etc.)
4018 sub registered_data_handlers {
4020 if(my $data_handlers = $class->_data_handlers) {
4021 return %$data_handlers;
4023 $class->setup_data_handlers;
4024 return $class->registered_data_handlers;
4028 sub setup_data_handlers {
4029 my ($class, %data_handler_callbacks) = @_;
4030 %data_handler_callbacks = (
4031 %{$class->default_data_handlers},
4032 %{$class->config->{'data_handlers'}||+{}},
4033 %data_handler_callbacks);
4035 $class->_data_handlers(\%data_handler_callbacks);
4038 sub default_data_handlers {
4041 'application/x-www-form-urlencoded' => sub {
4042 my ($fh, $req) = @_;
4043 my $params = $req->_use_hash_multivalue ? $req->body_parameters->mixed : $req->body_parameters;
4044 Class::Load::load_first_existing_class('CGI::Struct::XS', 'CGI::Struct')
4045 ->can('build_cgi_struct')->($params);
4047 'application/json' => sub {
4048 my ($fh, $req) = @_;
4049 my $parser = Class::Load::load_first_existing_class('JSON::MaybeXS', 'JSON');
4053 $slurped = $fh->getline;
4054 $parser->can("decode_json")->($slurped); # decode_json does utf8 decoding for us
4055 } || Catalyst::Exception->throw(sprintf "Error Parsing POST '%s', Error: %s", (defined($slurped) ? $slurped : 'undef') ,$@);
4060 sub _handle_http_exception {
4061 my ( $self, $error ) = @_;
4063 !$self->config->{always_catch_http_exceptions}
4066 $error->can('as_psgi')
4067 || ( $error->can('code')
4068 && $error->code =~ m/^[1-5][0-9][0-9]$/ )
4078 Returns an arrayref of the internal execution stack (actions that are
4079 currently executing).
4083 Returns the current timing statistics object. By default Catalyst uses
4084 L<Catalyst::Stats|Catalyst::Stats>, but can be set otherwise with
4085 L<< stats_class|/"$c->stats_class" >>.
4087 Even if L<< -Stats|/"-Stats" >> is not enabled, the stats object is still
4088 available. By enabling it with C< $c->stats->enabled(1) >, it can be used to
4089 profile explicitly, although MyApp.pm still won't profile nor output anything
4092 =head2 $c->stats_class
4094 Returns or sets the stats (timing statistics) class. L<Catalyst::Stats|Catalyst::Stats> is used by default.
4096 =head2 $app->stats_class_traits
4098 A arrayref of L<Moose::Role>s that are applied to the stats_class before creating it.
4100 =head2 $app->composed_stats_class
4102 this is the stats_class composed with any 'stats_class_traits'. You can
4103 name the full namespace of the role, or a namespace suffix, which will then
4104 be tried against the following standard namespace prefixes.
4106 $MyApp::TraitFor::Stats::$trait_suffix
4107 Catalyst::TraitFor::Stats::$trait_suffix
4109 So for example if you set:
4111 MyApp->stats_class_traits(['Foo']);
4113 We try each possible role in turn (and throw an error if none load)
4116 MyApp::TraitFor::Stats::Foo
4117 Catalyst::TraitFor::Stats::Foo
4119 The namespace part 'TraitFor::Stats' was chosen to assist in backwards
4120 compatibility with L<CatalystX::RoleApplicator> which previously provided
4121 these features in a stand alone package.
4123 =head2 $c->use_stats
4125 Returns 1 when L<< stats collection|/"-Stats" >> is enabled.
4127 Note that this is a static method, not an accessor and should be overridden
4128 by declaring C<sub use_stats { 1 }> in your MyApp.pm, not by calling C<< $c->use_stats(1) >>.
4135 =head2 $c->write( $data )
4137 Writes $data to the output stream. When using this method directly, you
4138 will need to manually set the C<Content-Length> header to the length of
4139 your output data, if known.
4146 # Finalize headers if someone manually writes output (for compat)
4147 $c->finalize_headers;
4149 return $c->response->write( @_ );
4154 Returns the Catalyst version number. Mostly useful for "powered by"
4155 messages in template systems.
4159 sub version { return $Catalyst::VERSION }
4161 =head1 CONFIGURATION
4163 There are a number of 'base' config variables which can be set:
4169 C<always_catch_http_exceptions> - As of version 5.90060 Catalyst
4170 rethrows errors conforming to the interface described by
4171 L<Plack::Middleware::HTTPExceptions> and lets the middleware deal with it.
4172 Set true to get the deprecated behaviour and have Catalyst catch HTTP exceptions.
4176 C<default_model> - The default model picked if you say C<< $c->model >>. See L<< /$c->model($name) >>.
4180 C<default_view> - The default view to be rendered or returned when C<< $c->view >> is called. See L<< /$c->view($name) >>.
4184 C<disable_component_resolution_regex_fallback> - Turns
4185 off the deprecated component resolution functionality so
4186 that if any of the component methods (e.g. C<< $c->controller('Foo') >>)
4187 are called then regex search will not be attempted on string values and
4188 instead C<undef> will be returned.
4192 C<home> - The application home directory. In an uninstalled application,
4193 this is the top level application directory. In an installed application,
4194 this will be the directory containing C<< MyApp.pm >>.
4198 C<ignore_frontend_proxy> - See L</PROXY SUPPORT>
4202 C<name> - The name of the application in debug messages and the debug and
4207 C<parse_on_demand> - The request body (for example file uploads) will not be parsed
4208 until it is accessed. This allows you to (for example) check authentication (and reject
4209 the upload) before actually receiving all the data. See L</ON-DEMAND PARSER>
4213 C<root> - The root directory for templates. Usually this is just a
4214 subdirectory of the home directory, but you can set it to change the
4215 templates to a different directory.
4219 C<search_extra> - Array reference passed to Module::Pluggable to for additional
4220 namespaces from which components will be loaded (and constructed and stored in
4221 C<< $c->components >>).
4225 C<show_internal_actions> - If true, causes internal actions such as C<< _DISPATCH >>
4226 to be shown in hit debug tables in the test server.
4230 C<use_request_uri_for_path> - Controls if the C<REQUEST_URI> or C<PATH_INFO> environment
4231 variable should be used for determining the request path.
4233 Most web server environments pass the requested path to the application using environment variables,
4234 from which Catalyst has to reconstruct the request base (i.e. the top level path to / in the application,
4235 exposed as C<< $c->request->base >>) and the request path below that base.
4237 There are two methods of doing this, both of which have advantages and disadvantages. Which method is used
4238 is determined by the C<< $c->config(use_request_uri_for_path) >> setting (which can either be true or false).
4242 =item use_request_uri_for_path => 0
4244 This is the default (and the) traditional method that Catalyst has used for determining the path information.
4245 The path is generated from a combination of the C<PATH_INFO> and C<SCRIPT_NAME> environment variables.
4246 The allows the application to behave correctly when C<mod_rewrite> is being used to redirect requests
4247 into the application, as these variables are adjusted by mod_rewrite to take account for the redirect.
4249 However this method has the major disadvantage that it is impossible to correctly decode some elements
4250 of the path, as RFC 3875 says: "C<< Unlike a URI path, the PATH_INFO is not URL-encoded, and cannot
4251 contain path-segment parameters. >>" This means PATH_INFO is B<always> decoded, and therefore Catalyst
4252 can't distinguish / vs %2F in paths (in addition to other encoded values).
4254 =item use_request_uri_for_path => 1
4256 This method uses the C<REQUEST_URI> and C<SCRIPT_NAME> environment variables. As C<REQUEST_URI> is never
4257 decoded, this means that applications using this mode can correctly handle URIs including the %2F character
4258 (i.e. with C<AllowEncodedSlashes> set to C<On> in Apache).
4260 Given that this method of path resolution is provably more correct, it is recommended that you use
4261 this unless you have a specific need to deploy your application in a non-standard environment, and you are
4262 aware of the implications of not being able to handle encoded URI paths correctly.
4264 However it also means that in a number of cases when the app isn't installed directly at a path, but instead
4265 is having paths rewritten into it (e.g. as a .cgi/fcgi in a public_html directory, with mod_rewrite in a
4266 .htaccess file, or when SSI is used to rewrite pages into the app, or when sub-paths of the app are exposed
4267 at other URIs than that which the app is 'normally' based at with C<mod_rewrite>), the resolution of
4268 C<< $c->request->base >> will be incorrect.
4274 C<using_frontend_proxy> - See L</PROXY SUPPORT>.
4278 C<using_frontend_proxy_path> - Enabled L<Plack::Middleware::ReverseProxyPath> on your application (if
4279 installed, otherwise log an error). This is useful if your application is not running on the
4280 'root' (or /) of your host server. B<NOTE> if you use this feature you should add the required
4281 middleware to your project dependency list since its not automatically a dependency of L<Catalyst>.
4282 This has been done since not all people need this feature and we wish to restrict the growth of
4283 L<Catalyst> dependencies.
4287 C<encoding> - See L</ENCODING>
4289 This now defaults to 'UTF-8'. You my turn it off by setting this configuration
4294 C<abort_chain_on_error_fix>
4296 When there is an error in an action chain, the default behavior is to continue
4297 processing the remaining actions and then catch the error upon chain end. This
4298 can lead to running actions when the application is in an unexpected state. If
4299 you have this issue, setting this config value to true will promptly exit a
4300 chain when there is an error raised in any action (thus terminating the chain
4305 __PACKAGE__->config(abort_chain_on_error_fix => 1);
4307 In the future this might become the default behavior.
4311 C<use_hash_multivalue_in_request>
4313 In L<Catalyst::Request> the methods C<query_parameters>, C<body_parametes>
4314 and C<parameters> return a hashref where values might be scalar or an arrayref
4315 depending on the incoming data. In many cases this can be undesirable as it
4316 leads one to writing defensive code like the following:
4318 my ($val) = ref($c->req->parameters->{a}) ?
4319 @{$c->req->parameters->{a}} :
4320 $c->req->parameters->{a};
4322 Setting this configuration item to true will make L<Catalyst> populate the
4323 attributes underlying these methods with an instance of L<Hash::MultiValue>
4324 which is used by L<Plack::Request> and others to solve this very issue. You
4325 may prefer this behavior to the default, if so enable this option (be warned
4326 if you enable it in a legacy application we are not sure if it is completely
4327 backwardly compatible).
4331 C<skip_complex_post_part_handling>
4333 When creating body parameters from a POST, if we run into a multipart POST
4334 that does not contain uploads, but instead contains inlined complex data
4335 (very uncommon) we cannot reliably convert that into field => value pairs. So
4336 instead we create an instance of L<Catalyst::Request::PartData>. If this causes
4337 issue for you, you can disable this by setting C<skip_complex_post_part_handling>
4338 to true (default is false).
4342 C<skip_body_param_unicode_decoding>
4344 Generally we decode incoming POST params based on your declared encoding (the
4345 default for this is to decode UTF-8). If this is causing you trouble and you
4346 do not wish to turn all encoding support off (with the C<encoding> configuration
4347 parameter) you may disable this step atomically by setting this configuration
4352 C<do_not_decode_query>
4354 If true, then do not try to character decode any wide characters in your
4355 request URL query or keywords. Most readings of the relevant specifications
4356 suggest these should be UTF-* encoded, which is the default that L<Catalyst>
4357 will use, however if you are creating a lot of URLs manually or have external
4358 evil clients, this might cause you trouble. If you find the changes introduced
4359 in Catalyst version 5.90080+ break some of your query code, you may disable
4360 the UTF-8 decoding globally using this configuration.
4362 This setting takes precedence over C<default_query_encoding>
4366 C<do_not_check_query_encoding>
4368 Catalyst versions 5.90080 - 5.90106 would decode query parts of an incoming
4369 request but would not raise an exception when the decoding failed due to
4370 incorrect unicode. It now does, but if this change is giving you trouble
4371 you may disable it by setting this configuration to true.
4375 C<default_query_encoding>
4377 By default we decode query and keywords in your request URL using UTF-8, which
4378 is our reading of the relevant specifications. This setting allows one to
4379 specify a fixed value for how to decode your query. You might need this if
4380 you are doing a lot of custom encoding of your URLs and not using UTF-8.
4384 C<use_chained_args_0_special_case>
4386 In older versions of Catalyst, when more than one action matched the same path
4387 AND all those matching actions declared Args(0), we'd break the tie by choosing
4388 the first action defined. We now normalized how Args(0) works so that it
4389 follows the same rule as Args(N), which is to say when we need to break a tie
4390 we choose the LAST action defined. If this breaks your code and you don't
4391 have time to update to follow the new normalized approach, you may set this
4392 value to true and it will globally revert to the original chaining behavior.
4396 C<psgi_middleware> - See L<PSGI MIDDLEWARE>.
4400 C<data_handlers> - See L<DATA HANDLERS>.
4404 C<stats_class_traits>
4406 An arrayref of L<Moose::Role>s that get composed into your stats class.
4410 C<request_class_traits>
4412 An arrayref of L<Moose::Role>s that get composed into your request class.
4416 C<response_class_traits>
4418 An arrayref of L<Moose::Role>s that get composed into your response class.
4422 C<inject_components>
4424 A Hashref of L<Catalyst::Component> subclasses that are 'injected' into configuration.
4428 inject_components => {
4429 'Controller::Err' => { from_component => 'Local::Controller::Errors' },
4430 'Model::Zoo' => { from_component => 'Local::Model::Foo' },
4431 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] },
4433 'Controller::Err' => { a => 100, b=>200, namespace=>'error' },
4434 'Model::Zoo' => { a => 2 },
4435 'Model::Foo' => { a => 100 },
4438 Generally L<Catalyst> looks for components in your Model/View or Controller directories.
4439 However for cases when you which to use an existing component and you don't need any
4440 customization (where for when you can apply a role to customize it) you may inject those
4441 components into your application. Please note any configuration should be done 'in the
4442 normal way', with a key under configuration named after the component affix, as in the
4445 Using this type of injection allows you to construct significant amounts of your application
4446 with only configuration!. This may or may not lead to increased code understanding.
4448 Please not you may also call the ->inject_components application method as well, although
4449 you must do so BEFORE setup.
4455 Generally when you throw an exception inside an Action (or somewhere in
4456 your stack, such as in a model that an Action is calling) that exception
4457 is caught by Catalyst and unless you either catch it yourself (via eval
4458 or something like L<Try::Tiny> or by reviewing the L</error> stack, it
4459 will eventually reach L</finalize_errors> and return either the debugging
4460 error stack page, or the default error page. However, if your exception
4461 can be caught by L<Plack::Middleware::HTTPExceptions>, L<Catalyst> will
4462 instead rethrow it so that it can be handled by that middleware (which
4463 is part of the default middleware). For example this would allow
4465 use HTTP::Throwable::Factory 'http_throw';
4467 sub throws_exception :Local {
4468 my ($self, $c) = @_;
4470 http_throw(SeeOther => { location =>
4471 $c->uri_for($self->action_for('redirect')) });
4475 =head1 INTERNAL ACTIONS
4477 Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>,
4478 C<_ACTION>, and C<_END>. These are by default not shown in the private
4479 action table, but you can make them visible with a config parameter.
4481 MyApp->config(show_internal_actions => 1);
4483 =head1 ON-DEMAND PARSER
4485 The request body is usually parsed at the beginning of a request,
4486 but if you want to handle input yourself, you can enable on-demand
4487 parsing with a config parameter.
4489 MyApp->config(parse_on_demand => 1);
4491 =head1 PROXY SUPPORT
4493 Many production servers operate using the common double-server approach,
4494 with a lightweight frontend web server passing requests to a larger
4495 backend server. An application running on the backend server must deal
4496 with two problems: the remote user always appears to be C<127.0.0.1> and
4497 the server's hostname will appear to be C<localhost> regardless of the
4498 virtual host that the user connected through.
4500 Catalyst will automatically detect this situation when you are running
4501 the frontend and backend servers on the same machine. The following
4502 changes are made to the request.
4504 $c->req->address is set to the user's real IP address, as read from
4505 the HTTP X-Forwarded-For header.
4507 The host value for $c->req->base and $c->req->uri is set to the real
4508 host, as read from the HTTP X-Forwarded-Host header.
4510 Additionally, you may be running your backend application on an insecure
4511 connection (port 80) while your frontend proxy is running under SSL. If there
4512 is a discrepancy in the ports, use the HTTP header C<X-Forwarded-Port> to
4513 tell Catalyst what port the frontend listens on. This will allow all URIs to
4514 be created properly.
4516 In the case of passing in:
4518 X-Forwarded-Port: 443
4520 All calls to C<uri_for> will result in an https link, as is expected.
4522 Obviously, your web server must support these headers for this to work.
4524 In a more complex server farm environment where you may have your
4525 frontend proxy server(s) on different machines, you will need to set a
4526 configuration option to tell Catalyst to read the proxied data from the
4529 MyApp->config(using_frontend_proxy => 1);
4531 If you do not wish to use the proxy support at all, you may set:
4533 MyApp->config(ignore_frontend_proxy => 0);
4535 =head2 Note about psgi files
4537 Note that if you supply your own .psgi file, calling
4538 C<< MyApp->psgi_app(@_); >>, then B<this will not happen automatically>.
4540 You either need to apply L<Plack::Middleware::ReverseProxy> yourself
4541 in your psgi, for example:
4544 enable "Plack::Middleware::ReverseProxy";
4548 This will unconditionally add the ReverseProxy support, or you need to call
4549 C<< $app = MyApp->apply_default_middlewares($app) >> (to conditionally
4550 apply the support depending upon your config).
4552 See L<Catalyst::PSGI> for more information.
4554 =head1 THREAD SAFETY
4556 Catalyst has been tested under Apache 2's threading C<mpm_worker>,
4557 C<mpm_winnt>, and the standalone forking HTTP server on Windows. We
4558 believe the Catalyst core to be thread-safe.
4560 If you plan to operate in a threaded environment, remember that all other
4561 modules you are using must also be thread-safe. Some modules, most notably
4562 L<DBD::SQLite>, are not thread-safe.
4564 =head1 DATA HANDLERS
4566 The L<Catalyst::Request> object uses L<HTTP::Body> to populate 'classic' HTML
4567 form parameters and URL search query fields. However it has become common
4568 for various alternative content types to be PUT or POSTed to your controllers
4569 and actions. People working on RESTful APIs, or using AJAX often use JSON,
4570 XML and other content types when communicating with an application server. In
4571 order to better support this use case, L<Catalyst> defines a global configuration
4572 option, C<data_handlers>, which lets you associate a content type with a coderef
4573 that parses that content type into something Perl can readily access.
4580 __PACKAGE__->config(
4582 'application/json' => sub { local $/; decode_json $_->getline },
4584 ## Any other configuration.
4589 By default L<Catalyst> comes with a generic JSON data handler similar to the
4590 example given above, which uses L<JSON::Maybe> to provide either L<JSON::PP>
4591 (a pure Perl, dependency free JSON parser) or L<Cpanel::JSON::XS> if you have
4592 it installed (if you want the faster XS parser, add it to you project Makefile.PL
4593 or dist.ini, cpanfile, etc.)
4595 The C<data_handlers> configuration is a hashref whose keys are HTTP Content-Types
4596 (matched against the incoming request type using a regexp such as to be case
4597 insensitive) and whose values are coderefs that receive a localized version of
4598 C<$_> which is a filehandle object pointing to received body.
4600 This feature is considered an early access release and we reserve the right
4601 to alter the interface in order to provide a performant and secure solution to
4602 alternative request body content. Your reports welcomed!
4604 =head1 PSGI MIDDLEWARE
4606 You can define middleware, defined as L<Plack::Middleware> or a compatible
4607 interface in configuration. Your middleware definitions are in the form of an
4608 arrayref under the configuration key C<psgi_middleware>. Here's an example
4609 with details to follow:
4614 use Plack::Middleware::StackTrace;
4616 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
4618 __PACKAGE__->config(
4619 'psgi_middleware', [
4622 $stacktrace_middleware,
4623 'Session' => {store => 'File'},
4628 $env->{myapp.customkey} = 'helloworld';
4637 So the general form is:
4639 __PACKAGE__->config(psgi_middleware => \@middleware_definitions);
4641 Where C<@middleware> is one or more of the following, applied in the REVERSE of
4642 the order listed (to make it function similarly to L<Plack::Builder>:
4644 Alternatively, you may also define middleware by calling the L</setup_middleware>
4651 __PACKAGE__->setup_middleware( \@middleware_definitions);
4654 In the case where you do both (use 'setup_middleware' and configuration) the
4655 package call to setup_middleware will be applied earlier (in other words its
4656 middleware will wrap closer to the application). Keep this in mind since in
4657 some cases the order of middleware is important.
4659 The two approaches are not exclusive.
4663 =item Middleware Object
4665 An already initialized object that conforms to the L<Plack::Middleware>
4668 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
4670 __PACKAGE__->config(
4671 'psgi_middleware', [
4672 $stacktrace_middleware,
4678 A coderef that is an inlined middleware:
4680 __PACKAGE__->config(
4681 'psgi_middleware', [
4686 if($env->{PATH_INFO} =~m/forced/) {
4688 ->new(file=>TestApp->path_to(qw/share static forced.txt/))
4691 return $app->($env);
4701 We assume the scalar refers to a namespace after normalizing it using the
4704 (1) If the scalar is prefixed with a "+" (as in C<+MyApp::Foo>) then the full string
4705 is assumed to be 'as is', and we just install and use the middleware.
4707 (2) If the scalar begins with "Plack::Middleware" or your application namespace
4708 (the package name of your Catalyst application subclass), we also assume then
4709 that it is a full namespace, and use it.
4711 (3) Lastly, we then assume that the scalar is a partial namespace, and attempt to
4712 resolve it first by looking for it under your application namespace (for example
4713 if you application is "MyApp::Web" and the scalar is "MyMiddleware", we'd look
4714 under "MyApp::Web::Middleware::MyMiddleware") and if we don't find it there, we
4715 will then look under the regular L<Plack::Middleware> namespace (i.e. for the
4716 previous we'd try "Plack::Middleware::MyMiddleware"). We look under your application
4717 namespace first to let you 'override' common L<Plack::Middleware> locally, should
4718 you find that a good idea.
4724 __PACKAGE__->config(
4725 'psgi_middleware', [
4726 'Debug', ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap
4727 'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap
4728 '+MyApp::Custom', ## MyApp::Custom->wrap
4732 =item a scalar followed by a hashref
4734 Just like the previous, except the following C<HashRef> is used as arguments
4735 to initialize the middleware object.
4737 __PACKAGE__->config(
4738 'psgi_middleware', [
4739 'Session' => {store => 'File'},
4744 Please see L<PSGI> for more on middleware.
4748 Starting in L<Catalyst> version 5.90080 encoding is automatically enabled
4749 and set to encode all body responses to UTF8 when possible and applicable.
4750 Following is documentation on this process. If you are using an older
4751 version of L<Catalyst> you should review documentation for that version since
4754 By default encoding is now 'UTF-8'. You may turn it off by setting
4755 the encoding configuration to undef.
4757 MyApp->config(encoding => undef);
4759 This is recommended for temporary backwards compatibility only.
4761 Encoding is automatically applied when the content-type is set to
4762 a type that can be encoded. Currently we encode when the content type
4763 matches the following regular expression:
4765 $content_type =~ /^text|xml$|javascript$/
4767 Encoding is set on the application, but it is copied to the context object
4768 so that you can override it on a request basis.
4770 Be default we don't automatically encode 'application/json' since the most
4771 common approaches to generating this type of response (Either via L<Catalyst::View::JSON>
4772 or L<Catalyst::Action::REST>) will do so already and we want to avoid double
4775 If you are producing JSON response in an unconventional manner (such
4776 as via a template or manual strings) you should perform the UTF8 encoding
4777 manually as well such as to conform to the JSON specification.
4779 NOTE: We also examine the value of $c->response->content_encoding. If
4780 you set this (like for example 'gzip', and manually gzipping the body)
4781 we assume that you have done all the necessary encoding yourself, since
4782 we cannot encode the gzipped contents. If you use a plugin like
4783 L<Catalyst::Plugin::Compress> you need to update to a modern version in order
4784 to have this function correctly with the new UTF8 encoding code, or you
4785 can use L<Plack::Middleware::Deflater> or (probably best) do your compression on
4794 Returns an instance of an C<Encode> encoding
4796 print $c->encoding->name
4798 =item handle_unicode_encoding_exception ($exception_context)
4800 Method called when decoding process for a request fails.
4802 An C<$exception_context> hashref is provided to allow you to override the
4803 behaviour of your application when given data with incorrect encodings.
4805 The default method throws exceptions in the case of invalid request parameters
4806 (resulting in a 500 error), but ignores errors in upload filenames.
4808 The keys passed in the C<$exception_context> hash are:
4814 The value which was not able to be decoded.
4818 The exception received from L<Encode>.
4822 What type of data was being decoded. Valid values are (currently)
4823 C<params> - for request parameters / arguments / captures
4824 and C<uploads> - for request upload filenames.
4834 Join #catalyst on irc.perl.org.
4838 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
4839 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
4843 http://catalyst.perl.org
4847 http://dev.catalyst.perl.org
4851 =head2 L<Task::Catalyst> - All you need to start with Catalyst
4853 =head2 L<Catalyst::Manual> - The Catalyst Manual
4855 =head2 L<Catalyst::Component>, L<Catalyst::Controller> - Base classes for components
4857 =head2 L<Catalyst::Engine> - Core engine
4859 =head2 L<Catalyst::Log> - Log class.
4861 =head2 L<Catalyst::Request> - Request object
4863 =head2 L<Catalyst::Response> - Response object
4865 =head2 L<Catalyst::Test> - The test suite.
4867 =head1 PROJECT FOUNDER
4869 sri: Sebastian Riedel <sri@cpan.org>
4875 acme: Leon Brocard <leon@astray.com>
4877 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
4879 andrewalker: André Walker <andre@cpan.org>
4883 Andrew Ford E<lt>A.Ford@ford-mason.co.ukE<gt>
4887 andyg: Andy Grundman <andy@hybridized.org>
4889 audreyt: Audrey Tang
4891 bricas: Brian Cassidy <bricas@cpan.org>
4893 Caelum: Rafael Kitover <rkitover@io.com>
4895 chansen: Christian Hansen
4897 Chase Venters C<chase.venters@gmail.com>
4899 chicks: Christopher Hicks
4901 Chisel Wright C<pause@herlpacker.co.uk>
4903 Danijel Milicevic C<me@danijel.de>
4905 davewood: David Schmidt <davewood@cpan.org>
4907 David Kamholz E<lt>dkamholz@cpan.orgE<gt>
4909 David Naughton, C<naughton@umn.edu>
4913 dhoss: Devin Austin <dhoss@cpan.org>
4915 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
4919 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
4921 esskar: Sascha Kiefer
4923 fireartist: Carl Franks <cfranks@cpan.org>
4925 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
4927 gabb: Danijel Milicevic
4931 Gavin Henry C<ghenry@perl.me.uk>
4935 groditi: Guillermo Roditi <groditi@gmail.com>
4937 hobbs: Andrew Rodland <andrew@cleverdomain.org>
4939 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
4941 jcamacho: Juan Camacho
4943 jester: Jesse Sheidlower C<jester@panix.com>
4945 jhannah: Jay Hannah <jay@jays.net>
4951 jon: Jon Schutz <jjschutz@cpan.org>
4953 Jonathan Rockway C<< <jrockway@cpan.org> >>
4955 Kieren Diment C<kd@totaldatasolution.com>
4957 konobi: Scott McWhirter <konobi@cpan.org>
4959 marcus: Marcus Ramberg <mramberg@cpan.org>
4961 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
4963 mgrimes: Mark Grimes <mgrimes@cpan.org>
4965 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
4969 naughton: David Naughton
4971 ningu: David Kamholz <dkamholz@cpan.org>
4973 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
4975 numa: Dan Sully <daniel@cpan.org>
4981 omega: Andreas Marienborg
4983 Oleg Kostyuk <cub.uanic@gmail.com>
4985 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
4987 rafl: Florian Ragwitz <rafl@debian.org>
4989 random: Roland Lammel <lammel@cpan.org>
4991 Robert Sedlacek C<< <rs@474.at> >>
4993 SpiceMan: Marcel Montes
4997 szbalint: Balint Szilakszi <szbalint@cpan.org>
4999 t0m: Tomas Doran <bobtfish@bobtfish.net>
5003 vanstyn: Henry Van Styn <vanstyn@cpan.org>
5005 Viljo Marrandi C<vilts@yahoo.com>
5007 Will Hawes C<info@whawes.co.uk>
5009 willert: Sebastian Willert <willert@cpan.org>
5011 wreis: Wallace Reis <wreis@cpan.org>
5013 Yuval Kogman, C<nothingmuch@woobling.org>
5015 rainboxx: Matthias Dietrich, C<perl@rainboxx.de>
5017 dd070: Dhaval Dhanani <dhaval070@gmail.com>
5019 Upasana <me@upasana.me>
5021 John Napiorkowski (jnap) <jjnapiork@cpan.org>
5025 Copyright (c) 2005-2015, the above named PROJECT FOUNDER and CONTRIBUTORS.
5029 This library is free software. You can redistribute it and/or modify it under
5030 the same terms as Perl itself.
5036 __PACKAGE__->meta->make_immutable;