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.90104';
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 # call these so we pre setup the composed classes
1424 $class->composed_request_class;
1425 $class->composed_response_class;
1426 $class->composed_stats_class;
1428 # Initialize our data structure
1429 $class->components( {} );
1431 $class->setup_components;
1433 if ( $class->debug ) {
1434 my @plugins = map { "$_ " . ( $_->VERSION || '' ) } $class->registered_plugins;
1437 my $column_width = Catalyst::Utils::term_width() - 6;
1438 my $t = Text::SimpleTable->new($column_width);
1439 $t->row($_) for @plugins;
1440 $class->log->debug( "Loaded plugins:\n" . $t->draw . "\n" );
1443 my @middleware = map {
1446 (ref($_) .' '. ($_->can('VERSION') ? $_->VERSION || '' : '')
1447 || '') } $class->registered_middlewares;
1450 my $column_width = Catalyst::Utils::term_width() - 6;
1451 my $t = Text::SimpleTable->new($column_width);
1452 $t->row($_) for @middleware;
1453 $class->log->debug( "Loaded PSGI Middleware:\n" . $t->draw . "\n" );
1456 my %dh = $class->registered_data_handlers;
1457 if (my @data_handlers = keys %dh) {
1458 my $column_width = Catalyst::Utils::term_width() - 6;
1459 my $t = Text::SimpleTable->new($column_width);
1460 $t->row($_) for @data_handlers;
1461 $class->log->debug( "Loaded Request Data Handlers:\n" . $t->draw . "\n" );
1464 my $dispatcher = $class->dispatcher;
1465 my $engine = $class->engine;
1466 my $home = $class->config->{home};
1468 $class->log->debug(sprintf(q/Loaded dispatcher "%s"/, blessed($dispatcher)));
1469 $class->log->debug(sprintf(q/Loaded engine "%s"/, blessed($engine)));
1473 ? $class->log->debug(qq/Found home "$home"/)
1474 : $class->log->debug(qq/Home "$home" doesn't exist/)
1475 : $class->log->debug(q/Couldn't find home/);
1477 my $column_width = Catalyst::Utils::term_width() - 8 - 9;
1479 my $t = Text::SimpleTable->new( [ $column_width, 'Class' ], [ 8, 'Type' ] );
1480 for my $comp ( sort keys %{ $class->components } ) {
1481 my $type = ref $class->components->{$comp} ? 'instance' : 'class';
1482 $t->row( $comp, $type );
1484 $class->log->debug( "Loaded components:\n" . $t->draw . "\n" )
1485 if ( keys %{ $class->components } );
1488 # Add our self to components, since we are also a component
1489 if( $class->isa('Catalyst::Controller') ){
1490 $class->components->{$class} = $class;
1493 $class->setup_actions;
1495 if ( $class->debug ) {
1496 my $name = $class->config->{name} || 'Application';
1497 $class->log->info("$name powered by Catalyst $Catalyst::VERSION");
1500 if ($class->config->{case_sensitive}) {
1501 $class->log->warn($class . "->config->{case_sensitive} is set.");
1502 $class->log->warn("This setting is deprecated and planned to be removed in Catalyst 5.81.");
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 $c->response->status(400);
2470 $c->response->content_type('text/plain');
2471 $c->response->body('Bad Request');
2472 # Note we call finalize and then die here, which escapes
2473 # finalize being called in the enclosing block..
2474 # It in fact couldn't be called, as we don't return $c..
2475 # This is a mess - but I'm unsure you can fix this without
2476 # breaking compat for people doing crazy things (we should set
2477 # the 400 and just return the ctx here IMO, letting finalize get called
2488 =head2 $c->prepare_action
2490 Prepares action. See L<Catalyst::Dispatcher>.
2494 sub prepare_action {
2496 my $ret = $c->dispatcher->prepare_action( $c, @_);
2499 foreach (@{$c->req->arguments}, @{$c->req->captures}) {
2500 $_ = $c->_handle_param_unicode_decoding($_);
2508 =head2 $c->prepare_body
2510 Prepares message body.
2517 return if $c->request->_has_body;
2519 # Initialize on-demand data
2520 $c->engine->prepare_body( $c, @_ );
2521 $c->prepare_parameters;
2522 $c->prepare_uploads;
2525 =head2 $c->prepare_body_chunk( $chunk )
2527 Prepares a chunk of data before sending it to L<HTTP::Body>.
2529 See L<Catalyst::Engine>.
2533 sub prepare_body_chunk {
2535 $c->engine->prepare_body_chunk( $c, @_ );
2538 =head2 $c->prepare_body_parameters
2540 Prepares body parameters.
2544 sub prepare_body_parameters {
2546 $c->request->prepare_body_parameters( $c, @_ );
2549 =head2 $c->prepare_connection
2551 Prepares connection.
2555 sub prepare_connection {
2557 $c->request->prepare_connection($c);
2560 =head2 $c->prepare_cookies
2562 Prepares cookies by ensuring that the attribute on the request
2563 object has been built.
2567 sub prepare_cookies { my $c = shift; $c->request->cookies }
2569 =head2 $c->prepare_headers
2571 Prepares request headers by ensuring that the attribute on the request
2572 object has been built.
2576 sub prepare_headers { my $c = shift; $c->request->headers }
2578 =head2 $c->prepare_parameters
2580 Prepares parameters.
2584 sub prepare_parameters {
2586 $c->prepare_body_parameters;
2587 $c->engine->prepare_parameters( $c, @_ );
2590 =head2 $c->prepare_path
2592 Prepares path and base.
2596 sub prepare_path { my $c = shift; $c->engine->prepare_path( $c, @_ ) }
2598 =head2 $c->prepare_query_parameters
2600 Prepares query parameters.
2604 sub prepare_query_parameters {
2607 $c->engine->prepare_query_parameters( $c, @_ );
2610 =head2 $c->log_request
2612 Writes information about the request to the debug logs. This includes:
2616 =item * Request method, path, and remote IP address
2618 =item * Query keywords (see L<Catalyst::Request/query_keywords>)
2620 =item * Request parameters
2622 =item * File uploads
2631 return unless $c->debug;
2633 my($dump) = grep {$_->[0] eq 'Request' } $c->dump_these;
2634 my $request = $dump->[1];
2636 my ( $method, $path, $address ) = ( $request->method, $request->path, $request->address );
2638 $path = '/' unless length $path;
2641 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
2642 $path = decode_utf8($path);
2644 $c->log->debug(qq/"$method" request for "$path" from "$address"/);
2646 $c->log_request_headers($request->headers);
2648 if ( my $keywords = $request->query_keywords ) {
2649 $c->log->debug("Query keywords are: $keywords");
2652 $c->log_request_parameters( query => $request->query_parameters, $request->_has_body ? (body => $request->body_parameters) : () );
2654 $c->log_request_uploads($request);
2657 =head2 $c->log_response
2659 Writes information about the response to the debug logs by calling
2660 C<< $c->log_response_status_line >> and C<< $c->log_response_headers >>.
2667 return unless $c->debug;
2669 my($dump) = grep {$_->[0] eq 'Response' } $c->dump_these;
2670 my $response = $dump->[1];
2672 $c->log_response_status_line($response);
2673 $c->log_response_headers($response->headers);
2676 =head2 $c->log_response_status_line($response)
2678 Writes one line of information about the response to the debug logs. This includes:
2682 =item * Response status code
2684 =item * Content-Type header (if present)
2686 =item * Content-Length header (if present)
2692 sub log_response_status_line {
2693 my ($c, $response) = @_;
2697 'Response Code: %s; Content-Type: %s; Content-Length: %s',
2698 $response->status || 'unknown',
2699 $response->headers->header('Content-Type') || 'unknown',
2700 $response->headers->header('Content-Length') || 'unknown'
2705 =head2 $c->log_response_headers($headers);
2707 Hook method which can be wrapped by plugins to log the response headers.
2708 No-op in the default implementation.
2712 sub log_response_headers {}
2714 =head2 $c->log_request_parameters( query => {}, body => {} )
2716 Logs request parameters to debug logs
2720 sub log_request_parameters {
2722 my %all_params = @_;
2724 return unless $c->debug;
2726 my $column_width = Catalyst::Utils::term_width() - 44;
2727 foreach my $type (qw(query body)) {
2728 my $params = $all_params{$type};
2729 next if ! keys %$params;
2730 my $t = Text::SimpleTable->new( [ 35, 'Parameter' ], [ $column_width, 'Value' ] );
2731 for my $key ( sort keys %$params ) {
2732 my $param = $params->{$key};
2733 my $value = defined($param) ? $param : '';
2734 $t->row( $key, ref $value eq 'ARRAY' ? ( join ', ', @$value ) : $value );
2736 $c->log->debug( ucfirst($type) . " Parameters are:\n" . $t->draw );
2740 =head2 $c->log_request_uploads
2742 Logs file uploads included in the request to the debug logs.
2743 The parameter name, filename, file type, and file size are all included in
2748 sub log_request_uploads {
2750 my $request = shift;
2751 return unless $c->debug;
2752 my $uploads = $request->uploads;
2753 if ( keys %$uploads ) {
2754 my $t = Text::SimpleTable->new(
2755 [ 12, 'Parameter' ],
2760 for my $key ( sort keys %$uploads ) {
2761 my $upload = $uploads->{$key};
2762 for my $u ( ref $upload eq 'ARRAY' ? @{$upload} : ($upload) ) {
2763 $t->row( $key, $u->filename, $u->type, $u->size );
2766 $c->log->debug( "File Uploads are:\n" . $t->draw );
2770 =head2 $c->log_request_headers($headers);
2772 Hook method which can be wrapped by plugins to log the request headers.
2773 No-op in the default implementation.
2777 sub log_request_headers {}
2779 =head2 $c->log_headers($type => $headers)
2781 Logs L<HTTP::Headers> (either request or response) to the debug logs.
2788 my $headers = shift; # an HTTP::Headers instance
2790 return unless $c->debug;
2792 my $column_width = Catalyst::Utils::term_width() - 28;
2793 my $t = Text::SimpleTable->new( [ 15, 'Header Name' ], [ $column_width, 'Value' ] );
2796 my ( $name, $value ) = @_;
2797 $t->row( $name, $value );
2800 $c->log->debug( ucfirst($type) . " Headers:\n" . $t->draw );
2804 =head2 $c->prepare_read
2806 Prepares the input for reading.
2810 sub prepare_read { my $c = shift; $c->engine->prepare_read( $c, @_ ) }
2812 =head2 $c->prepare_request
2814 Prepares the engine request.
2818 sub prepare_request { my $c = shift; $c->engine->prepare_request( $c, @_ ) }
2820 =head2 $c->prepare_uploads
2826 sub prepare_uploads {
2828 $c->engine->prepare_uploads( $c, @_ );
2831 =head2 $c->prepare_write
2833 Prepares the output for writing.
2837 sub prepare_write { my $c = shift; $c->engine->prepare_write( $c, @_ ) }
2839 =head2 $c->request_class
2841 Returns or sets the request class. Defaults to L<Catalyst::Request>.
2843 =head2 $app->request_class_traits
2845 An arrayref of L<Moose::Role>s which are applied to the request class. You can
2846 name the full namespace of the role, or a namespace suffix, which will then
2847 be tried against the following standard namespace prefixes.
2849 $MyApp::TraitFor::Request::$trait_suffix
2850 Catalyst::TraitFor::Request::$trait_suffix
2852 So for example if you set:
2854 MyApp->request_class_traits(['Foo']);
2856 We try each possible role in turn (and throw an error if none load)
2859 MyApp::TraitFor::Request::Foo
2860 Catalyst::TraitFor::Request::Foo
2862 The namespace part 'TraitFor::Request' was chosen to assist in backwards
2863 compatibility with L<CatalystX::RoleApplicator> which previously provided
2864 these features in a stand alone package.
2866 =head2 $app->composed_request_class
2868 This is the request class which has been composed with any request_class_traits.
2870 =head2 $c->response_class
2872 Returns or sets the response class. Defaults to L<Catalyst::Response>.
2874 =head2 $app->response_class_traits
2876 An arrayref of L<Moose::Role>s which are applied to the response class. You can
2877 name the full namespace of the role, or a namespace suffix, which will then
2878 be tried against the following standard namespace prefixes.
2880 $MyApp::TraitFor::Response::$trait_suffix
2881 Catalyst::TraitFor::Response::$trait_suffix
2883 So for example if you set:
2885 MyApp->response_class_traits(['Foo']);
2887 We try each possible role in turn (and throw an error if none load)
2890 MyApp::TraitFor::Response::Foo
2891 Catalyst::TraitFor::Responset::Foo
2893 The namespace part 'TraitFor::Response' was chosen to assist in backwards
2894 compatibility with L<CatalystX::RoleApplicator> which previously provided
2895 these features in a stand alone package.
2898 =head2 $app->composed_response_class
2900 This is the request class which has been composed with any response_class_traits.
2902 =head2 $c->read( [$maxlength] )
2904 Reads a chunk of data from the request body. This method is designed to
2905 be used in a while loop, reading C<$maxlength> bytes on every call.
2906 C<$maxlength> defaults to the size of the request if not specified.
2908 You have to set C<< MyApp->config(parse_on_demand => 1) >> to use this
2911 Warning: If you use read(), Catalyst will not process the body,
2912 so you will not be able to access POST parameters or file uploads via
2913 $c->request. You must handle all body parsing yourself.
2917 sub read { my $c = shift; return $c->request->read( @_ ) }
2927 $app->_make_immutable_if_needed;
2928 $app->engine_loader->needs_psgi_engine_compat_hack ?
2929 $app->engine->run($app, @_) :
2930 $app->engine->run( $app, $app->_finalized_psgi_app, @_ );
2933 sub _make_immutable_if_needed {
2935 my $meta = find_meta($class);
2936 my $isa_ca = $class->isa('Class::Accessor::Fast') || $class->isa('Class::Accessor');
2939 && ! { $meta->immutable_options }->{replace_constructor}
2942 warn("You made your application class ($class) immutable, "
2943 . "but did not inline the\nconstructor. "
2944 . "This will break catalyst, as your app \@ISA "
2945 . "Class::Accessor(::Fast)?\nPlease pass "
2946 . "(replace_constructor => 1)\nwhen making your class immutable.\n");
2948 unless ($meta->is_immutable) {
2949 # XXX - FIXME warning here as you should make your app immutable yourself.
2950 $meta->make_immutable(
2951 replace_constructor => 1,
2956 =head2 $c->set_action( $action, $code, $namespace, $attrs )
2958 Sets an action in a given namespace.
2962 sub set_action { my $c = shift; $c->dispatcher->set_action( $c, @_ ) }
2964 =head2 $c->setup_actions($component)
2966 Sets up actions for a component.
2970 sub setup_actions { my $c = shift; $c->dispatcher->setup_actions( $c, @_ ) }
2972 =head2 $c->setup_components
2974 This method is called internally to set up the application's components.
2976 It finds modules by calling the L<locate_components> method, expands them to
2977 package names with the L<expand_component_module> method, and then installs
2978 each component into the application.
2980 The C<setup_components> config option is passed to both of the above methods.
2982 Installation of each component is performed by the L<setup_component> method,
2987 sub setup_components {
2990 my $config = $class->config->{ setup_components };
2992 my @comps = $class->locate_components($config);
2993 my %comps = map { $_ => 1 } @comps;
2995 my $deprecatedcatalyst_component_names = grep { /::[CMV]::/ } @comps;
2996 $class->log->warn(qq{Your application is using the deprecated ::[MVC]:: type naming scheme.\n}.
2997 qq{Please switch your class names to ::Model::, ::View:: and ::Controller: as appropriate.\n}
2998 ) if $deprecatedcatalyst_component_names;
3000 for my $component ( @comps ) {
3002 # We pass ignore_loaded here so that overlay files for (e.g.)
3003 # Model::DBI::Schema sub-classes are loaded - if it's in @comps
3004 # we know M::P::O found a file on disk so this is safe
3006 Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
3009 for my $component (@comps) {
3010 my $instance = $class->components->{ $component } = $class->delayed_setup_component($component);
3013 # Inject a component or wrap a stand alone class in an adaptor. This makes a list
3014 # of named components in the configuration that are not actually existing (not a
3017 my @injected = $class->setup_injected_components;
3019 # All components are registered, now we need to 'init' them.
3020 foreach my $component_name (@comps, @injected) {
3021 $class->components->{$component_name} = $class->components->{$component_name}->() if
3022 (ref($class->components->{$component_name}) || '') eq 'CODE';
3026 =head2 $app->setup_injected_components
3028 Called by setup_compoents to setup components that are injected.
3032 sub setup_injected_components {
3034 my @injected_components = keys %{$class->config->{inject_components} ||+{}};
3036 foreach my $injected_comp_name(@injected_components) {
3037 $class->setup_injected_component(
3038 $injected_comp_name,
3039 $class->config->{inject_components}->{$injected_comp_name});
3042 return map { $class ."::" . $_ }
3043 @injected_components;
3046 =head2 $app->setup_injected_component( $injected_component_name, $config )
3048 Setup a given injected component.
3052 sub setup_injected_component {
3053 my ($class, $injected_comp_name, $config) = @_;
3054 if(my $component_class = $config->{from_component}) {
3055 my @roles = @{$config->{roles} ||[]};
3056 Catalyst::Utils::inject_component(
3058 component => $component_class,
3059 (scalar(@roles) ? (traits => \@roles) : ()),
3060 as => $injected_comp_name);
3064 =head2 $app->inject_component($MyApp_Component_name => \%args);
3066 Add a component that is injected at setup:
3068 MyApp->inject_component( 'Model::Foo' => { from_component => 'Common::Foo' } );
3070 Must be called before ->setup. Expects a component name for your
3071 current application and \%args where
3075 =item from_component
3077 The target component being injected into your application
3081 An arrayref of L<Moose::Role>s that are applied to your component.
3087 MyApp->inject_component(
3089 from_component => 'Common::Model::Foo',
3090 roles => ['Role1', 'Role2'],
3093 =head2 $app->inject_components
3095 Inject a list of components:
3097 MyApp->inject_components(
3098 'Model::FooOne' => {
3099 from_component => 'Common::Model::Foo',
3100 roles => ['Role1', 'Role2'],
3102 'Model::FooTwo' => {
3103 from_component => 'Common::Model::Foo',
3104 roles => ['Role1', 'Role2'],
3109 sub inject_component {
3110 my ($app, $name, $args) = @_;
3111 die "Component $name exists" if
3112 $app->config->{inject_components}->{$name};
3113 $app->config->{inject_components}->{$name} = $args;
3116 sub inject_components {
3119 $app->inject_component(shift, shift);
3123 =head2 $c->locate_components( $setup_component_config )
3125 This method is meant to provide a list of component modules that should be
3126 setup for the application. By default, it will use L<Module::Pluggable>.
3128 Specify a C<setup_components> config option to pass additional options directly
3129 to L<Module::Pluggable>. To add additional search paths, specify a key named
3130 C<search_extra> as an array reference. Items in the array beginning with C<::>
3131 will have the application class name prepended to them.
3135 sub locate_components {
3139 my @paths = qw( ::M ::Model ::V ::View ::C ::Controller );
3140 my $extra = $config->{ search_extra } || [];
3142 unshift @paths, @$extra;
3144 my @comps = map { sort { length($a) <=> length($b) } Module::Pluggable::Object->new(
3145 search_path => [ map { s/^(?=::)/$class/; $_; } ($_) ],
3147 )->plugins } @paths;
3152 =head2 $c->expand_component_module( $component, $setup_component_config )
3154 Components found by C<locate_components> will be passed to this method, which
3155 is expected to return a list of component (package) names to be set up.
3159 sub expand_component_module {
3160 my ($class, $module) = @_;
3161 return Devel::InnerPackage::list_packages( $module );
3164 =head2 $app->delayed_setup_component
3166 Returns a coderef that points to a setup_component instance. Used
3167 internally for when you want to delay setup until the first time
3168 the component is called.
3172 sub delayed_setup_component {
3173 my($class, $component, @more) = @_;
3175 return my $instance = $class->setup_component($component, @more);
3179 =head2 $c->setup_component
3183 sub setup_component {
3184 my( $class, $component ) = @_;
3186 unless ( $component->can( 'COMPONENT' ) ) {
3190 my $config = $class->config_for($component);
3191 # Stash catalyst_component_name in the config here, so that custom COMPONENT
3192 # methods also pass it. local to avoid pointlessly shitting in config
3193 # for the debug screen, as $component is already the key name.
3194 local $config->{catalyst_component_name} = $component;
3196 my $instance = eval {
3197 $component->COMPONENT( $class, $config );
3201 Catalyst::Exception->throw(
3202 message => qq/Couldn't instantiate component "$component", "$error"/
3206 unless (blessed $instance) {
3207 my $metaclass = Moose::Util::find_meta($component);
3208 my $method_meta = $metaclass->find_method_by_name('COMPONENT');
3209 my $component_method_from = $method_meta->associated_metaclass->name;
3210 my $value = defined($instance) ? $instance : 'undef';
3211 Catalyst::Exception->throw(
3213 qq/Couldn't instantiate component "$component", COMPONENT() method (from $component_method_from) didn't return an object-like value (value was $value)./
3217 my @expanded_components = $instance->can('expand_modules')
3218 ? $instance->expand_modules( $component, $config )
3219 : $class->expand_component_module( $component, $config );
3220 for my $component (@expanded_components) {
3221 next if $class->components->{ $component };
3222 $class->components->{ $component } = $class->setup_component($component);
3228 =head2 $app->config_for( $component_name )
3230 Return the application level configuration (which is not yet merged with any
3231 local component configuration, via $component_class->config) for the named
3232 component or component object. Example:
3235 'Model::Foo' => { a => 1, b => 2},
3238 my $config = MyApp->config_for('MyApp::Model::Foo');
3240 In this case $config is the hashref C< {a=>1, b=>2} >.
3242 This is also handy for looking up configuration for a plugin, to make sure you follow
3243 existing L<Catalyst> standards for where a plugin should put its configuration.
3248 my ($class, $component_name) = @_;
3249 my $component_suffix = Catalyst::Utils::class2classsuffix($component_name);
3250 my $config = $class->config->{ $component_suffix } || {};
3255 =head2 $c->setup_dispatcher
3261 sub setup_dispatcher {
3262 my ( $class, $dispatcher ) = @_;
3265 $dispatcher = 'Catalyst::Dispatcher::' . $dispatcher;
3268 if ( my $env = Catalyst::Utils::env_value( $class, 'DISPATCHER' ) ) {
3269 $dispatcher = 'Catalyst::Dispatcher::' . $env;
3272 unless ($dispatcher) {
3273 $dispatcher = $class->dispatcher_class;
3276 load_class($dispatcher);
3278 # dispatcher instance
3279 $class->dispatcher( $dispatcher->new );
3282 =head2 $c->setup_engine
3289 my ($class, $requested_engine) = @_;
3291 if (!$class->engine_loader || $requested_engine) {
3292 $class->engine_loader(
3293 Catalyst::EngineLoader->new({
3294 application_name => $class,
3295 (defined $requested_engine
3296 ? (catalyst_engine_class => $requested_engine) : ()),
3301 $class->engine_loader->catalyst_engine_class;
3305 my ($class, $requested_engine) = @_;
3308 my $loader = $class->engine_loader;
3310 if (!$loader || $requested_engine) {
3311 $loader = Catalyst::EngineLoader->new({
3312 application_name => $class,
3313 (defined $requested_engine
3314 ? (requested_engine => $requested_engine) : ()),
3317 $class->engine_loader($loader);
3320 $loader->catalyst_engine_class;
3323 # Don't really setup_engine -- see _setup_psgi_app for explanation.
3324 return if $class->loading_psgi_file;
3326 load_class($engine);
3328 if ($ENV{MOD_PERL}) {
3329 my $apache = $class->engine_loader->auto;
3331 my $meta = find_meta($class);
3332 my $was_immutable = $meta->is_immutable;
3333 my %immutable_options = $meta->immutable_options;
3334 $meta->make_mutable if $was_immutable;
3336 $meta->add_method(handler => sub {
3338 my $psgi_app = $class->_finalized_psgi_app;
3339 $apache->call_app($r, $psgi_app);
3342 $meta->make_immutable(%immutable_options) if $was_immutable;
3345 $class->engine( $engine->new );
3350 ## This exists just to supply a prebuild psgi app for mod_perl and for the
3351 ## build in server support (back compat support for pre psgi port behavior).
3352 ## This is so that we don't build a new psgi app for each request when using
3353 ## the mod_perl handler or the built in servers (http and fcgi, etc).
3355 sub _finalized_psgi_app {
3358 unless ($app->_psgi_app) {
3359 my $psgi_app = $app->_setup_psgi_app;
3360 $app->_psgi_app($psgi_app);
3363 return $app->_psgi_app;
3366 ## Look for a psgi file like 'myapp_web.psgi' (if the app is MyApp::Web) in the
3367 ## home directory and load that and return it (just assume it is doing the
3368 ## right thing :) ). If that does not exist, call $app->psgi_app, wrap that
3369 ## in default_middleware and return it ( this is for backward compatibility
3370 ## with pre psgi port behavior ).
3372 sub _setup_psgi_app {
3375 for my $home (Path::Class::Dir->new($app->config->{home})) {
3376 my $psgi_file = $home->file(
3377 Catalyst::Utils::appprefix($app) . '.psgi',
3380 next unless -e $psgi_file;
3382 # If $psgi_file calls ->setup_engine, it's doing so to load
3383 # Catalyst::Engine::PSGI. But if it does that, we're only going to
3384 # throw away the loaded PSGI-app and load the 5.9 Catalyst::Engine
3385 # anyway. So set a flag (ick) that tells setup_engine not to populate
3386 # $c->engine or do any other things we might regret.
3388 $app->loading_psgi_file(1);
3389 my $psgi_app = Plack::Util::load_psgi($psgi_file);
3390 $app->loading_psgi_file(0);
3393 unless $app->engine_loader->needs_psgi_engine_compat_hack;
3396 Found a legacy Catalyst::Engine::PSGI .psgi file at ${psgi_file}.
3398 Its content has been ignored. Please consult the Catalyst::Upgrading
3399 documentation on how to upgrade from Catalyst::Engine::PSGI.
3403 return $app->apply_default_middlewares($app->psgi_app);
3406 =head2 $c->apply_default_middlewares
3408 Adds the following L<Plack> middlewares to your application, since they are
3409 useful and commonly needed:
3411 L<Plack::Middleware::LighttpdScriptNameFix> (if you are using Lighttpd),
3412 L<Plack::Middleware::IIS6ScriptNameFix> (always applied since this middleware
3413 is smart enough to conditionally apply itself).
3415 We will also automatically add L<Plack::Middleware::ReverseProxy> if we notice
3416 that your HTTP $env variable C<REMOTE_ADDR> is '127.0.0.1'. This is usually
3417 an indication that your server is running behind a proxy frontend. However in
3418 2014 this is often not the case. We preserve this code for backwards compatibility
3419 however I B<highly> recommend that if you are running the server behind a front
3420 end proxy that you clearly indicate so with the C<using_frontend_proxy> configuration
3421 setting to true for your environment configurations that run behind a proxy. This
3422 way if you change your front end proxy address someday your code would inexplicably
3423 stop working as expected.
3425 Additionally if we detect we are using Nginx, we add a bit of custom middleware
3426 to solve some problems with the way that server handles $ENV{PATH_INFO} and
3429 Please B<NOTE> that if you do use C<using_frontend_proxy> the middleware is now
3430 adding via C<registered_middleware> rather than this method.
3432 If you are using Lighttpd or IIS6 you may wish to apply these middlewares. In
3433 general this is no longer a common case but we have this here for backward
3439 sub apply_default_middlewares {
3440 my ($app, $psgi_app) = @_;
3442 # Don't add this conditional IF we are explicitly saying we want the
3443 # frontend proxy support. We don't need it here since if that is the
3444 # case it will be always loaded in the default_middleware.
3446 unless($app->config->{using_frontend_proxy}) {
3447 $psgi_app = Plack::Middleware::Conditional->wrap(
3449 builder => sub { Plack::Middleware::ReverseProxy->wrap($_[0]) },
3452 return if $app->config->{ignore_frontend_proxy};
3453 return $env->{REMOTE_ADDR} eq '127.0.0.1';
3458 # If we're running under Lighttpd, swap PATH_INFO and SCRIPT_NAME
3459 # http://lists.scsys.co.uk/pipermail/catalyst/2006-June/008361.html
3460 $psgi_app = Plack::Middleware::Conditional->wrap(
3462 builder => sub { Plack::Middleware::LighttpdScriptNameFix->wrap($_[0]) },
3465 return unless $env->{SERVER_SOFTWARE} && $env->{SERVER_SOFTWARE} =~ m!lighttpd[-/]1\.(\d+\.\d+)!;
3466 return unless $1 < 4.23;
3471 # we're applying this unconditionally as the middleware itself already makes
3472 # sure it doesn't fuck things up if it's not running under one of the right
3474 $psgi_app = Plack::Middleware::IIS6ScriptNameFix->wrap($psgi_app);
3476 # And another IIS issue, this time with IIS7.
3477 $psgi_app = Plack::Middleware::Conditional->wrap(
3479 builder => sub { Plack::Middleware::IIS7KeepAliveFix->wrap($_[0]) },
3482 return $env->{SERVER_SOFTWARE} && $env->{SERVER_SOFTWARE} =~ m!IIS/7\.[0-9]!;
3489 =head2 App->psgi_app
3493 Returns a PSGI application code reference for the catalyst application
3494 C<$c>. This is the bare application created without the C<apply_default_middlewares>
3495 method called. We do however apply C<registered_middleware> since those are
3496 integral to how L<Catalyst> functions. Also, unlike starting your application
3497 with a generated server script (via L<Catalyst::Devel> and C<catalyst.pl>) we do
3498 not attempt to return a valid L<PSGI> application using any existing C<${myapp}.psgi>
3499 scripts in your $HOME directory.
3501 B<NOTE> C<apply_default_middlewares> was originally created when the first PSGI
3502 port was done for v5.90000. These are middlewares that are added to achieve
3503 backward compatibility with older applications. If you start your application
3504 using one of the supplied server scripts (generated with L<Catalyst::Devel> and
3505 the project skeleton script C<catalyst.pl>) we apply C<apply_default_middlewares>
3506 automatically. This was done so that pre and post PSGI port applications would
3509 This is what you want to be using to retrieve the PSGI application code
3510 reference of your Catalyst application for use in a custom F<.psgi> or in your
3511 own created server modules.
3515 *to_app = \&psgi_app;
3519 my $psgi = $app->engine->build_psgi_app($app);
3520 return $app->Catalyst::Utils::apply_registered_middleware($psgi);
3523 =head2 $c->setup_home
3525 Sets up the home directory.
3530 my ( $class, $home ) = @_;
3532 if ( my $env = Catalyst::Utils::env_value( $class, 'HOME' ) ) {
3536 $home ||= Catalyst::Utils::home($class);
3539 #I remember recently being scolded for assigning config values like this
3540 $class->config->{home} ||= $home;
3541 $class->config->{root} ||= Path::Class::Dir->new($home)->subdir('root');
3545 =head2 $c->setup_encoding
3547 Sets up the input/output encoding. See L<ENCODING>
3551 sub setup_encoding {
3553 if( exists($c->config->{encoding}) && !defined($c->config->{encoding}) ) {
3554 # Ok, so the user has explicitly said "I don't want encoding..."
3557 my $enc = defined($c->config->{encoding}) ?
3558 delete $c->config->{encoding} : 'UTF-8'; # not sure why we delete it... (JNAP)
3563 =head2 handle_unicode_encoding_exception
3565 Hook to let you customize how encoding errors are handled. By default
3566 we just throw an exception. Receives a hashref of debug information.
3569 $c->handle_unicode_encoding_exception({
3570 param_value => $value,
3572 encoding_step => 'params',
3577 sub handle_unicode_encoding_exception {
3578 my ( $self, $exception_ctx ) = @_;
3579 die $exception_ctx->{error_msg};
3582 # Some unicode helpers cargo culted from the old plugin. These could likely
3585 sub _handle_unicode_decoding {
3586 my ( $self, $value ) = @_;
3588 return unless defined $value;
3590 ## I think this mess is to support the old nested
3591 if ( ref $value eq 'ARRAY' ) {
3592 foreach ( @$value ) {
3593 $_ = $self->_handle_unicode_decoding($_);
3597 elsif ( ref $value eq 'HASH' ) {
3598 foreach (keys %$value) {
3599 my $encoded_key = $self->_handle_param_unicode_decoding($_);
3600 $value->{$encoded_key} = $self->_handle_unicode_decoding($value->{$_});
3602 # If the key was encoded we now have two (the original and current so
3603 # delete the original.
3604 delete $value->{$_} if $_ ne $encoded_key;
3609 return $self->_handle_param_unicode_decoding($value);
3613 sub _handle_param_unicode_decoding {
3614 my ( $self, $value ) = @_;
3615 return unless defined $value; # not in love with just ignoring undefs - jnap
3616 return $value if blessed($value); #don't decode when the value is an object.
3618 my $enc = $self->encoding;
3620 $enc->decode( $value, $self->_encode_check );
3623 $self->handle_unicode_encoding_exception({
3624 param_value => $value,
3626 encoding_step => 'params',
3631 =head2 $c->setup_log
3633 Sets up log by instantiating a L<Catalyst::Log|Catalyst::Log> object and
3634 passing it to C<log()>. Pass in a comma-delimited list of levels to set the
3637 This method also installs a C<debug> method that returns a true value into the
3638 catalyst subclass if the "debug" level is passed in the comma-delimited list,
3639 or if the C<$CATALYST_DEBUG> environment variable is set to a true value.
3641 Note that if the log has already been setup, by either a previous call to
3642 C<setup_log> or by a call such as C<< __PACKAGE__->log( MyLogger->new ) >>,
3643 that this method won't actually set up the log object.
3648 my ( $class, $levels ) = @_;
3651 $levels =~ s/^\s+//;
3652 $levels =~ s/\s+$//;
3653 my %levels = map { $_ => 1 } split /\s*,\s*/, $levels;
3655 my $env_debug = Catalyst::Utils::env_value( $class, 'DEBUG' );
3656 if ( defined $env_debug ) {
3657 $levels{debug} = 1 if $env_debug; # Ugly!
3658 delete($levels{debug}) unless $env_debug;
3661 unless ( $class->log ) {
3662 $class->log( Catalyst::Log->new(keys %levels) );
3665 if ( $levels{debug} ) {
3666 Class::MOP::get_metaclass_by_name($class)->add_method('debug' => sub { 1 });
3667 $class->log->debug('Debug messages enabled');
3671 =head2 $c->setup_plugins
3677 =head2 $c->setup_stats
3679 Sets up timing statistics class.
3684 my ( $class, $stats ) = @_;
3686 Catalyst::Utils::ensure_class_loaded($class->stats_class);
3688 my $env = Catalyst::Utils::env_value( $class, 'STATS' );
3689 if ( defined($env) ? $env : ($stats || $class->debug ) ) {
3690 Class::MOP::get_metaclass_by_name($class)->add_method('use_stats' => sub { 1 });
3691 $class->log->debug('Statistics enabled');
3696 =head2 $c->registered_plugins
3698 Returns a sorted list of the plugins which have either been stated in the
3701 If passed a given plugin name, it will report a boolean value indicating
3702 whether or not that plugin is loaded. A fully qualified name is required if
3703 the plugin name does not begin with C<Catalyst::Plugin::>.
3705 if ($c->registered_plugins('Some::Plugin')) {
3713 sub registered_plugins {
3715 return sort keys %{ $proto->_plugins } unless @_;
3717 return 1 if exists $proto->_plugins->{$plugin};
3718 return exists $proto->_plugins->{"Catalyst::Plugin::$plugin"};
3721 sub _register_plugin {
3722 my ( $proto, $plugin, $instant ) = @_;
3723 my $class = ref $proto || $proto;
3725 load_class( $plugin );
3726 $class->log->warn( "$plugin inherits from 'Catalyst::Component' - this is deprecated and will not work in 5.81" )
3727 if $plugin->isa( 'Catalyst::Component' );
3728 my $plugin_meta = Moose::Meta::Class->create($plugin);
3729 if (!$plugin_meta->has_method('new')
3730 && ( $plugin->isa('Class::Accessor::Fast') || $plugin->isa('Class::Accessor') ) ) {
3731 $plugin_meta->add_method('new', Moose::Object->meta->get_method('new'))
3733 if (!$instant && !$proto->_plugins->{$plugin}) {
3734 my $meta = Class::MOP::get_metaclass_by_name($class);
3735 $meta->superclasses($plugin, $meta->superclasses);
3737 $proto->_plugins->{$plugin} = 1;
3741 sub _default_plugins { return qw() }
3744 my ( $class, $plugins ) = @_;
3746 $class->_plugins( {} ) unless $class->_plugins;
3748 m/Unicode::Encoding/ ? do {
3750 'Unicode::Encoding plugin is auto-applied,'
3751 . ' please remove this from your appclass'
3752 . ' and make sure to define "encoding" config'
3754 unless (exists $class->config->{'encoding'}) {
3755 $class->config->{'encoding'} = 'UTF-8';
3760 push @$plugins, $class->_default_plugins;
3761 $plugins = Data::OptList::mkopt($plugins || []);
3764 [ Catalyst::Utils::resolve_namespace(
3765 $class . '::Plugin',
3766 'Catalyst::Plugin', $_->[0]
3772 for my $plugin ( reverse @plugins ) {
3773 load_class($plugin->[0], $plugin->[1]);
3774 my $meta = find_meta($plugin->[0]);
3775 next if $meta && $meta->isa('Moose::Meta::Role');
3777 $class->_register_plugin($plugin->[0]);
3781 map { $_->[0]->name, $_->[1] }
3782 grep { blessed($_->[0]) && $_->[0]->isa('Moose::Meta::Role') }
3783 map { [find_meta($_->[0]), $_->[1]] }
3786 Moose::Util::apply_all_roles(
3792 =head2 default_middleware
3794 Returns a list of instantiated PSGI middleware objects which is the default
3795 middleware that is active for this application (taking any configuration
3796 options into account, excluding your custom added middleware via the C<psgi_middleware>
3797 configuration option). You can override this method if you wish to change
3798 the default middleware (although do so at risk since some middleware is vital
3799 to application function.)
3801 The current default middleware list is:
3803 Catalyst::Middleware::Stash
3804 Plack::Middleware::HTTPExceptions
3805 Plack::Middleware::RemoveRedundantBody
3806 Plack::Middleware::FixMissingBodyInRedirect
3807 Plack::Middleware::ContentLength
3808 Plack::Middleware::MethodOverride
3809 Plack::Middleware::Head
3811 If the configuration setting C<using_frontend_proxy> is true we add:
3813 Plack::Middleware::ReverseProxy
3815 If the configuration setting C<using_frontend_proxy_path> is true we add:
3817 Plack::Middleware::ReverseProxyPath
3819 But B<NOTE> that L<Plack::Middleware::ReverseProxyPath> is not a dependency of the
3820 L<Catalyst> distribution so if you want to use this option you should add it to
3821 your project distribution file.
3823 These middlewares will be added at L</setup_middleware> during the
3824 L</setup> phase of application startup.
3828 sub default_middleware {
3831 Catalyst::Middleware::Stash->new,
3832 Plack::Middleware::HTTPExceptions->new,
3833 Plack::Middleware::RemoveRedundantBody->new,
3834 Plack::Middleware::FixMissingBodyInRedirect->new,
3835 Plack::Middleware::ContentLength->new,
3836 Plack::Middleware::MethodOverride->new,
3837 Plack::Middleware::Head->new);
3839 if($class->config->{using_frontend_proxy}) {
3840 push @mw, Plack::Middleware::ReverseProxy->new;
3843 if($class->config->{using_frontend_proxy_path}) {
3844 if(Class::Load::try_load_class('Plack::Middleware::ReverseProxyPath')) {
3845 push @mw, Plack::Middleware::ReverseProxyPath->new;
3847 $class->log->error("Cannot use configuration 'using_frontend_proxy_path' because 'Plack::Middleware::ReverseProxyPath' is not installed");
3854 =head2 registered_middlewares
3856 Read only accessor that returns an array of all the middleware in the order
3857 that they were added (which is the REVERSE of the order they will be applied).
3859 The values returned will be either instances of L<Plack::Middleware> or of a
3860 compatible interface, or a coderef, which is assumed to be inlined middleware
3862 =head2 setup_middleware (?@middleware)
3864 Read configuration information stored in configuration key C<psgi_middleware> or
3867 See under L</CONFIGURATION> information regarding C<psgi_middleware> and how
3868 to use it to enable L<Plack::Middleware>
3870 This method is automatically called during 'setup' of your application, so
3871 you really don't need to invoke it. However you may do so if you find the idea
3872 of loading middleware via configuration weird :). For example:
3878 __PACKAGE__->setup_middleware('Head');
3881 When we read middleware definitions from configuration, we reverse the list
3882 which sounds odd but is likely how you expect it to work if you have prior
3883 experience with L<Plack::Builder> or if you previously used the plugin
3884 L<Catalyst::Plugin::EnableMiddleware> (which is now considered deprecated)
3886 So basically your middleware handles an incoming request from the first
3887 registered middleware, down and handles the response from the last middleware
3892 sub registered_middlewares {
3894 if(my $middleware = $class->_psgi_middleware) {
3895 my @mw = ($class->default_middleware, @$middleware);
3897 if($class->config->{using_frontend_proxy}) {
3898 push @mw, Plack::Middleware::ReverseProxy->new;
3903 die "You cannot call ->registered_middlewares until middleware has been setup";
3907 sub setup_middleware {
3909 my @middleware_definitions;
3911 # If someone calls this method you can add middleware with args. However if its
3912 # called without an arg we need to setup the configuration middleware.
3914 @middleware_definitions = reverse(@_);
3916 @middleware_definitions = reverse(@{$class->config->{'psgi_middleware'}||[]})
3917 unless $class->finalized_default_middleware;
3918 $class->finalized_default_middleware(1); # Only do this once, just in case some people call setup over and over...
3921 my @middleware = ();
3922 while(my $next = shift(@middleware_definitions)) {
3924 if(Scalar::Util::blessed $next && $next->can('wrap')) {
3925 push @middleware, $next;
3926 } elsif(ref $next eq 'CODE') {
3927 push @middleware, $next;
3928 } elsif(ref $next eq 'HASH') {
3929 my $namespace = shift @middleware_definitions;
3930 my $mw = $class->Catalyst::Utils::build_middleware($namespace, %$next);
3931 push @middleware, $mw;
3933 die "I can't handle middleware definition ${\ref $next}";
3936 my $mw = $class->Catalyst::Utils::build_middleware($next);
3937 push @middleware, $mw;
3941 my @existing = @{$class->_psgi_middleware || []};
3942 $class->_psgi_middleware([@middleware,@existing,]);
3945 =head2 registered_data_handlers
3947 A read only copy of registered Data Handlers returned as a Hash, where each key
3948 is a content type and each value is a subref that attempts to decode that content
3951 =head2 setup_data_handlers (?@data_handler)
3953 Read configuration information stored in configuration key C<data_handlers> or
3956 See under L</CONFIGURATION> information regarding C<data_handlers>.
3958 This method is automatically called during 'setup' of your application, so
3959 you really don't need to invoke it.
3961 =head2 default_data_handlers
3963 Default Data Handlers that come bundled with L<Catalyst>. Currently there are
3964 only two default data handlers, for 'application/json' and an alternative to
3965 'application/x-www-form-urlencoded' which supposed nested form parameters via
3966 L<CGI::Struct> or via L<CGI::Struct::XS> IF you've installed it.
3968 The 'application/json' data handler is used to parse incoming JSON into a Perl
3969 data structure. It used either L<JSON::MaybeXS> or L<JSON>, depending on which
3970 is installed. This allows you to fail back to L<JSON:PP>, which is a Pure Perl
3971 JSON decoder, and has the smallest dependency impact.
3973 Because we don't wish to add more dependencies to L<Catalyst>, if you wish to
3974 use this new feature we recommend installing L<JSON> or L<JSON::MaybeXS> in
3975 order to get the best performance. You should add either to your dependency
3976 list (Makefile.PL, dist.ini, cpanfile, etc.)
3980 sub registered_data_handlers {
3982 if(my $data_handlers = $class->_data_handlers) {
3983 return %$data_handlers;
3985 $class->setup_data_handlers;
3986 return $class->registered_data_handlers;
3990 sub setup_data_handlers {
3991 my ($class, %data_handler_callbacks) = @_;
3992 %data_handler_callbacks = (
3993 %{$class->default_data_handlers},
3994 %{$class->config->{'data_handlers'}||+{}},
3995 %data_handler_callbacks);
3997 $class->_data_handlers(\%data_handler_callbacks);
4000 sub default_data_handlers {
4003 'application/x-www-form-urlencoded' => sub {
4004 my ($fh, $req) = @_;
4005 my $params = $req->_use_hash_multivalue ? $req->body_parameters->mixed : $req->body_parameters;
4006 Class::Load::load_first_existing_class('CGI::Struct::XS', 'CGI::Struct')
4007 ->can('build_cgi_struct')->($params);
4009 'application/json' => sub {
4010 my ($fh, $req) = @_;
4011 my $parser = Class::Load::load_first_existing_class('JSON::MaybeXS', 'JSON');
4015 $slurped = $fh->getline;
4016 $parser->can("decode_json")->($slurped); # decode_json does utf8 decoding for us
4017 } || Catalyst::Exception->throw(sprintf "Error Parsing POST '%s', Error: %s", (defined($slurped) ? $slurped : 'undef') ,$@);
4022 sub _handle_http_exception {
4023 my ( $self, $error ) = @_;
4025 !$self->config->{always_catch_http_exceptions}
4028 $error->can('as_psgi')
4029 || ( $error->can('code')
4030 && $error->code =~ m/^[1-5][0-9][0-9]$/ )
4040 Returns an arrayref of the internal execution stack (actions that are
4041 currently executing).
4045 Returns the current timing statistics object. By default Catalyst uses
4046 L<Catalyst::Stats|Catalyst::Stats>, but can be set otherwise with
4047 L<< stats_class|/"$c->stats_class" >>.
4049 Even if L<< -Stats|/"-Stats" >> is not enabled, the stats object is still
4050 available. By enabling it with C< $c->stats->enabled(1) >, it can be used to
4051 profile explicitly, although MyApp.pm still won't profile nor output anything
4054 =head2 $c->stats_class
4056 Returns or sets the stats (timing statistics) class. L<Catalyst::Stats|Catalyst::Stats> is used by default.
4058 =head2 $app->stats_class_traits
4060 A arrayref of L<Moose::Role>s that are applied to the stats_class before creating it.
4062 =head2 $app->composed_stats_class
4064 this is the stats_class composed with any 'stats_class_traits'. You can
4065 name the full namespace of the role, or a namespace suffix, which will then
4066 be tried against the following standard namespace prefixes.
4068 $MyApp::TraitFor::Stats::$trait_suffix
4069 Catalyst::TraitFor::Stats::$trait_suffix
4071 So for example if you set:
4073 MyApp->stats_class_traits(['Foo']);
4075 We try each possible role in turn (and throw an error if none load)
4078 MyApp::TraitFor::Stats::Foo
4079 Catalyst::TraitFor::Stats::Foo
4081 The namespace part 'TraitFor::Stats' was chosen to assist in backwards
4082 compatibility with L<CatalystX::RoleApplicator> which previously provided
4083 these features in a stand alone package.
4085 =head2 $c->use_stats
4087 Returns 1 when L<< stats collection|/"-Stats" >> is enabled.
4089 Note that this is a static method, not an accessor and should be overridden
4090 by declaring C<sub use_stats { 1 }> in your MyApp.pm, not by calling C<< $c->use_stats(1) >>.
4097 =head2 $c->write( $data )
4099 Writes $data to the output stream. When using this method directly, you
4100 will need to manually set the C<Content-Length> header to the length of
4101 your output data, if known.
4108 # Finalize headers if someone manually writes output (for compat)
4109 $c->finalize_headers;
4111 return $c->response->write( @_ );
4116 Returns the Catalyst version number. Mostly useful for "powered by"
4117 messages in template systems.
4121 sub version { return $Catalyst::VERSION }
4123 =head1 CONFIGURATION
4125 There are a number of 'base' config variables which can be set:
4131 C<always_catch_http_exceptions> - As of version 5.90060 Catalyst
4132 rethrows errors conforming to the interface described by
4133 L<Plack::Middleware::HTTPExceptions> and lets the middleware deal with it.
4134 Set true to get the deprecated behaviour and have Catalyst catch HTTP exceptions.
4138 C<default_model> - The default model picked if you say C<< $c->model >>. See L<< /$c->model($name) >>.
4142 C<default_view> - The default view to be rendered or returned when C<< $c->view >> is called. See L<< /$c->view($name) >>.
4146 C<disable_component_resolution_regex_fallback> - Turns
4147 off the deprecated component resolution functionality so
4148 that if any of the component methods (e.g. C<< $c->controller('Foo') >>)
4149 are called then regex search will not be attempted on string values and
4150 instead C<undef> will be returned.
4154 C<home> - The application home directory. In an uninstalled application,
4155 this is the top level application directory. In an installed application,
4156 this will be the directory containing C<< MyApp.pm >>.
4160 C<ignore_frontend_proxy> - See L</PROXY SUPPORT>
4164 C<name> - The name of the application in debug messages and the debug and
4169 C<parse_on_demand> - The request body (for example file uploads) will not be parsed
4170 until it is accessed. This allows you to (for example) check authentication (and reject
4171 the upload) before actually receiving all the data. See L</ON-DEMAND PARSER>
4175 C<root> - The root directory for templates. Usually this is just a
4176 subdirectory of the home directory, but you can set it to change the
4177 templates to a different directory.
4181 C<search_extra> - Array reference passed to Module::Pluggable to for additional
4182 namespaces from which components will be loaded (and constructed and stored in
4183 C<< $c->components >>).
4187 C<show_internal_actions> - If true, causes internal actions such as C<< _DISPATCH >>
4188 to be shown in hit debug tables in the test server.
4192 C<use_request_uri_for_path> - Controls if the C<REQUEST_URI> or C<PATH_INFO> environment
4193 variable should be used for determining the request path.
4195 Most web server environments pass the requested path to the application using environment variables,
4196 from which Catalyst has to reconstruct the request base (i.e. the top level path to / in the application,
4197 exposed as C<< $c->request->base >>) and the request path below that base.
4199 There are two methods of doing this, both of which have advantages and disadvantages. Which method is used
4200 is determined by the C<< $c->config(use_request_uri_for_path) >> setting (which can either be true or false).
4204 =item use_request_uri_for_path => 0
4206 This is the default (and the) traditional method that Catalyst has used for determining the path information.
4207 The path is generated from a combination of the C<PATH_INFO> and C<SCRIPT_NAME> environment variables.
4208 The allows the application to behave correctly when C<mod_rewrite> is being used to redirect requests
4209 into the application, as these variables are adjusted by mod_rewrite to take account for the redirect.
4211 However this method has the major disadvantage that it is impossible to correctly decode some elements
4212 of the path, as RFC 3875 says: "C<< Unlike a URI path, the PATH_INFO is not URL-encoded, and cannot
4213 contain path-segment parameters. >>" This means PATH_INFO is B<always> decoded, and therefore Catalyst
4214 can't distinguish / vs %2F in paths (in addition to other encoded values).
4216 =item use_request_uri_for_path => 1
4218 This method uses the C<REQUEST_URI> and C<SCRIPT_NAME> environment variables. As C<REQUEST_URI> is never
4219 decoded, this means that applications using this mode can correctly handle URIs including the %2F character
4220 (i.e. with C<AllowEncodedSlashes> set to C<On> in Apache).
4222 Given that this method of path resolution is provably more correct, it is recommended that you use
4223 this unless you have a specific need to deploy your application in a non-standard environment, and you are
4224 aware of the implications of not being able to handle encoded URI paths correctly.
4226 However it also means that in a number of cases when the app isn't installed directly at a path, but instead
4227 is having paths rewritten into it (e.g. as a .cgi/fcgi in a public_html directory, with mod_rewrite in a
4228 .htaccess file, or when SSI is used to rewrite pages into the app, or when sub-paths of the app are exposed
4229 at other URIs than that which the app is 'normally' based at with C<mod_rewrite>), the resolution of
4230 C<< $c->request->base >> will be incorrect.
4236 C<using_frontend_proxy> - See L</PROXY SUPPORT>.
4240 C<using_frontend_proxy_path> - Enabled L<Plack::Middleware::ReverseProxyPath> on your application (if
4241 installed, otherwise log an error). This is useful if your application is not running on the
4242 'root' (or /) of your host server. B<NOTE> if you use this feature you should add the required
4243 middleware to your project dependency list since its not automatically a dependency of L<Catalyst>.
4244 This has been done since not all people need this feature and we wish to restrict the growth of
4245 L<Catalyst> dependencies.
4249 C<encoding> - See L</ENCODING>
4251 This now defaults to 'UTF-8'. You my turn it off by setting this configuration
4256 C<abort_chain_on_error_fix>
4258 When there is an error in an action chain, the default behavior is to continue
4259 processing the remaining actions and then catch the error upon chain end. This
4260 can lead to running actions when the application is in an unexpected state. If
4261 you have this issue, setting this config value to true will promptly exit a
4262 chain when there is an error raised in any action (thus terminating the chain
4267 __PACKAGE__->config(abort_chain_on_error_fix => 1);
4269 In the future this might become the default behavior.
4273 C<use_hash_multivalue_in_request>
4275 In L<Catalyst::Request> the methods C<query_parameters>, C<body_parametes>
4276 and C<parameters> return a hashref where values might be scalar or an arrayref
4277 depending on the incoming data. In many cases this can be undesirable as it
4278 leads one to writing defensive code like the following:
4280 my ($val) = ref($c->req->parameters->{a}) ?
4281 @{$c->req->parameters->{a}} :
4282 $c->req->parameters->{a};
4284 Setting this configuration item to true will make L<Catalyst> populate the
4285 attributes underlying these methods with an instance of L<Hash::MultiValue>
4286 which is used by L<Plack::Request> and others to solve this very issue. You
4287 may prefer this behavior to the default, if so enable this option (be warned
4288 if you enable it in a legacy application we are not sure if it is completely
4289 backwardly compatible).
4293 C<skip_complex_post_part_handling>
4295 When creating body parameters from a POST, if we run into a multipart POST
4296 that does not contain uploads, but instead contains inlined complex data
4297 (very uncommon) we cannot reliably convert that into field => value pairs. So
4298 instead we create an instance of L<Catalyst::Request::PartData>. If this causes
4299 issue for you, you can disable this by setting C<skip_complex_post_part_handling>
4300 to true (default is false).
4304 C<skip_body_param_unicode_decoding>
4306 Generally we decode incoming POST params based on your declared encoding (the
4307 default for this is to decode UTF-8). If this is causing you trouble and you
4308 do not wish to turn all encoding support off (with the C<encoding> configuration
4309 parameter) you may disable this step atomically by setting this configuration
4314 C<do_not_decode_query>
4316 If true, then do not try to character decode any wide characters in your
4317 request URL query or keywords. Most readings of the relevant specifications
4318 suggest these should be UTF-* encoded, which is the default that L<Catalyst>
4319 will use, however if you are creating a lot of URLs manually or have external
4320 evil clients, this might cause you trouble. If you find the changes introduced
4321 in Catalyst version 5.90080+ break some of your query code, you may disable
4322 the UTF-8 decoding globally using this configuration.
4324 This setting takes precedence over C<default_query_encoding> and
4325 C<decode_query_using_global_encoding>
4329 C<default_query_encoding>
4331 By default we decode query and keywords in your request URL using UTF-8, which
4332 is our reading of the relevant specifications. This setting allows one to
4333 specify a fixed value for how to decode your query. You might need this if
4334 you are doing a lot of custom encoding of your URLs and not using UTF-8.
4336 This setting take precedence over C<decode_query_using_global_encoding>.
4340 C<decode_query_using_global_encoding>
4342 Setting this to true will default your query decoding to whatever your
4343 general global encoding is (the default is UTF-8).
4347 C<use_chained_args_0_special_case>
4349 In older versions of Catalyst, when more than one action matched the same path
4350 AND all those matching actions declared Args(0), we'd break the tie by choosing
4351 the first action defined. We now normalized how Args(0) works so that it
4352 follows the same rule as Args(N), which is to say when we need to break a tie
4353 we choose the LAST action defined. If this breaks your code and you don't
4354 have time to update to follow the new normalized approach, you may set this
4355 value to true and it will globally revert to the original chaining behavior.
4359 C<psgi_middleware> - See L<PSGI MIDDLEWARE>.
4363 C<data_handlers> - See L<DATA HANDLERS>.
4367 C<stats_class_traits>
4369 An arrayref of L<Moose::Role>s that get composed into your stats class.
4373 C<request_class_traits>
4375 An arrayref of L<Moose::Role>s that get composed into your request class.
4379 C<response_class_traits>
4381 An arrayref of L<Moose::Role>s that get composed into your response class.
4385 C<inject_components>
4387 A Hashref of L<Catalyst::Component> subclasses that are 'injected' into configuration.
4391 inject_components => {
4392 'Controller::Err' => { from_component => 'Local::Controller::Errors' },
4393 'Model::Zoo' => { from_component => 'Local::Model::Foo' },
4394 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] },
4396 'Controller::Err' => { a => 100, b=>200, namespace=>'error' },
4397 'Model::Zoo' => { a => 2 },
4398 'Model::Foo' => { a => 100 },
4401 Generally L<Catalyst> looks for components in your Model/View or Controller directories.
4402 However for cases when you which to use an existing component and you don't need any
4403 customization (where for when you can apply a role to customize it) you may inject those
4404 components into your application. Please note any configuration should be done 'in the
4405 normal way', with a key under configuration named after the component affix, as in the
4408 Using this type of injection allows you to construct significant amounts of your application
4409 with only configuration!. This may or may not lead to increased code understanding.
4411 Please not you may also call the ->inject_components application method as well, although
4412 you must do so BEFORE setup.
4418 Generally when you throw an exception inside an Action (or somewhere in
4419 your stack, such as in a model that an Action is calling) that exception
4420 is caught by Catalyst and unless you either catch it yourself (via eval
4421 or something like L<Try::Tiny> or by reviewing the L</error> stack, it
4422 will eventually reach L</finalize_errors> and return either the debugging
4423 error stack page, or the default error page. However, if your exception
4424 can be caught by L<Plack::Middleware::HTTPExceptions>, L<Catalyst> will
4425 instead rethrow it so that it can be handled by that middleware (which
4426 is part of the default middleware). For example this would allow
4428 use HTTP::Throwable::Factory 'http_throw';
4430 sub throws_exception :Local {
4431 my ($self, $c) = @_;
4433 http_throw(SeeOther => { location =>
4434 $c->uri_for($self->action_for('redirect')) });
4438 =head1 INTERNAL ACTIONS
4440 Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>,
4441 C<_ACTION>, and C<_END>. These are by default not shown in the private
4442 action table, but you can make them visible with a config parameter.
4444 MyApp->config(show_internal_actions => 1);
4446 =head1 ON-DEMAND PARSER
4448 The request body is usually parsed at the beginning of a request,
4449 but if you want to handle input yourself, you can enable on-demand
4450 parsing with a config parameter.
4452 MyApp->config(parse_on_demand => 1);
4454 =head1 PROXY SUPPORT
4456 Many production servers operate using the common double-server approach,
4457 with a lightweight frontend web server passing requests to a larger
4458 backend server. An application running on the backend server must deal
4459 with two problems: the remote user always appears to be C<127.0.0.1> and
4460 the server's hostname will appear to be C<localhost> regardless of the
4461 virtual host that the user connected through.
4463 Catalyst will automatically detect this situation when you are running
4464 the frontend and backend servers on the same machine. The following
4465 changes are made to the request.
4467 $c->req->address is set to the user's real IP address, as read from
4468 the HTTP X-Forwarded-For header.
4470 The host value for $c->req->base and $c->req->uri is set to the real
4471 host, as read from the HTTP X-Forwarded-Host header.
4473 Additionally, you may be running your backend application on an insecure
4474 connection (port 80) while your frontend proxy is running under SSL. If there
4475 is a discrepancy in the ports, use the HTTP header C<X-Forwarded-Port> to
4476 tell Catalyst what port the frontend listens on. This will allow all URIs to
4477 be created properly.
4479 In the case of passing in:
4481 X-Forwarded-Port: 443
4483 All calls to C<uri_for> will result in an https link, as is expected.
4485 Obviously, your web server must support these headers for this to work.
4487 In a more complex server farm environment where you may have your
4488 frontend proxy server(s) on different machines, you will need to set a
4489 configuration option to tell Catalyst to read the proxied data from the
4492 MyApp->config(using_frontend_proxy => 1);
4494 If you do not wish to use the proxy support at all, you may set:
4496 MyApp->config(ignore_frontend_proxy => 0);
4498 =head2 Note about psgi files
4500 Note that if you supply your own .psgi file, calling
4501 C<< MyApp->psgi_app(@_); >>, then B<this will not happen automatically>.
4503 You either need to apply L<Plack::Middleware::ReverseProxy> yourself
4504 in your psgi, for example:
4507 enable "Plack::Middleware::ReverseProxy";
4511 This will unconditionally add the ReverseProxy support, or you need to call
4512 C<< $app = MyApp->apply_default_middlewares($app) >> (to conditionally
4513 apply the support depending upon your config).
4515 See L<Catalyst::PSGI> for more information.
4517 =head1 THREAD SAFETY
4519 Catalyst has been tested under Apache 2's threading C<mpm_worker>,
4520 C<mpm_winnt>, and the standalone forking HTTP server on Windows. We
4521 believe the Catalyst core to be thread-safe.
4523 If you plan to operate in a threaded environment, remember that all other
4524 modules you are using must also be thread-safe. Some modules, most notably
4525 L<DBD::SQLite>, are not thread-safe.
4527 =head1 DATA HANDLERS
4529 The L<Catalyst::Request> object uses L<HTTP::Body> to populate 'classic' HTML
4530 form parameters and URL search query fields. However it has become common
4531 for various alternative content types to be PUT or POSTed to your controllers
4532 and actions. People working on RESTful APIs, or using AJAX often use JSON,
4533 XML and other content types when communicating with an application server. In
4534 order to better support this use case, L<Catalyst> defines a global configuration
4535 option, C<data_handlers>, which lets you associate a content type with a coderef
4536 that parses that content type into something Perl can readily access.
4543 __PACKAGE__->config(
4545 'application/json' => sub { local $/; decode_json $_->getline },
4547 ## Any other configuration.
4552 By default L<Catalyst> comes with a generic JSON data handler similar to the
4553 example given above, which uses L<JSON::Maybe> to provide either L<JSON::PP>
4554 (a pure Perl, dependency free JSON parser) or L<Cpanel::JSON::XS> if you have
4555 it installed (if you want the faster XS parser, add it to you project Makefile.PL
4556 or dist.ini, cpanfile, etc.)
4558 The C<data_handlers> configuration is a hashref whose keys are HTTP Content-Types
4559 (matched against the incoming request type using a regexp such as to be case
4560 insensitive) and whose values are coderefs that receive a localized version of
4561 C<$_> which is a filehandle object pointing to received body.
4563 This feature is considered an early access release and we reserve the right
4564 to alter the interface in order to provide a performant and secure solution to
4565 alternative request body content. Your reports welcomed!
4567 =head1 PSGI MIDDLEWARE
4569 You can define middleware, defined as L<Plack::Middleware> or a compatible
4570 interface in configuration. Your middleware definitions are in the form of an
4571 arrayref under the configuration key C<psgi_middleware>. Here's an example
4572 with details to follow:
4577 use Plack::Middleware::StackTrace;
4579 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
4581 __PACKAGE__->config(
4582 'psgi_middleware', [
4585 $stacktrace_middleware,
4586 'Session' => {store => 'File'},
4591 $env->{myapp.customkey} = 'helloworld';
4600 So the general form is:
4602 __PACKAGE__->config(psgi_middleware => \@middleware_definitions);
4604 Where C<@middleware> is one or more of the following, applied in the REVERSE of
4605 the order listed (to make it function similarly to L<Plack::Builder>:
4607 Alternatively, you may also define middleware by calling the L</setup_middleware>
4614 __PACKAGE__->setup_middleware( \@middleware_definitions);
4617 In the case where you do both (use 'setup_middleware' and configuration) the
4618 package call to setup_middleware will be applied earlier (in other words its
4619 middleware will wrap closer to the application). Keep this in mind since in
4620 some cases the order of middleware is important.
4622 The two approaches are not exclusive.
4626 =item Middleware Object
4628 An already initialized object that conforms to the L<Plack::Middleware>
4631 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
4633 __PACKAGE__->config(
4634 'psgi_middleware', [
4635 $stacktrace_middleware,
4641 A coderef that is an inlined middleware:
4643 __PACKAGE__->config(
4644 'psgi_middleware', [
4649 if($env->{PATH_INFO} =~m/forced/) {
4651 ->new(file=>TestApp->path_to(qw/share static forced.txt/))
4654 return $app->($env);
4664 We assume the scalar refers to a namespace after normalizing it using the
4667 (1) If the scalar is prefixed with a "+" (as in C<+MyApp::Foo>) then the full string
4668 is assumed to be 'as is', and we just install and use the middleware.
4670 (2) If the scalar begins with "Plack::Middleware" or your application namespace
4671 (the package name of your Catalyst application subclass), we also assume then
4672 that it is a full namespace, and use it.
4674 (3) Lastly, we then assume that the scalar is a partial namespace, and attempt to
4675 resolve it first by looking for it under your application namespace (for example
4676 if you application is "MyApp::Web" and the scalar is "MyMiddleware", we'd look
4677 under "MyApp::Web::Middleware::MyMiddleware") and if we don't find it there, we
4678 will then look under the regular L<Plack::Middleware> namespace (i.e. for the
4679 previous we'd try "Plack::Middleware::MyMiddleware"). We look under your application
4680 namespace first to let you 'override' common L<Plack::Middleware> locally, should
4681 you find that a good idea.
4687 __PACKAGE__->config(
4688 'psgi_middleware', [
4689 'Debug', ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap
4690 'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap
4691 '+MyApp::Custom', ## MyApp::Custom->wrap
4695 =item a scalar followed by a hashref
4697 Just like the previous, except the following C<HashRef> is used as arguments
4698 to initialize the middleware object.
4700 __PACKAGE__->config(
4701 'psgi_middleware', [
4702 'Session' => {store => 'File'},
4707 Please see L<PSGI> for more on middleware.
4711 Starting in L<Catalyst> version 5.90080 encoding is automatically enabled
4712 and set to encode all body responses to UTF8 when possible and applicable.
4713 Following is documentation on this process. If you are using an older
4714 version of L<Catalyst> you should review documentation for that version since
4717 By default encoding is now 'UTF-8'. You may turn it off by setting
4718 the encoding configuration to undef.
4720 MyApp->config(encoding => undef);
4722 This is recommended for temporary backwards compatibility only.
4724 Encoding is automatically applied when the content-type is set to
4725 a type that can be encoded. Currently we encode when the content type
4726 matches the following regular expression:
4728 $content_type =~ /^text|xml$|javascript$/
4730 Encoding is set on the application, but it is copied to the context object
4731 so that you can override it on a request basis.
4733 Be default we don't automatically encode 'application/json' since the most
4734 common approaches to generating this type of response (Either via L<Catalyst::View::JSON>
4735 or L<Catalyst::Action::REST>) will do so already and we want to avoid double
4738 If you are producing JSON response in an unconventional manner (such
4739 as via a template or manual strings) you should perform the UTF8 encoding
4740 manually as well such as to conform to the JSON specification.
4742 NOTE: We also examine the value of $c->response->content_encoding. If
4743 you set this (like for example 'gzip', and manually gzipping the body)
4744 we assume that you have done all the necessary encoding yourself, since
4745 we cannot encode the gzipped contents. If you use a plugin like
4746 L<Catalyst::Plugin::Compress> you need to update to a modern version in order
4747 to have this function correctly with the new UTF8 encoding code, or you
4748 can use L<Plack::Middleware::Deflater> or (probably best) do your compression on
4757 Returns an instance of an C<Encode> encoding
4759 print $c->encoding->name
4761 =item handle_unicode_encoding_exception ($exception_context)
4763 Method called when decoding process for a request fails.
4765 An C<$exception_context> hashref is provided to allow you to override the
4766 behaviour of your application when given data with incorrect encodings.
4768 The default method throws exceptions in the case of invalid request parameters
4769 (resulting in a 500 error), but ignores errors in upload filenames.
4771 The keys passed in the C<$exception_context> hash are:
4777 The value which was not able to be decoded.
4781 The exception received from L<Encode>.
4785 What type of data was being decoded. Valid values are (currently)
4786 C<params> - for request parameters / arguments / captures
4787 and C<uploads> - for request upload filenames.
4797 Join #catalyst on irc.perl.org.
4801 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
4802 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
4806 http://catalyst.perl.org
4810 http://dev.catalyst.perl.org
4814 =head2 L<Task::Catalyst> - All you need to start with Catalyst
4816 =head2 L<Catalyst::Manual> - The Catalyst Manual
4818 =head2 L<Catalyst::Component>, L<Catalyst::Controller> - Base classes for components
4820 =head2 L<Catalyst::Engine> - Core engine
4822 =head2 L<Catalyst::Log> - Log class.
4824 =head2 L<Catalyst::Request> - Request object
4826 =head2 L<Catalyst::Response> - Response object
4828 =head2 L<Catalyst::Test> - The test suite.
4830 =head1 PROJECT FOUNDER
4832 sri: Sebastian Riedel <sri@cpan.org>
4838 acme: Leon Brocard <leon@astray.com>
4840 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
4842 andrewalker: André Walker <andre@cpan.org>
4846 Andrew Ford E<lt>A.Ford@ford-mason.co.ukE<gt>
4850 andyg: Andy Grundman <andy@hybridized.org>
4852 audreyt: Audrey Tang
4854 bricas: Brian Cassidy <bricas@cpan.org>
4856 Caelum: Rafael Kitover <rkitover@io.com>
4858 chansen: Christian Hansen
4860 Chase Venters C<chase.venters@gmail.com>
4862 chicks: Christopher Hicks
4864 Chisel Wright C<pause@herlpacker.co.uk>
4866 Danijel Milicevic C<me@danijel.de>
4868 davewood: David Schmidt <davewood@cpan.org>
4870 David Kamholz E<lt>dkamholz@cpan.orgE<gt>
4872 David Naughton, C<naughton@umn.edu>
4876 dhoss: Devin Austin <dhoss@cpan.org>
4878 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
4882 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
4884 esskar: Sascha Kiefer
4886 fireartist: Carl Franks <cfranks@cpan.org>
4888 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
4890 gabb: Danijel Milicevic
4894 Gavin Henry C<ghenry@perl.me.uk>
4898 groditi: Guillermo Roditi <groditi@gmail.com>
4900 hobbs: Andrew Rodland <andrew@cleverdomain.org>
4902 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
4904 jcamacho: Juan Camacho
4906 jester: Jesse Sheidlower C<jester@panix.com>
4908 jhannah: Jay Hannah <jay@jays.net>
4914 jon: Jon Schutz <jjschutz@cpan.org>
4916 Jonathan Rockway C<< <jrockway@cpan.org> >>
4918 Kieren Diment C<kd@totaldatasolution.com>
4920 konobi: Scott McWhirter <konobi@cpan.org>
4922 marcus: Marcus Ramberg <mramberg@cpan.org>
4924 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
4926 mgrimes: Mark Grimes <mgrimes@cpan.org>
4928 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
4932 naughton: David Naughton
4934 ningu: David Kamholz <dkamholz@cpan.org>
4936 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
4938 numa: Dan Sully <daniel@cpan.org>
4944 omega: Andreas Marienborg
4946 Oleg Kostyuk <cub.uanic@gmail.com>
4948 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
4950 rafl: Florian Ragwitz <rafl@debian.org>
4952 random: Roland Lammel <lammel@cpan.org>
4954 Robert Sedlacek C<< <rs@474.at> >>
4956 SpiceMan: Marcel Montes
4960 szbalint: Balint Szilakszi <szbalint@cpan.org>
4962 t0m: Tomas Doran <bobtfish@bobtfish.net>
4966 vanstyn: Henry Van Styn <vanstyn@cpan.org>
4968 Viljo Marrandi C<vilts@yahoo.com>
4970 Will Hawes C<info@whawes.co.uk>
4972 willert: Sebastian Willert <willert@cpan.org>
4974 wreis: Wallace Reis <wreis@cpan.org>
4976 Yuval Kogman, C<nothingmuch@woobling.org>
4978 rainboxx: Matthias Dietrich, C<perl@rainboxx.de>
4980 dd070: Dhaval Dhanani <dhaval070@gmail.com>
4982 Upasana <me@upasana.me>
4984 John Napiorkowski (jnap) <jjnapiork@cpan.org>
4988 Copyright (c) 2005-2015, the above named PROJECT FOUNDER and CONTRIBUTORS.
4992 This library is free software. You can redistribute it and/or modify it under
4993 the same terms as Perl itself.
4999 __PACKAGE__->meta->make_immutable;