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.90113';
208 $VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
211 my ( $class, @arguments ) = @_;
213 # We have to limit $class to Catalyst to avoid pushing Catalyst upon every
215 return unless $class eq 'Catalyst';
217 my $caller = caller();
218 return if $caller eq 'main';
220 my $meta = Moose::Meta::Class->initialize($caller);
221 unless ( $caller->isa('Catalyst') ) {
222 my @superclasses = ($meta->superclasses, $class, 'Catalyst::Controller');
223 $meta->superclasses(@superclasses);
225 # Avoid possible C3 issues if 'Moose::Object' is already on RHS of MyApp
226 $meta->superclasses(grep { $_ ne 'Moose::Object' } $meta->superclasses);
228 unless( $meta->has_method('meta') ){
229 if ($Moose::VERSION >= 1.15) {
230 $meta->_add_meta_method('meta');
233 $meta->add_method(meta => sub { Moose::Meta::Class->initialize("${caller}") } );
237 $caller->arguments( [@arguments] );
241 sub _application { $_[0] }
247 Catalyst - The Elegant MVC Web Application Framework
250 <a href="https://badge.fury.io/pl/Catalyst-Runtime"><img src="https://badge.fury.io/pl/Catalyst-Runtime.svg" alt="CPAN version" height="18"></a>
251 <a href="https://travis-ci.org/perl-catalyst/catalyst-runtime/"><img src="https://api.travis-ci.org/perl-catalyst/catalyst-runtime.png" alt="Catalyst></a>
252 <a href="http://cpants.cpanauthors.org/dist/Catalyst-Runtime"><img src="http://cpants.cpanauthors.org/dist/Catalyst-Runtime.png" alt='Kwalitee Score' /></a>
256 See the L<Catalyst::Manual> distribution for comprehensive
257 documentation and tutorials.
259 # Install Catalyst::Devel for helpers and other development tools
260 # use the helper to create a new application
263 # add models, views, controllers
264 script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
265 script/myapp_create.pl view MyTemplate TT
266 script/myapp_create.pl controller Search
268 # built in testserver -- use -r to restart automatically on changes
269 # --help to see all available options
270 script/myapp_server.pl
272 # command line testing interface
273 script/myapp_test.pl /yada
276 use Catalyst qw/-Debug/; # include plugins here as well
278 ### In lib/MyApp/Controller/Root.pm (autocreated)
279 sub foo : Chained('/') Args() { # called for /foo, /foo/1, /foo/1/2, etc.
280 my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
281 $c->stash->{template} = 'foo.tt'; # set the template
282 # lookup something from db -- stash vars are passed to TT
284 $c->model('Database::Foo')->search( { country => $args[0] } );
285 if ( $c->req->params->{bar} ) { # access GET or POST parameters
286 $c->forward( 'bar' ); # process another action
287 # do something else after forward returns
291 # The foo.tt TT template can use the stash data from the database
292 [% WHILE (item = data.next) %]
296 # called for /bar/of/soap, /bar/of/soap/10, etc.
297 sub bar : Chained('/') PathPart('/bar/of/soap') Args() { ... }
299 # called after all actions are finished
301 my ( $self, $c ) = @_;
302 if ( scalar @{ $c->error } ) { ... } # handle errors
303 return if $c->res->body; # already have a response
304 $c->forward( 'MyApp::View::TT' ); # render template
307 See L<Catalyst::Manual::Intro> for additional information.
311 Catalyst is a modern framework for making web applications without the
312 pain usually associated with this process. This document is a reference
313 to the main Catalyst application. If you are a new user, we suggest you
314 start with L<Catalyst::Manual::Tutorial> or L<Catalyst::Manual::Intro>.
316 See L<Catalyst::Manual> for more documentation.
318 Catalyst plugins can be loaded by naming them as arguments to the "use
319 Catalyst" statement. Omit the C<Catalyst::Plugin::> prefix from the
320 plugin name, i.e., C<Catalyst::Plugin::My::Module> becomes
323 use Catalyst qw/My::Module/;
325 If your plugin starts with a name other than C<Catalyst::Plugin::>, you can
326 fully qualify the name by using a unary plus:
330 +Fully::Qualified::Plugin::Name
333 Special flags like C<-Debug> can also be specified as
334 arguments when Catalyst is loaded:
336 use Catalyst qw/-Debug My::Module/;
338 The position of plugins and flags in the chain is important, because
339 they are loaded in the order in which they appear.
341 The following flags are supported:
345 Enables debug output. You can also force this setting from the system
346 environment with CATALYST_DEBUG or <MYAPP>_DEBUG. The environment
347 settings override the application, with <MYAPP>_DEBUG having the highest
350 This sets the log level to 'debug' and enables full debug output on the
351 error screen. If you only want the latter, see L<< $c->debug >>.
355 Forces Catalyst to use a specific home directory, e.g.:
357 use Catalyst qw[-Home=/usr/mst];
359 This can also be done in the shell environment by setting either the
360 C<CATALYST_HOME> environment variable or C<MYAPP_HOME>; where C<MYAPP>
361 is replaced with the uppercased name of your application, any "::" in
362 the name will be replaced with underscores, e.g. MyApp::Web should use
363 MYAPP_WEB_HOME. If both variables are set, the MYAPP_HOME one will be used.
365 If none of these are set, Catalyst will attempt to automatically detect the
366 home directory. If you are working in a development environment, Catalyst
367 will try and find the directory containing either Makefile.PL, Build.PL,
368 dist.ini, or cpanfile. If the application has been installed into the system
369 (i.e. you have done C<make install>), then Catalyst will use the path to your
370 application module, without the .pm extension (e.g., /foo/MyApp if your
371 application was installed at /foo/MyApp.pm)
375 use Catalyst '-Log=warn,fatal,error';
377 Specifies a comma-delimited list of log levels.
381 Enables statistics collection and reporting.
383 use Catalyst qw/-Stats=1/;
385 You can also force this setting from the system environment with CATALYST_STATS
386 or <MYAPP>_STATS. The environment settings override the application, with
387 <MYAPP>_STATS having the highest priority.
389 Stats are also enabled if L<< debugging |/"-Debug" >> is enabled.
393 =head2 INFORMATION ABOUT THE CURRENT REQUEST
397 Returns a L<Catalyst::Action> object for the current action, which
398 stringifies to the action name. See L<Catalyst::Action>.
402 Returns the namespace of the current action, i.e., the URI prefix
403 corresponding to the controller of the current action. For example:
405 # in Controller::Foo::Bar
406 $c->namespace; # returns 'foo/bar';
412 Returns the current L<Catalyst::Request> object, giving access to
413 information about the current client request (including parameters,
414 cookies, HTTP headers, etc.). See L<Catalyst::Request>.
416 =head2 REQUEST FLOW HANDLING
418 =head2 $c->forward( $action [, \@arguments ] )
420 =head2 $c->forward( $class, $method, [, \@arguments ] )
422 This is one way of calling another action (method) in the same or
423 a different controller. You can also use C<< $self->my_method($c, @args) >>
424 in the same controller or C<< $c->controller('MyController')->my_method($c, @args) >>
425 in a different controller.
426 The main difference is that 'forward' uses some of the Catalyst request
427 cycle overhead, including debugging, which may be useful to you. On the
428 other hand, there are some complications to using 'forward', restrictions
429 on values returned from 'forward', and it may not handle errors as you prefer.
430 Whether you use 'forward' or not is up to you; it is not considered superior to
431 the other ways to call a method.
433 'forward' calls another action, by its private name. If you give a
434 class name but no method, C<process()> is called. You may also optionally
435 pass arguments in an arrayref. The action will receive the arguments in
436 C<@_> and C<< $c->req->args >>. Upon returning from the function,
437 C<< $c->req->args >> will be restored to the previous values.
439 Any data C<return>ed from the action forwarded to, will be returned by the
442 my $foodata = $c->forward('/foo');
443 $c->forward('index');
444 $c->forward(qw/Model::DBIC::Foo do_stuff/);
445 $c->forward('View::TT');
447 Note that L<< forward|/"$c->forward( $action [, \@arguments ] )" >> implies
448 an C<< eval { } >> around the call (actually
449 L<< execute|/"$c->execute( $class, $coderef )" >> does), thus rendering all
450 exceptions thrown by the called action non-fatal and pushing them onto
451 $c->error instead. If you want C<die> to propagate you need to do something
455 die join "\n", @{ $c->error } if @{ $c->error };
457 Or make sure to always return true values from your actions and write
460 $c->forward('foo') || return;
462 Another note is that C<< $c->forward >> always returns a scalar because it
463 actually returns $c->state which operates in a scalar context.
464 Thus, something like:
468 in an action that is forwarded to is going to return a scalar,
469 i.e. how many items are in that array, which is probably not what you want.
470 If you need to return an array then return a reference to it,
473 $c->stash->{array} = \@array;
475 and access it from the stash.
477 Keep in mind that the C<end> method used is that of the caller action. So a C<$c-E<gt>detach> inside a forwarded action would run the C<end> method from the original action requested.
481 sub forward { my $c = shift; no warnings 'recursion'; $c->dispatcher->forward( $c, @_ ) }
483 =head2 $c->detach( $action [, \@arguments ] )
485 =head2 $c->detach( $class, $method, [, \@arguments ] )
489 The same as L<< forward|/"$c->forward( $action [, \@arguments ] )" >>, but
490 doesn't return to the previous action when processing is finished.
492 When called with no arguments it escapes the processing chain entirely.
496 sub detach { my $c = shift; $c->dispatcher->detach( $c, @_ ) }
498 =head2 $c->visit( $action [, \@arguments ] )
500 =head2 $c->visit( $action [, \@captures, \@arguments ] )
502 =head2 $c->visit( $class, $method, [, \@arguments ] )
504 =head2 $c->visit( $class, $method, [, \@captures, \@arguments ] )
506 Almost the same as L<< forward|/"$c->forward( $action [, \@arguments ] )" >>,
507 but does a full dispatch, instead of just calling the new C<$action> /
508 C<< $class->$method >>. This means that C<begin>, C<auto> and the method
509 you go to are called, just like a new request.
511 In addition both C<< $c->action >> and C<< $c->namespace >> are localized.
512 This means, for example, that C<< $c->action >> methods such as
513 L<name|Catalyst::Action/name>, L<class|Catalyst::Action/class> and
514 L<reverse|Catalyst::Action/reverse> return information for the visited action
515 when they are invoked within the visited action. This is different from the
516 behavior of L<< forward|/"$c->forward( $action [, \@arguments ] )" >>, which
517 continues to use the $c->action object from the caller action even when
518 invoked from the called action.
520 C<< $c->stash >> is kept unchanged.
522 In effect, L<< visit|/"$c->visit( $action [, \@captures, \@arguments ] )" >>
523 allows you to "wrap" another action, just as it would have been called by
524 dispatching from a URL, while the analogous
525 L<< go|/"$c->go( $action [, \@captures, \@arguments ] )" >> allows you to
526 transfer control to another action as if it had been reached directly from a URL.
530 sub visit { my $c = shift; $c->dispatcher->visit( $c, @_ ) }
532 =head2 $c->go( $action [, \@arguments ] )
534 =head2 $c->go( $action [, \@captures, \@arguments ] )
536 =head2 $c->go( $class, $method, [, \@arguments ] )
538 =head2 $c->go( $class, $method, [, \@captures, \@arguments ] )
540 The relationship between C<go> and
541 L<< visit|/"$c->visit( $action [, \@captures, \@arguments ] )" >> is the same as
542 the relationship between
543 L<< forward|/"$c->forward( $class, $method, [, \@arguments ] )" >> and
544 L<< detach|/"$c->detach( $action [, \@arguments ] )" >>. Like C<< $c->visit >>,
545 C<< $c->go >> will perform a full dispatch on the specified action or method,
546 with localized C<< $c->action >> and C<< $c->namespace >>. Like C<detach>,
547 C<go> escapes the processing of the current request chain on completion, and
548 does not return to its caller.
550 @arguments are arguments to the final destination of $action. @captures are
551 arguments to the intermediate steps, if any, on the way to the final sub of
556 sub go { my $c = shift; $c->dispatcher->go( $c, @_ ) }
562 Returns the current L<Catalyst::Response> object, see there for details.
566 Returns a hashref to the stash, which may be used to store data and pass
567 it between components during a request. You can also set hash keys by
568 passing arguments. The stash is automatically sent to the view. The
569 stash is cleared at the end of a request; it cannot be used for
570 persistent storage (for this you must use a session; see
571 L<Catalyst::Plugin::Session> for a complete system integrated with
574 $c->stash->{foo} = $bar;
575 $c->stash( { moose => 'majestic', qux => 0 } );
576 $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
578 # stash is automatically passed to the view for use in a template
579 $c->forward( 'MyApp::View::TT' );
581 The stash hash is currently stored in the PSGI C<$env> and is managed by
582 L<Catalyst::Middleware::Stash>. Since it's part of the C<$env> items in
583 the stash can be accessed in sub applications mounted under your main
584 L<Catalyst> application. For example if you delegate the response of an
585 action to another L<Catalyst> application, that sub application will have
586 access to all the stash keys of the main one, and if can of course add
587 more keys of its own. However those new keys will not 'bubble' back up
588 to the main application.
590 For more information the best thing to do is to review the test case:
591 t/middleware-stash.t in the distribution /t directory.
597 $c->log->error("You are requesting the stash but you don't have a context") unless blessed $c;
598 return Catalyst::Middleware::Stash::get_stash($c->req->env)->(@_);
603 =head2 $c->error($error, ...)
605 =head2 $c->error($arrayref)
607 Returns an arrayref containing error messages. If Catalyst encounters an
608 error while processing a request, it stores the error in $c->error. This
609 method should only be used to store fatal error messages.
611 my @error = @{ $c->error };
615 $c->error('Something bad happened');
617 Calling this will always return an arrayref (if there are no errors it
618 will be an empty arrayref.
625 my $error = ref $_[0] eq 'ARRAY' ? $_[0] : [@_];
626 croak @$error unless ref $c;
627 push @{ $c->{error} }, @$error;
629 elsif ( defined $_[0] ) { $c->{error} = undef }
630 return $c->{error} || [];
635 Contains the return value of the last executed action.
636 Note that << $c->state >> operates in a scalar context which means that all
637 values it returns are scalar.
639 Please note that if an action throws an exception, the value of state
640 should no longer be considered the return if the last action. It is generally
641 going to be 0, which indicates an error state. Examine $c->error for error
644 =head2 $c->clear_errors
646 Clear errors. You probably don't want to clear the errors unless you are
647 implementing a custom error screen.
649 This is equivalent to running
660 =head2 $c->has_errors
662 Returns true if you have errors
666 sub has_errors { scalar(@{shift->error}) ? 1:0 }
668 =head2 $c->last_error
670 Returns the most recent error in the stack (the one most recently added...)
671 or nothing if there are no errors. This does not modify the contents of the
677 my (@errs) = @{shift->error};
678 return scalar(@errs) ? $errs[-1]: undef;
683 shifts the most recently added error off the error stack and returns it. Returns
684 nothing if there are no more errors.
690 my @errors = @{$self->error};
691 my $err = shift(@errors);
692 $self->{error} = \@errors;
698 pops the most recently added error off the error stack and returns it. Returns
699 nothing if there are no more errors.
705 my @errors = @{$self->error};
706 my $err = pop(@errors);
707 $self->{error} = \@errors;
711 sub _comp_search_prefixes {
713 return map $c->components->{ $_ }, $c->_comp_names_search_prefixes(@_);
716 # search components given a name and some prefixes
717 sub _comp_names_search_prefixes {
718 my ( $c, $name, @prefixes ) = @_;
719 my $appclass = ref $c || $c;
720 my $filter = "^${appclass}::(" . join( '|', @prefixes ) . ')::';
721 $filter = qr/$filter/; # Compile regex now rather than once per loop
723 # map the original component name to the sub part that we will search against
724 my %eligible = map { my $n = $_; $n =~ s{^$appclass\::[^:]+::}{}; $_ => $n; }
725 grep { /$filter/ } keys %{ $c->components };
727 # undef for a name will return all
728 return keys %eligible if !defined $name;
730 my $query = $name->$_isa('Regexp') ? $name : qr/^$name$/i;
731 my @result = grep { $eligible{$_} =~ m{$query} } keys %eligible;
733 return @result if @result;
735 # if we were given a regexp to search against, we're done.
736 return if $name->$_isa('Regexp');
738 # skip regexp fallback if configured
740 if $appclass->config->{disable_component_resolution_regex_fallback};
744 @result = grep { $eligible{ $_ } =~ m{$query} } keys %eligible;
746 # no results? try against full names
748 @result = grep { m{$query} } keys %eligible;
751 # don't warn if we didn't find any results, it just might not exist
753 # Disgusting hack to work out correct method name
754 my $warn_for = lc $prefixes[0];
755 my $msg = "Used regexp fallback for \$c->${warn_for}('${name}'), which found '" .
756 (join '", "', @result) . "'. Relying on regexp fallback behavior for " .
757 "component resolution is unreliable and unsafe.";
758 my $short = $result[0];
759 # remove the component namespace prefix
760 $short =~ s/.*?(Model|Controller|View):://;
761 my $shortmess = Carp::shortmess('');
762 if ($shortmess =~ m#Catalyst/Plugin#) {
763 $msg .= " You probably need to set '$short' instead of '${name}' in this " .
765 } elsif ($shortmess =~ m#Catalyst/lib/(View|Controller)#) {
766 $msg .= " You probably need to set '$short' instead of '${name}' in this " .
767 "component's config";
769 $msg .= " You probably meant \$c->${warn_for}('$short') instead of \$c->${warn_for}('${name}'), " .
770 "but if you really wanted to search, pass in a regexp as the argument " .
771 "like so: \$c->${warn_for}(qr/${name}/)";
773 $c->log->warn( "${msg}$shortmess" );
779 # Find possible names for a prefix
781 my ( $c, @prefixes ) = @_;
782 my $appclass = ref $c || $c;
784 my $filter = "^${appclass}::(" . join( '|', @prefixes ) . ')::';
786 my @names = map { s{$filter}{}; $_; }
787 $c->_comp_names_search_prefixes( undef, @prefixes );
792 # Filter a component before returning by calling ACCEPT_CONTEXT if available
794 sub _filter_component {
795 my ( $c, $comp, @args ) = @_;
797 if(ref $comp eq 'CODE') {
801 if ( eval { $comp->can('ACCEPT_CONTEXT'); } ) {
802 return $comp->ACCEPT_CONTEXT( $c, @args );
805 $c->log->warn("You called component '${\$comp->catalyst_component_name}' with arguments [@args], but this component does not ACCEPT_CONTEXT, so args are ignored.") if scalar(@args) && $c->debug;
810 =head2 COMPONENT ACCESSORS
812 =head2 $c->controller($name)
814 Gets a L<Catalyst::Controller> instance by name.
816 $c->controller('Foo')->do_stuff;
818 If the name is omitted, will return the controller for the dispatched
821 If you want to search for controllers, pass in a regexp as the argument.
823 # find all controllers that start with Foo
824 my @foo_controllers = $c->controller(qr{^Foo});
830 my ( $c, $name, @args ) = @_;
832 my $appclass = ref($c) || $c;
834 unless ( $name->$_isa('Regexp') ) { # Direct component hash lookup to avoid costly regexps
835 my $comps = $c->components;
836 my $check = $appclass."::Controller::".$name;
837 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
838 foreach my $path (@{$appclass->config->{ setup_components }->{ search_extra }}) {
839 next unless $path =~ /.*::Controller/;
840 $check = $path."::".$name;
841 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
844 my @result = $c->_comp_search_prefixes( $name, qw/Controller C/ );
845 return map { $c->_filter_component( $_, @args ) } @result if ref $name;
846 return $c->_filter_component( $result[ 0 ], @args );
849 return $c->component( $c->action->class );
852 =head2 $c->model($name)
854 Gets a L<Catalyst::Model> instance by name.
856 $c->model('Foo')->do_stuff;
858 Any extra arguments are directly passed to ACCEPT_CONTEXT, if the model
859 defines ACCEPT_CONTEXT. If it does not, the args are discarded.
861 If the name is omitted, it will look for
862 - a model object in $c->stash->{current_model_instance}, then
863 - a model name in $c->stash->{current_model}, then
864 - a config setting 'default_model', or
865 - check if there is only one model, and return it if that's the case.
867 If you want to search for models, pass in a regexp as the argument.
869 # find all models that start with Foo
870 my @foo_models = $c->model(qr{^Foo});
875 my ( $c, $name, @args ) = @_;
876 my $appclass = ref($c) || $c;
878 unless ( $name->$_isa('Regexp') ) { # Direct component hash lookup to avoid costly regexps
879 my $comps = $c->components;
880 my $check = $appclass."::Model::".$name;
881 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
882 foreach my $path (@{$appclass->config->{ setup_components }->{ search_extra }}) {
883 next unless $path =~ /.*::Model/;
884 $check = $path."::".$name;
885 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
888 my @result = $c->_comp_search_prefixes( $name, qw/Model M/ );
889 return map { $c->_filter_component( $_, @args ) } @result if ref $name;
890 return $c->_filter_component( $result[ 0 ], @args );
894 return $c->stash->{current_model_instance}
895 if $c->stash->{current_model_instance};
896 return $c->model( $c->stash->{current_model} )
897 if $c->stash->{current_model};
899 return $c->model( $appclass->config->{default_model} )
900 if $appclass->config->{default_model};
902 my( $comp, $rest ) = $c->_comp_search_prefixes( undef, qw/Model M/);
905 $c->log->warn( Carp::shortmess('Calling $c->model() will return a random model unless you specify one of:') );
906 $c->log->warn( '* $c->config(default_model => "the name of the default model to use")' );
907 $c->log->warn( '* $c->stash->{current_model} # the name of the model to use for this request' );
908 $c->log->warn( '* $c->stash->{current_model_instance} # the instance of the model to use for this request' );
909 $c->log->warn( 'NB: in version 5.81, the "random" behavior will not work at all.' );
912 return $c->_filter_component( $comp );
916 =head2 $c->view($name)
918 Gets a L<Catalyst::View> instance by name.
920 $c->view('Foo')->do_stuff;
922 Any extra arguments are directly passed to ACCEPT_CONTEXT.
924 If the name is omitted, it will look for
925 - a view object in $c->stash->{current_view_instance}, then
926 - a view name in $c->stash->{current_view}, then
927 - a config setting 'default_view', or
928 - check if there is only one view, and return it if that's the case.
930 If you want to search for views, pass in a regexp as the argument.
932 # find all views that start with Foo
933 my @foo_views = $c->view(qr{^Foo});
938 my ( $c, $name, @args ) = @_;
940 my $appclass = ref($c) || $c;
942 unless ( $name->$_isa('Regexp') ) { # Direct component hash lookup to avoid costly regexps
943 my $comps = $c->components;
944 my $check = $appclass."::View::".$name;
945 if( exists $comps->{$check} ) {
946 return $c->_filter_component( $comps->{$check}, @args );
949 $c->log->warn( "Attempted to use view '$check', but does not exist" );
951 foreach my $path (@{$appclass->config->{ setup_components }->{ search_extra }}) {
952 next unless $path =~ /.*::View/;
953 $check = $path."::".$name;
954 return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
957 my @result = $c->_comp_search_prefixes( $name, qw/View V/ );
958 return map { $c->_filter_component( $_, @args ) } @result if ref $name;
959 return $c->_filter_component( $result[ 0 ], @args );
963 return $c->stash->{current_view_instance}
964 if $c->stash->{current_view_instance};
965 return $c->view( $c->stash->{current_view} )
966 if $c->stash->{current_view};
968 return $c->view( $appclass->config->{default_view} )
969 if $appclass->config->{default_view};
971 my( $comp, $rest ) = $c->_comp_search_prefixes( undef, qw/View V/);
974 $c->log->warn( 'Calling $c->view() will return a random view unless you specify one of:' );
975 $c->log->warn( '* $c->config(default_view => "the name of the default view to use")' );
976 $c->log->warn( '* $c->stash->{current_view} # the name of the view to use for this request' );
977 $c->log->warn( '* $c->stash->{current_view_instance} # the instance of the view to use for this request' );
978 $c->log->warn( 'NB: in version 5.81, the "random" behavior will not work at all.' );
981 return $c->_filter_component( $comp );
984 =head2 $c->controllers
986 Returns the available names which can be passed to $c->controller
992 return $c->_comp_names(qw/Controller C/);
997 Returns the available names which can be passed to $c->model
1003 return $c->_comp_names(qw/Model M/);
1009 Returns the available names which can be passed to $c->view
1015 return $c->_comp_names(qw/View V/);
1018 =head2 $c->comp($name)
1020 =head2 $c->component($name)
1022 Gets a component object by name. This method is not recommended,
1023 unless you want to get a specific component by full
1024 class. C<< $c->controller >>, C<< $c->model >>, and C<< $c->view >>
1025 should be used instead.
1027 If C<$name> is a regexp, a list of components matched against the full
1028 component name will be returned.
1030 If Catalyst can't find a component by name, it will fallback to regex
1031 matching by default. To disable this behaviour set
1032 disable_component_resolution_regex_fallback to a true value.
1034 __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );
1039 my ( $c, $name, @args ) = @_;
1042 my $comps = $c->components;
1045 # is it the exact name?
1046 return $c->_filter_component( $comps->{ $name }, @args )
1047 if exists $comps->{ $name };
1049 # perhaps we just omitted "MyApp"?
1050 my $composed = ( ref $c || $c ) . "::${name}";
1051 return $c->_filter_component( $comps->{ $composed }, @args )
1052 if exists $comps->{ $composed };
1054 # search all of the models, views and controllers
1055 my( $comp ) = $c->_comp_search_prefixes( $name, qw/Model M Controller C View V/ );
1056 return $c->_filter_component( $comp, @args ) if $comp;
1060 if $c->config->{disable_component_resolution_regex_fallback};
1062 # This is here so $c->comp( '::M::' ) works
1063 my $query = ref $name ? $name : qr{$name}i;
1065 my @result = grep { m{$query} } keys %{ $c->components };
1066 return map { $c->_filter_component( $_, @args ) } @result if ref $name;
1068 if( $result[ 0 ] ) {
1069 $c->log->warn( Carp::shortmess(qq(Found results for "${name}" using regexp fallback)) );
1070 $c->log->warn( 'Relying on the regexp fallback behavior for component resolution' );
1071 $c->log->warn( 'is unreliable and unsafe. You have been warned' );
1072 return $c->_filter_component( $result[ 0 ], @args );
1075 # I would expect to return an empty list here, but that breaks back-compat
1079 return sort keys %{ $c->components };
1082 =head2 CLASS DATA AND HELPER CLASSES
1086 Returns or takes a hashref containing the application's configuration.
1088 __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
1090 You can also use a C<YAML>, C<XML> or L<Config::General> config file
1091 like C<myapp.conf> in your applications home directory. See
1092 L<Catalyst::Plugin::ConfigLoader>.
1094 =head3 Cascading configuration
1096 The config method is present on all Catalyst components, and configuration
1097 will be merged when an application is started. Configuration loaded with
1098 L<Catalyst::Plugin::ConfigLoader> takes precedence over other configuration,
1099 followed by configuration in your top level C<MyApp> class. These two
1100 configurations are merged, and then configuration data whose hash key matches a
1101 component name is merged with configuration for that component.
1103 The configuration for a component is then passed to the C<new> method when a
1104 component is constructed.
1108 MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
1109 MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });
1111 will mean that C<MyApp::Model::Foo> receives the following data when
1114 MyApp::Model::Foo->new({
1120 It's common practice to use a Moose attribute
1121 on the receiving component to access the config value.
1123 package MyApp::Model::Foo;
1127 # this attr will receive 'baz' at construction time
1133 You can then get the value 'baz' by calling $c->model('Foo')->bar
1134 (or $self->bar inside code in the model).
1136 B<NOTE:> you MUST NOT call C<< $self->config >> or C<< __PACKAGE__->config >>
1137 as a way of reading config within your code, as this B<will not> give you the
1138 correctly merged config back. You B<MUST> take the config values supplied to
1139 the constructor and use those instead.
1143 around config => sub {
1147 croak('Setting config after setup has been run is not allowed.')
1148 if ( @_ and $c->setup_finished );
1155 Returns the logging object instance. Unless it is already set, Catalyst
1156 sets this up with a L<Catalyst::Log> object. To use your own log class,
1157 set the logger with the C<< __PACKAGE__->log >> method prior to calling
1158 C<< __PACKAGE__->setup >>.
1160 __PACKAGE__->log( MyLogger->new );
1165 $c->log->info( 'Now logging with my own logger!' );
1167 Your log class should implement the methods described in
1172 Returned True if there's a valid encoding
1174 =head2 clear_encoding
1176 Clears the encoding for the current context
1180 Sets or gets the application encoding. Setting encoding takes either an
1181 Encoding object or a string that we try to resolve via L<Encode::find_encoding>.
1183 You would expect to get the encoding object back if you attempt to set it. If
1184 there is a failure you will get undef returned and an error message in the log.
1188 sub has_encoding { shift->encoding ? 1:0 }
1190 sub clear_encoding {
1193 $c->encoding(undef);
1195 $c->log->error("You can't clear encoding on the application");
1205 # Don't let one change this once we are too far into the response
1206 if(blessed $c && $c->res->finalized_headers) {
1207 Carp::croak("You may not change the encoding once the headers are finalized");
1211 # Let it be set to undef
1212 if (my $wanted = shift) {
1213 $encoding = Encode::find_encoding($wanted)
1214 or Carp::croak( qq/Unknown encoding '$wanted'/ );
1215 binmode(STDERR, ':encoding(' . $encoding->name . ')');
1222 ? $c->{encoding} = $encoding
1223 : $c->_encoding($encoding);
1225 $encoding = ref $c && exists $c->{encoding}
1235 Returns 1 if debug mode is enabled, 0 otherwise.
1237 You can enable debug mode in several ways:
1241 =item By calling myapp_server.pl with the -d flag
1243 =item With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG
1245 =item The -Debug option in your MyApp.pm
1247 =item By declaring C<sub debug { 1 }> in your MyApp.pm.
1251 The first three also set the log level to 'debug'.
1253 Calling C<< $c->debug(1) >> has no effect.
1259 =head2 $c->dispatcher
1261 Returns the dispatcher instance. See L<Catalyst::Dispatcher>.
1265 Returns the engine instance. See L<Catalyst::Engine>.
1268 =head2 UTILITY METHODS
1270 =head2 $c->path_to(@path)
1272 Merges C<@path> with C<< $c->config->{home} >> and returns a
1273 L<Path::Class::Dir> object. Note you can usually use this object as
1274 a filename, but sometimes you will have to explicitly stringify it
1275 yourself by calling the C<< ->stringify >> method.
1279 $c->path_to( 'db', 'sqlite.db' );
1284 my ( $c, @path ) = @_;
1285 my $path = Path::Class::Dir->new( $c->config->{home}, @path );
1286 if ( -d $path ) { return $path }
1287 else { return Path::Class::File->new( $c->config->{home}, @path ) }
1291 my ( $class, $name, $plugin, @args ) = @_;
1293 # See block comment in t/unit_core_plugin.t
1294 $class->log->warn(qq/Adding plugin using the ->plugin method is deprecated, and will be removed in a future release/);
1296 $class->_register_plugin( $plugin, 1 );
1298 eval { $plugin->import };
1299 $class->mk_classdata($name);
1301 eval { $obj = $plugin->new(@args) };
1304 Catalyst::Exception->throw( message =>
1305 qq/Couldn't instantiate instant plugin "$plugin", "$@"/ );
1308 $class->$name($obj);
1309 $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
1315 Initializes the dispatcher and engine, loads any plugins, and loads the
1316 model, view, and controller components. You may also specify an array
1317 of plugins to load here, if you choose to not load them in the C<use
1321 MyApp->setup( qw/-Debug/ );
1323 B<Note:> You B<should not> wrap this method with method modifiers
1324 or bad things will happen - wrap the C<setup_finalize> method instead.
1326 B<Note:> You can create a custom setup stage that will execute when the
1327 application is starting. Use this to customize setup.
1329 MyApp->setup(-Custom=value);
1332 my ($class, $value) = @_;
1335 Can be handy if you want to hook into the setup phase.
1340 my ( $class, @arguments ) = @_;
1341 croak('Running setup more than once')
1342 if ( $class->setup_finished );
1344 unless ( $class->isa('Catalyst') ) {
1346 Catalyst::Exception->throw(
1347 message => qq/'$class' does not inherit from Catalyst/ );
1350 if ( $class->arguments ) {
1351 @arguments = ( @arguments, @{ $class->arguments } );
1357 foreach (@arguments) {
1361 ( $flags->{log} ) ? 'debug,' . $flags->{log} : 'debug';
1363 elsif (/^-(\w+)=?(.*)$/) {
1364 $flags->{ lc $1 } = $2;
1367 push @{ $flags->{plugins} }, $_;
1371 $class->setup_home( delete $flags->{home} );
1373 $class->setup_log( delete $flags->{log} );
1374 $class->setup_plugins( delete $flags->{plugins} );
1376 $class->setup_data_handlers();
1377 $class->setup_dispatcher( delete $flags->{dispatcher} );
1378 if (my $engine = delete $flags->{engine}) {
1379 $class->log->warn("Specifying the engine in ->setup is no longer supported, see Catalyst::Upgrading");
1381 $class->setup_engine();
1382 $class->setup_stats( delete $flags->{stats} );
1384 for my $flag ( sort keys %{$flags} ) {
1386 if ( my $code = $class->can( 'setup_' . $flag ) ) {
1387 &$code( $class, delete $flags->{$flag} );
1390 $class->log->warn(qq/Unknown flag "$flag"/);
1394 eval { require Catalyst::Devel; };
1395 if( !$@ && $ENV{CATALYST_SCRIPT_GEN} && ( $ENV{CATALYST_SCRIPT_GEN} < $Catalyst::Devel::CATALYST_SCRIPT_GEN ) ) {
1396 $class->log->warn(<<"EOF");
1397 You are running an old script!
1399 Please update by running (this will overwrite existing files):
1400 catalyst.pl -force -scripts $class
1402 or (this will not overwrite existing files):
1403 catalyst.pl -scripts $class
1408 # Call plugins setup, this is stupid and evil.
1409 # Also screws C3 badly on 5.10, hack to avoid.
1411 no warnings qw/redefine/;
1412 local *setup = sub { };
1413 $class->setup unless $Catalyst::__AM_RESTARTING;
1416 # If you are expecting configuration info as part of your setup, it needs
1417 # to get called here and below, since we need the above line to support
1418 # ConfigLoader based configs.
1420 $class->setup_encoding();
1421 $class->setup_middleware();
1423 # Initialize our data structure
1424 $class->components( {} );
1426 $class->setup_components;
1428 if ( $class->debug ) {
1429 my @plugins = map { "$_ " . ( $_->VERSION || '' ) } $class->registered_plugins;
1432 my $column_width = Catalyst::Utils::term_width() - 6;
1433 my $t = Text::SimpleTable->new($column_width);
1434 $t->row($_) for @plugins;
1435 $class->log->debug( "Loaded plugins:\n" . $t->draw . "\n" );
1438 my @middleware = map {
1441 (ref($_) .' '. ($_->can('VERSION') ? $_->VERSION || '' : '')
1442 || '') } $class->registered_middlewares;
1445 my $column_width = Catalyst::Utils::term_width() - 6;
1446 my $t = Text::SimpleTable->new($column_width);
1447 $t->row($_) for @middleware;
1448 $class->log->debug( "Loaded PSGI Middleware:\n" . $t->draw . "\n" );
1451 my %dh = $class->registered_data_handlers;
1452 if (my @data_handlers = keys %dh) {
1453 my $column_width = Catalyst::Utils::term_width() - 6;
1454 my $t = Text::SimpleTable->new($column_width);
1455 $t->row($_) for @data_handlers;
1456 $class->log->debug( "Loaded Request Data Handlers:\n" . $t->draw . "\n" );
1459 my $dispatcher = $class->dispatcher;
1460 my $engine = $class->engine;
1461 my $home = $class->config->{home};
1463 $class->log->debug(sprintf(q/Loaded dispatcher "%s"/, blessed($dispatcher)));
1464 $class->log->debug(sprintf(q/Loaded engine "%s"/, blessed($engine)));
1468 ? $class->log->debug(qq/Found home "$home"/)
1469 : $class->log->debug(qq/Home "$home" doesn't exist/)
1470 : $class->log->debug(q/Couldn't find home/);
1472 my $column_width = Catalyst::Utils::term_width() - 8 - 9;
1474 my $t = Text::SimpleTable->new( [ $column_width, 'Class' ], [ 8, 'Type' ] );
1475 for my $comp ( sort keys %{ $class->components } ) {
1476 my $type = ref $class->components->{$comp} ? 'instance' : 'class';
1477 $t->row( $comp, $type );
1479 $class->log->debug( "Loaded components:\n" . $t->draw . "\n" )
1480 if ( keys %{ $class->components } );
1483 # Add our self to components, since we are also a component
1484 if( $class->isa('Catalyst::Controller') ){
1485 $class->components->{$class} = $class;
1488 $class->setup_actions;
1490 if ( $class->debug ) {
1491 my $name = $class->config->{name} || 'Application';
1492 $class->log->info("$name powered by Catalyst $Catalyst::VERSION");
1495 if ($class->config->{case_sensitive}) {
1496 $class->log->warn($class . "->config->{case_sensitive} is set.");
1497 $class->log->warn("This setting is deprecated and planned to be removed in Catalyst 5.81.");
1500 # call these so we pre setup the composed classes
1501 $class->composed_request_class;
1502 $class->composed_response_class;
1503 $class->composed_stats_class;
1505 $class->setup_finalize;
1507 # Flush the log for good measure (in case something turned off 'autoflush' early)
1508 $class->log->_flush() if $class->log->can('_flush');
1510 return $class || 1; # Just in case someone named their Application 0...
1513 =head2 $app->setup_finalize
1515 A hook to attach modifiers to. This method does not do anything except set the
1516 C<setup_finished> accessor.
1518 Applying method modifiers to the C<setup> method doesn't work, because of quirky things done for plugin setup.
1522 after setup_finalize => sub {
1530 sub setup_finalize {
1532 $class->setup_finished(1);
1535 =head2 $c->uri_for( $path?, @args?, \%query_values?, \$fragment? )
1537 =head2 $c->uri_for( $action, \@captures?, @args?, \%query_values?, \$fragment? )
1539 =head2 $c->uri_for( $action, [@captures, @args], \%query_values?, \$fragment? )
1541 Constructs an absolute L<URI> object based on the application root, the
1542 provided path, and the additional arguments and query parameters provided.
1543 When used as a string, provides a textual URI. If you need more flexibility
1544 than this (i.e. the option to provide relative URIs etc.) see
1545 L<Catalyst::Plugin::SmartURI>.
1547 If no arguments are provided, the URI for the current action is returned.
1548 To return the current action and also provide @args, use
1549 C<< $c->uri_for( $c->action, @args ) >>.
1551 If the first argument is a string, it is taken as a public URI path relative
1552 to C<< $c->namespace >> (if it doesn't begin with a forward slash) or
1553 relative to the application root (if it does). It is then merged with
1554 C<< $c->request->base >>; any C<@args> are appended as additional path
1555 components; and any C<%query_values> are appended as C<?foo=bar> parameters.
1557 B<NOTE> If you are using this 'stringy' first argument, we skip encoding and
1558 allow you to declare something like:
1560 $c->uri_for('/foo/bar#baz')
1562 Where 'baz' is a URI fragment. We consider this first argument string to be
1563 'expert' mode where you are expected to create a valid URL and we for the most
1564 part just pass it through without a lot of internal effort to escape and encode.
1566 If the first argument is a L<Catalyst::Action> it represents an action which
1567 will have its path resolved using C<< $c->dispatcher->uri_for_action >>. The
1568 optional C<\@captures> argument (an arrayref) allows passing the captured
1569 variables that are needed to fill in the paths of Chained and Regex actions;
1570 once the path is resolved, C<uri_for> continues as though a path was
1571 provided, appending any arguments or parameters and creating an absolute
1574 The captures for the current request can be found in
1575 C<< $c->request->captures >>, and actions can be resolved using
1576 C<< Catalyst::Controller->action_for($name) >>. If you have a private action
1577 path, use C<< $c->uri_for_action >> instead.
1579 # Equivalent to $c->req->uri
1580 $c->uri_for($c->action, $c->req->captures,
1581 @{ $c->req->args }, $c->req->params);
1583 # For the Foo action in the Bar controller
1584 $c->uri_for($c->controller('Bar')->action_for('Foo'));
1586 # Path to a static resource
1587 $c->uri_for('/static/images/logo.png');
1589 In general the scheme of the generated URI object will follow the incoming request
1590 however if your targeted action or action chain has the Scheme attribute it will
1593 Also, if the targeted Action or Action chain declares Args/CaptureArgs that have
1594 type constraints, we will require that your proposed URL verify on those declared
1600 my ( $c, $path, @args ) = @_;
1602 if ( $path->$_isa('Catalyst::Controller') ) {
1603 $path = $path->path_prefix;
1608 my $fragment = ((scalar(@args) && ref($args[-1]) eq 'SCALAR') ? pop @args : undef );
1610 unless(blessed $path) {
1611 if (defined($path) and $path =~ s/#(.+)$//) {
1612 if(defined($1) and $fragment) {
1613 carp "Abiguious fragment declaration: You cannot define a fragment in '$path' and as an argument '$fragment'";
1622 ( scalar @args && ref $args[$#args] eq 'HASH' ? pop @args : {} );
1624 undef($path) if (defined $path && $path eq '');
1626 carp "uri_for called with undef argument" if grep { ! defined $_ } @args;
1628 my $target_action = $path->$_isa('Catalyst::Action') ? $path : undef;
1629 if ( $path->$_isa('Catalyst::Action') ) { # action object
1630 s|/|%2F|g for @args;
1631 my $captures = [ map { s|/|%2F|g; $_; }
1632 ( scalar @args && ref $args[0] eq 'ARRAY'
1637 my $expanded_action = $c->dispatcher->expand_action( $action );
1638 my $num_captures = $expanded_action->number_of_captures;
1640 # ->uri_for( $action, \@captures_and_args, \%query_values? )
1641 if( !@args && $action->number_of_args ) {
1642 unshift @args, splice @$captures, $num_captures;
1646 unless($expanded_action->match_captures_constraints($c, $captures)) {
1647 carp "captures [@{$captures}] do not match the type constraints in actionchain ending with '$expanded_action'";
1652 $path = $c->dispatcher->uri_for_action($action, $captures);
1653 if (not defined $path) {
1654 $c->log->debug(qq/Can't find uri_for action '$action' @$captures/)
1658 $path = '/' if $path eq '';
1660 # At this point @encoded_args is the remaining Args (all captures removed).
1661 if($expanded_action->has_args_constraints) {
1662 unless($expanded_action->match_args($c,\@args)) {
1663 carp "args [@args] do not match the type constraints in action '$expanded_action'";
1669 unshift(@args, $path);
1671 unless (defined $path && $path =~ s!^/!!) { # in-place strip
1672 my $namespace = $c->namespace;
1673 if (defined $path) { # cheesy hack to handle path '../foo'
1674 $namespace =~ s{(?:^|/)[^/]+$}{} while $args[0] =~ s{^\.\./}{};
1676 unshift(@args, $namespace || '');
1679 # join args with '/', or a blank string
1680 my $args = join('/', grep { defined($_) } @args);
1681 $args =~ s/\?/%3F/g; # STUPID STUPID SPECIAL CASE
1684 my ($base, $class) = ('/', 'URI::_generic');
1686 $base = $c->req->base;
1687 if($target_action) {
1688 $target_action = $c->dispatcher->expand_action($target_action);
1689 if(my $s = $target_action->scheme) {
1694 $class = ref($base);
1697 $class = ref($base);
1700 $base =~ s{(?<!/)$}{/};
1704 if (my @keys = keys %$params) {
1705 # somewhat lifted from URI::_query's query_form
1706 $query = '?'.join('&', map {
1707 my $val = $params->{$_};
1708 #s/([;\/?:@&=+,\$\[\]%])/$URI::Escape::escapes{$1}/go; ## Commented out because seems to lead to double encoding - JNAP
1711 $val = '' unless defined $val;
1714 $param = encode_utf8($param);
1715 # using the URI::Escape pattern here so utf8 chars survive
1716 $param =~ s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
1719 $key = encode_utf8($key);
1720 # using the URI::Escape pattern here so utf8 chars survive
1721 $key =~ s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
1724 "${key}=$param"; } ( ref $val eq 'ARRAY' ? @$val : $val ));
1728 $base = encode_utf8 $base;
1729 $base =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1730 $args = encode_utf8 $args;
1731 $args =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1733 if(defined $fragment) {
1735 $fragment = encode_utf8(${$fragment});
1736 $fragment =~ s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
1737 $fragment =~ s/ /+/g;
1739 $query .= "#$fragment";
1742 my $res = bless(\"${base}${args}${query}", $class);
1746 =head2 $c->uri_for_action( $path, \@captures_and_args?, @args?, \%query_values? )
1748 =head2 $c->uri_for_action( $action, \@captures_and_args?, @args?, \%query_values? )
1754 A private path to the Catalyst action you want to create a URI for.
1756 This is a shortcut for calling C<< $c->dispatcher->get_action_by_path($path)
1757 >> and passing the resulting C<$action> and the remaining arguments to C<<
1760 You can also pass in a Catalyst::Action object, in which case it is passed to
1763 Note that although the path looks like a URI that dispatches to the wanted action, it is not a URI, but an internal path to that action.
1765 For example, if the action looks like:
1767 package MyApp::Controller::Users;
1769 sub lst : Path('the-list') {}
1773 $c->uri_for_action('/users/lst')
1775 and it will create the URI /users/the-list.
1777 =item \@captures_and_args?
1779 Optional array reference of Captures (i.e. C<<CaptureArgs or $c->req->captures>)
1780 and arguments to the request. Usually used with L<Catalyst::DispatchType::Chained>
1781 to interpolate all the parameters in the URI.
1785 Optional list of extra arguments - can be supplied in the
1786 C<< \@captures_and_args? >> array ref, or here - whichever is easier for your
1789 Your action can have zero, a fixed or a variable number of args (e.g.
1790 C<< Args(1) >> for a fixed number or C<< Args() >> for a variable number)..
1792 =item \%query_values?
1794 Optional array reference of query parameters to append. E.g.
1800 /rest/of/your/uri?foo=bar
1806 sub uri_for_action {
1807 my ( $c, $path, @args ) = @_;
1808 my $action = blessed($path)
1810 : $c->dispatcher->get_action_by_path($path);
1811 unless (defined $action) {
1812 croak "Can't find action for path '$path'";
1814 return $c->uri_for( $action, @args );
1817 =head2 $c->welcome_message
1819 Returns the Catalyst welcome HTML page.
1823 sub welcome_message {
1825 my $name = $c->config->{name};
1826 my $logo = $c->uri_for('/static/images/catalyst_logo.png');
1827 my $prefix = Catalyst::Utils::appprefix( ref $c );
1828 $c->response->content_type('text/html; charset=utf-8');
1830 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1831 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1832 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
1834 <meta http-equiv="Content-Language" content="en" />
1835 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
1836 <title>$name on Catalyst $VERSION</title>
1837 <style type="text/css">
1840 background-color: #eee;
1847 margin-bottom: 10px;
1849 background-color: #ccc;
1850 border: 1px solid #aaa;
1855 font-family: verdana, tahoma, sans-serif;
1858 font-family: verdana, tahoma, sans-serif;
1861 text-decoration: none;
1863 border-bottom: 1px dotted #bbb;
1865 :link:hover, :visited:hover {
1878 background-color: #fff;
1879 border: 1px solid #aaa;
1883 font-weight: normal;
1905 <h1><span id="appname">$name</span> on <a href="http://catalyst.perl.org">Catalyst</a>
1910 <img src="$logo" alt="Catalyst Logo" />
1912 <p>Welcome to the world of Catalyst.
1913 This <a href="http://en.wikipedia.org/wiki/MVC">MVC</a>
1914 framework will make web development something you had
1915 never expected it to be: Fun, rewarding, and quick.</p>
1916 <h2>What to do now?</h2>
1917 <p>That really depends on what <b>you</b> want to do.
1918 We do, however, provide you with a few starting points.</p>
1919 <p>If you want to jump right into web development with Catalyst
1920 you might want to start with a tutorial.</p>
1921 <pre>perldoc <a href="https://metacpan.org/module/Catalyst::Manual::Tutorial">Catalyst::Manual::Tutorial</a></code>
1923 <p>Afterwards you can go on to check out a more complete look at our features.</p>
1925 <code>perldoc <a href="https://metacpan.org/module/Catalyst::Manual::Intro">Catalyst::Manual::Intro</a>
1926 <!-- Something else should go here, but the Catalyst::Manual link seems unhelpful -->
1928 <h2>What to do next?</h2>
1929 <p>Next it's time to write an actual application. Use the
1930 helper scripts to generate <a href="https://metacpan.org/search?q=Catalyst%3A%3AController">controllers</a>,
1931 <a href="https://metacpan.org/search?q=Catalyst%3A%3AModel">models</a>, and
1932 <a href="https://metacpan.org/search?q=Catalyst%3A%3AView">views</a>;
1933 they can save you a lot of work.</p>
1934 <pre><code>script/${prefix}_create.pl --help</code></pre>
1935 <p>Also, be sure to check out the vast and growing
1936 collection of <a href="http://search.cpan.org/search?query=Catalyst">plugins for Catalyst on CPAN</a>;
1937 you are likely to find what you need there.
1941 <p>Catalyst has a very active community. Here are the main places to
1942 get in touch with us.</p>
1945 <a href="http://dev.catalyst.perl.org">Wiki</a>
1948 <a href="http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst">Mailing-List</a>
1951 <a href="irc://irc.perl.org/catalyst">IRC channel #catalyst on irc.perl.org</a>
1954 <h2>In conclusion</h2>
1955 <p>The Catalyst team hopes you will enjoy using Catalyst as much
1956 as we enjoyed making it. Please contact us if you have ideas
1957 for improvement or other feedback.</p>
1967 Contains a hash of options passed from the application script, including
1968 the original ARGV the script received, the processed values from that
1969 ARGV and any extra arguments to the script which were not processed.
1971 This can be used to add custom options to your application's scripts
1972 and setup your application differently depending on the values of these
1975 =head1 INTERNAL METHODS
1977 These methods are not meant to be used by end users.
1979 =head2 $c->components
1981 Returns a hash of components.
1983 =head2 $c->context_class
1985 Returns or sets the context class.
1989 Returns a hashref containing coderefs and execution counts (needed for
1990 deep recursion detection).
1994 Returns the number of actions on the current internal execution stack.
1998 Dispatches a request to actions.
2002 sub dispatch { my $c = shift; $c->dispatcher->dispatch( $c, @_ ) }
2004 =head2 $c->dispatcher_class
2006 Returns or sets the dispatcher class.
2008 =head2 $c->dump_these
2010 Returns a list of 2-element array references (name, structure) pairs
2011 that will be dumped on the error page in debug mode.
2017 [ Request => $c->req ],
2018 [ Response => $c->res ],
2019 [ Stash => $c->stash ],
2020 [ Config => $c->config ];
2023 =head2 $c->engine_class
2025 Returns or sets the engine class.
2027 =head2 $c->execute( $class, $coderef )
2029 Execute a coderef in given class and catch exceptions. Errors are available
2035 my ( $c, $class, $code ) = @_;
2036 $class = $c->component($class) || $class;
2039 if ( $c->depth >= $RECURSION ) {
2040 my $action = $code->reverse();
2041 $action = "/$action" unless $action =~ /->/;
2042 my $error = qq/Deep recursion detected calling "${action}"/;
2043 $c->log->error($error);
2049 my $stats_info = $c->_stats_start_execute( $code ) if $c->use_stats;
2051 push( @{ $c->stack }, $code );
2053 no warnings 'recursion';
2054 # N.B. This used to be combined, but I have seen $c get clobbered if so, and
2055 # I have no idea how, ergo $ret (which appears to fix the issue)
2056 eval { my $ret = $code->execute( $class, $c, @{ $c->req->args } ) || 0; $c->state( $ret ) };
2058 $c->_stats_finish_execute( $stats_info ) if $c->use_stats and $stats_info;
2060 my $last = pop( @{ $c->stack } );
2062 if ( my $error = $@ ) {
2063 #rethow if this can be handled by middleware
2064 if ( $c->_handle_http_exception($error) ) {
2065 foreach my $err (@{$c->error}) {
2066 $c->log->error($err);
2069 $c->log->_flush if $c->log->can('_flush');
2071 $error->can('rethrow') ? $error->rethrow : croak $error;
2073 if ( blessed($error) and $error->isa('Catalyst::Exception::Detach') ) {
2074 $error->rethrow if $c->depth > 1;
2076 elsif ( blessed($error) and $error->isa('Catalyst::Exception::Go') ) {
2077 $error->rethrow if $c->depth > 0;
2080 unless ( ref $error ) {
2081 no warnings 'uninitialized';
2083 my $class = $last->class;
2084 my $name = $last->name;
2085 $error = qq/Caught exception in $class->$name "$error"/;
2094 sub _stats_start_execute {
2095 my ( $c, $code ) = @_;
2096 my $appclass = ref($c) || $c;
2097 return if ( ( $code->name =~ /^_.*/ )
2098 && ( !$appclass->config->{show_internal_actions} ) );
2100 my $action_name = $code->reverse();
2101 $c->counter->{$action_name}++;
2103 my $action = $action_name;
2104 $action = "/$action" unless $action =~ /->/;
2106 # determine if the call was the result of a forward
2107 # this is done by walking up the call stack and looking for a calling
2108 # sub of Catalyst::forward before the eval
2110 for my $index ( 2 .. 11 ) {
2112 if ( ( caller($index) )[0] eq 'Catalyst'
2113 && ( caller($index) )[3] eq '(eval)' );
2115 if ( ( caller($index) )[3] =~ /forward$/ ) {
2116 $callsub = ( caller($index) )[3];
2117 $action = "-> $action";
2122 my $uid = $action_name . $c->counter->{$action_name};
2124 # is this a root-level call or a forwarded call?
2125 if ( $callsub =~ /forward$/ ) {
2126 my $parent = $c->stack->[-1];
2128 # forward, locate the caller
2129 if ( defined $parent && exists $c->counter->{"$parent"} ) {
2132 parent => "$parent" . $c->counter->{"$parent"},
2138 # forward with no caller may come from a plugin
2157 sub _stats_finish_execute {
2158 my ( $c, $info ) = @_;
2159 $c->stats->profile( end => $info );
2164 Finalizes the request.
2171 for my $error ( @{ $c->error } ) {
2172 $c->log->error($error);
2175 # Support skipping finalize for psgix.io style 'jailbreak'. Used to support
2176 # stuff like cometd and websockets
2178 if($c->request->_has_io_fh) {
2183 # Allow engine to handle finalize flow (for POE)
2184 my $engine = $c->engine;
2185 if ( my $code = $engine->can('finalize') ) {
2190 $c->finalize_uploads;
2193 if ( $#{ $c->error } >= 0 ) {
2197 $c->finalize_encoding;
2198 $c->finalize_headers unless $c->response->finalized_headers;
2204 if ($c->use_stats) {
2205 my $elapsed = $c->stats->elapsed;
2206 my $av = $elapsed == 0 ? '??' : sprintf '%.3f', 1 / $elapsed;
2208 "Request took ${elapsed}s ($av/s)\n" . $c->stats->report . "\n" );
2211 return $c->response->status;
2214 =head2 $c->finalize_body
2220 sub finalize_body { my $c = shift; $c->engine->finalize_body( $c, @_ ) }
2222 =head2 $c->finalize_cookies
2228 sub finalize_cookies { my $c = shift; $c->engine->finalize_cookies( $c, @_ ) }
2230 =head2 $c->finalize_error
2232 Finalizes error. If there is only one error in L</error> and it is an object that
2233 does C<as_psgi> or C<code> we rethrow the error and presume it caught by middleware
2234 up the ladder. Otherwise we return the debugging error page (in debug mode) or we
2235 return the default error page (production mode).
2239 sub finalize_error {
2241 if($#{$c->error} > 0) {
2242 $c->engine->finalize_error( $c, @_ );
2244 my ($error) = @{$c->error};
2245 if ( $c->_handle_http_exception($error) ) {
2246 # In the case where the error 'knows what it wants', becauses its PSGI
2247 # aware, just rethow and let middleware catch it
2248 $error->can('rethrow') ? $error->rethrow : croak $error;
2250 $c->engine->finalize_error( $c, @_ )
2255 =head2 $c->finalize_headers
2261 sub finalize_headers {
2264 my $response = $c->response; #accessor calls can add up?
2266 # Check if we already finalized headers
2267 return if $response->finalized_headers;
2270 if ( my $location = $response->redirect ) {
2271 $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
2272 $response->header( Location => $location );
2275 # Remove incorrectly added body and content related meta data when returning
2276 # an information response, or a response the is required to not include a body
2278 $c->finalize_cookies;
2280 # This currently is a NOOP but I don't want to remove it since I guess people
2281 # might have Response subclasses that use it for something... (JNAP)
2282 $c->response->finalize_headers();
2285 $response->finalized_headers(1);
2288 =head2 $c->finalize_encoding
2290 Make sure your body is encoded properly IF you set an encoding. By
2291 default the encoding is UTF-8 but you can disable it by explicitly setting the
2292 encoding configuration value to undef.
2294 We can only encode when the body is a scalar. Methods for encoding via the
2295 streaming interfaces (such as C<write> and C<write_fh> on L<Catalyst::Response>
2302 sub finalize_encoding {
2304 my $res = $c->res || return;
2306 # Warn if the set charset is different from the one you put into encoding. We need
2307 # to do this early since encodable_response is false for this condition and we need
2308 # to match the debug output for backcompat (there's a test for this...) -JNAP
2310 $res->content_type_charset and $c->encoding and
2311 (uc($c->encoding->mime_name) ne uc($res->content_type_charset))
2313 my $ct = lc($res->content_type_charset);
2314 $c->log->debug("Catalyst encoding config is set to encode in '" .
2315 $c->encoding->mime_name .
2316 "', content type is '$ct', not encoding ");
2320 ($res->encodable_response) and
2321 (defined($res->body)) and
2322 (ref(\$res->body) eq 'SCALAR')
2324 $c->res->body( $c->encoding->encode( $c->res->body, $c->_encode_check ) );
2326 # Set the charset if necessary. This might be a bit bonkers since encodable response
2327 # is false when the set charset is not the same as the encoding mimetype (maybe
2328 # confusing action at a distance here..
2329 # Don't try to set the charset if one already exists or if headers are already finalized
2330 $c->res->content_type($c->res->content_type . "; charset=" . $c->encoding->mime_name)
2331 unless($c->res->content_type_charset ||
2332 ($c->res->_context && $c->res->finalized_headers && !$c->res->_has_response_cb));
2336 =head2 $c->finalize_output
2338 An alias for finalize_body.
2340 =head2 $c->finalize_read
2342 Finalizes the input after reading is complete.
2346 sub finalize_read { my $c = shift; $c->engine->finalize_read( $c, @_ ) }
2348 =head2 $c->finalize_uploads
2350 Finalizes uploads. Cleans up any temporary files.
2354 sub finalize_uploads { my $c = shift; $c->engine->finalize_uploads( $c, @_ ) }
2356 =head2 $c->get_action( $action, $namespace )
2358 Gets an action in a given namespace.
2362 sub get_action { my $c = shift; $c->dispatcher->get_action(@_) }
2364 =head2 $c->get_actions( $action, $namespace )
2366 Gets all actions of a given name in a namespace and all parent
2371 sub get_actions { my $c = shift; $c->dispatcher->get_actions( $c, @_ ) }
2373 =head2 $app->handle_request( @arguments )
2375 Called to handle each HTTP request.
2379 sub handle_request {
2380 my ( $class, @arguments ) = @_;
2382 # Always expect worst case!
2385 if ($class->debug) {
2386 my $secs = time - $START || 1;
2387 my $av = sprintf '%.3f', $COUNT / $secs;
2388 my $time = localtime time;
2389 $class->log->info("*** Request $COUNT ($av/s) [$$] [$time] ***");
2392 my $c = $class->prepare(@arguments);
2394 $status = $c->finalize;
2396 #rethow if this can be handled by middleware
2397 if ( $class->_handle_http_exception($_) ) {
2398 $_->can('rethrow') ? $_->rethrow : croak $_;
2400 chomp(my $error = $_);
2401 $class->log->error(qq/Caught exception in engine "$error"/);
2406 if(my $coderef = $class->log->can('_flush')){
2407 $class->log->$coderef();
2412 =head2 $class->prepare( @arguments )
2414 Creates a Catalyst context from an engine-specific request (Apache, CGI,
2421 predicate => '_has_uploadtmp',
2425 my ( $class, @arguments ) = @_;
2428 # After the app/ctxt split, this should become an attribute based on something passed
2429 # into the application.
2430 $class->context_class( ref $class || $class ) unless $class->context_class;
2432 my $uploadtmp = $class->config->{uploadtmp};
2433 my $c = $class->context_class->new({ $uploadtmp ? (_uploadtmp => $uploadtmp) : ()});
2435 $c->response->_context($c);
2436 $c->stats($class->stats_class->new)->enable($c->use_stats);
2438 if ( $c->debug || $c->config->{enable_catalyst_header} ) {
2439 $c->res->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
2443 # Allow engine to direct the prepare flow (for POE)
2444 if ( my $prepare = $c->engine->can('prepare') ) {
2445 $c->engine->$prepare( $c, @arguments );
2448 $c->prepare_request(@arguments);
2449 $c->prepare_connection;
2450 $c->prepare_query_parameters;
2451 $c->prepare_headers; # Just hooks, no longer needed - they just
2452 $c->prepare_cookies; # cause the lazy attribute on req to build
2455 # Prepare the body for reading, either by prepare_body
2456 # or the user, if they are using $c->read
2459 # Parse the body unless the user wants it on-demand
2460 unless ( ref($c)->config->{parse_on_demand} ) {
2466 # VERY ugly and probably shouldn't rely on ->finalize actually working
2468 # failed prepare is always due to an invalid request, right?
2469 # Note we call finalize and then die here, which escapes
2470 # finalize being called in the enclosing block..
2471 # It in fact couldn't be called, as we don't return $c..
2472 # This is a mess - but I'm unsure you can fix this without
2473 # breaking compat for people doing crazy things (we should set
2474 # the 400 and just return the ctx here IMO, letting finalize get called
2476 if ( $c->_handle_http_exception($_) ) {
2477 foreach my $err (@{$c->error}) {
2478 $c->log->error($err);
2481 $c->log->_flush if $c->log->can('_flush');
2482 $_->can('rethrow') ? $_->rethrow : croak $_;
2484 $c->response->status(400);
2485 $c->response->content_type('text/plain');
2486 $c->response->body('Bad Request');
2493 $c->{stash} = $c->stash;
2498 =head2 $c->prepare_action
2500 Prepares action. See L<Catalyst::Dispatcher>.
2504 sub prepare_action {
2506 my $ret = $c->dispatcher->prepare_action( $c, @_);
2509 foreach (@{$c->req->arguments}, @{$c->req->captures}) {
2510 $_ = $c->_handle_param_unicode_decoding($_);
2518 =head2 $c->prepare_body
2520 Prepares message body.
2527 return if $c->request->_has_body;
2529 # Initialize on-demand data
2530 $c->engine->prepare_body( $c, @_ );
2531 $c->prepare_parameters;
2532 $c->prepare_uploads;
2535 =head2 $c->prepare_body_chunk( $chunk )
2537 Prepares a chunk of data before sending it to L<HTTP::Body>.
2539 See L<Catalyst::Engine>.
2543 sub prepare_body_chunk {
2545 $c->engine->prepare_body_chunk( $c, @_ );
2548 =head2 $c->prepare_body_parameters
2550 Prepares body parameters.
2554 sub prepare_body_parameters {
2556 $c->request->prepare_body_parameters( $c, @_ );
2559 =head2 $c->prepare_connection
2561 Prepares connection.
2565 sub prepare_connection {
2567 $c->request->prepare_connection($c);
2570 =head2 $c->prepare_cookies
2572 Prepares cookies by ensuring that the attribute on the request
2573 object has been built.
2577 sub prepare_cookies { my $c = shift; $c->request->cookies }
2579 =head2 $c->prepare_headers
2581 Prepares request headers by ensuring that the attribute on the request
2582 object has been built.
2586 sub prepare_headers { my $c = shift; $c->request->headers }
2588 =head2 $c->prepare_parameters
2590 Prepares parameters.
2594 sub prepare_parameters {
2596 $c->prepare_body_parameters;
2597 $c->engine->prepare_parameters( $c, @_ );
2600 =head2 $c->prepare_path
2602 Prepares path and base.
2606 sub prepare_path { my $c = shift; $c->engine->prepare_path( $c, @_ ) }
2608 =head2 $c->prepare_query_parameters
2610 Prepares query parameters.
2614 sub prepare_query_parameters {
2617 $c->engine->prepare_query_parameters( $c, @_ );
2620 =head2 $c->log_request
2622 Writes information about the request to the debug logs. This includes:
2626 =item * Request method, path, and remote IP address
2628 =item * Query keywords (see L<Catalyst::Request/query_keywords>)
2630 =item * Request parameters
2632 =item * File uploads
2641 return unless $c->debug;
2643 my($dump) = grep {$_->[0] eq 'Request' } $c->dump_these;
2644 my $request = $dump->[1];
2646 my ( $method, $path, $address ) = ( $request->method, $request->path, $request->address );
2648 $path = '/' unless length $path;
2651 $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
2652 $path = decode_utf8($path);
2654 $c->log->debug(qq/"$method" request for "$path" from "$address"/);
2656 $c->log_request_headers($request->headers);
2658 if ( my $keywords = $request->query_keywords ) {
2659 $c->log->debug("Query keywords are: $keywords");
2662 $c->log_request_parameters( query => $request->query_parameters, $request->_has_body ? (body => $request->body_parameters) : () );
2664 $c->log_request_uploads($request);
2667 =head2 $c->log_response
2669 Writes information about the response to the debug logs by calling
2670 C<< $c->log_response_status_line >> and C<< $c->log_response_headers >>.
2677 return unless $c->debug;
2679 my($dump) = grep {$_->[0] eq 'Response' } $c->dump_these;
2680 my $response = $dump->[1];
2682 $c->log_response_status_line($response);
2683 $c->log_response_headers($response->headers);
2686 =head2 $c->log_response_status_line($response)
2688 Writes one line of information about the response to the debug logs. This includes:
2692 =item * Response status code
2694 =item * Content-Type header (if present)
2696 =item * Content-Length header (if present)
2702 sub log_response_status_line {
2703 my ($c, $response) = @_;
2707 'Response Code: %s; Content-Type: %s; Content-Length: %s',
2708 $response->status || 'unknown',
2709 $response->headers->header('Content-Type') || 'unknown',
2710 $response->headers->header('Content-Length') || 'unknown'
2715 =head2 $c->log_response_headers($headers);
2717 Hook method which can be wrapped by plugins to log the response headers.
2718 No-op in the default implementation.
2722 sub log_response_headers {}
2724 =head2 $c->log_request_parameters( query => {}, body => {} )
2726 Logs request parameters to debug logs
2730 sub log_request_parameters {
2732 my %all_params = @_;
2734 return unless $c->debug;
2736 my $column_width = Catalyst::Utils::term_width() - 44;
2737 foreach my $type (qw(query body)) {
2738 my $params = $all_params{$type};
2739 next if ! keys %$params;
2740 my $t = Text::SimpleTable->new( [ 35, 'Parameter' ], [ $column_width, 'Value' ] );
2741 for my $key ( sort keys %$params ) {
2742 my $param = $params->{$key};
2743 my $value = defined($param) ? $param : '';
2744 $t->row( $key, ref $value eq 'ARRAY' ? ( join ', ', @$value ) : $value );
2746 $c->log->debug( ucfirst($type) . " Parameters are:\n" . $t->draw );
2750 =head2 $c->log_request_uploads
2752 Logs file uploads included in the request to the debug logs.
2753 The parameter name, filename, file type, and file size are all included in
2758 sub log_request_uploads {
2760 my $request = shift;
2761 return unless $c->debug;
2762 my $uploads = $request->uploads;
2763 if ( keys %$uploads ) {
2764 my $t = Text::SimpleTable->new(
2765 [ 12, 'Parameter' ],
2770 for my $key ( sort keys %$uploads ) {
2771 my $upload = $uploads->{$key};
2772 for my $u ( ref $upload eq 'ARRAY' ? @{$upload} : ($upload) ) {
2773 $t->row( $key, $u->filename, $u->type, $u->size );
2776 $c->log->debug( "File Uploads are:\n" . $t->draw );
2780 =head2 $c->log_request_headers($headers);
2782 Hook method which can be wrapped by plugins to log the request headers.
2783 No-op in the default implementation.
2787 sub log_request_headers {}
2789 =head2 $c->log_headers($type => $headers)
2791 Logs L<HTTP::Headers> (either request or response) to the debug logs.
2798 my $headers = shift; # an HTTP::Headers instance
2800 return unless $c->debug;
2802 my $column_width = Catalyst::Utils::term_width() - 28;
2803 my $t = Text::SimpleTable->new( [ 15, 'Header Name' ], [ $column_width, 'Value' ] );
2806 my ( $name, $value ) = @_;
2807 $t->row( $name, $value );
2810 $c->log->debug( ucfirst($type) . " Headers:\n" . $t->draw );
2814 =head2 $c->prepare_read
2816 Prepares the input for reading.
2820 sub prepare_read { my $c = shift; $c->engine->prepare_read( $c, @_ ) }
2822 =head2 $c->prepare_request
2824 Prepares the engine request.
2828 sub prepare_request { my $c = shift; $c->engine->prepare_request( $c, @_ ) }
2830 =head2 $c->prepare_uploads
2836 sub prepare_uploads {
2838 $c->engine->prepare_uploads( $c, @_ );
2841 =head2 $c->prepare_write
2843 Prepares the output for writing.
2847 sub prepare_write { my $c = shift; $c->engine->prepare_write( $c, @_ ) }
2849 =head2 $c->request_class
2851 Returns or sets the request class. Defaults to L<Catalyst::Request>.
2853 =head2 $app->request_class_traits
2855 An arrayref of L<Moose::Role>s which are applied to the request class. You can
2856 name the full namespace of the role, or a namespace suffix, which will then
2857 be tried against the following standard namespace prefixes.
2859 $MyApp::TraitFor::Request::$trait_suffix
2860 Catalyst::TraitFor::Request::$trait_suffix
2862 So for example if you set:
2864 MyApp->request_class_traits(['Foo']);
2866 We try each possible role in turn (and throw an error if none load)
2869 MyApp::TraitFor::Request::Foo
2870 Catalyst::TraitFor::Request::Foo
2872 The namespace part 'TraitFor::Request' was chosen to assist in backwards
2873 compatibility with L<CatalystX::RoleApplicator> which previously provided
2874 these features in a stand alone package.
2876 =head2 $app->composed_request_class
2878 This is the request class which has been composed with any request_class_traits.
2880 =head2 $c->response_class
2882 Returns or sets the response class. Defaults to L<Catalyst::Response>.
2884 =head2 $app->response_class_traits
2886 An arrayref of L<Moose::Role>s which are applied to the response class. You can
2887 name the full namespace of the role, or a namespace suffix, which will then
2888 be tried against the following standard namespace prefixes.
2890 $MyApp::TraitFor::Response::$trait_suffix
2891 Catalyst::TraitFor::Response::$trait_suffix
2893 So for example if you set:
2895 MyApp->response_class_traits(['Foo']);
2897 We try each possible role in turn (and throw an error if none load)
2900 MyApp::TraitFor::Response::Foo
2901 Catalyst::TraitFor::Responset::Foo
2903 The namespace part 'TraitFor::Response' was chosen to assist in backwards
2904 compatibility with L<CatalystX::RoleApplicator> which previously provided
2905 these features in a stand alone package.
2908 =head2 $app->composed_response_class
2910 This is the request class which has been composed with any response_class_traits.
2912 =head2 $c->read( [$maxlength] )
2914 Reads a chunk of data from the request body. This method is designed to
2915 be used in a while loop, reading C<$maxlength> bytes on every call.
2916 C<$maxlength> defaults to the size of the request if not specified.
2918 You have to set C<< MyApp->config(parse_on_demand => 1) >> to use this
2921 Warning: If you use read(), Catalyst will not process the body,
2922 so you will not be able to access POST parameters or file uploads via
2923 $c->request. You must handle all body parsing yourself.
2927 sub read { my $c = shift; return $c->request->read( @_ ) }
2937 $app->_make_immutable_if_needed;
2938 $app->engine_loader->needs_psgi_engine_compat_hack ?
2939 $app->engine->run($app, @_) :
2940 $app->engine->run( $app, $app->_finalized_psgi_app, @_ );
2943 sub _make_immutable_if_needed {
2945 my $meta = find_meta($class);
2946 my $isa_ca = $class->isa('Class::Accessor::Fast') || $class->isa('Class::Accessor');
2949 && ! { $meta->immutable_options }->{replace_constructor}
2952 warn("You made your application class ($class) immutable, "
2953 . "but did not inline the\nconstructor. "
2954 . "This will break catalyst, as your app \@ISA "
2955 . "Class::Accessor(::Fast)?\nPlease pass "
2956 . "(replace_constructor => 1)\nwhen making your class immutable.\n");
2958 unless ($meta->is_immutable) {
2959 # XXX - FIXME warning here as you should make your app immutable yourself.
2960 $meta->make_immutable(
2961 replace_constructor => 1,
2966 =head2 $c->set_action( $action, $code, $namespace, $attrs )
2968 Sets an action in a given namespace.
2972 sub set_action { my $c = shift; $c->dispatcher->set_action( $c, @_ ) }
2974 =head2 $c->setup_actions($component)
2976 Sets up actions for a component.
2980 sub setup_actions { my $c = shift; $c->dispatcher->setup_actions( $c, @_ ) }
2982 =head2 $c->setup_components
2984 This method is called internally to set up the application's components.
2986 It finds modules by calling the L<locate_components> method, expands them to
2987 package names with the L<expand_component_module> method, and then installs
2988 each component into the application.
2990 The C<setup_components> config option is passed to both of the above methods.
2992 Installation of each component is performed by the L<setup_component> method,
2997 sub setup_components {
3000 my $config = $class->config->{ setup_components };
3002 my @comps = $class->locate_components($config);
3003 my %comps = map { $_ => 1 } @comps;
3005 my $deprecatedcatalyst_component_names = grep { /::[CMV]::/ } @comps;
3006 $class->log->warn(qq{Your application is using the deprecated ::[MVC]:: type naming scheme.\n}.
3007 qq{Please switch your class names to ::Model::, ::View:: and ::Controller: as appropriate.\n}
3008 ) if $deprecatedcatalyst_component_names;
3010 for my $component ( @comps ) {
3012 # We pass ignore_loaded here so that overlay files for (e.g.)
3013 # Model::DBI::Schema sub-classes are loaded - if it's in @comps
3014 # we know M::P::O found a file on disk so this is safe
3016 Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
3019 for my $component (@comps) {
3020 my $instance = $class->components->{ $component } = $class->delayed_setup_component($component);
3023 # Inject a component or wrap a stand alone class in an adaptor. This makes a list
3024 # of named components in the configuration that are not actually existing (not a
3027 my @injected = $class->setup_injected_components;
3029 # All components are registered, now we need to 'init' them.
3030 foreach my $component_name (@comps, @injected) {
3031 $class->components->{$component_name} = $class->components->{$component_name}->() if
3032 (ref($class->components->{$component_name}) || '') eq 'CODE';
3036 =head2 $app->setup_injected_components
3038 Called by setup_compoents to setup components that are injected.
3042 sub setup_injected_components {
3044 my @injected_components = keys %{$class->config->{inject_components} ||+{}};
3046 foreach my $injected_comp_name(@injected_components) {
3047 $class->setup_injected_component(
3048 $injected_comp_name,
3049 $class->config->{inject_components}->{$injected_comp_name});
3052 return map { $class ."::" . $_ }
3053 @injected_components;
3056 =head2 $app->setup_injected_component( $injected_component_name, $config )
3058 Setup a given injected component.
3062 sub setup_injected_component {
3063 my ($class, $injected_comp_name, $config) = @_;
3064 if(my $component_class = $config->{from_component}) {
3065 my @roles = @{$config->{roles} ||[]};
3066 Catalyst::Utils::inject_component(
3068 component => $component_class,
3069 (scalar(@roles) ? (traits => \@roles) : ()),
3070 as => $injected_comp_name);
3074 =head2 $app->inject_component($MyApp_Component_name => \%args);
3076 Add a component that is injected at setup:
3078 MyApp->inject_component( 'Model::Foo' => { from_component => 'Common::Foo' } );
3080 Must be called before ->setup. Expects a component name for your
3081 current application and \%args where
3085 =item from_component
3087 The target component being injected into your application
3091 An arrayref of L<Moose::Role>s that are applied to your component.
3097 MyApp->inject_component(
3099 from_component => 'Common::Model::Foo',
3100 roles => ['Role1', 'Role2'],
3103 =head2 $app->inject_components
3105 Inject a list of components:
3107 MyApp->inject_components(
3108 'Model::FooOne' => {
3109 from_component => 'Common::Model::Foo',
3110 roles => ['Role1', 'Role2'],
3112 'Model::FooTwo' => {
3113 from_component => 'Common::Model::Foo',
3114 roles => ['Role1', 'Role2'],
3119 sub inject_component {
3120 my ($app, $name, $args) = @_;
3121 die "Component $name exists" if
3122 $app->config->{inject_components}->{$name};
3123 $app->config->{inject_components}->{$name} = $args;
3126 sub inject_components {
3129 $app->inject_component(shift, shift);
3133 =head2 $c->locate_components( $setup_component_config )
3135 This method is meant to provide a list of component modules that should be
3136 setup for the application. By default, it will use L<Module::Pluggable>.
3138 Specify a C<setup_components> config option to pass additional options directly
3139 to L<Module::Pluggable>. To add additional search paths, specify a key named
3140 C<search_extra> as an array reference. Items in the array beginning with C<::>
3141 will have the application class name prepended to them.
3145 sub locate_components {
3149 my @paths = qw( ::M ::Model ::V ::View ::C ::Controller );
3150 my $extra = $config->{ search_extra } || [];
3152 unshift @paths, @$extra;
3154 my @comps = map { sort { length($a) <=> length($b) } Module::Pluggable::Object->new(
3155 search_path => [ map { s/^(?=::)/$class/; $_; } ($_) ],
3157 )->plugins } @paths;
3162 =head2 $c->expand_component_module( $component, $setup_component_config )
3164 Components found by C<locate_components> will be passed to this method, which
3165 is expected to return a list of component (package) names to be set up.
3169 sub expand_component_module {
3170 my ($class, $module) = @_;
3171 return Devel::InnerPackage::list_packages( $module );
3174 =head2 $app->delayed_setup_component
3176 Returns a coderef that points to a setup_component instance. Used
3177 internally for when you want to delay setup until the first time
3178 the component is called.
3182 sub delayed_setup_component {
3183 my($class, $component, @more) = @_;
3185 return my $instance = $class->setup_component($component, @more);
3189 =head2 $c->setup_component
3193 sub setup_component {
3194 my( $class, $component ) = @_;
3196 unless ( $component->can( 'COMPONENT' ) ) {
3200 my $config = $class->config_for($component);
3201 # Stash catalyst_component_name in the config here, so that custom COMPONENT
3202 # methods also pass it. local to avoid pointlessly shitting in config
3203 # for the debug screen, as $component is already the key name.
3204 local $config->{catalyst_component_name} = $component;
3206 my $instance = eval {
3207 $component->COMPONENT( $class, $config );
3211 Catalyst::Exception->throw(
3212 message => qq/Couldn't instantiate component "$component", "$error"/
3216 unless (blessed $instance) {
3217 my $metaclass = Moose::Util::find_meta($component);
3218 my $method_meta = $metaclass->find_method_by_name('COMPONENT');
3219 my $component_method_from = $method_meta->associated_metaclass->name;
3220 my $value = defined($instance) ? $instance : 'undef';
3221 Catalyst::Exception->throw(
3223 qq/Couldn't instantiate component "$component", COMPONENT() method (from $component_method_from) didn't return an object-like value (value was $value)./
3227 my @expanded_components = $instance->can('expand_modules')
3228 ? $instance->expand_modules( $component, $config )
3229 : $class->expand_component_module( $component, $config );
3230 for my $component (@expanded_components) {
3231 next if $class->components->{ $component };
3232 $class->components->{ $component } = $class->setup_component($component);
3238 =head2 $app->config_for( $component_name )
3240 Return the application level configuration (which is not yet merged with any
3241 local component configuration, via $component_class->config) for the named
3242 component or component object. Example:
3245 'Model::Foo' => { a => 1, b => 2},
3248 my $config = MyApp->config_for('MyApp::Model::Foo');
3250 In this case $config is the hashref C< {a=>1, b=>2} >.
3252 This is also handy for looking up configuration for a plugin, to make sure you follow
3253 existing L<Catalyst> standards for where a plugin should put its configuration.
3258 my ($class, $component_name) = @_;
3259 my $component_suffix = Catalyst::Utils::class2classsuffix($component_name);
3260 my $config = $class->config->{ $component_suffix } || {};
3265 =head2 $c->setup_dispatcher
3271 sub setup_dispatcher {
3272 my ( $class, $dispatcher ) = @_;
3275 $dispatcher = 'Catalyst::Dispatcher::' . $dispatcher;
3278 if ( my $env = Catalyst::Utils::env_value( $class, 'DISPATCHER' ) ) {
3279 $dispatcher = 'Catalyst::Dispatcher::' . $env;
3282 unless ($dispatcher) {
3283 $dispatcher = $class->dispatcher_class;
3286 load_class($dispatcher);
3288 # dispatcher instance
3289 $class->dispatcher( $dispatcher->new );
3292 =head2 $c->setup_engine
3299 my ($class, $requested_engine) = @_;
3301 if (!$class->engine_loader || $requested_engine) {
3302 $class->engine_loader(
3303 Catalyst::EngineLoader->new({
3304 application_name => $class,
3305 (defined $requested_engine
3306 ? (catalyst_engine_class => $requested_engine) : ()),
3311 $class->engine_loader->catalyst_engine_class;
3315 my ($class, $requested_engine) = @_;
3318 my $loader = $class->engine_loader;
3320 if (!$loader || $requested_engine) {
3321 $loader = Catalyst::EngineLoader->new({
3322 application_name => $class,
3323 (defined $requested_engine
3324 ? (requested_engine => $requested_engine) : ()),
3327 $class->engine_loader($loader);
3330 $loader->catalyst_engine_class;
3333 # Don't really setup_engine -- see _setup_psgi_app for explanation.
3334 return if $class->loading_psgi_file;
3336 load_class($engine);
3338 if ($ENV{MOD_PERL}) {
3339 my $apache = $class->engine_loader->auto;
3341 my $meta = find_meta($class);
3342 my $was_immutable = $meta->is_immutable;
3343 my %immutable_options = $meta->immutable_options;
3344 $meta->make_mutable if $was_immutable;
3346 $meta->add_method(handler => sub {
3348 my $psgi_app = $class->_finalized_psgi_app;
3349 $apache->call_app($r, $psgi_app);
3352 $meta->make_immutable(%immutable_options) if $was_immutable;
3355 $class->engine( $engine->new );
3360 ## This exists just to supply a prebuild psgi app for mod_perl and for the
3361 ## build in server support (back compat support for pre psgi port behavior).
3362 ## This is so that we don't build a new psgi app for each request when using
3363 ## the mod_perl handler or the built in servers (http and fcgi, etc).
3365 sub _finalized_psgi_app {
3368 unless ($app->_psgi_app) {
3369 my $psgi_app = $app->_setup_psgi_app;
3370 $app->_psgi_app($psgi_app);
3373 return $app->_psgi_app;
3376 ## Look for a psgi file like 'myapp_web.psgi' (if the app is MyApp::Web) in the
3377 ## home directory and load that and return it (just assume it is doing the
3378 ## right thing :) ). If that does not exist, call $app->psgi_app, wrap that
3379 ## in default_middleware and return it ( this is for backward compatibility
3380 ## with pre psgi port behavior ).
3382 sub _setup_psgi_app {
3385 for my $home (Path::Class::Dir->new($app->config->{home})) {
3386 my $psgi_file = $home->file(
3387 Catalyst::Utils::appprefix($app) . '.psgi',
3390 next unless -e $psgi_file;
3392 # If $psgi_file calls ->setup_engine, it's doing so to load
3393 # Catalyst::Engine::PSGI. But if it does that, we're only going to
3394 # throw away the loaded PSGI-app and load the 5.9 Catalyst::Engine
3395 # anyway. So set a flag (ick) that tells setup_engine not to populate
3396 # $c->engine or do any other things we might regret.
3398 $app->loading_psgi_file(1);
3399 my $psgi_app = Plack::Util::load_psgi($psgi_file);
3400 $app->loading_psgi_file(0);
3403 unless $app->engine_loader->needs_psgi_engine_compat_hack;
3406 Found a legacy Catalyst::Engine::PSGI .psgi file at ${psgi_file}.
3408 Its content has been ignored. Please consult the Catalyst::Upgrading
3409 documentation on how to upgrade from Catalyst::Engine::PSGI.
3413 return $app->apply_default_middlewares($app->psgi_app);
3416 =head2 $c->apply_default_middlewares
3418 Adds the following L<Plack> middlewares to your application, since they are
3419 useful and commonly needed:
3421 L<Plack::Middleware::LighttpdScriptNameFix> (if you are using Lighttpd),
3422 L<Plack::Middleware::IIS6ScriptNameFix> (always applied since this middleware
3423 is smart enough to conditionally apply itself).
3425 We will also automatically add L<Plack::Middleware::ReverseProxy> if we notice
3426 that your HTTP $env variable C<REMOTE_ADDR> is '127.0.0.1'. This is usually
3427 an indication that your server is running behind a proxy frontend. However in
3428 2014 this is often not the case. We preserve this code for backwards compatibility
3429 however I B<highly> recommend that if you are running the server behind a front
3430 end proxy that you clearly indicate so with the C<using_frontend_proxy> configuration
3431 setting to true for your environment configurations that run behind a proxy. This
3432 way if you change your front end proxy address someday your code would inexplicably
3433 stop working as expected.
3435 Additionally if we detect we are using Nginx, we add a bit of custom middleware
3436 to solve some problems with the way that server handles $ENV{PATH_INFO} and
3439 Please B<NOTE> that if you do use C<using_frontend_proxy> the middleware is now
3440 adding via C<registered_middleware> rather than this method.
3442 If you are using Lighttpd or IIS6 you may wish to apply these middlewares. In
3443 general this is no longer a common case but we have this here for backward
3449 sub apply_default_middlewares {
3450 my ($app, $psgi_app) = @_;
3452 # Don't add this conditional IF we are explicitly saying we want the
3453 # frontend proxy support. We don't need it here since if that is the
3454 # case it will be always loaded in the default_middleware.
3456 unless($app->config->{using_frontend_proxy}) {
3457 $psgi_app = Plack::Middleware::Conditional->wrap(
3459 builder => sub { Plack::Middleware::ReverseProxy->wrap($_[0]) },
3462 return if $app->config->{ignore_frontend_proxy};
3463 return $env->{REMOTE_ADDR} eq '127.0.0.1';
3468 # If we're running under Lighttpd, swap PATH_INFO and SCRIPT_NAME
3469 # http://lists.scsys.co.uk/pipermail/catalyst/2006-June/008361.html
3470 $psgi_app = Plack::Middleware::Conditional->wrap(
3472 builder => sub { Plack::Middleware::LighttpdScriptNameFix->wrap($_[0]) },
3475 return unless $env->{SERVER_SOFTWARE} && $env->{SERVER_SOFTWARE} =~ m!lighttpd[-/]1\.(\d+\.\d+)!;
3476 return unless $1 < 4.23;
3481 # we're applying this unconditionally as the middleware itself already makes
3482 # sure it doesn't fuck things up if it's not running under one of the right
3484 $psgi_app = Plack::Middleware::IIS6ScriptNameFix->wrap($psgi_app);
3486 # And another IIS issue, this time with IIS7.
3487 $psgi_app = Plack::Middleware::Conditional->wrap(
3489 builder => sub { Plack::Middleware::IIS7KeepAliveFix->wrap($_[0]) },
3492 return $env->{SERVER_SOFTWARE} && $env->{SERVER_SOFTWARE} =~ m!IIS/7\.[0-9]!;
3499 =head2 App->psgi_app
3503 Returns a PSGI application code reference for the catalyst application
3504 C<$c>. This is the bare application created without the C<apply_default_middlewares>
3505 method called. We do however apply C<registered_middleware> since those are
3506 integral to how L<Catalyst> functions. Also, unlike starting your application
3507 with a generated server script (via L<Catalyst::Devel> and C<catalyst.pl>) we do
3508 not attempt to return a valid L<PSGI> application using any existing C<${myapp}.psgi>
3509 scripts in your $HOME directory.
3511 B<NOTE> C<apply_default_middlewares> was originally created when the first PSGI
3512 port was done for v5.90000. These are middlewares that are added to achieve
3513 backward compatibility with older applications. If you start your application
3514 using one of the supplied server scripts (generated with L<Catalyst::Devel> and
3515 the project skeleton script C<catalyst.pl>) we apply C<apply_default_middlewares>
3516 automatically. This was done so that pre and post PSGI port applications would
3519 This is what you want to be using to retrieve the PSGI application code
3520 reference of your Catalyst application for use in a custom F<.psgi> or in your
3521 own created server modules.
3525 *to_app = \&psgi_app;
3529 my $psgi = $app->engine->build_psgi_app($app);
3530 return $app->Catalyst::Utils::apply_registered_middleware($psgi);
3533 =head2 $c->setup_home
3535 Sets up the home directory.
3540 my ( $class, $home ) = @_;
3542 if ( my $env = Catalyst::Utils::env_value( $class, 'HOME' ) ) {
3546 $home ||= Catalyst::Utils::home($class);
3549 #I remember recently being scolded for assigning config values like this
3550 $class->config->{home} ||= $home;
3551 $class->config->{root} ||= Path::Class::Dir->new($home)->subdir('root');
3555 =head2 $c->setup_encoding
3557 Sets up the input/output encoding. See L<ENCODING>
3561 sub setup_encoding {
3563 if( exists($c->config->{encoding}) && !defined($c->config->{encoding}) ) {
3564 # Ok, so the user has explicitly said "I don't want encoding..."
3567 my $enc = defined($c->config->{encoding}) ?
3568 delete $c->config->{encoding} : 'UTF-8'; # not sure why we delete it... (JNAP)
3573 =head2 handle_unicode_encoding_exception
3575 Hook to let you customize how encoding errors are handled. By default
3576 we just throw an exception and the default error page will pick it up.
3577 Receives a hashref of debug information. Example of call (from the
3578 Catalyst internals):
3580 my $decoded_after_fail = $c->handle_unicode_encoding_exception({
3581 param_value => $value,
3583 encoding_step => 'params',
3586 The calling code expects to receive a decoded string or an exception.
3588 You can override this for custom handling of unicode errors. By
3589 default we just die. If you want a custom response here, one approach
3590 is to throw an HTTP style exception, instead of returning a decoded
3591 string or throwing a generic exception.
3593 sub handle_unicode_encoding_exception {
3594 my ($c, $params) = @_;
3595 HTTP::Exception::BAD_REQUEST->throw(status_message=>$params->{error_msg});
3598 Alternatively you can 'catch' the error, stash it and write handling code later
3599 in your application:
3601 sub handle_unicode_encoding_exception {
3602 my ($c, $params) = @_;
3603 $c->stash(BAD_UNICODE_DATA=>$params);
3604 # return a dummy string.
3608 <B>NOTE:</b> Please keep in mind that once an error like this occurs,
3609 the request setup is still ongoing, which means the state of C<$c> and
3610 related context parts like the request and response may not be setup
3611 up correctly (since we haven't finished the setup yet). If you throw
3612 an exception the setup is aborted.
3616 sub handle_unicode_encoding_exception {
3617 my ( $self, $exception_ctx ) = @_;
3618 die $exception_ctx->{error_msg};
3621 # Some unicode helpers cargo culted from the old plugin. These could likely
3624 sub _handle_unicode_decoding {
3625 my ( $self, $value ) = @_;
3627 return unless defined $value;
3629 ## I think this mess is to support the old nested
3630 if ( ref $value eq 'ARRAY' ) {
3631 foreach ( @$value ) {
3632 $_ = $self->_handle_unicode_decoding($_);
3636 elsif ( ref $value eq 'HASH' ) {
3637 foreach (keys %$value) {
3638 my $encoded_key = $self->_handle_param_unicode_decoding($_);
3639 $value->{$encoded_key} = $self->_handle_unicode_decoding($value->{$_});
3641 # If the key was encoded we now have two (the original and current so
3642 # delete the original.
3643 delete $value->{$_} if $_ ne $encoded_key;
3648 return $self->_handle_param_unicode_decoding($value);
3652 sub _handle_param_unicode_decoding {
3653 my ( $self, $value, $check ) = @_;
3654 return unless defined $value; # not in love with just ignoring undefs - jnap
3655 return $value if blessed($value); #don't decode when the value is an object.
3657 my $enc = $self->encoding;
3659 return $value unless $enc; # don't decode if no encoding is specified
3661 $check ||= $self->_encode_check;
3663 $enc->decode( $value, $check);
3666 return $self->handle_unicode_encoding_exception({
3667 param_value => $value,
3669 encoding_step => 'params',
3674 =head2 $c->setup_log
3676 Sets up log by instantiating a L<Catalyst::Log|Catalyst::Log> object and
3677 passing it to C<log()>. Pass in a comma-delimited list of levels to set the
3680 This method also installs a C<debug> method that returns a true value into the
3681 catalyst subclass if the "debug" level is passed in the comma-delimited list,
3682 or if the C<$CATALYST_DEBUG> environment variable is set to a true value.
3684 Note that if the log has already been setup, by either a previous call to
3685 C<setup_log> or by a call such as C<< __PACKAGE__->log( MyLogger->new ) >>,
3686 that this method won't actually set up the log object.
3691 my ( $class, $levels ) = @_;
3694 $levels =~ s/^\s+//;
3695 $levels =~ s/\s+$//;
3696 my %levels = map { $_ => 1 } split /\s*,\s*/, $levels;
3698 my $env_debug = Catalyst::Utils::env_value( $class, 'DEBUG' );
3699 if ( defined $env_debug ) {
3700 $levels{debug} = 1 if $env_debug; # Ugly!
3701 delete($levels{debug}) unless $env_debug;
3704 unless ( $class->log ) {
3705 $class->log( Catalyst::Log->new(keys %levels) );
3708 if ( $levels{debug} ) {
3709 Class::MOP::get_metaclass_by_name($class)->add_method('debug' => sub { 1 });
3710 $class->log->debug('Debug messages enabled');
3714 =head2 $c->setup_plugins
3720 =head2 $c->setup_stats
3722 Sets up timing statistics class.
3727 my ( $class, $stats ) = @_;
3729 Catalyst::Utils::ensure_class_loaded($class->stats_class);
3731 my $env = Catalyst::Utils::env_value( $class, 'STATS' );
3732 if ( defined($env) ? $env : ($stats || $class->debug ) ) {
3733 Class::MOP::get_metaclass_by_name($class)->add_method('use_stats' => sub { 1 });
3734 $class->log->debug('Statistics enabled');
3739 =head2 $c->registered_plugins
3741 Returns a sorted list of the plugins which have either been stated in the
3744 If passed a given plugin name, it will report a boolean value indicating
3745 whether or not that plugin is loaded. A fully qualified name is required if
3746 the plugin name does not begin with C<Catalyst::Plugin::>.
3748 if ($c->registered_plugins('Some::Plugin')) {
3756 sub registered_plugins {
3758 return sort keys %{ $proto->_plugins } unless @_;
3760 return 1 if exists $proto->_plugins->{$plugin};
3761 return exists $proto->_plugins->{"Catalyst::Plugin::$plugin"};
3764 sub _register_plugin {
3765 my ( $proto, $plugin, $instant ) = @_;
3766 my $class = ref $proto || $proto;
3768 load_class( $plugin );
3769 $class->log->warn( "$plugin inherits from 'Catalyst::Component' - this is deprecated and will not work in 5.81" )
3770 if $plugin->isa( 'Catalyst::Component' );
3771 my $plugin_meta = Moose::Meta::Class->create($plugin);
3772 if (!$plugin_meta->has_method('new')
3773 && ( $plugin->isa('Class::Accessor::Fast') || $plugin->isa('Class::Accessor') ) ) {
3774 $plugin_meta->add_method('new', Moose::Object->meta->get_method('new'))
3776 if (!$instant && !$proto->_plugins->{$plugin}) {
3777 my $meta = Class::MOP::get_metaclass_by_name($class);
3778 $meta->superclasses($plugin, $meta->superclasses);
3780 $proto->_plugins->{$plugin} = 1;
3784 sub _default_plugins { return qw() }
3787 my ( $class, $plugins ) = @_;
3789 $class->_plugins( {} ) unless $class->_plugins;
3791 m/Unicode::Encoding/ ? do {
3793 'Unicode::Encoding plugin is auto-applied,'
3794 . ' please remove this from your appclass'
3795 . ' and make sure to define "encoding" config'
3797 unless (exists $class->config->{'encoding'}) {
3798 $class->config->{'encoding'} = 'UTF-8';
3803 push @$plugins, $class->_default_plugins;
3804 $plugins = Data::OptList::mkopt($plugins || []);
3807 [ Catalyst::Utils::resolve_namespace(
3808 $class . '::Plugin',
3809 'Catalyst::Plugin', $_->[0]
3815 for my $plugin ( reverse @plugins ) {
3816 load_class($plugin->[0], $plugin->[1]);
3817 my $meta = find_meta($plugin->[0]);
3818 next if $meta && $meta->isa('Moose::Meta::Role');
3820 $class->_register_plugin($plugin->[0]);
3824 map { $_->[0]->name, $_->[1] }
3825 grep { blessed($_->[0]) && $_->[0]->isa('Moose::Meta::Role') }
3826 map { [find_meta($_->[0]), $_->[1]] }
3829 Moose::Util::apply_all_roles(
3835 =head2 default_middleware
3837 Returns a list of instantiated PSGI middleware objects which is the default
3838 middleware that is active for this application (taking any configuration
3839 options into account, excluding your custom added middleware via the C<psgi_middleware>
3840 configuration option). You can override this method if you wish to change
3841 the default middleware (although do so at risk since some middleware is vital
3842 to application function.)
3844 The current default middleware list is:
3846 Catalyst::Middleware::Stash
3847 Plack::Middleware::HTTPExceptions
3848 Plack::Middleware::RemoveRedundantBody
3849 Plack::Middleware::FixMissingBodyInRedirect
3850 Plack::Middleware::ContentLength
3851 Plack::Middleware::MethodOverride
3852 Plack::Middleware::Head
3854 If the configuration setting C<using_frontend_proxy> is true we add:
3856 Plack::Middleware::ReverseProxy
3858 If the configuration setting C<using_frontend_proxy_path> is true we add:
3860 Plack::Middleware::ReverseProxyPath
3862 But B<NOTE> that L<Plack::Middleware::ReverseProxyPath> is not a dependency of the
3863 L<Catalyst> distribution so if you want to use this option you should add it to
3864 your project distribution file.
3866 These middlewares will be added at L</setup_middleware> during the
3867 L</setup> phase of application startup.
3871 sub default_middleware {
3874 Catalyst::Middleware::Stash->new,
3875 Plack::Middleware::HTTPExceptions->new,
3876 Plack::Middleware::RemoveRedundantBody->new,
3877 Plack::Middleware::FixMissingBodyInRedirect->new,
3878 Plack::Middleware::ContentLength->new,
3879 Plack::Middleware::MethodOverride->new,
3880 Plack::Middleware::Head->new);
3882 if($class->config->{using_frontend_proxy}) {
3883 push @mw, Plack::Middleware::ReverseProxy->new;
3886 if($class->config->{using_frontend_proxy_path}) {
3887 if(Class::Load::try_load_class('Plack::Middleware::ReverseProxyPath')) {
3888 push @mw, Plack::Middleware::ReverseProxyPath->new;
3890 $class->log->error("Cannot use configuration 'using_frontend_proxy_path' because 'Plack::Middleware::ReverseProxyPath' is not installed");
3897 =head2 registered_middlewares
3899 Read only accessor that returns an array of all the middleware in the order
3900 that they were added (which is the REVERSE of the order they will be applied).
3902 The values returned will be either instances of L<Plack::Middleware> or of a
3903 compatible interface, or a coderef, which is assumed to be inlined middleware
3905 =head2 setup_middleware (?@middleware)
3907 Read configuration information stored in configuration key C<psgi_middleware> or
3910 See under L</CONFIGURATION> information regarding C<psgi_middleware> and how
3911 to use it to enable L<Plack::Middleware>
3913 This method is automatically called during 'setup' of your application, so
3914 you really don't need to invoke it. However you may do so if you find the idea
3915 of loading middleware via configuration weird :). For example:
3921 __PACKAGE__->setup_middleware('Head');
3924 When we read middleware definitions from configuration, we reverse the list
3925 which sounds odd but is likely how you expect it to work if you have prior
3926 experience with L<Plack::Builder> or if you previously used the plugin
3927 L<Catalyst::Plugin::EnableMiddleware> (which is now considered deprecated)
3929 So basically your middleware handles an incoming request from the first
3930 registered middleware, down and handles the response from the last middleware
3935 sub registered_middlewares {
3937 if(my $middleware = $class->_psgi_middleware) {
3938 my @mw = ($class->default_middleware, @$middleware);
3940 if($class->config->{using_frontend_proxy}) {
3941 push @mw, Plack::Middleware::ReverseProxy->new;
3946 die "You cannot call ->registered_middlewares until middleware has been setup";
3950 sub setup_middleware {
3952 my @middleware_definitions;
3954 # If someone calls this method you can add middleware with args. However if its
3955 # called without an arg we need to setup the configuration middleware.
3957 @middleware_definitions = reverse(@_);
3959 @middleware_definitions = reverse(@{$class->config->{'psgi_middleware'}||[]})
3960 unless $class->finalized_default_middleware;
3961 $class->finalized_default_middleware(1); # Only do this once, just in case some people call setup over and over...
3964 my @middleware = ();
3965 while(my $next = shift(@middleware_definitions)) {
3967 if(Scalar::Util::blessed $next && $next->can('wrap')) {
3968 push @middleware, $next;
3969 } elsif(ref $next eq 'CODE') {
3970 push @middleware, $next;
3971 } elsif(ref $next eq 'HASH') {
3972 my $namespace = shift @middleware_definitions;
3973 my $mw = $class->Catalyst::Utils::build_middleware($namespace, %$next);
3974 push @middleware, $mw;
3976 die "I can't handle middleware definition ${\ref $next}";
3979 my $mw = $class->Catalyst::Utils::build_middleware($next);
3980 push @middleware, $mw;
3984 my @existing = @{$class->_psgi_middleware || []};
3985 $class->_psgi_middleware([@middleware,@existing,]);
3988 =head2 registered_data_handlers
3990 A read only copy of registered Data Handlers returned as a Hash, where each key
3991 is a content type and each value is a subref that attempts to decode that content
3994 =head2 setup_data_handlers (?@data_handler)
3996 Read configuration information stored in configuration key C<data_handlers> or
3999 See under L</CONFIGURATION> information regarding C<data_handlers>.
4001 This method is automatically called during 'setup' of your application, so
4002 you really don't need to invoke it.
4004 =head2 default_data_handlers
4006 Default Data Handlers that come bundled with L<Catalyst>. Currently there are
4007 only two default data handlers, for 'application/json' and an alternative to
4008 'application/x-www-form-urlencoded' which supposed nested form parameters via
4009 L<CGI::Struct> or via L<CGI::Struct::XS> IF you've installed it.
4011 The 'application/json' data handler is used to parse incoming JSON into a Perl
4012 data structure. It used either L<JSON::MaybeXS> or L<JSON>, depending on which
4013 is installed. This allows you to fail back to L<JSON:PP>, which is a Pure Perl
4014 JSON decoder, and has the smallest dependency impact.
4016 Because we don't wish to add more dependencies to L<Catalyst>, if you wish to
4017 use this new feature we recommend installing L<JSON> or L<JSON::MaybeXS> in
4018 order to get the best performance. You should add either to your dependency
4019 list (Makefile.PL, dist.ini, cpanfile, etc.)
4023 sub registered_data_handlers {
4025 if(my $data_handlers = $class->_data_handlers) {
4026 return %$data_handlers;
4028 $class->setup_data_handlers;
4029 return $class->registered_data_handlers;
4033 sub setup_data_handlers {
4034 my ($class, %data_handler_callbacks) = @_;
4035 %data_handler_callbacks = (
4036 %{$class->default_data_handlers},
4037 %{$class->config->{'data_handlers'}||+{}},
4038 %data_handler_callbacks);
4040 $class->_data_handlers(\%data_handler_callbacks);
4043 sub default_data_handlers {
4046 'application/x-www-form-urlencoded' => sub {
4047 my ($fh, $req) = @_;
4048 my $params = $req->_use_hash_multivalue ? $req->body_parameters->mixed : $req->body_parameters;
4049 Class::Load::load_first_existing_class('CGI::Struct::XS', 'CGI::Struct')
4050 ->can('build_cgi_struct')->($params);
4052 'application/json' => sub {
4053 my ($fh, $req) = @_;
4054 my $parser = Class::Load::load_first_existing_class('JSON::MaybeXS', 'JSON');
4058 $slurped = $fh->getline;
4059 $parser->can("decode_json")->($slurped); # decode_json does utf8 decoding for us
4060 } || Catalyst::Exception->throw(sprintf "Error Parsing POST '%s', Error: %s", (defined($slurped) ? $slurped : 'undef') ,$@);
4065 sub _handle_http_exception {
4066 my ( $self, $error ) = @_;
4068 !$self->config->{always_catch_http_exceptions}
4071 $error->can('as_psgi')
4072 || ( $error->can('code')
4073 && $error->code =~ m/^[1-5][0-9][0-9]$/ )
4083 Returns an arrayref of the internal execution stack (actions that are
4084 currently executing).
4088 Returns the current timing statistics object. By default Catalyst uses
4089 L<Catalyst::Stats|Catalyst::Stats>, but can be set otherwise with
4090 L<< stats_class|/"$c->stats_class" >>.
4092 Even if L<< -Stats|/"-Stats" >> is not enabled, the stats object is still
4093 available. By enabling it with C< $c->stats->enabled(1) >, it can be used to
4094 profile explicitly, although MyApp.pm still won't profile nor output anything
4097 =head2 $c->stats_class
4099 Returns or sets the stats (timing statistics) class. L<Catalyst::Stats|Catalyst::Stats> is used by default.
4101 =head2 $app->stats_class_traits
4103 A arrayref of L<Moose::Role>s that are applied to the stats_class before creating it.
4105 =head2 $app->composed_stats_class
4107 this is the stats_class composed with any 'stats_class_traits'. You can
4108 name the full namespace of the role, or a namespace suffix, which will then
4109 be tried against the following standard namespace prefixes.
4111 $MyApp::TraitFor::Stats::$trait_suffix
4112 Catalyst::TraitFor::Stats::$trait_suffix
4114 So for example if you set:
4116 MyApp->stats_class_traits(['Foo']);
4118 We try each possible role in turn (and throw an error if none load)
4121 MyApp::TraitFor::Stats::Foo
4122 Catalyst::TraitFor::Stats::Foo
4124 The namespace part 'TraitFor::Stats' was chosen to assist in backwards
4125 compatibility with L<CatalystX::RoleApplicator> which previously provided
4126 these features in a stand alone package.
4128 =head2 $c->use_stats
4130 Returns 1 when L<< stats collection|/"-Stats" >> is enabled.
4132 Note that this is a static method, not an accessor and should be overridden
4133 by declaring C<sub use_stats { 1 }> in your MyApp.pm, not by calling C<< $c->use_stats(1) >>.
4140 =head2 $c->write( $data )
4142 Writes $data to the output stream. When using this method directly, you
4143 will need to manually set the C<Content-Length> header to the length of
4144 your output data, if known.
4151 # Finalize headers if someone manually writes output (for compat)
4152 $c->finalize_headers;
4154 return $c->response->write( @_ );
4159 Returns the Catalyst version number. Mostly useful for "powered by"
4160 messages in template systems.
4164 sub version { return $Catalyst::VERSION }
4166 =head1 CONFIGURATION
4168 There are a number of 'base' config variables which can be set:
4174 C<always_catch_http_exceptions> - As of version 5.90060 Catalyst
4175 rethrows errors conforming to the interface described by
4176 L<Plack::Middleware::HTTPExceptions> and lets the middleware deal with it.
4177 Set true to get the deprecated behaviour and have Catalyst catch HTTP exceptions.
4181 C<default_model> - The default model picked if you say C<< $c->model >>. See L<< /$c->model($name) >>.
4185 C<default_view> - The default view to be rendered or returned when C<< $c->view >> is called. See L<< /$c->view($name) >>.
4189 C<disable_component_resolution_regex_fallback> - Turns
4190 off the deprecated component resolution functionality so
4191 that if any of the component methods (e.g. C<< $c->controller('Foo') >>)
4192 are called then regex search will not be attempted on string values and
4193 instead C<undef> will be returned.
4197 C<home> - The application home directory. In an uninstalled application,
4198 this is the top level application directory. In an installed application,
4199 this will be the directory containing C<< MyApp.pm >>.
4203 C<ignore_frontend_proxy> - See L</PROXY SUPPORT>
4207 C<name> - The name of the application in debug messages and the debug and
4212 C<parse_on_demand> - The request body (for example file uploads) will not be parsed
4213 until it is accessed. This allows you to (for example) check authentication (and reject
4214 the upload) before actually receiving all the data. See L</ON-DEMAND PARSER>
4218 C<root> - The root directory for templates. Usually this is just a
4219 subdirectory of the home directory, but you can set it to change the
4220 templates to a different directory.
4224 C<search_extra> - Array reference passed to Module::Pluggable to for additional
4225 namespaces from which components will be loaded (and constructed and stored in
4226 C<< $c->components >>).
4230 C<show_internal_actions> - If true, causes internal actions such as C<< _DISPATCH >>
4231 to be shown in hit debug tables in the test server.
4235 C<use_request_uri_for_path> - Controls if the C<REQUEST_URI> or C<PATH_INFO> environment
4236 variable should be used for determining the request path.
4238 Most web server environments pass the requested path to the application using environment variables,
4239 from which Catalyst has to reconstruct the request base (i.e. the top level path to / in the application,
4240 exposed as C<< $c->request->base >>) and the request path below that base.
4242 There are two methods of doing this, both of which have advantages and disadvantages. Which method is used
4243 is determined by the C<< $c->config(use_request_uri_for_path) >> setting (which can either be true or false).
4247 =item use_request_uri_for_path => 0
4249 This is the default (and the) traditional method that Catalyst has used for determining the path information.
4250 The path is generated from a combination of the C<PATH_INFO> and C<SCRIPT_NAME> environment variables.
4251 The allows the application to behave correctly when C<mod_rewrite> is being used to redirect requests
4252 into the application, as these variables are adjusted by mod_rewrite to take account for the redirect.
4254 However this method has the major disadvantage that it is impossible to correctly decode some elements
4255 of the path, as RFC 3875 says: "C<< Unlike a URI path, the PATH_INFO is not URL-encoded, and cannot
4256 contain path-segment parameters. >>" This means PATH_INFO is B<always> decoded, and therefore Catalyst
4257 can't distinguish / vs %2F in paths (in addition to other encoded values).
4259 =item use_request_uri_for_path => 1
4261 This method uses the C<REQUEST_URI> and C<SCRIPT_NAME> environment variables. As C<REQUEST_URI> is never
4262 decoded, this means that applications using this mode can correctly handle URIs including the %2F character
4263 (i.e. with C<AllowEncodedSlashes> set to C<On> in Apache).
4265 Given that this method of path resolution is provably more correct, it is recommended that you use
4266 this unless you have a specific need to deploy your application in a non-standard environment, and you are
4267 aware of the implications of not being able to handle encoded URI paths correctly.
4269 However it also means that in a number of cases when the app isn't installed directly at a path, but instead
4270 is having paths rewritten into it (e.g. as a .cgi/fcgi in a public_html directory, with mod_rewrite in a
4271 .htaccess file, or when SSI is used to rewrite pages into the app, or when sub-paths of the app are exposed
4272 at other URIs than that which the app is 'normally' based at with C<mod_rewrite>), the resolution of
4273 C<< $c->request->base >> will be incorrect.
4279 C<using_frontend_proxy> - See L</PROXY SUPPORT>.
4283 C<using_frontend_proxy_path> - Enabled L<Plack::Middleware::ReverseProxyPath> on your application (if
4284 installed, otherwise log an error). This is useful if your application is not running on the
4285 'root' (or /) of your host server. B<NOTE> if you use this feature you should add the required
4286 middleware to your project dependency list since its not automatically a dependency of L<Catalyst>.
4287 This has been done since not all people need this feature and we wish to restrict the growth of
4288 L<Catalyst> dependencies.
4292 C<encoding> - See L</ENCODING>
4294 This now defaults to 'UTF-8'. You my turn it off by setting this configuration
4299 C<abort_chain_on_error_fix>
4301 When there is an error in an action chain, the default behavior is to continue
4302 processing the remaining actions and then catch the error upon chain end. This
4303 can lead to running actions when the application is in an unexpected state. If
4304 you have this issue, setting this config value to true will promptly exit a
4305 chain when there is an error raised in any action (thus terminating the chain
4310 __PACKAGE__->config(abort_chain_on_error_fix => 1);
4312 In the future this might become the default behavior.
4316 C<use_hash_multivalue_in_request>
4318 In L<Catalyst::Request> the methods C<query_parameters>, C<body_parametes>
4319 and C<parameters> return a hashref where values might be scalar or an arrayref
4320 depending on the incoming data. In many cases this can be undesirable as it
4321 leads one to writing defensive code like the following:
4323 my ($val) = ref($c->req->parameters->{a}) ?
4324 @{$c->req->parameters->{a}} :
4325 $c->req->parameters->{a};
4327 Setting this configuration item to true will make L<Catalyst> populate the
4328 attributes underlying these methods with an instance of L<Hash::MultiValue>
4329 which is used by L<Plack::Request> and others to solve this very issue. You
4330 may prefer this behavior to the default, if so enable this option (be warned
4331 if you enable it in a legacy application we are not sure if it is completely
4332 backwardly compatible).
4336 C<skip_complex_post_part_handling>
4338 When creating body parameters from a POST, if we run into a multipart POST
4339 that does not contain uploads, but instead contains inlined complex data
4340 (very uncommon) we cannot reliably convert that into field => value pairs. So
4341 instead we create an instance of L<Catalyst::Request::PartData>. If this causes
4342 issue for you, you can disable this by setting C<skip_complex_post_part_handling>
4343 to true (default is false).
4347 C<skip_body_param_unicode_decoding>
4349 Generally we decode incoming POST params based on your declared encoding (the
4350 default for this is to decode UTF-8). If this is causing you trouble and you
4351 do not wish to turn all encoding support off (with the C<encoding> configuration
4352 parameter) you may disable this step atomically by setting this configuration
4357 C<do_not_decode_query>
4359 If true, then do not try to character decode any wide characters in your
4360 request URL query or keywords. Most readings of the relevant specifications
4361 suggest these should be UTF-* encoded, which is the default that L<Catalyst>
4362 will use, however if you are creating a lot of URLs manually or have external
4363 evil clients, this might cause you trouble. If you find the changes introduced
4364 in Catalyst version 5.90080+ break some of your query code, you may disable
4365 the UTF-8 decoding globally using this configuration.
4367 This setting takes precedence over C<default_query_encoding>
4371 C<do_not_check_query_encoding>
4373 Catalyst versions 5.90080 - 5.90106 would decode query parts of an incoming
4374 request but would not raise an exception when the decoding failed due to
4375 incorrect unicode. It now does, but if this change is giving you trouble
4376 you may disable it by setting this configuration to true.
4380 C<default_query_encoding>
4382 By default we decode query and keywords in your request URL using UTF-8, which
4383 is our reading of the relevant specifications. This setting allows one to
4384 specify a fixed value for how to decode your query. You might need this if
4385 you are doing a lot of custom encoding of your URLs and not using UTF-8.
4389 C<use_chained_args_0_special_case>
4391 In older versions of Catalyst, when more than one action matched the same path
4392 AND all those matching actions declared Args(0), we'd break the tie by choosing
4393 the first action defined. We now normalized how Args(0) works so that it
4394 follows the same rule as Args(N), which is to say when we need to break a tie
4395 we choose the LAST action defined. If this breaks your code and you don't
4396 have time to update to follow the new normalized approach, you may set this
4397 value to true and it will globally revert to the original chaining behavior.
4401 C<psgi_middleware> - See L<PSGI MIDDLEWARE>.
4405 C<data_handlers> - See L<DATA HANDLERS>.
4409 C<stats_class_traits>
4411 An arrayref of L<Moose::Role>s that get composed into your stats class.
4415 C<request_class_traits>
4417 An arrayref of L<Moose::Role>s that get composed into your request class.
4421 C<response_class_traits>
4423 An arrayref of L<Moose::Role>s that get composed into your response class.
4427 C<inject_components>
4429 A Hashref of L<Catalyst::Component> subclasses that are 'injected' into configuration.
4433 inject_components => {
4434 'Controller::Err' => { from_component => 'Local::Controller::Errors' },
4435 'Model::Zoo' => { from_component => 'Local::Model::Foo' },
4436 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] },
4438 'Controller::Err' => { a => 100, b=>200, namespace=>'error' },
4439 'Model::Zoo' => { a => 2 },
4440 'Model::Foo' => { a => 100 },
4443 Generally L<Catalyst> looks for components in your Model/View or Controller directories.
4444 However for cases when you which to use an existing component and you don't need any
4445 customization (where for when you can apply a role to customize it) you may inject those
4446 components into your application. Please note any configuration should be done 'in the
4447 normal way', with a key under configuration named after the component affix, as in the
4450 Using this type of injection allows you to construct significant amounts of your application
4451 with only configuration!. This may or may not lead to increased code understanding.
4453 Please not you may also call the ->inject_components application method as well, although
4454 you must do so BEFORE setup.
4460 Generally when you throw an exception inside an Action (or somewhere in
4461 your stack, such as in a model that an Action is calling) that exception
4462 is caught by Catalyst and unless you either catch it yourself (via eval
4463 or something like L<Try::Tiny> or by reviewing the L</error> stack, it
4464 will eventually reach L</finalize_errors> and return either the debugging
4465 error stack page, or the default error page. However, if your exception
4466 can be caught by L<Plack::Middleware::HTTPExceptions>, L<Catalyst> will
4467 instead rethrow it so that it can be handled by that middleware (which
4468 is part of the default middleware). For example this would allow
4470 use HTTP::Throwable::Factory 'http_throw';
4472 sub throws_exception :Local {
4473 my ($self, $c) = @_;
4475 http_throw(SeeOther => { location =>
4476 $c->uri_for($self->action_for('redirect')) });
4480 =head1 INTERNAL ACTIONS
4482 Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>,
4483 C<_ACTION>, and C<_END>. These are by default not shown in the private
4484 action table, but you can make them visible with a config parameter.
4486 MyApp->config(show_internal_actions => 1);
4488 =head1 ON-DEMAND PARSER
4490 The request body is usually parsed at the beginning of a request,
4491 but if you want to handle input yourself, you can enable on-demand
4492 parsing with a config parameter.
4494 MyApp->config(parse_on_demand => 1);
4496 =head1 PROXY SUPPORT
4498 Many production servers operate using the common double-server approach,
4499 with a lightweight frontend web server passing requests to a larger
4500 backend server. An application running on the backend server must deal
4501 with two problems: the remote user always appears to be C<127.0.0.1> and
4502 the server's hostname will appear to be C<localhost> regardless of the
4503 virtual host that the user connected through.
4505 Catalyst will automatically detect this situation when you are running
4506 the frontend and backend servers on the same machine. The following
4507 changes are made to the request.
4509 $c->req->address is set to the user's real IP address, as read from
4510 the HTTP X-Forwarded-For header.
4512 The host value for $c->req->base and $c->req->uri is set to the real
4513 host, as read from the HTTP X-Forwarded-Host header.
4515 Additionally, you may be running your backend application on an insecure
4516 connection (port 80) while your frontend proxy is running under SSL. If there
4517 is a discrepancy in the ports, use the HTTP header C<X-Forwarded-Port> to
4518 tell Catalyst what port the frontend listens on. This will allow all URIs to
4519 be created properly.
4521 In the case of passing in:
4523 X-Forwarded-Port: 443
4525 All calls to C<uri_for> will result in an https link, as is expected.
4527 Obviously, your web server must support these headers for this to work.
4529 In a more complex server farm environment where you may have your
4530 frontend proxy server(s) on different machines, you will need to set a
4531 configuration option to tell Catalyst to read the proxied data from the
4534 MyApp->config(using_frontend_proxy => 1);
4536 If you do not wish to use the proxy support at all, you may set:
4538 MyApp->config(ignore_frontend_proxy => 0);
4540 =head2 Note about psgi files
4542 Note that if you supply your own .psgi file, calling
4543 C<< MyApp->psgi_app(@_); >>, then B<this will not happen automatically>.
4545 You either need to apply L<Plack::Middleware::ReverseProxy> yourself
4546 in your psgi, for example:
4549 enable "Plack::Middleware::ReverseProxy";
4553 This will unconditionally add the ReverseProxy support, or you need to call
4554 C<< $app = MyApp->apply_default_middlewares($app) >> (to conditionally
4555 apply the support depending upon your config).
4557 See L<Catalyst::PSGI> for more information.
4559 =head1 THREAD SAFETY
4561 Catalyst has been tested under Apache 2's threading C<mpm_worker>,
4562 C<mpm_winnt>, and the standalone forking HTTP server on Windows. We
4563 believe the Catalyst core to be thread-safe.
4565 If you plan to operate in a threaded environment, remember that all other
4566 modules you are using must also be thread-safe. Some modules, most notably
4567 L<DBD::SQLite>, are not thread-safe.
4569 =head1 DATA HANDLERS
4571 The L<Catalyst::Request> object uses L<HTTP::Body> to populate 'classic' HTML
4572 form parameters and URL search query fields. However it has become common
4573 for various alternative content types to be PUT or POSTed to your controllers
4574 and actions. People working on RESTful APIs, or using AJAX often use JSON,
4575 XML and other content types when communicating with an application server. In
4576 order to better support this use case, L<Catalyst> defines a global configuration
4577 option, C<data_handlers>, which lets you associate a content type with a coderef
4578 that parses that content type into something Perl can readily access.
4585 __PACKAGE__->config(
4587 'application/json' => sub { local $/; decode_json $_->getline },
4589 ## Any other configuration.
4594 By default L<Catalyst> comes with a generic JSON data handler similar to the
4595 example given above, which uses L<JSON::Maybe> to provide either L<JSON::PP>
4596 (a pure Perl, dependency free JSON parser) or L<Cpanel::JSON::XS> if you have
4597 it installed (if you want the faster XS parser, add it to you project Makefile.PL
4598 or dist.ini, cpanfile, etc.)
4600 The C<data_handlers> configuration is a hashref whose keys are HTTP Content-Types
4601 (matched against the incoming request type using a regexp such as to be case
4602 insensitive) and whose values are coderefs that receive a localized version of
4603 C<$_> which is a filehandle object pointing to received body.
4605 This feature is considered an early access release and we reserve the right
4606 to alter the interface in order to provide a performant and secure solution to
4607 alternative request body content. Your reports welcomed!
4609 =head1 PSGI MIDDLEWARE
4611 You can define middleware, defined as L<Plack::Middleware> or a compatible
4612 interface in configuration. Your middleware definitions are in the form of an
4613 arrayref under the configuration key C<psgi_middleware>. Here's an example
4614 with details to follow:
4619 use Plack::Middleware::StackTrace;
4621 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
4623 __PACKAGE__->config(
4624 'psgi_middleware', [
4627 $stacktrace_middleware,
4628 'Session' => {store => 'File'},
4633 $env->{myapp.customkey} = 'helloworld';
4642 So the general form is:
4644 __PACKAGE__->config(psgi_middleware => \@middleware_definitions);
4646 Where C<@middleware> is one or more of the following, applied in the REVERSE of
4647 the order listed (to make it function similarly to L<Plack::Builder>:
4649 Alternatively, you may also define middleware by calling the L</setup_middleware>
4656 __PACKAGE__->setup_middleware( \@middleware_definitions);
4659 In the case where you do both (use 'setup_middleware' and configuration) the
4660 package call to setup_middleware will be applied earlier (in other words its
4661 middleware will wrap closer to the application). Keep this in mind since in
4662 some cases the order of middleware is important.
4664 The two approaches are not exclusive.
4668 =item Middleware Object
4670 An already initialized object that conforms to the L<Plack::Middleware>
4673 my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
4675 __PACKAGE__->config(
4676 'psgi_middleware', [
4677 $stacktrace_middleware,
4683 A coderef that is an inlined middleware:
4685 __PACKAGE__->config(
4686 'psgi_middleware', [
4691 if($env->{PATH_INFO} =~m/forced/) {
4693 ->new(file=>TestApp->path_to(qw/share static forced.txt/))
4696 return $app->($env);
4706 We assume the scalar refers to a namespace after normalizing it using the
4709 (1) If the scalar is prefixed with a "+" (as in C<+MyApp::Foo>) then the full string
4710 is assumed to be 'as is', and we just install and use the middleware.
4712 (2) If the scalar begins with "Plack::Middleware" or your application namespace
4713 (the package name of your Catalyst application subclass), we also assume then
4714 that it is a full namespace, and use it.
4716 (3) Lastly, we then assume that the scalar is a partial namespace, and attempt to
4717 resolve it first by looking for it under your application namespace (for example
4718 if you application is "MyApp::Web" and the scalar is "MyMiddleware", we'd look
4719 under "MyApp::Web::Middleware::MyMiddleware") and if we don't find it there, we
4720 will then look under the regular L<Plack::Middleware> namespace (i.e. for the
4721 previous we'd try "Plack::Middleware::MyMiddleware"). We look under your application
4722 namespace first to let you 'override' common L<Plack::Middleware> locally, should
4723 you find that a good idea.
4729 __PACKAGE__->config(
4730 'psgi_middleware', [
4731 'Debug', ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap
4732 'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap
4733 '+MyApp::Custom', ## MyApp::Custom->wrap
4737 =item a scalar followed by a hashref
4739 Just like the previous, except the following C<HashRef> is used as arguments
4740 to initialize the middleware object.
4742 __PACKAGE__->config(
4743 'psgi_middleware', [
4744 'Session' => {store => 'File'},
4749 Please see L<PSGI> for more on middleware.
4753 Starting in L<Catalyst> version 5.90080 encoding is automatically enabled
4754 and set to encode all body responses to UTF8 when possible and applicable.
4755 Following is documentation on this process. If you are using an older
4756 version of L<Catalyst> you should review documentation for that version since
4759 By default encoding is now 'UTF-8'. You may turn it off by setting
4760 the encoding configuration to undef.
4762 MyApp->config(encoding => undef);
4764 This is recommended for temporary backwards compatibility only.
4766 Encoding is automatically applied when the content-type is set to
4767 a type that can be encoded. Currently we encode when the content type
4768 matches the following regular expression:
4770 $content_type =~ /^text|xml$|javascript$/
4772 Encoding is set on the application, but it is copied to the context object
4773 so that you can override it on a request basis.
4775 Be default we don't automatically encode 'application/json' since the most
4776 common approaches to generating this type of response (Either via L<Catalyst::View::JSON>
4777 or L<Catalyst::Action::REST>) will do so already and we want to avoid double
4780 If you are producing JSON response in an unconventional manner (such
4781 as via a template or manual strings) you should perform the UTF8 encoding
4782 manually as well such as to conform to the JSON specification.
4784 NOTE: We also examine the value of $c->response->content_encoding. If
4785 you set this (like for example 'gzip', and manually gzipping the body)
4786 we assume that you have done all the necessary encoding yourself, since
4787 we cannot encode the gzipped contents. If you use a plugin like
4788 L<Catalyst::Plugin::Compress> you need to update to a modern version in order
4789 to have this function correctly with the new UTF8 encoding code, or you
4790 can use L<Plack::Middleware::Deflater> or (probably best) do your compression on
4799 Returns an instance of an C<Encode> encoding
4801 print $c->encoding->name
4803 =item handle_unicode_encoding_exception ($exception_context)
4805 Method called when decoding process for a request fails.
4807 An C<$exception_context> hashref is provided to allow you to override the
4808 behaviour of your application when given data with incorrect encodings.
4810 The default method throws exceptions in the case of invalid request parameters
4811 (resulting in a 500 error), but ignores errors in upload filenames.
4813 The keys passed in the C<$exception_context> hash are:
4819 The value which was not able to be decoded.
4823 The exception received from L<Encode>.
4827 What type of data was being decoded. Valid values are (currently)
4828 C<params> - for request parameters / arguments / captures
4829 and C<uploads> - for request upload filenames.
4839 Join #catalyst on irc.perl.org.
4843 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
4844 http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
4848 http://catalyst.perl.org
4852 http://dev.catalyst.perl.org
4856 =head2 L<Task::Catalyst> - All you need to start with Catalyst
4858 =head2 L<Catalyst::Manual> - The Catalyst Manual
4860 =head2 L<Catalyst::Component>, L<Catalyst::Controller> - Base classes for components
4862 =head2 L<Catalyst::Engine> - Core engine
4864 =head2 L<Catalyst::Log> - Log class.
4866 =head2 L<Catalyst::Request> - Request object
4868 =head2 L<Catalyst::Response> - Response object
4870 =head2 L<Catalyst::Test> - The test suite.
4872 =head1 PROJECT FOUNDER
4874 sri: Sebastian Riedel <sri@cpan.org>
4880 acme: Leon Brocard <leon@astray.com>
4882 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
4884 andrewalker: André Walker <andre@cpan.org>
4888 Andrew Ford E<lt>A.Ford@ford-mason.co.ukE<gt>
4892 andyg: Andy Grundman <andy@hybridized.org>
4894 audreyt: Audrey Tang
4896 bricas: Brian Cassidy <bricas@cpan.org>
4898 Caelum: Rafael Kitover <rkitover@io.com>
4900 chansen: Christian Hansen
4902 Chase Venters C<chase.venters@gmail.com>
4904 chicks: Christopher Hicks
4906 Chisel Wright C<pause@herlpacker.co.uk>
4908 Danijel Milicevic C<me@danijel.de>
4910 davewood: David Schmidt <davewood@cpan.org>
4912 David Kamholz E<lt>dkamholz@cpan.orgE<gt>
4914 David Naughton, C<naughton@umn.edu>
4918 dhoss: Devin Austin <dhoss@cpan.org>
4920 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
4924 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
4926 esskar: Sascha Kiefer
4928 fireartist: Carl Franks <cfranks@cpan.org>
4930 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
4932 gabb: Danijel Milicevic
4936 Gavin Henry C<ghenry@perl.me.uk>
4940 groditi: Guillermo Roditi <groditi@gmail.com>
4942 hobbs: Andrew Rodland <andrew@cleverdomain.org>
4944 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
4946 jcamacho: Juan Camacho
4948 jester: Jesse Sheidlower C<jester@panix.com>
4950 jhannah: Jay Hannah <jay@jays.net>
4956 jon: Jon Schutz <jjschutz@cpan.org>
4958 Jonathan Rockway C<< <jrockway@cpan.org> >>
4960 Kieren Diment C<kd@totaldatasolution.com>
4962 konobi: Scott McWhirter <konobi@cpan.org>
4964 marcus: Marcus Ramberg <mramberg@cpan.org>
4966 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
4968 mgrimes: Mark Grimes <mgrimes@cpan.org>
4970 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
4974 naughton: David Naughton
4976 ningu: David Kamholz <dkamholz@cpan.org>
4978 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
4980 numa: Dan Sully <daniel@cpan.org>
4986 omega: Andreas Marienborg
4988 Oleg Kostyuk <cub.uanic@gmail.com>
4990 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
4992 rafl: Florian Ragwitz <rafl@debian.org>
4994 random: Roland Lammel <lammel@cpan.org>
4996 Robert Sedlacek C<< <rs@474.at> >>
4998 SpiceMan: Marcel Montes
5002 szbalint: Balint Szilakszi <szbalint@cpan.org>
5004 t0m: Tomas Doran <bobtfish@bobtfish.net>
5008 vanstyn: Henry Van Styn <vanstyn@cpan.org>
5010 Viljo Marrandi C<vilts@yahoo.com>
5012 Will Hawes C<info@whawes.co.uk>
5014 willert: Sebastian Willert <willert@cpan.org>
5016 wreis: Wallace Reis <wreis@cpan.org>
5018 Yuval Kogman, C<nothingmuch@woobling.org>
5020 rainboxx: Matthias Dietrich, C<perl@rainboxx.de>
5022 dd070: Dhaval Dhanani <dhaval070@gmail.com>
5024 Upasana <me@upasana.me>
5026 John Napiorkowski (jnap) <jjnapiork@cpan.org>
5030 Copyright (c) 2005-2015, the above named PROJECT FOUNDER and CONTRIBUTORS.
5034 This library is free software. You can redistribute it and/or modify it under
5035 the same terms as Perl itself.
5041 __PACKAGE__->meta->make_immutable;