lib/Catalyst.pm

   1 package Catalyst;
   2
   3 use Moose;
   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;
  11 use Catalyst::Log;
  12 use Catalyst::Request;
  13 use Catalyst::Request::Upload;
  14 use Catalyst::Response;
  15 use Catalyst::Utils;
  16 use Catalyst::Controller;
  17 use Data::OptList;
  18 use Devel::InnerPackage ();
  19 use Module::Pluggable::Object ();
  20 use Text::SimpleTable ();
  21 use Path::Class::Dir ();
  22 use Path::Class::File ();
  23 use URI ();
  24 use URI::http;
  25 use URI::https;
  26 use HTML::Entities;
  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/;
  31 use attributes;
  32 use String::RewritePrefix;
  33 use Catalyst::EngineLoader;
  34 use utf8;
  35 use Carp qw/croak carp shortmess/;
  36 use Try::Tiny;
  37 use Safe::Isa;
  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;
  51 use Plack::Util;
  52 use Class::Load 'load_class';
  53 use Encode 2.21 'decode_utf8', 'encode_utf8';
  54
  55 BEGIN { require 5.008003; }
  56
  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 { {} });
  62 has request => (
  63     is => 'rw',
  64     default => sub {
  65         my $self = shift;
  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);
  69     },
  70     lazy => 1,
  71 );
  72 sub _build_request_constructor_args {
  73     my $self = shift;
  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};
  79     \%p;
  80 }
  81
  82 sub composed_request_class {
  83   my $class = shift;
  84   return $class->_composed_request_class ||
  85     $class->_composed_request_class(Moose::Util::with_traits($class->request_class, @{$class->request_class_traits||[]}));
  86 }
  87
  88 has response => (
  89     is => 'rw',
  90     default => sub {
  91         my $self = shift;
  92         my $class = ref $self;
  93         my $composed_response_class = $class->composed_response_class;
  94         return $composed_response_class->new( $self->_build_response_constructor_args);
  95     },
  96     lazy => 1,
  97 );
  98 sub _build_response_constructor_args {
  99     return +{
 100       _log => $_[0]->log,
 101       encoding => $_[0]->encoding,
 102     };
 103 }
 104
 105 sub composed_response_class {
 106   my $class = shift;
 107   return $class->_composed_response_class ||
 108     $class->_composed_response_class(Moose::Util::with_traits($class->response_class, @{$class->response_class_traits||[]}));
 109 }
 110
 111 has namespace => (is => 'rw');
 112
 113 sub depth { scalar @{ shift->stack || [] }; }
 114 sub comp { shift->component(@_) }
 115
 116 sub req {
 117     my $self = shift; return $self->request(@_);
 118 }
 119 sub res {
 120     my $self = shift; return $self->response(@_);
 121 }
 122
 123 # For backwards compatibility
 124 sub finalize_output { shift->finalize_body(@_) };
 125
 126 # For statistics
 127 our $COUNT     = 1;
 128 our $START     = time;
 129 our $RECURSION = 1000;
 130 our $DETACH    = Catalyst::Exception::Detach->new;
 131 our $GO        = Catalyst::Exception::Go->new;
 132
 133 #I imagine that very few of these really need to be class variables. if any.
 134 #maybe we should just make them attributes with a default?
 135 __PACKAGE__->mk_classdata($_)
 136   for qw/components arguments dispatcher engine log dispatcher_class
 137   engine_loader context_class request_class response_class stats_class
 138   setup_finished _psgi_app loading_psgi_file run_options _psgi_middleware
 139   _data_handlers _encoding _encode_check finalized_default_middleware
 140   request_class_traits response_class_traits stats_class_traits
 141   _composed_request_class _composed_response_class _composed_stats_class/;
 142
 143 __PACKAGE__->dispatcher_class('Catalyst::Dispatcher');
 144 __PACKAGE__->request_class('Catalyst::Request');
 145 __PACKAGE__->response_class('Catalyst::Response');
 146 __PACKAGE__->stats_class('Catalyst::Stats');
 147
 148 sub composed_stats_class {
 149   my $class = shift;
 150   return $class->_composed_stats_class ||
 151     $class->_composed_stats_class(Moose::Util::with_traits($class->stats_class, @{$class->stats_class_traits||[]}));
 152 }
 153
 154 __PACKAGE__->_encode_check(Encode::FB_CROAK | Encode::LEAVE_SRC);
 155
 156 # Remember to update this in Catalyst::Runtime as well!
 157 our $VERSION = '5.90089_001';
 158 $VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
 159
 160 sub import {
 161     my ( $class, @arguments ) = @_;
 162
 163     # We have to limit $class to Catalyst to avoid pushing Catalyst upon every
 164     # callers @ISA.
 165     return unless $class eq 'Catalyst';
 166
 167     my $caller = caller();
 168     return if $caller eq 'main';
 169
 170     my $meta = Moose::Meta::Class->initialize($caller);
 171     unless ( $caller->isa('Catalyst') ) {
 172         my @superclasses = ($meta->superclasses, $class, 'Catalyst::Controller');
 173         $meta->superclasses(@superclasses);
 174     }
 175     # Avoid possible C3 issues if 'Moose::Object' is already on RHS of MyApp
 176     $meta->superclasses(grep { $_ ne 'Moose::Object' } $meta->superclasses);
 177
 178     unless( $meta->has_method('meta') ){
 179         if ($Moose::VERSION >= 1.15) {
 180             $meta->_add_meta_method('meta');
 181         }
 182         else {
 183             $meta->add_method(meta => sub { Moose::Meta::Class->initialize("${caller}") } );
 184         }
 185     }
 186
 187     $caller->arguments( [@arguments] );
 188     $caller->setup_home;
 189 }
 190
 191 sub _application { $_[0] }
 192
 193 =encoding UTF-8
 194
 195 =head1 NAME
 196
 197 Catalyst - The Elegant MVC Web Application Framework
 198
 199 =head1 SYNOPSIS
 200
 201 See the L<Catalyst::Manual> distribution for comprehensive
 202 documentation and tutorials.
 203
 204     # Install Catalyst::Devel for helpers and other development tools
 205     # use the helper to create a new application
 206     catalyst.pl MyApp
 207
 208     # add models, views, controllers
 209     script/myapp_create.pl model MyDatabase DBIC::Schema create=static dbi:SQLite:/path/to/db
 210     script/myapp_create.pl view MyTemplate TT
 211     script/myapp_create.pl controller Search
 212
 213     # built in testserver -- use -r to restart automatically on changes
 214     # --help to see all available options
 215     script/myapp_server.pl
 216
 217     # command line testing interface
 218     script/myapp_test.pl /yada
 219
 220     ### in lib/MyApp.pm
 221     use Catalyst qw/-Debug/; # include plugins here as well
 222
 223     ### In lib/MyApp/Controller/Root.pm (autocreated)
 224     sub foo : Chained('/') Args() { # called for /foo, /foo/1, /foo/1/2, etc.
 225         my ( $self, $c, @args ) = @_; # args are qw/1 2/ for /foo/1/2
 226         $c->stash->{template} = 'foo.tt'; # set the template
 227         # lookup something from db -- stash vars are passed to TT
 228         $c->stash->{data} =
 229           $c->model('Database::Foo')->search( { country => $args[0] } );
 230         if ( $c->req->params->{bar} ) { # access GET or POST parameters
 231             $c->forward( 'bar' ); # process another action
 232             # do something else after forward returns
 233         }
 234     }
 235
 236     # The foo.tt TT template can use the stash data from the database
 237     [% WHILE (item = data.next) %]
 238         [% item.foo %]
 239     [% END %]
 240
 241     # called for /bar/of/soap, /bar/of/soap/10, etc.
 242     sub bar : Chained('/') PathPart('/bar/of/soap') Args() { ... }
 243
 244     # called after all actions are finished
 245     sub end : Action {
 246         my ( $self, $c ) = @_;
 247         if ( scalar @{ $c->error } ) { ... } # handle errors
 248         return if $c->res->body; # already have a response
 249         $c->forward( 'MyApp::View::TT' ); # render template
 250     }
 251
 252 See L<Catalyst::Manual::Intro> for additional information.
 253
 254 =head1 DESCRIPTION
 255
 256 Catalyst is a modern framework for making web applications without the
 257 pain usually associated with this process. This document is a reference
 258 to the main Catalyst application. If you are a new user, we suggest you
 259 start with L<Catalyst::Manual::Tutorial> or L<Catalyst::Manual::Intro>.
 260
 261 See L<Catalyst::Manual> for more documentation.
 262
 263 Catalyst plugins can be loaded by naming them as arguments to the "use
 264 Catalyst" statement. Omit the C<Catalyst::Plugin::> prefix from the
 265 plugin name, i.e., C<Catalyst::Plugin::My::Module> becomes
 266 C<My::Module>.
 267
 268     use Catalyst qw/My::Module/;
 269
 270 If your plugin starts with a name other than C<Catalyst::Plugin::>, you can
 271 fully qualify the name by using a unary plus:
 272
 273     use Catalyst qw/
 274         My::Module
 275         +Fully::Qualified::Plugin::Name
 276     /;
 277
 278 Special flags like C<-Debug> can also be specified as
 279 arguments when Catalyst is loaded:
 280
 281     use Catalyst qw/-Debug My::Module/;
 282
 283 The position of plugins and flags in the chain is important, because
 284 they are loaded in the order in which they appear.
 285
 286 The following flags are supported:
 287
 288 =head2 -Debug
 289
 290 Enables debug output. You can also force this setting from the system
 291 environment with CATALYST_DEBUG or <MYAPP>_DEBUG. The environment
 292 settings override the application, with <MYAPP>_DEBUG having the highest
 293 priority.
 294
 295 This sets the log level to 'debug' and enables full debug output on the
 296 error screen. If you only want the latter, see L<< $c->debug >>.
 297
 298 =head2 -Home
 299
 300 Forces Catalyst to use a specific home directory, e.g.:
 301
 302     use Catalyst qw[-Home=/usr/mst];
 303
 304 This can also be done in the shell environment by setting either the
 305 C<CATALYST_HOME> environment variable or C<MYAPP_HOME>; where C<MYAPP>
 306 is replaced with the uppercased name of your application, any "::" in
 307 the name will be replaced with underscores, e.g. MyApp::Web should use
 308 MYAPP_WEB_HOME. If both variables are set, the MYAPP_HOME one will be used.
 309
 310 If none of these are set, Catalyst will attempt to automatically detect the
 311 home directory. If you are working in a development environment, Catalyst
 312 will try and find the directory containing either Makefile.PL, Build.PL,
 313 dist.ini, or cpanfile. If the application has been installed into the system
 314 (i.e. you have done C<make install>), then Catalyst will use the path to your
 315 application module, without the .pm extension (e.g., /foo/MyApp if your
 316 application was installed at /foo/MyApp.pm)
 317
 318 =head2 -Log
 319
 320     use Catalyst '-Log=warn,fatal,error';
 321
 322 Specifies a comma-delimited list of log levels.
 323
 324 =head2 -Stats
 325
 326 Enables statistics collection and reporting.
 327
 328    use Catalyst qw/-Stats=1/;
 329
 330 You can also force this setting from the system environment with CATALYST_STATS
 331 or <MYAPP>_STATS. The environment settings override the application, with
 332 <MYAPP>_STATS having the highest priority.
 333
 334 Stats are also enabled if L<< debugging |/"-Debug" >> is enabled.
 335
 336 =head1 METHODS
 337
 338 =head2 INFORMATION ABOUT THE CURRENT REQUEST
 339
 340 =head2 $c->action
 341
 342 Returns a L<Catalyst::Action> object for the current action, which
 343 stringifies to the action name. See L<Catalyst::Action>.
 344
 345 =head2 $c->namespace
 346
 347 Returns the namespace of the current action, i.e., the URI prefix
 348 corresponding to the controller of the current action. For example:
 349
 350     # in Controller::Foo::Bar
 351     $c->namespace; # returns 'foo/bar';
 352
 353 =head2 $c->request
 354
 355 =head2 $c->req
 356
 357 Returns the current L<Catalyst::Request> object, giving access to
 358 information about the current client request (including parameters,
 359 cookies, HTTP headers, etc.). See L<Catalyst::Request>.
 360
 361 =head2 REQUEST FLOW HANDLING
 362
 363 =head2 $c->forward( $action [, \@arguments ] )
 364
 365 =head2 $c->forward( $class, $method, [, \@arguments ] )
 366
 367 This is one way of calling another action (method) in the same or
 368 a different controller. You can also use C<< $self->my_method($c, @args) >>
 369 in the same controller or C<< $c->controller('MyController')->my_method($c, @args) >>
 370 in a different controller.
 371 The main difference is that 'forward' uses some of the Catalyst request
 372 cycle overhead, including debugging, which may be useful to you. On the
 373 other hand, there are some complications to using 'forward', restrictions
 374 on values returned from 'forward', and it may not handle errors as you prefer.
 375 Whether you use 'forward' or not is up to you; it is not considered superior to
 376 the other ways to call a method.
 377
 378 'forward' calls  another action, by its private name. If you give a
 379 class name but no method, C<process()> is called. You may also optionally
 380 pass arguments in an arrayref. The action will receive the arguments in
 381 C<@_> and C<< $c->req->args >>. Upon returning from the function,
 382 C<< $c->req->args >> will be restored to the previous values.
 383
 384 Any data C<return>ed from the action forwarded to, will be returned by the
 385 call to forward.
 386
 387     my $foodata = $c->forward('/foo');
 388     $c->forward('index');
 389     $c->forward(qw/Model::DBIC::Foo do_stuff/);
 390     $c->forward('View::TT');
 391
 392 Note that L<< forward|/"$c->forward( $action [, \@arguments ] )" >> implies
 393 an C<< eval { } >> around the call (actually
 394 L<< execute|/"$c->execute( $class, $coderef )" >> does), thus rendering all
 395 exceptions thrown by the called action non-fatal and pushing them onto
 396 $c->error instead. If you want C<die> to propagate you need to do something
 397 like:
 398
 399     $c->forward('foo');
 400     die join "\n", @{ $c->error } if @{ $c->error };
 401
 402 Or make sure to always return true values from your actions and write
 403 your code like this:
 404
 405     $c->forward('foo') || return;
 406
 407 Another note is that C<< $c->forward >> always returns a scalar because it
 408 actually returns $c->state which operates in a scalar context.
 409 Thus, something like:
 410
 411     return @array;
 412
 413 in an action that is forwarded to is going to return a scalar,
 414 i.e. how many items are in that array, which is probably not what you want.
 415 If you need to return an array then return a reference to it,
 416 or stash it like so:
 417
 418     $c->stash->{array} = \@array;
 419
 420 and access it from the stash.
 421
 422 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.
 423
 424 =cut
 425
 426 sub forward { my $c = shift; no warnings 'recursion'; $c->dispatcher->forward( $c, @_ ) }
 427
 428 =head2 $c->detach( $action [, \@arguments ] )
 429
 430 =head2 $c->detach( $class, $method, [, \@arguments ] )
 431
 432 =head2 $c->detach()
 433
 434 The same as L<< forward|/"$c->forward( $action [, \@arguments ] )" >>, but
 435 doesn't return to the previous action when processing is finished.
 436
 437 When called with no arguments it escapes the processing chain entirely.
 438
 439 =cut
 440
 441 sub detach { my $c = shift; $c->dispatcher->detach( $c, @_ ) }
 442
 443 =head2 $c->visit( $action [, \@arguments ] )
 444
 445 =head2 $c->visit( $action [, \@captures, \@arguments ] )
 446
 447 =head2 $c->visit( $class, $method, [, \@arguments ] )
 448
 449 =head2 $c->visit( $class, $method, [, \@captures, \@arguments ] )
 450
 451 Almost the same as L<< forward|/"$c->forward( $action [, \@arguments ] )" >>,
 452 but does a full dispatch, instead of just calling the new C<$action> /
 453 C<< $class->$method >>. This means that C<begin>, C<auto> and the method
 454 you go to are called, just like a new request.
 455
 456 In addition both C<< $c->action >> and C<< $c->namespace >> are localized.
 457 This means, for example, that C<< $c->action >> methods such as
 458 L<name|Catalyst::Action/name>, L<class|Catalyst::Action/class> and
 459 L<reverse|Catalyst::Action/reverse> return information for the visited action
 460 when they are invoked within the visited action.  This is different from the
 461 behavior of L<< forward|/"$c->forward( $action [, \@arguments ] )" >>, which
 462 continues to use the $c->action object from the caller action even when
 463 invoked from the called action.
 464
 465 C<< $c->stash >> is kept unchanged.
 466
 467 In effect, L<< visit|/"$c->visit( $action [, \@captures, \@arguments ] )" >>
 468 allows you to "wrap" another action, just as it would have been called by
 469 dispatching from a URL, while the analogous
 470 L<< go|/"$c->go( $action [, \@captures, \@arguments ] )" >> allows you to
 471 transfer control to another action as if it had been reached directly from a URL.
 472
 473 =cut
 474
 475 sub visit { my $c = shift; $c->dispatcher->visit( $c, @_ ) }
 476
 477 =head2 $c->go( $action [, \@arguments ] )
 478
 479 =head2 $c->go( $action [, \@captures, \@arguments ] )
 480
 481 =head2 $c->go( $class, $method, [, \@arguments ] )
 482
 483 =head2 $c->go( $class, $method, [, \@captures, \@arguments ] )
 484
 485 The relationship between C<go> and
 486 L<< visit|/"$c->visit( $action [, \@captures, \@arguments ] )" >> is the same as
 487 the relationship between
 488 L<< forward|/"$c->forward( $class, $method, [, \@arguments ] )" >> and
 489 L<< detach|/"$c->detach( $action [, \@arguments ] )" >>. Like C<< $c->visit >>,
 490 C<< $c->go >> will perform a full dispatch on the specified action or method,
 491 with localized C<< $c->action >> and C<< $c->namespace >>. Like C<detach>,
 492 C<go> escapes the processing of the current request chain on completion, and
 493 does not return to its caller.
 494
 495 @arguments are arguments to the final destination of $action. @captures are
 496 arguments to the intermediate steps, if any, on the way to the final sub of
 497 $action.
 498
 499 =cut
 500
 501 sub go { my $c = shift; $c->dispatcher->go( $c, @_ ) }
 502
 503 =head2 $c->response
 504
 505 =head2 $c->res
 506
 507 Returns the current L<Catalyst::Response> object, see there for details.
 508
 509 =head2 $c->stash
 510
 511 Returns a hashref to the stash, which may be used to store data and pass
 512 it between components during a request. You can also set hash keys by
 513 passing arguments. The stash is automatically sent to the view. The
 514 stash is cleared at the end of a request; it cannot be used for
 515 persistent storage (for this you must use a session; see
 516 L<Catalyst::Plugin::Session> for a complete system integrated with
 517 Catalyst).
 518
 519     $c->stash->{foo} = $bar;
 520     $c->stash( { moose => 'majestic', qux => 0 } );
 521     $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref
 522
 523     # stash is automatically passed to the view for use in a template
 524     $c->forward( 'MyApp::View::TT' );
 525
 526 The stash hash is currently stored in the PSGI C<$env> and is managed by
 527 L<Catalyst::Middleware::Stash>.  Since it's part of the C<$env> items in
 528 the stash can be accessed in sub applications mounted under your main
 529 L<Catalyst> application.  For example if you delegate the response of an
 530 action to another L<Catalyst> application, that sub application will have
 531 access to all the stash keys of the main one, and if can of course add
 532 more keys of its own.  However those new keys will not 'bubble' back up
 533 to the main application.
 534
 535 For more information the best thing to do is to review the test case:
 536 t/middleware-stash.t in the distribution /t directory.
 537
 538 =cut
 539
 540 sub stash {
 541   my $c = shift;
 542   return Catalyst::Middleware::Stash::get_stash($c->req->env)->(@_);
 543 }
 544
 545 =head2 $c->error
 546
 547 =head2 $c->error($error, ...)
 548
 549 =head2 $c->error($arrayref)
 550
 551 Returns an arrayref containing error messages.  If Catalyst encounters an
 552 error while processing a request, it stores the error in $c->error.  This
 553 method should only be used to store fatal error messages.
 554
 555     my @error = @{ $c->error };
 556
 557 Add a new error.
 558
 559     $c->error('Something bad happened');
 560
 561 Calling this will always return an arrayref (if there are no errors it
 562 will be an empty arrayref.
 563
 564 =cut
 565
 566 sub error {
 567     my $c = shift;
 568     if ( $_[0] ) {
 569         my $error = ref $_[0] eq 'ARRAY' ? $_[0] : [@_];
 570         croak @$error unless ref $c;
 571         push @{ $c->{error} }, @$error;
 572     }
 573     elsif ( defined $_[0] ) { $c->{error} = undef }
 574     return $c->{error} || [];
 575 }
 576
 577
 578 =head2 $c->state
 579
 580 Contains the return value of the last executed action.
 581 Note that << $c->state >> operates in a scalar context which means that all
 582 values it returns are scalar.
 583
 584 =head2 $c->clear_errors
 585
 586 Clear errors.  You probably don't want to clear the errors unless you are
 587 implementing a custom error screen.
 588
 589 This is equivalent to running
 590
 591     $c->error(0);
 592
 593 =cut
 594
 595 sub clear_errors {
 596     my $c = shift;
 597     $c->error(0);
 598 }
 599
 600 =head2 $c->has_errors
 601
 602 Returns true if you have errors
 603
 604 =cut
 605
 606 sub has_errors { scalar(@{shift->error}) ? 1:0 }
 607
 608 =head2 $c->last_error
 609
 610 Returns the most recent error in the stack (the one most recently added...)
 611 or nothing if there are no errors.
 612
 613 =cut
 614
 615 sub last_error { my ($err, @errs) = @{shift->error}; return $err }
 616
 617 =head2 shift_errors
 618
 619 shifts the most recently added error off the error stack and returns if.  Returns
 620 nothing if there are no more errors.
 621
 622 =cut
 623
 624 sub shift_errors {
 625     my ($self) = @_;
 626     my ($err, @errors) = @{$self->error};
 627     $self->{error} = \@errors;
 628     return $err;
 629 }
 630
 631 sub _comp_search_prefixes {
 632     my $c = shift;
 633     return map $c->components->{ $_ }, $c->_comp_names_search_prefixes(@_);
 634 }
 635
 636 # search components given a name and some prefixes
 637 sub _comp_names_search_prefixes {
 638     my ( $c, $name, @prefixes ) = @_;
 639     my $appclass = ref $c || $c;
 640     my $filter   = "^${appclass}::(" . join( '|', @prefixes ) . ')::';
 641     $filter = qr/$filter/; # Compile regex now rather than once per loop
 642
 643     # map the original component name to the sub part that we will search against
 644     my %eligible = map { my $n = $_; $n =~ s{^$appclass\::[^:]+::}{}; $_ => $n; }
 645         grep { /$filter/ } keys %{ $c->components };
 646
 647     # undef for a name will return all
 648     return keys %eligible if !defined $name;
 649
 650     my $query  = $name->$_isa('Regexp') ? $name : qr/^$name$/i;
 651     my @result = grep { $eligible{$_} =~ m{$query} } keys %eligible;
 652
 653     return @result if @result;
 654
 655     # if we were given a regexp to search against, we're done.
 656     return if $name->$_isa('Regexp');
 657
 658     # skip regexp fallback if configured
 659     return
 660         if $appclass->config->{disable_component_resolution_regex_fallback};
 661
 662     # regexp fallback
 663     $query  = qr/$name/i;
 664     @result = grep { $eligible{ $_ } =~ m{$query} } keys %eligible;
 665
 666     # no results? try against full names
 667     if( !@result ) {
 668         @result = grep { m{$query} } keys %eligible;
 669     }
 670
 671     # don't warn if we didn't find any results, it just might not exist
 672     if( @result ) {
 673         # Disgusting hack to work out correct method name
 674         my $warn_for = lc $prefixes[0];
 675         my $msg = "Used regexp fallback for \$c->${warn_for}('${name}'), which found '" .
 676            (join '", "', @result) . "'. Relying on regexp fallback behavior for " .
 677            "component resolution is unreliable and unsafe.";
 678         my $short = $result[0];
 679         # remove the component namespace prefix
 680         $short =~ s/.*?(Model|Controller|View):://;
 681         my $shortmess = Carp::shortmess('');
 682         if ($shortmess =~ m#Catalyst/Plugin#) {
 683            $msg .= " You probably need to set '$short' instead of '${name}' in this " .
 684               "plugin's config";
 685         } elsif ($shortmess =~ m#Catalyst/lib/(View|Controller)#) {
 686            $msg .= " You probably need to set '$short' instead of '${name}' in this " .
 687               "component's config";
 688         } else {
 689            $msg .= " You probably meant \$c->${warn_for}('$short') instead of \$c->${warn_for}('${name}'), " .
 690               "but if you really wanted to search, pass in a regexp as the argument " .
 691               "like so: \$c->${warn_for}(qr/${name}/)";
 692         }
 693         $c->log->warn( "${msg}$shortmess" );
 694     }
 695
 696     return @result;
 697 }
 698
 699 # Find possible names for a prefix
 700 sub _comp_names {
 701     my ( $c, @prefixes ) = @_;
 702     my $appclass = ref $c || $c;
 703
 704     my $filter = "^${appclass}::(" . join( '|', @prefixes ) . ')::';
 705
 706     my @names = map { s{$filter}{}; $_; }
 707         $c->_comp_names_search_prefixes( undef, @prefixes );
 708
 709     return @names;
 710 }
 711
 712 # Filter a component before returning by calling ACCEPT_CONTEXT if available
 713 sub _filter_component {
 714     my ( $c, $comp, @args ) = @_;
 715
 716     if(ref $comp eq 'CODE') {
 717       $comp = $comp->();
 718     }
 719
 720     if ( eval { $comp->can('ACCEPT_CONTEXT'); } ) {
 721         return $comp->ACCEPT_CONTEXT( $c, @args );
 722     }
 723
 724     $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;
 725
 726     return $comp;
 727 }
 728
 729 =head2 COMPONENT ACCESSORS
 730
 731 =head2 $c->controller($name)
 732
 733 Gets a L<Catalyst::Controller> instance by name.
 734
 735     $c->controller('Foo')->do_stuff;
 736
 737 If the name is omitted, will return the controller for the dispatched
 738 action.
 739
 740 If you want to search for controllers, pass in a regexp as the argument.
 741
 742     # find all controllers that start with Foo
 743     my @foo_controllers = $c->controller(qr{^Foo});
 744
 745
 746 =cut
 747
 748 sub controller {
 749     my ( $c, $name, @args ) = @_;
 750
 751     my $appclass = ref($c) || $c;
 752     if( $name ) {
 753         unless ( $name->$_isa('Regexp') ) { # Direct component hash lookup to avoid costly regexps
 754             my $comps = $c->components;
 755             my $check = $appclass."::Controller::".$name;
 756             return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
 757         }
 758         my @result = $c->_comp_search_prefixes( $name, qw/Controller C/ );
 759         return map { $c->_filter_component( $_, @args ) } @result if ref $name;
 760         return $c->_filter_component( $result[ 0 ], @args );
 761     }
 762
 763     return $c->component( $c->action->class );
 764 }
 765
 766 =head2 $c->model($name)
 767
 768 Gets a L<Catalyst::Model> instance by name.
 769
 770     $c->model('Foo')->do_stuff;
 771
 772 Any extra arguments are directly passed to ACCEPT_CONTEXT, if the model
 773 defines ACCEPT_CONTEXT.  If it does not, the args are discarded.
 774
 775 If the name is omitted, it will look for
 776  - a model object in $c->stash->{current_model_instance}, then
 777  - a model name in $c->stash->{current_model}, then
 778  - a config setting 'default_model', or
 779  - check if there is only one model, and return it if that's the case.
 780
 781 If you want to search for models, pass in a regexp as the argument.
 782
 783     # find all models that start with Foo
 784     my @foo_models = $c->model(qr{^Foo});
 785
 786 =cut
 787
 788 sub model {
 789     my ( $c, $name, @args ) = @_;
 790     my $appclass = ref($c) || $c;
 791     if( $name ) {
 792         unless ( $name->$_isa('Regexp') ) { # Direct component hash lookup to avoid costly regexps
 793             my $comps = $c->components;
 794             my $check = $appclass."::Model::".$name;
 795             return $c->_filter_component( $comps->{$check}, @args ) if exists $comps->{$check};
 796         }
 797         my @result = $c->_comp_search_prefixes( $name, qw/Model M/ );
 798         return map { $c->_filter_component( $_, @args ) } @result if ref $name;
 799         return $c->_filter_component( $result[ 0 ], @args );
 800     }
 801
 802     if (ref $c) {
 803         return $c->stash->{current_model_instance}
 804           if $c->stash->{current_model_instance};
 805         return $c->model( $c->stash->{current_model} )
 806           if $c->stash->{current_model};
 807     }
 808     return $c->model( $appclass->config->{default_model} )
 809       if $appclass->config->{default_model};
 810
 811     my( $comp, $rest ) = $c->_comp_search_prefixes( undef, qw/Model M/);
 812
 813     if( $rest ) {
 814         $c->log->warn( Carp::shortmess('Calling $c->model() will return a random model unless you specify one of:') );
 815         $c->log->warn( '* $c->config(default_model => "the name of the default model to use")' );
 816         $c->log->warn( '* $c->stash->{current_model} # the name of the model to use for this request' );
 817         $c->log->warn( '* $c->stash->{current_model_instance} # the instance of the model to use for this request' );
 818         $c->log->warn( 'NB: in version 5.81, the "random" behavior will not work at all.' );
 819     }
 820
 821     return $c->_filter_component( $comp );
 822 }
 823
 824
 825 =head2 $c->view($name)
 826
 827 Gets a L<Catalyst::View> instance by name.
 828
 829     $c->view('Foo')->do_stuff;
 830
 831 Any extra arguments are directly passed to ACCEPT_CONTEXT.
 832
 833 If the name is omitted, it will look for
 834  - a view object in $c->stash->{current_view_instance}, then
 835  - a view name in $c->stash->{current_view}, then
 836  - a config setting 'default_view', or
 837  - check if there is only one view, and return it if that's the case.
 838
 839 If you want to search for views, pass in a regexp as the argument.
 840
 841     # find all views that start with Foo
 842     my @foo_views = $c->view(qr{^Foo});
 843
 844 =cut
 845
 846 sub view {
 847     my ( $c, $name, @args ) = @_;
 848
 849     my $appclass = ref($c) || $c;
 850     if( $name ) {
 851         unless ( $name->$_isa('Regexp') ) { # Direct component hash lookup to avoid costly regexps
 852             my $comps = $c->components;
 853             my $check = $appclass."::View::".$name;
 854             if( exists $comps->{$check} ) {
 855                 return $c->_filter_component( $comps->{$check}, @args );
 856             }
 857             else {
 858                 $c->log->warn( "Attempted to use view '$check', but does not exist" );
 859             }
 860         }
 861         my @result = $c->_comp_search_prefixes( $name, qw/View V/ );
 862         return map { $c->_filter_component( $_, @args ) } @result if ref $name;
 863         return $c->_filter_component( $result[ 0 ], @args );
 864     }
 865
 866     if (ref $c) {
 867         return $c->stash->{current_view_instance}
 868           if $c->stash->{current_view_instance};
 869         return $c->view( $c->stash->{current_view} )
 870           if $c->stash->{current_view};
 871     }
 872     return $c->view( $appclass->config->{default_view} )
 873       if $appclass->config->{default_view};
 874
 875     my( $comp, $rest ) = $c->_comp_search_prefixes( undef, qw/View V/);
 876
 877     if( $rest ) {
 878         $c->log->warn( 'Calling $c->view() will return a random view unless you specify one of:' );
 879         $c->log->warn( '* $c->config(default_view => "the name of the default view to use")' );
 880         $c->log->warn( '* $c->stash->{current_view} # the name of the view to use for this request' );
 881         $c->log->warn( '* $c->stash->{current_view_instance} # the instance of the view to use for this request' );
 882         $c->log->warn( 'NB: in version 5.81, the "random" behavior will not work at all.' );
 883     }
 884
 885     return $c->_filter_component( $comp );
 886 }
 887
 888 =head2 $c->controllers
 889
 890 Returns the available names which can be passed to $c->controller
 891
 892 =cut
 893
 894 sub controllers {
 895     my ( $c ) = @_;
 896     return $c->_comp_names(qw/Controller C/);
 897 }
 898
 899 =head2 $c->models
 900
 901 Returns the available names which can be passed to $c->model
 902
 903 =cut
 904
 905 sub models {
 906     my ( $c ) = @_;
 907     return $c->_comp_names(qw/Model M/);
 908 }
 909
 910
 911 =head2 $c->views
 912
 913 Returns the available names which can be passed to $c->view
 914
 915 =cut
 916
 917 sub views {
 918     my ( $c ) = @_;
 919     return $c->_comp_names(qw/View V/);
 920 }
 921
 922 =head2 $c->comp($name)
 923
 924 =head2 $c->component($name)
 925
 926 Gets a component object by name. This method is not recommended,
 927 unless you want to get a specific component by full
 928 class. C<< $c->controller >>, C<< $c->model >>, and C<< $c->view >>
 929 should be used instead.
 930
 931 If C<$name> is a regexp, a list of components matched against the full
 932 component name will be returned.
 933
 934 If Catalyst can't find a component by name, it will fallback to regex
 935 matching by default. To disable this behaviour set
 936 disable_component_resolution_regex_fallback to a true value.
 937
 938     __PACKAGE__->config( disable_component_resolution_regex_fallback => 1 );
 939
 940 =cut
 941
 942 sub component {
 943     my ( $c, $name, @args ) = @_;
 944
 945     if( $name ) {
 946         my $comps = $c->components;
 947
 948         if( !ref $name ) {
 949             # is it the exact name?
 950             return $c->_filter_component( $comps->{ $name }, @args )
 951                        if exists $comps->{ $name };
 952
 953             # perhaps we just omitted "MyApp"?
 954             my $composed = ( ref $c || $c ) . "::${name}";
 955             return $c->_filter_component( $comps->{ $composed }, @args )
 956                        if exists $comps->{ $composed };
 957
 958             # search all of the models, views and controllers
 959             my( $comp ) = $c->_comp_search_prefixes( $name, qw/Model M Controller C View V/ );
 960             return $c->_filter_component( $comp, @args ) if $comp;
 961         }
 962
 963         return
 964             if $c->config->{disable_component_resolution_regex_fallback};
 965
 966         # This is here so $c->comp( '::M::' ) works
 967         my $query = ref $name ? $name : qr{$name}i;
 968
 969         my @result = grep { m{$query} } keys %{ $c->components };
 970         return map { $c->_filter_component( $_, @args ) } @result if ref $name;
 971
 972         if( $result[ 0 ] ) {
 973             $c->log->warn( Carp::shortmess(qq(Found results for "${name}" using regexp fallback)) );
 974             $c->log->warn( 'Relying on the regexp fallback behavior for component resolution' );
 975             $c->log->warn( 'is unreliable and unsafe. You have been warned' );
 976             return $c->_filter_component( $result[ 0 ], @args );
 977         }
 978
 979         # I would expect to return an empty list here, but that breaks back-compat
 980     }
 981
 982     # fallback
 983     return sort keys %{ $c->components };
 984 }
 985
 986 =head2 CLASS DATA AND HELPER CLASSES
 987
 988 =head2 $c->config
 989
 990 Returns or takes a hashref containing the application's configuration.
 991
 992     __PACKAGE__->config( { db => 'dsn:SQLite:foo.db' } );
 993
 994 You can also use a C<YAML>, C<XML> or L<Config::General> config file
 995 like C<myapp.conf> in your applications home directory. See
 996 L<Catalyst::Plugin::ConfigLoader>.
 997
 998 =head3 Cascading configuration
 999
1000 The config method is present on all Catalyst components, and configuration
1001 will be merged when an application is started. Configuration loaded with
1002 L<Catalyst::Plugin::ConfigLoader> takes precedence over other configuration,
1003 followed by configuration in your top level C<MyApp> class. These two
1004 configurations are merged, and then configuration data whose hash key matches a
1005 component name is merged with configuration for that component.
1006
1007 The configuration for a component is then passed to the C<new> method when a
1008 component is constructed.
1009
1010 For example:
1011
1012     MyApp->config({ 'Model::Foo' => { bar => 'baz', overrides => 'me' } });
1013     MyApp::Model::Foo->config({ quux => 'frob', overrides => 'this' });
1014
1015 will mean that C<MyApp::Model::Foo> receives the following data when
1016 constructed:
1017
1018     MyApp::Model::Foo->new({
1019         bar => 'baz',
1020         quux => 'frob',
1021         overrides => 'me',
1022     });
1023
1024 It's common practice to use a Moose attribute
1025 on the receiving component to access the config value.
1026
1027     package MyApp::Model::Foo;
1028
1029     use Moose;
1030
1031     # this attr will receive 'baz' at construction time
1032     has 'bar' => (
1033         is  => 'rw',
1034         isa => 'Str',
1035     );
1036
1037 You can then get the value 'baz' by calling $c->model('Foo')->bar
1038 (or $self->bar inside code in the model).
1039
1040 B<NOTE:> you MUST NOT call C<< $self->config >> or C<< __PACKAGE__->config >>
1041 as a way of reading config within your code, as this B<will not> give you the
1042 correctly merged config back. You B<MUST> take the config values supplied to
1043 the constructor and use those instead.
1044
1045 =cut
1046
1047 around config => sub {
1048     my $orig = shift;
1049     my $c = shift;
1050
1051     croak('Setting config after setup has been run is not allowed.')
1052         if ( @_ and $c->setup_finished );
1053
1054     $c->$orig(@_);
1055 };
1056
1057 =head2 $c->log
1058
1059 Returns the logging object instance. Unless it is already set, Catalyst
1060 sets this up with a L<Catalyst::Log> object. To use your own log class,
1061 set the logger with the C<< __PACKAGE__->log >> method prior to calling
1062 C<< __PACKAGE__->setup >>.
1063
1064  __PACKAGE__->log( MyLogger->new );
1065  __PACKAGE__->setup;
1066
1067 And later:
1068
1069     $c->log->info( 'Now logging with my own logger!' );
1070
1071 Your log class should implement the methods described in
1072 L<Catalyst::Log>.
1073
1074 =head2 has_encoding
1075
1076 Returned True if there's a valid encoding
1077
1078 =head2 clear_encoding
1079
1080 Clears the encoding for the current context
1081
1082 =head2 encoding
1083
1084 Sets or gets the application encoding.  Setting encoding takes either an
1085 Encoding object or a string that we try to resolve via L<Encode::find_encoding>.
1086
1087 You would expect to get the encoding object back if you attempt to set it.  If
1088 there is a failure you will get undef returned and an error message in the log.
1089
1090 =cut
1091
1092 sub has_encoding { shift->encoding ? 1:0 }
1093
1094 sub clear_encoding {
1095     my $c = shift;
1096     if(blessed $c) {
1097         $c->encoding(undef);
1098     } else {
1099         $c->log->error("You can't clear encoding on the application");
1100     }
1101 }
1102
1103 sub encoding {
1104     my $c = shift;
1105     my $encoding;
1106
1107     if ( scalar @_ ) {
1108
1109         # Don't let one change this once we are too far into the response
1110         if(blessed $c && $c->res->finalized_headers) {
1111           Carp::croak("You may not change the encoding once the headers are finalized");
1112           return;
1113         }
1114
1115         # Let it be set to undef
1116         if (my $wanted = shift)  {
1117             $encoding = Encode::find_encoding($wanted)
1118               or Carp::croak( qq/Unknown encoding '$wanted'/ );
1119             binmode(STDERR, ':encoding(' . $encoding->name . ')');
1120         }
1121         else {
1122             binmode(STDERR);
1123         }
1124
1125         $encoding = ref $c
1126                   ? $c->{encoding} = $encoding
1127                   : $c->_encoding($encoding);
1128     } else {
1129       $encoding = ref $c && exists $c->{encoding}
1130                 ? $c->{encoding}
1131                 : $c->_encoding;
1132     }
1133
1134     return $encoding;
1135 }
1136
1137 =head2 $c->debug
1138
1139 Returns 1 if debug mode is enabled, 0 otherwise.
1140
1141 You can enable debug mode in several ways:
1142
1143 =over
1144
1145 =item By calling myapp_server.pl with the -d flag
1146
1147 =item With the environment variables MYAPP_DEBUG, or CATALYST_DEBUG
1148
1149 =item The -Debug option in your MyApp.pm
1150
1151 =item By declaring C<sub debug { 1 }> in your MyApp.pm.
1152
1153 =back
1154
1155 The first three also set the log level to 'debug'.
1156
1157 Calling C<< $c->debug(1) >> has no effect.
1158
1159 =cut
1160
1161 sub debug { 0 }
1162
1163 =head2 $c->dispatcher
1164
1165 Returns the dispatcher instance. See L<Catalyst::Dispatcher>.
1166
1167 =head2 $c->engine
1168
1169 Returns the engine instance. See L<Catalyst::Engine>.
1170
1171
1172 =head2 UTILITY METHODS
1173
1174 =head2 $c->path_to(@path)
1175
1176 Merges C<@path> with C<< $c->config->{home} >> and returns a
1177 L<Path::Class::Dir> object. Note you can usually use this object as
1178 a filename, but sometimes you will have to explicitly stringify it
1179 yourself by calling the C<< ->stringify >> method.
1180
1181 For example:
1182
1183     $c->path_to( 'db', 'sqlite.db' );
1184
1185 =cut
1186
1187 sub path_to {
1188     my ( $c, @path ) = @_;
1189     my $path = Path::Class::Dir->new( $c->config->{home}, @path );
1190     if ( -d $path ) { return $path }
1191     else { return Path::Class::File->new( $c->config->{home}, @path ) }
1192 }
1193
1194 sub plugin {
1195     my ( $class, $name, $plugin, @args ) = @_;
1196
1197     # See block comment in t/unit_core_plugin.t
1198     $class->log->warn(qq/Adding plugin using the ->plugin method is deprecated, and will be removed in a future release/);
1199
1200     $class->_register_plugin( $plugin, 1 );
1201
1202     eval { $plugin->import };
1203     $class->mk_classdata($name);
1204     my $obj;
1205     eval { $obj = $plugin->new(@args) };
1206
1207     if ($@) {
1208         Catalyst::Exception->throw( message =>
1209               qq/Couldn't instantiate instant plugin "$plugin", "$@"/ );
1210     }
1211
1212     $class->$name($obj);
1213     $class->log->debug(qq/Initialized instant plugin "$plugin" as "$name"/)
1214       if $class->debug;
1215 }
1216
1217 =head2 MyApp->setup
1218
1219 Initializes the dispatcher and engine, loads any plugins, and loads the
1220 model, view, and controller components. You may also specify an array
1221 of plugins to load here, if you choose to not load them in the C<use
1222 Catalyst> line.
1223
1224     MyApp->setup;
1225     MyApp->setup( qw/-Debug/ );
1226
1227 B<Note:> You B<should not> wrap this method with method modifiers
1228 or bad things will happen - wrap the C<setup_finalize> method instead.
1229
1230 B<Note:> You can create a custom setup stage that will execute when the
1231 application is starting.  Use this to customize setup.
1232
1233     MyApp->setup(-Custom=value);
1234
1235     sub setup_custom {
1236       my ($class, $value) = @_;
1237     }
1238
1239 Can be handy if you want to hook into the setup phase.
1240
1241 =cut
1242
1243 sub setup {
1244     my ( $class, @arguments ) = @_;
1245     croak('Running setup more than once')
1246         if ( $class->setup_finished );
1247
1248     unless ( $class->isa('Catalyst') ) {
1249
1250         Catalyst::Exception->throw(
1251             message => qq/'$class' does not inherit from Catalyst/ );
1252     }
1253
1254     if ( $class->arguments ) {
1255         @arguments = ( @arguments, @{ $class->arguments } );
1256     }
1257
1258     # Process options
1259     my $flags = {};
1260
1261     foreach (@arguments) {
1262
1263         if (/^-Debug$/) {
1264             $flags->{log} =
1265               ( $flags->{log} ) ? 'debug,' . $flags->{log} : 'debug';
1266         }
1267         elsif (/^-(\w+)=?(.*)$/) {
1268             $flags->{ lc $1 } = $2;
1269         }
1270         else {
1271             push @{ $flags->{plugins} }, $_;
1272         }
1273     }
1274
1275     $class->setup_home( delete $flags->{home} );
1276
1277     $class->setup_log( delete $flags->{log} );
1278     $class->setup_plugins( delete $flags->{plugins} );
1279
1280     $class->setup_data_handlers();
1281     $class->setup_dispatcher( delete $flags->{dispatcher} );
1282     if (my $engine = delete $flags->{engine}) {
1283         $class->log->warn("Specifying the engine in ->setup is no longer supported, see Catalyst::Upgrading");
1284     }
1285     $class->setup_engine();
1286     $class->setup_stats( delete $flags->{stats} );
1287
1288     for my $flag ( sort keys %{$flags} ) {
1289
1290         if ( my $code = $class->can( 'setup_' . $flag ) ) {
1291             &$code( $class, delete $flags->{$flag} );
1292         }
1293         else {
1294             $class->log->warn(qq/Unknown flag "$flag"/);
1295         }
1296     }
1297
1298     eval { require Catalyst::Devel; };
1299     if( !$@ && $ENV{CATALYST_SCRIPT_GEN} && ( $ENV{CATALYST_SCRIPT_GEN} < $Catalyst::Devel::CATALYST_SCRIPT_GEN ) ) {
1300         $class->log->warn(<<"EOF");
1301 You are running an old script!
1302
1303   Please update by running (this will overwrite existing files):
1304     catalyst.pl -force -scripts $class
1305
1306   or (this will not overwrite existing files):
1307     catalyst.pl -scripts $class
1308
1309 EOF
1310     }
1311
1312     # Call plugins setup, this is stupid and evil.
1313     # Also screws C3 badly on 5.10, hack to avoid.
1314     {
1315         no warnings qw/redefine/;
1316         local *setup = sub { };
1317         $class->setup unless $Catalyst::__AM_RESTARTING;
1318     }
1319
1320     # If you are expecting configuration info as part of your setup, it needs
1321     # to get called here and below, since we need the above line to support
1322     # ConfigLoader based configs.
1323
1324     $class->setup_encoding();
1325     $class->setup_middleware();
1326
1327     # Initialize our data structure
1328     $class->components( {} );
1329
1330     $class->setup_components;
1331
1332     if ( $class->debug ) {
1333         my @plugins = map { "$_  " . ( $_->VERSION || '' ) } $class->registered_plugins;
1334
1335         if (@plugins) {
1336             my $column_width = Catalyst::Utils::term_width() - 6;
1337             my $t = Text::SimpleTable->new($column_width);
1338             $t->row($_) for @plugins;
1339             $class->log->debug( "Loaded plugins:\n" . $t->draw . "\n" );
1340         }
1341
1342         my @middleware = map {
1343           ref $_ eq 'CODE' ?
1344             "Inline Coderef" :
1345               (ref($_) .'  '. ($_->can('VERSION') ? $_->VERSION || '' : '')
1346                 || '')  } $class->registered_middlewares;
1347
1348         if (@middleware) {
1349             my $column_width = Catalyst::Utils::term_width() - 6;
1350             my $t = Text::SimpleTable->new($column_width);
1351             $t->row($_) for @middleware;
1352             $class->log->debug( "Loaded PSGI Middleware:\n" . $t->draw . "\n" );
1353         }
1354
1355         my %dh = $class->registered_data_handlers;
1356         if (my @data_handlers = keys %dh) {
1357             my $column_width = Catalyst::Utils::term_width() - 6;
1358             my $t = Text::SimpleTable->new($column_width);
1359             $t->row($_) for @data_handlers;
1360             $class->log->debug( "Loaded Request Data Handlers:\n" . $t->draw . "\n" );
1361         }
1362
1363         my $dispatcher = $class->dispatcher;
1364         my $engine     = $class->engine;
1365         my $home       = $class->config->{home};
1366
1367         $class->log->debug(sprintf(q/Loaded dispatcher "%s"/, blessed($dispatcher)));
1368         $class->log->debug(sprintf(q/Loaded engine "%s"/, blessed($engine)));
1369
1370         $home
1371           ? ( -d $home )
1372           ? $class->log->debug(qq/Found home "$home"/)
1373           : $class->log->debug(qq/Home "$home" doesn't exist/)
1374           : $class->log->debug(q/Couldn't find home/);
1375
1376         my $column_width = Catalyst::Utils::term_width() - 8 - 9;
1377         my $t = Text::SimpleTable->new( [ $column_width, 'Class' ], [ 8, 'Type' ] );
1378         for my $comp ( sort keys %{ $class->components } ) {
1379             my $type = ref $class->components->{$comp} ? 'instance' : 'class';
1380             $t->row( $comp, $type );
1381         }
1382         $class->log->debug( "Loaded components:\n" . $t->draw . "\n" )
1383           if ( keys %{ $class->components } );
1384     }
1385
1386     # Add our self to components, since we are also a component
1387     if( $class->isa('Catalyst::Controller') ){
1388       $class->components->{$class} = $class;
1389     }
1390
1391     $class->setup_actions;
1392
1393     if ( $class->debug ) {
1394         my $name = $class->config->{name} || 'Application';
1395         $class->log->info("$name powered by Catalyst $Catalyst::VERSION");
1396     }
1397
1398     if ($class->config->{case_sensitive}) {
1399         $class->log->warn($class . "->config->{case_sensitive} is set.");
1400         $class->log->warn("This setting is deprecated and planned to be removed in Catalyst 5.81.");
1401     }
1402
1403     $class->setup_finalize;
1404
1405     # Flush the log for good measure (in case something turned off 'autoflush' early)
1406     $class->log->_flush() if $class->log->can('_flush');
1407
1408     return $class || 1; # Just in case someone named their Application 0...
1409 }
1410
1411 =head2 $app->setup_finalize
1412
1413 A hook to attach modifiers to. This method does not do anything except set the
1414 C<setup_finished> accessor.
1415
1416 Applying method modifiers to the C<setup> method doesn't work, because of quirky things done for plugin setup.
1417
1418 Example:
1419
1420     after setup_finalize => sub {
1421         my $app = shift;
1422
1423         ## do stuff here..
1424     };
1425
1426 =cut
1427
1428 sub setup_finalize {
1429     my ($class) = @_;
1430     $class->setup_finished(1);
1431 }
1432
1433 =head2 $c->uri_for( $path?, @args?, \%query_values? )
1434
1435 =head2 $c->uri_for( $action, \@captures?, @args?, \%query_values? )
1436
1437 =head2 $c->uri_for( $action, [@captures, @args], \%query_values? )
1438
1439 Constructs an absolute L<URI> object based on the application root, the
1440 provided path, and the additional arguments and query parameters provided.
1441 When used as a string, provides a textual URI.  If you need more flexibility
1442 than this (i.e. the option to provide relative URIs etc.) see
1443 L<Catalyst::Plugin::SmartURI>.
1444
1445 If no arguments are provided, the URI for the current action is returned.
1446 To return the current action and also provide @args, use
1447 C<< $c->uri_for( $c->action, @args ) >>.
1448
1449 If the first argument is a string, it is taken as a public URI path relative
1450 to C<< $c->namespace >> (if it doesn't begin with a forward slash) or
1451 relative to the application root (if it does). It is then merged with
1452 C<< $c->request->base >>; any C<@args> are appended as additional path
1453 components; and any C<%query_values> are appended as C<?foo=bar> parameters.
1454
1455 If the first argument is a L<Catalyst::Action> it represents an action which
1456 will have its path resolved using C<< $c->dispatcher->uri_for_action >>. The
1457 optional C<\@captures> argument (an arrayref) allows passing the captured
1458 variables that are needed to fill in the paths of Chained and Regex actions;
1459 once the path is resolved, C<uri_for> continues as though a path was
1460 provided, appending any arguments or parameters and creating an absolute
1461 URI.
1462
1463 The captures for the current request can be found in
1464 C<< $c->request->captures >>, and actions can be resolved using
1465 C<< Catalyst::Controller->action_for($name) >>. If you have a private action
1466 path, use C<< $c->uri_for_action >> instead.
1467
1468   # Equivalent to $c->req->uri
1469   $c->uri_for($c->action, $c->req->captures,
1470       @{ $c->req->args }, $c->req->params);
1471
1472   # For the Foo action in the Bar controller
1473   $c->uri_for($c->controller('Bar')->action_for('Foo'));
1474
1475   # Path to a static resource
1476   $c->uri_for('/static/images/logo.png');
1477
1478 In general the scheme of the generated URI object will follow the incoming request
1479 however if your targeted action or action chain has the Scheme attribute it will
1480 use that instead.
1481
1482 Also, if the targeted Action or Action chain declares Args/CaptureArgs that have
1483 type constraints, we will require that your proposed URL verify on those declared
1484 constraints.
1485
1486 =cut
1487
1488 sub uri_for {
1489     my ( $c, $path, @args ) = @_;
1490
1491     if ( $path->$_isa('Catalyst::Controller') ) {
1492         $path = $path->path_prefix;
1493         $path =~ s{/+\z}{};
1494         $path .= '/';
1495     }
1496
1497     undef($path) if (defined $path && $path eq '');
1498
1499     my $params =
1500       ( scalar @args && ref $args[$#args] eq 'HASH' ? pop @args : {} );
1501
1502     carp "uri_for called with undef argument" if grep { ! defined $_ } @args;
1503
1504     my $target_action = $path->$_isa('Catalyst::Action') ? $path : undef;
1505     if ( $path->$_isa('Catalyst::Action') ) { # action object
1506         s|/|%2F|g for @args;
1507         my $captures = [ map { s|/|%2F|g; $_; }
1508                         ( scalar @args && ref $args[0] eq 'ARRAY'
1509                          ? @{ shift(@args) }
1510                          : ()) ];
1511
1512         my $action = $path;
1513         my $expanded_action = $c->dispatcher->expand_action( $action );
1514         my $num_captures = $expanded_action->number_of_captures;
1515
1516         # ->uri_for( $action, \@captures_and_args, \%query_values? )
1517         if( !@args && $action->number_of_args ) {
1518           unshift @args, splice @$captures, $num_captures;
1519         }
1520
1521         if($num_captures) {
1522           unless($expanded_action->match_captures_constraints($c, $captures)) {
1523             carp "captures [@{$captures}] do not match the type constraints in actionchain ending with '$expanded_action'";
1524             return;
1525           }
1526         }
1527
1528         $path = $c->dispatcher->uri_for_action($action, $captures);
1529         if (not defined $path) {
1530             $c->log->debug(qq/Can't find uri_for action '$action' @$captures/)
1531                 if $c->debug;
1532             return undef;
1533         }
1534         $path = '/' if $path eq '';
1535
1536         # At this point @encoded_args is the remaining Args (all captures removed).
1537         if($expanded_action->has_args_constraints) {
1538           unless($expanded_action->match_args($c,\@args)) {
1539              carp "args [@args] do not match the type constraints in action '$expanded_action'";
1540              return;
1541           }
1542         }
1543     }
1544
1545     unshift(@args, $path);
1546
1547     unless (defined $path && $path =~ s!^/!!) { # in-place strip
1548         my $namespace = $c->namespace;
1549         if (defined $path) { # cheesy hack to handle path '../foo'
1550            $namespace =~ s{(?:^|/)[^/]+$}{} while $args[0] =~ s{^\.\./}{};
1551         }
1552         unshift(@args, $namespace || '');
1553     }
1554
1555     # join args with '/', or a blank string
1556     my $args = join('/', grep { defined($_) } @args);
1557     $args =~ s/\?/%3F/g; # STUPID STUPID SPECIAL CASE
1558     $args =~ s!^/+!!;
1559
1560     my ($base, $class) = ('/', 'URI::_generic');
1561     if(blessed($c)) {
1562       $base = $c->req->base;
1563       if($target_action) {
1564         $target_action = $c->dispatcher->expand_action($target_action);
1565         if(my $s = $target_action->scheme) {
1566           $s = lc($s);
1567           $class = "URI::$s";
1568           $base->scheme($s);
1569         } else {
1570           $class = ref($base);
1571         }
1572       } else {
1573         $class = ref($base);
1574       }
1575
1576       $base =~ s{(?<!/)$}{/};
1577     }
1578
1579     my $query = '';
1580
1581     if (my @keys = keys %$params) {
1582       # somewhat lifted from URI::_query's query_form
1583       $query = '?'.join('&', map {
1584           my $val = $params->{$_};
1585           #s/([;\/?:@&=+,\$\[\]%])/$URI::Escape::escapes{$1}/go; ## Commented out because seems to lead to double encoding - JNAP
1586           s/ /+/g;
1587           my $key = $_;
1588           $val = '' unless defined $val;
1589           (map {
1590               my $param = "$_";
1591               $param = encode_utf8($param);
1592               # using the URI::Escape pattern here so utf8 chars survive
1593               $param =~ s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
1594               $param =~ s/ /+/g;
1595
1596               $key = encode_utf8($key);
1597               # using the URI::Escape pattern here so utf8 chars survive
1598               $key =~ s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
1599               $key =~ s/ /+/g;
1600
1601               "${key}=$param"; } ( ref $val eq 'ARRAY' ? @$val : $val ));
1602       } @keys);
1603     }
1604
1605     $base = encode_utf8 $base;
1606     $base =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1607     $args = encode_utf8 $args;
1608     $args =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1609
1610     my $res = bless(\"${base}${args}${query}", $class);
1611     $res;
1612 }
1613
1614 =head2 $c->uri_for_action( $path, \@captures_and_args?, @args?, \%query_values? )
1615
1616 =head2 $c->uri_for_action( $action, \@captures_and_args?, @args?, \%query_values? )
1617
1618 =over
1619
1620 =item $path
1621
1622 A private path to the Catalyst action you want to create a URI for.
1623
1624 This is a shortcut for calling C<< $c->dispatcher->get_action_by_path($path)
1625 >> and passing the resulting C<$action> and the remaining arguments to C<<
1626 $c->uri_for >>.
1627
1628 You can also pass in a Catalyst::Action object, in which case it is passed to
1629 C<< $c->uri_for >>.
1630
1631 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.
1632
1633 For example, if the action looks like:
1634
1635  package MyApp::Controller::Users;
1636
1637  sub lst : Path('the-list') {}
1638
1639 You can use:
1640
1641  $c->uri_for_action('/users/lst')
1642
1643 and it will create the URI /users/the-list.
1644
1645 =item \@captures_and_args?
1646
1647 Optional array reference of Captures (i.e. C<<CaptureArgs or $c->req->captures>)
1648 and arguments to the request. Usually used with L<Catalyst::DispatchType::Chained>
1649 to interpolate all the parameters in the URI.
1650
1651 =item @args?
1652
1653 Optional list of extra arguments - can be supplied in the
1654 C<< \@captures_and_args? >> array ref, or here - whichever is easier for your
1655 code.
1656
1657 Your action can have zero, a fixed or a variable number of args (e.g.
1658 C<< Args(1) >> for a fixed number or C<< Args() >> for a variable number)..
1659
1660 =item \%query_values?
1661
1662 Optional array reference of query parameters to append. E.g.
1663
1664   { foo => 'bar' }
1665
1666 will generate
1667
1668   /rest/of/your/uri?foo=bar
1669
1670 =back
1671
1672 =cut
1673
1674 sub uri_for_action {
1675     my ( $c, $path, @args ) = @_;
1676     my $action = blessed($path)
1677       ? $path
1678       : $c->dispatcher->get_action_by_path($path);
1679     unless (defined $action) {
1680       croak "Can't find action for path '$path'";
1681     }
1682     return $c->uri_for( $action, @args );
1683 }
1684
1685 =head2 $c->welcome_message
1686
1687 Returns the Catalyst welcome HTML page.
1688
1689 =cut
1690
1691 sub welcome_message {
1692     my $c      = shift;
1693     my $name   = $c->config->{name};
1694     my $logo   = $c->uri_for('/static/images/catalyst_logo.png');
1695     my $prefix = Catalyst::Utils::appprefix( ref $c );
1696     $c->response->content_type('text/html; charset=utf-8');
1697     return <<"EOF";
1698 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1699     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1700 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
1701     <head>
1702     <meta http-equiv="Content-Language" content="en" />
1703     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
1704         <title>$name on Catalyst $VERSION</title>
1705         <style type="text/css">
1706             body {
1707                 color: #000;
1708                 background-color: #eee;
1709             }
1710             div#content {
1711                 width: 640px;
1712                 margin-left: auto;
1713                 margin-right: auto;
1714                 margin-top: 10px;
1715                 margin-bottom: 10px;
1716                 text-align: left;
1717                 background-color: #ccc;
1718                 border: 1px solid #aaa;
1719             }
1720             p, h1, h2 {
1721                 margin-left: 20px;
1722                 margin-right: 20px;
1723                 font-family: verdana, tahoma, sans-serif;
1724             }
1725             a {
1726                 font-family: verdana, tahoma, sans-serif;
1727             }
1728             :link, :visited {
1729                     text-decoration: none;
1730                     color: #b00;
1731                     border-bottom: 1px dotted #bbb;
1732             }
1733             :link:hover, :visited:hover {
1734                     color: #555;
1735             }
1736             div#topbar {
1737                 margin: 0px;
1738             }
1739             pre {
1740                 margin: 10px;
1741                 padding: 8px;
1742             }
1743             div#answers {
1744                 padding: 8px;
1745                 margin: 10px;
1746                 background-color: #fff;
1747                 border: 1px solid #aaa;
1748             }
1749             h1 {
1750                 font-size: 0.9em;
1751                 font-weight: normal;
1752                 text-align: center;
1753             }
1754             h2 {
1755                 font-size: 1.0em;
1756             }
1757             p {
1758                 font-size: 0.9em;
1759             }
1760             p img {
1761                 float: right;
1762                 margin-left: 10px;
1763             }
1764             span#appname {
1765                 font-weight: bold;
1766                 font-size: 1.6em;
1767             }
1768         </style>
1769     </head>
1770     <body>
1771         <div id="content">
1772             <div id="topbar">
1773                 <h1><span id="appname">$name</span> on <a href="http://catalyst.perl.org">Catalyst</a>
1774                     $VERSION</h1>
1775              </div>
1776              <div id="answers">
1777                  <p>
1778                  <img src="$logo" alt="Catalyst Logo" />
1779                  </p>
1780                  <p>Welcome to the  world of Catalyst.
1781                     This <a href="http://en.wikipedia.org/wiki/MVC">MVC</a>
1782                     framework will make web development something you had
1783                     never expected it to be: Fun, rewarding, and quick.</p>
1784                  <h2>What to do now?</h2>
1785                  <p>That really depends  on what <b>you</b> want to do.
1786                     We do, however, provide you with a few starting points.</p>
1787                  <p>If you want to jump right into web development with Catalyst
1788                     you might want to start with a tutorial.</p>
1789 <pre>perldoc <a href="https://metacpan.org/module/Catalyst::Manual::Tutorial">Catalyst::Manual::Tutorial</a></code>
1790 </pre>
1791 <p>Afterwards you can go on to check out a more complete look at our features.</p>
1792 <pre>
1793 <code>perldoc <a href="https://metacpan.org/module/Catalyst::Manual::Intro">Catalyst::Manual::Intro</a>
1794 <!-- Something else should go here, but the Catalyst::Manual link seems unhelpful -->
1795 </code></pre>
1796                  <h2>What to do next?</h2>
1797                  <p>Next it's time to write an actual application. Use the
1798                     helper scripts to generate <a href="https://metacpan.org/search?q=Catalyst%3A%3AController">controllers</a>,
1799                     <a href="https://metacpan.org/search?q=Catalyst%3A%3AModel">models</a>, and
1800                     <a href="https://metacpan.org/search?q=Catalyst%3A%3AView">views</a>;
1801                     they can save you a lot of work.</p>
1802                     <pre><code>script/${prefix}_create.pl --help</code></pre>
1803                     <p>Also, be sure to check out the vast and growing
1804                     collection of <a href="http://search.cpan.org/search?query=Catalyst">plugins for Catalyst on CPAN</a>;
1805                     you are likely to find what you need there.
1806                     </p>
1807
1808                  <h2>Need help?</h2>
1809                  <p>Catalyst has a very active community. Here are the main places to
1810                     get in touch with us.</p>
1811                  <ul>
1812                      <li>
1813                          <a href="http://dev.catalyst.perl.org">Wiki</a>
1814                      </li>
1815                      <li>
1816                          <a href="http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst">Mailing-List</a>
1817                      </li>
1818                      <li>
1819                          <a href="irc://irc.perl.org/catalyst">IRC channel #catalyst on irc.perl.org</a>
1820                      </li>
1821                  </ul>
1822                  <h2>In conclusion</h2>
1823                  <p>The Catalyst team hopes you will enjoy using Catalyst as much
1824                     as we enjoyed making it. Please contact us if you have ideas
1825                     for improvement or other feedback.</p>
1826              </div>
1827          </div>
1828     </body>
1829 </html>
1830 EOF
1831 }
1832
1833 =head2 run_options
1834
1835 Contains a hash of options passed from the application script, including
1836 the original ARGV the script received, the processed values from that
1837 ARGV and any extra arguments to the script which were not processed.
1838
1839 This can be used to add custom options to your application's scripts
1840 and setup your application differently depending on the values of these
1841 options.
1842
1843 =head1 INTERNAL METHODS
1844
1845 These methods are not meant to be used by end users.
1846
1847 =head2 $c->components
1848
1849 Returns a hash of components.
1850
1851 =head2 $c->context_class
1852
1853 Returns or sets the context class.
1854
1855 =head2 $c->counter
1856
1857 Returns a hashref containing coderefs and execution counts (needed for
1858 deep recursion detection).
1859
1860 =head2 $c->depth
1861
1862 Returns the number of actions on the current internal execution stack.
1863
1864 =head2 $c->dispatch
1865
1866 Dispatches a request to actions.
1867
1868 =cut
1869
1870 sub dispatch { my $c = shift; $c->dispatcher->dispatch( $c, @_ ) }
1871
1872 =head2 $c->dispatcher_class
1873
1874 Returns or sets the dispatcher class.
1875
1876 =head2 $c->dump_these
1877
1878 Returns a list of 2-element array references (name, structure) pairs
1879 that will be dumped on the error page in debug mode.
1880
1881 =cut
1882
1883 sub dump_these {
1884     my $c = shift;
1885     [ Request => $c->req ],
1886     [ Response => $c->res ],
1887     [ Stash => $c->stash ],
1888     [ Config => $c->config ];
1889 }
1890
1891 =head2 $c->engine_class
1892
1893 Returns or sets the engine class.
1894
1895 =head2 $c->execute( $class, $coderef )
1896
1897 Execute a coderef in given class and catch exceptions. Errors are available
1898 via $c->error.
1899
1900 =cut
1901
1902 sub execute {
1903     my ( $c, $class, $code ) = @_;
1904     $class = $c->component($class) || $class;
1905     $c->state(0);
1906
1907     if ( $c->depth >= $RECURSION ) {
1908         my $action = $code->reverse();
1909         $action = "/$action" unless $action =~ /->/;
1910         my $error = qq/Deep recursion detected calling "${action}"/;
1911         $c->log->error($error);
1912         $c->error($error);
1913         $c->state(0);
1914         return $c->state;
1915     }
1916
1917     my $stats_info = $c->_stats_start_execute( $code ) if $c->use_stats;
1918
1919     push( @{ $c->stack }, $code );
1920
1921     no warnings 'recursion';
1922     # N.B. This used to be combined, but I have seen $c get clobbered if so, and
1923     #      I have no idea how, ergo $ret (which appears to fix the issue)
1924     eval { my $ret = $code->execute( $class, $c, @{ $c->req->args } ) || 0; $c->state( $ret ) };
1925
1926     $c->_stats_finish_execute( $stats_info ) if $c->use_stats and $stats_info;
1927
1928     my $last = pop( @{ $c->stack } );
1929
1930     if ( my $error = $@ ) {
1931         #rethow if this can be handled by middleware
1932         if ( $c->_handle_http_exception($error) ) {
1933             foreach my $err (@{$c->error}) {
1934                 $c->log->error($err);
1935             }
1936             $c->clear_errors;
1937             $c->log->_flush if $c->log->can('_flush');
1938
1939             $error->can('rethrow') ? $error->rethrow : croak $error;
1940         }
1941         if ( blessed($error) and $error->isa('Catalyst::Exception::Detach') ) {
1942             $error->rethrow if $c->depth > 1;
1943         }
1944         elsif ( blessed($error) and $error->isa('Catalyst::Exception::Go') ) {
1945             $error->rethrow if $c->depth > 0;
1946         }
1947         else {
1948             unless ( ref $error ) {
1949                 no warnings 'uninitialized';
1950                 chomp $error;
1951                 my $class = $last->class;
1952                 my $name  = $last->name;
1953                 $error = qq/Caught exception in $class->$name "$error"/;
1954             }
1955             $c->error($error);
1956         }
1957         $c->state(0);
1958     }
1959     return $c->state;
1960 }
1961
1962 sub _stats_start_execute {
1963     my ( $c, $code ) = @_;
1964     my $appclass = ref($c) || $c;
1965     return if ( ( $code->name =~ /^_.*/ )
1966         && ( !$appclass->config->{show_internal_actions} ) );
1967
1968     my $action_name = $code->reverse();
1969     $c->counter->{$action_name}++;
1970
1971     my $action = $action_name;
1972     $action = "/$action" unless $action =~ /->/;
1973
1974     # determine if the call was the result of a forward
1975     # this is done by walking up the call stack and looking for a calling
1976     # sub of Catalyst::forward before the eval
1977     my $callsub = q{};
1978     for my $index ( 2 .. 11 ) {
1979         last
1980         if ( ( caller($index) )[0] eq 'Catalyst'
1981             && ( caller($index) )[3] eq '(eval)' );
1982
1983         if ( ( caller($index) )[3] =~ /forward$/ ) {
1984             $callsub = ( caller($index) )[3];
1985             $action  = "-> $action";
1986             last;
1987         }
1988     }
1989
1990     my $uid = $action_name . $c->counter->{$action_name};
1991
1992     # is this a root-level call or a forwarded call?
1993     if ( $callsub =~ /forward$/ ) {
1994         my $parent = $c->stack->[-1];
1995
1996         # forward, locate the caller
1997         if ( defined $parent && exists $c->counter->{"$parent"} ) {
1998             $c->stats->profile(
1999                 begin  => $action,
2000                 parent => "$parent" . $c->counter->{"$parent"},
2001                 uid    => $uid,
2002             );
2003         }
2004         else {
2005
2006             # forward with no caller may come from a plugin
2007             $c->stats->profile(
2008                 begin => $action,
2009                 uid   => $uid,
2010             );
2011         }
2012     }
2013     else {
2014
2015         # root-level call
2016         $c->stats->profile(
2017             begin => $action,
2018             uid   => $uid,
2019         );
2020     }
2021     return $action;
2022
2023 }
2024
2025 sub _stats_finish_execute {
2026     my ( $c, $info ) = @_;
2027     $c->stats->profile( end => $info );
2028 }
2029
2030 =head2 $c->finalize
2031
2032 Finalizes the request.
2033
2034 =cut
2035
2036 sub finalize {
2037     my $c = shift;
2038
2039     for my $error ( @{ $c->error } ) {
2040         $c->log->error($error);
2041     }
2042
2043     # Support skipping finalize for psgix.io style 'jailbreak'.  Used to support
2044     # stuff like cometd and websockets
2045
2046     if($c->request->_has_io_fh) {
2047       $c->log_response;
2048       return;
2049     }
2050
2051     # Allow engine to handle finalize flow (for POE)
2052     my $engine = $c->engine;
2053     if ( my $code = $engine->can('finalize') ) {
2054         $engine->$code($c);
2055     }
2056     else {
2057
2058         $c->finalize_uploads;
2059
2060         # Error
2061         if ( $#{ $c->error } >= 0 ) {
2062             $c->finalize_error;
2063         }
2064
2065         $c->finalize_encoding;
2066         $c->finalize_headers unless $c->response->finalized_headers;
2067         $c->finalize_body;
2068     }
2069
2070     $c->log_response;
2071
2072     if ($c->use_stats) {
2073         my $elapsed = $c->stats->elapsed;
2074         my $av = $elapsed == 0 ? '??' : sprintf '%.3f', 1 / $elapsed;
2075         $c->log->info(
2076             "Request took ${elapsed}s ($av/s)\n" . $c->stats->report . "\n" );
2077     }
2078
2079     return $c->response->status;
2080 }
2081
2082 =head2 $c->finalize_body
2083
2084 Finalizes body.
2085
2086 =cut
2087
2088 sub finalize_body { my $c = shift; $c->engine->finalize_body( $c, @_ ) }
2089
2090 =head2 $c->finalize_cookies
2091
2092 Finalizes cookies.
2093
2094 =cut
2095
2096 sub finalize_cookies { my $c = shift; $c->engine->finalize_cookies( $c, @_ ) }
2097
2098 =head2 $c->finalize_error
2099
2100 Finalizes error.  If there is only one error in L</error> and it is an object that
2101 does C<as_psgi> or C<code> we rethrow the error and presume it caught by middleware
2102 up the ladder.  Otherwise we return the debugging error page (in debug mode) or we
2103 return the default error page (production mode).
2104
2105 =cut
2106
2107 sub finalize_error {
2108     my $c = shift;
2109     if($#{$c->error} > 0) {
2110         $c->engine->finalize_error( $c, @_ );
2111     } else {
2112         my ($error) = @{$c->error};
2113         if ( $c->_handle_http_exception($error) ) {
2114             # In the case where the error 'knows what it wants', becauses its PSGI
2115             # aware, just rethow and let middleware catch it
2116             $error->can('rethrow') ? $error->rethrow : croak $error;
2117         } else {
2118             $c->engine->finalize_error( $c, @_ )
2119         }
2120     }
2121 }
2122
2123 =head2 $c->finalize_headers
2124
2125 Finalizes headers.
2126
2127 =cut
2128
2129 sub finalize_headers {
2130     my $c = shift;
2131
2132     my $response = $c->response; #accessor calls can add up?
2133
2134     # Check if we already finalized headers
2135     return if $response->finalized_headers;
2136
2137     # Handle redirects
2138     if ( my $location = $response->redirect ) {
2139         $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
2140         $response->header( Location => $location );
2141     }
2142
2143     # Remove incorrectly added body and content related meta data when returning
2144     # an information response, or a response the is required to not include a body
2145
2146     $c->finalize_cookies;
2147
2148     # This currently is a NOOP but I don't want to remove it since I guess people
2149     # might have Response subclasses that use it for something... (JNAP)
2150     $c->response->finalize_headers();
2151
2152     # Done
2153     $response->finalized_headers(1);
2154 }
2155
2156 =head2 $c->finalize_encoding
2157
2158 Make sure your body is encoded properly IF you set an encoding.  By
2159 default the encoding is UTF-8 but you can disable it by explicitly setting the
2160 encoding configuration value to undef.
2161
2162 We can only encode when the body is a scalar.  Methods for encoding via the
2163 streaming interfaces (such as C<write> and C<write_fh> on L<Catalyst::Response>
2164 are available).
2165
2166 See L</ENCODING>.
2167
2168 =cut
2169
2170 sub finalize_encoding {
2171     my $c = shift;
2172     my $res = $c->res || return;
2173
2174     # Warn if the set charset is different from the one you put into encoding.  We need
2175     # to do this early since encodable_response is false for this condition and we need
2176     # to match the debug output for backcompat (there's a test for this...) -JNAP
2177     if(
2178       $res->content_type_charset and $c->encoding and
2179       (uc($c->encoding->mime_name) ne uc($res->content_type_charset))
2180     ) {
2181         my $ct = lc($res->content_type_charset);
2182         $c->log->debug("Catalyst encoding config is set to encode in '" .
2183             $c->encoding->mime_name .
2184             "', content type is '$ct', not encoding ");
2185     }
2186
2187     if(
2188       ($res->encodable_response) and
2189       (defined($res->body)) and
2190       (ref(\$res->body) eq 'SCALAR')
2191     ) {
2192         $c->res->body( $c->encoding->encode( $c->res->body, $c->_encode_check ) );
2193
2194         # Set the charset if necessary.  This might be a bit bonkers since encodable response
2195         # is false when the set charset is not the same as the encoding mimetype (maybe
2196         # confusing action at a distance here..
2197         # Don't try to set the charset if one already exists
2198         $c->res->content_type($c->res->content_type . "; charset=" . $c->encoding->mime_name)
2199           unless($c->res->content_type_charset);
2200     }
2201 }
2202
2203 =head2 $c->finalize_output
2204
2205 An alias for finalize_body.
2206
2207 =head2 $c->finalize_read
2208
2209 Finalizes the input after reading is complete.
2210
2211 =cut
2212
2213 sub finalize_read { my $c = shift; $c->engine->finalize_read( $c, @_ ) }
2214
2215 =head2 $c->finalize_uploads
2216
2217 Finalizes uploads. Cleans up any temporary files.
2218
2219 =cut
2220
2221 sub finalize_uploads { my $c = shift; $c->engine->finalize_uploads( $c, @_ ) }
2222
2223 =head2 $c->get_action( $action, $namespace )
2224
2225 Gets an action in a given namespace.
2226
2227 =cut
2228
2229 sub get_action { my $c = shift; $c->dispatcher->get_action(@_) }
2230
2231 =head2 $c->get_actions( $action, $namespace )
2232
2233 Gets all actions of a given name in a namespace and all parent
2234 namespaces.
2235
2236 =cut
2237
2238 sub get_actions { my $c = shift; $c->dispatcher->get_actions( $c, @_ ) }
2239
2240 =head2 $app->handle_request( @arguments )
2241
2242 Called to handle each HTTP request.
2243
2244 =cut
2245
2246 sub handle_request {
2247     my ( $class, @arguments ) = @_;
2248
2249     # Always expect worst case!
2250     my $status = -1;
2251     try {
2252         if ($class->debug) {
2253             my $secs = time - $START || 1;
2254             my $av = sprintf '%.3f', $COUNT / $secs;
2255             my $time = localtime time;
2256             $class->log->info("*** Request $COUNT ($av/s) [$$] [$time] ***");
2257         }
2258
2259         my $c = $class->prepare(@arguments);
2260         $c->dispatch;
2261         $status = $c->finalize;
2262     } catch {
2263         #rethow if this can be handled by middleware
2264         if ( $class->_handle_http_exception($_) ) {
2265             $_->can('rethrow') ? $_->rethrow : croak $_;
2266         }
2267         chomp(my $error = $_);
2268         $class->log->error(qq/Caught exception in engine "$error"/);
2269     };
2270
2271     $COUNT++;
2272
2273     if(my $coderef = $class->log->can('_flush')){
2274         $class->log->$coderef();
2275     }
2276     return $status;
2277 }
2278
2279 =head2 $class->prepare( @arguments )
2280
2281 Creates a Catalyst context from an engine-specific request (Apache, CGI,
2282 etc.).
2283
2284 =cut
2285
2286 has _uploadtmp => (
2287     is => 'ro',
2288     predicate => '_has_uploadtmp',
2289 );
2290
2291 sub prepare {
2292     my ( $class, @arguments ) = @_;
2293
2294     # XXX
2295     # After the app/ctxt split, this should become an attribute based on something passed
2296     # into the application.
2297     $class->context_class( ref $class || $class ) unless $class->context_class;
2298
2299     my $uploadtmp = $class->config->{uploadtmp};
2300     my $c = $class->context_class->new({ $uploadtmp ? (_uploadtmp => $uploadtmp) : ()});
2301
2302     $c->response->_context($c);
2303
2304     if($c->use_stats) {
2305       $c->stats($class->composed_stats_class->new)->enable;
2306     }
2307
2308     if ( $c->debug || $c->config->{enable_catalyst_header} ) {
2309         $c->res->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
2310     }
2311
2312     try {
2313         # Allow engine to direct the prepare flow (for POE)
2314         if ( my $prepare = $c->engine->can('prepare') ) {
2315             $c->engine->$prepare( $c, @arguments );
2316         }
2317         else {
2318             $c->prepare_request(@arguments);
2319             $c->prepare_connection;
2320             $c->prepare_query_parameters;
2321             $c->prepare_headers; # Just hooks, no longer needed - they just
2322             $c->prepare_cookies; # cause the lazy attribute on req to build
2323             $c->prepare_path;
2324
2325             # Prepare the body for reading, either by prepare_body
2326             # or the user, if they are using $c->read
2327             $c->prepare_read;
2328
2329             # Parse the body unless the user wants it on-demand
2330             unless ( ref($c)->config->{parse_on_demand} ) {
2331                 $c->prepare_body;
2332             }
2333         }
2334         $c->prepare_action;
2335     }
2336     # VERY ugly and probably shouldn't rely on ->finalize actually working
2337     catch {
2338         # failed prepare is always due to an invalid request, right?
2339         $c->response->status(400);
2340         $c->response->content_type('text/plain');
2341         $c->response->body('Bad Request');
2342         # Note we call finalize and then die here, which escapes
2343         # finalize being called in the enclosing block..
2344         # It in fact couldn't be called, as we don't return $c..
2345         # This is a mess - but I'm unsure you can fix this without
2346         # breaking compat for people doing crazy things (we should set
2347         # the 400 and just return the ctx here IMO, letting finalize get called
2348         # above...
2349         $c->finalize;
2350         die $_;
2351     };
2352
2353     $c->log_request;
2354
2355     return $c;
2356 }
2357
2358 =head2 $c->prepare_action
2359
2360 Prepares action. See L<Catalyst::Dispatcher>.
2361
2362 =cut
2363
2364 sub prepare_action {
2365     my $c = shift;
2366     my $ret = $c->dispatcher->prepare_action( $c, @_);
2367
2368     if($c->encoding) {
2369         foreach (@{$c->req->arguments}, @{$c->req->captures}) {
2370           $_ = $c->_handle_param_unicode_decoding($_);
2371         }
2372     }
2373
2374     return $ret;
2375 }
2376
2377
2378 =head2 $c->prepare_body
2379
2380 Prepares message body.
2381
2382 =cut
2383
2384 sub prepare_body {
2385     my $c = shift;
2386
2387     return if $c->request->_has_body;
2388
2389     # Initialize on-demand data
2390     $c->engine->prepare_body( $c, @_ );
2391     $c->prepare_parameters;
2392     $c->prepare_uploads;
2393 }
2394
2395 =head2 $c->prepare_body_chunk( $chunk )
2396
2397 Prepares a chunk of data before sending it to L<HTTP::Body>.
2398
2399 See L<Catalyst::Engine>.
2400
2401 =cut
2402
2403 sub prepare_body_chunk {
2404     my $c = shift;
2405     $c->engine->prepare_body_chunk( $c, @_ );
2406 }
2407
2408 =head2 $c->prepare_body_parameters
2409
2410 Prepares body parameters.
2411
2412 =cut
2413
2414 sub prepare_body_parameters {
2415     my $c = shift;
2416     $c->request->prepare_body_parameters( $c, @_ );
2417 }
2418
2419 =head2 $c->prepare_connection
2420
2421 Prepares connection.
2422
2423 =cut
2424
2425 sub prepare_connection {
2426     my $c = shift;
2427     $c->request->prepare_connection($c);
2428 }
2429
2430 =head2 $c->prepare_cookies
2431
2432 Prepares cookies by ensuring that the attribute on the request
2433 object has been built.
2434
2435 =cut
2436
2437 sub prepare_cookies { my $c = shift; $c->request->cookies }
2438
2439 =head2 $c->prepare_headers
2440
2441 Prepares request headers by ensuring that the attribute on the request
2442 object has been built.
2443
2444 =cut
2445
2446 sub prepare_headers { my $c = shift; $c->request->headers }
2447
2448 =head2 $c->prepare_parameters
2449
2450 Prepares parameters.
2451
2452 =cut
2453
2454 sub prepare_parameters {
2455     my $c = shift;
2456     $c->prepare_body_parameters;
2457     $c->engine->prepare_parameters( $c, @_ );
2458 }
2459
2460 =head2 $c->prepare_path
2461
2462 Prepares path and base.
2463
2464 =cut
2465
2466 sub prepare_path { my $c = shift; $c->engine->prepare_path( $c, @_ ) }
2467
2468 =head2 $c->prepare_query_parameters
2469
2470 Prepares query parameters.
2471
2472 =cut
2473
2474 sub prepare_query_parameters {
2475     my $c = shift;
2476
2477     $c->engine->prepare_query_parameters( $c, @_ );
2478 }
2479
2480 =head2 $c->log_request
2481
2482 Writes information about the request to the debug logs.  This includes:
2483
2484 =over 4
2485
2486 =item * Request method, path, and remote IP address
2487
2488 =item * Query keywords (see L<Catalyst::Request/query_keywords>)
2489
2490 =item * Request parameters
2491
2492 =item * File uploads
2493
2494 =back
2495
2496 =cut
2497
2498 sub log_request {
2499     my $c = shift;
2500
2501     return unless $c->debug;
2502
2503     my($dump) = grep {$_->[0] eq 'Request' } $c->dump_these;
2504     my $request = $dump->[1];
2505
2506     my ( $method, $path, $address ) = ( $request->method, $request->path, $request->address );
2507     $method ||= '';
2508     $path = '/' unless length $path;
2509     $address ||= '';
2510
2511     $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
2512     $path = decode_utf8($path);
2513
2514     $c->log->debug(qq/"$method" request for "$path" from "$address"/);
2515
2516     $c->log_request_headers($request->headers);
2517
2518     if ( my $keywords = $request->query_keywords ) {
2519         $c->log->debug("Query keywords are: $keywords");
2520     }
2521
2522     $c->log_request_parameters( query => $request->query_parameters, $request->_has_body ? (body => $request->body_parameters) : () );
2523
2524     $c->log_request_uploads($request);
2525 }
2526
2527 =head2 $c->log_response
2528
2529 Writes information about the response to the debug logs by calling
2530 C<< $c->log_response_status_line >> and C<< $c->log_response_headers >>.
2531
2532 =cut
2533
2534 sub log_response {
2535     my $c = shift;
2536
2537     return unless $c->debug;
2538
2539     my($dump) = grep {$_->[0] eq 'Response' } $c->dump_these;
2540     my $response = $dump->[1];
2541
2542     $c->log_response_status_line($response);
2543     $c->log_response_headers($response->headers);
2544 }
2545
2546 =head2 $c->log_response_status_line($response)
2547
2548 Writes one line of information about the response to the debug logs.  This includes:
2549
2550 =over 4
2551
2552 =item * Response status code
2553
2554 =item * Content-Type header (if present)
2555
2556 =item * Content-Length header (if present)
2557
2558 =back
2559
2560 =cut
2561
2562 sub log_response_status_line {
2563     my ($c, $response) = @_;
2564
2565     $c->log->debug(
2566         sprintf(
2567             'Response Code: %s; Content-Type: %s; Content-Length: %s',
2568             $response->status                            || 'unknown',
2569             $response->headers->header('Content-Type')   || 'unknown',
2570             $response->headers->header('Content-Length') || 'unknown'
2571         )
2572     );
2573 }
2574
2575 =head2 $c->log_response_headers($headers);
2576
2577 Hook method which can be wrapped by plugins to log the response headers.
2578 No-op in the default implementation.
2579
2580 =cut
2581
2582 sub log_response_headers {}
2583
2584 =head2 $c->log_request_parameters( query => {}, body => {} )
2585
2586 Logs request parameters to debug logs
2587
2588 =cut
2589
2590 sub log_request_parameters {
2591     my $c          = shift;
2592     my %all_params = @_;
2593
2594     return unless $c->debug;
2595
2596     my $column_width = Catalyst::Utils::term_width() - 44;
2597     foreach my $type (qw(query body)) {
2598         my $params = $all_params{$type};
2599         next if ! keys %$params;
2600         my $t = Text::SimpleTable->new( [ 35, 'Parameter' ], [ $column_width, 'Value' ] );
2601         for my $key ( sort keys %$params ) {
2602             my $param = $params->{$key};
2603             my $value = defined($param) ? $param : '';
2604             $t->row( $key, ref $value eq 'ARRAY' ? ( join ', ', @$value ) : $value );
2605         }
2606         $c->log->debug( ucfirst($type) . " Parameters are:\n" . $t->draw );
2607     }
2608 }
2609
2610 =head2 $c->log_request_uploads
2611
2612 Logs file uploads included in the request to the debug logs.
2613 The parameter name, filename, file type, and file size are all included in
2614 the debug logs.
2615
2616 =cut
2617
2618 sub log_request_uploads {
2619     my $c = shift;
2620     my $request = shift;
2621     return unless $c->debug;
2622     my $uploads = $request->uploads;
2623     if ( keys %$uploads ) {
2624         my $t = Text::SimpleTable->new(
2625             [ 12, 'Parameter' ],
2626             [ 26, 'Filename' ],
2627             [ 18, 'Type' ],
2628             [ 9,  'Size' ]
2629         );
2630         for my $key ( sort keys %$uploads ) {
2631             my $upload = $uploads->{$key};
2632             for my $u ( ref $upload eq 'ARRAY' ? @{$upload} : ($upload) ) {
2633                 $t->row( $key, $u->filename, $u->type, $u->size );
2634             }
2635         }
2636         $c->log->debug( "File Uploads are:\n" . $t->draw );
2637     }
2638 }
2639
2640 =head2 $c->log_request_headers($headers);
2641
2642 Hook method which can be wrapped by plugins to log the request headers.
2643 No-op in the default implementation.
2644
2645 =cut
2646
2647 sub log_request_headers {}
2648
2649 =head2 $c->log_headers($type => $headers)
2650
2651 Logs L<HTTP::Headers> (either request or response) to the debug logs.
2652
2653 =cut
2654
2655 sub log_headers {
2656     my $c       = shift;
2657     my $type    = shift;
2658     my $headers = shift;    # an HTTP::Headers instance
2659
2660     return unless $c->debug;
2661
2662     my $column_width = Catalyst::Utils::term_width() - 28;
2663     my $t = Text::SimpleTable->new( [ 15, 'Header Name' ], [ $column_width, 'Value' ] );
2664     $headers->scan(
2665         sub {
2666             my ( $name, $value ) = @_;
2667             $t->row( $name, $value );
2668         }
2669     );
2670     $c->log->debug( ucfirst($type) . " Headers:\n" . $t->draw );
2671 }
2672
2673
2674 =head2 $c->prepare_read
2675
2676 Prepares the input for reading.
2677
2678 =cut
2679
2680 sub prepare_read { my $c = shift; $c->engine->prepare_read( $c, @_ ) }
2681
2682 =head2 $c->prepare_request
2683
2684 Prepares the engine request.
2685
2686 =cut
2687
2688 sub prepare_request { my $c = shift; $c->engine->prepare_request( $c, @_ ) }
2689
2690 =head2 $c->prepare_uploads
2691
2692 Prepares uploads.
2693
2694 =cut
2695
2696 sub prepare_uploads {
2697     my $c = shift;
2698     $c->engine->prepare_uploads( $c, @_ );
2699 }
2700
2701 =head2 $c->prepare_write
2702
2703 Prepares the output for writing.
2704
2705 =cut
2706
2707 sub prepare_write { my $c = shift; $c->engine->prepare_write( $c, @_ ) }
2708
2709 =head2 $c->request_class
2710
2711 Returns or sets the request class. Defaults to L<Catalyst::Request>.
2712
2713 =head2 $app->request_class_traits
2714
2715 An arrayref of L<Moose::Role>s which are applied to the request class.
2716
2717 =head2 $app->composed_request_class
2718
2719 This is the request class which has been composed with any request_class_traits.
2720
2721 =head2 $c->response_class
2722
2723 Returns or sets the response class. Defaults to L<Catalyst::Response>.
2724
2725 =head2 $app->response_class_traits
2726
2727 An arrayref of L<Moose::Role>s which are applied to the response class.
2728
2729 =head2 $app->composed_response_class
2730
2731 This is the request class which has been composed with any response_class_traits.
2732
2733 =head2 $c->read( [$maxlength] )
2734
2735 Reads a chunk of data from the request body. This method is designed to
2736 be used in a while loop, reading C<$maxlength> bytes on every call.
2737 C<$maxlength> defaults to the size of the request if not specified.
2738
2739 You have to set C<< MyApp->config(parse_on_demand => 1) >> to use this
2740 directly.
2741
2742 Warning: If you use read(), Catalyst will not process the body,
2743 so you will not be able to access POST parameters or file uploads via
2744 $c->request.  You must handle all body parsing yourself.
2745
2746 =cut
2747
2748 sub read { my $c = shift; return $c->request->read( @_ ) }
2749
2750 =head2 $c->run
2751
2752 Starts the engine.
2753
2754 =cut
2755
2756 sub run {
2757   my $app = shift;
2758   $app->_make_immutable_if_needed;
2759   $app->engine_loader->needs_psgi_engine_compat_hack ?
2760     $app->engine->run($app, @_) :
2761       $app->engine->run( $app, $app->_finalized_psgi_app, @_ );
2762 }
2763
2764 sub _make_immutable_if_needed {
2765     my $class = shift;
2766     my $meta = find_meta($class);
2767     my $isa_ca = $class->isa('Class::Accessor::Fast') || $class->isa('Class::Accessor');
2768     if (
2769         $meta->is_immutable
2770         && ! { $meta->immutable_options }->{replace_constructor}
2771         && $isa_ca
2772     ) {
2773         warn("You made your application class ($class) immutable, "
2774             . "but did not inline the\nconstructor. "
2775             . "This will break catalyst, as your app \@ISA "
2776             . "Class::Accessor(::Fast)?\nPlease pass "
2777             . "(replace_constructor => 1)\nwhen making your class immutable.\n");
2778     }
2779     unless ($meta->is_immutable) {
2780         # XXX - FIXME warning here as you should make your app immutable yourself.
2781         $meta->make_immutable(
2782             replace_constructor => 1,
2783         );
2784     }
2785 }
2786
2787 =head2 $c->set_action( $action, $code, $namespace, $attrs )
2788
2789 Sets an action in a given namespace.
2790
2791 =cut
2792
2793 sub set_action { my $c = shift; $c->dispatcher->set_action( $c, @_ ) }
2794
2795 =head2 $c->setup_actions($component)
2796
2797 Sets up actions for a component.
2798
2799 =cut
2800
2801 sub setup_actions { my $c = shift; $c->dispatcher->setup_actions( $c, @_ ) }
2802
2803 =head2 $c->setup_components
2804
2805 This method is called internally to set up the application's components.
2806
2807 It finds modules by calling the L<locate_components> method, expands them to
2808 package names with the L<expand_component_module> method, and then installs
2809 each component into the application.
2810
2811 The C<setup_components> config option is passed to both of the above methods.
2812
2813 Installation of each component is performed by the L<setup_component> method,
2814 below.
2815
2816 =cut
2817
2818 sub setup_components {
2819     my $class = shift;
2820
2821     my $config  = $class->config->{ setup_components };
2822
2823     my @comps = $class->locate_components($config);
2824     my %comps = map { $_ => 1 } @comps;
2825
2826     my $deprecatedcatalyst_component_names = grep { /::[CMV]::/ } @comps;
2827     $class->log->warn(qq{Your application is using the deprecated ::[MVC]:: type naming scheme.\n}.
2828         qq{Please switch your class names to ::Model::, ::View:: and ::Controller: as appropriate.\n}
2829     ) if $deprecatedcatalyst_component_names;
2830
2831     for my $component ( @comps ) {
2832
2833         # We pass ignore_loaded here so that overlay files for (e.g.)
2834         # Model::DBI::Schema sub-classes are loaded - if it's in @comps
2835         # we know M::P::O found a file on disk so this is safe
2836
2837         Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
2838     }
2839
2840     for my $component (@comps) {
2841         my $instance = $class->components->{ $component } = $class->setup_component($component);
2842     }
2843
2844     # Inject a component or wrap a stand alone class in an adaptor. This makes a list
2845     # of named components in the configuration that are not actually existing (not a
2846     # real file).
2847     my @configured_comps = grep { not($class->components->{$_}||'') }
2848       grep { /^(Model)::|(View)::|(Controller::)/ }
2849         keys %{$class->config ||+{}};
2850
2851     foreach my $configured_comp(@configured_comps) {
2852       my $component_class = exists $class->config->{$configured_comp}->{from_component} ?
2853         delete $class->config->{$configured_comp}->{from_component} : '';
2854
2855       if($component_class) {
2856         my @roles = @{ exists $class->config->{$configured_comp}->{roles} ?
2857           delete $class->config->{$configured_comp}->{roles} : [] };
2858
2859         my %args = %{ exists $class->config->{$configured_comp}->{args} ?
2860           delete $class->config->{$configured_comp}->{args} : +{} };
2861
2862         $class->config->{$configured_comp} = \%args;
2863         Catalyst::Utils::inject_component(
2864           into => $class,
2865           component => $component_class,
2866           (scalar(@roles) ? (traits => \@roles) : ()),
2867           as => $configured_comp);
2868       }
2869     }
2870
2871     # All components are registered, now we need to 'init' them.
2872     foreach my $component_name (keys %{$class->components||{}}) {
2873       $class->components->{$component_name} = $class->components->{$component_name}->();
2874     }
2875
2876 }
2877
2878 =head2 $c->locate_components( $setup_component_config )
2879
2880 This method is meant to provide a list of component modules that should be
2881 setup for the application.  By default, it will use L<Module::Pluggable>.
2882
2883 Specify a C<setup_components> config option to pass additional options directly
2884 to L<Module::Pluggable>. To add additional search paths, specify a key named
2885 C<search_extra> as an array reference. Items in the array beginning with C<::>
2886 will have the application class name prepended to them.
2887
2888 =cut
2889
2890 sub locate_components {
2891     my $class  = shift;
2892     my $config = shift;
2893
2894     my @paths   = qw( ::M ::Model ::V ::View ::C ::Controller );
2895     my $extra   = delete $config->{ search_extra } || [];
2896
2897     unshift @paths, @$extra;
2898
2899     my @comps = map { sort { length($a) <=> length($b) } Module::Pluggable::Object->new(
2900       search_path => [ map { s/^(?=::)/$class/; $_; } ($_) ],
2901       %$config
2902     )->plugins } @paths;
2903
2904     return @comps;
2905 }
2906
2907 =head2 $c->expand_component_module( $component, $setup_component_config )
2908
2909 Components found by C<locate_components> will be passed to this method, which
2910 is expected to return a list of component (package) names to be set up.
2911
2912 =cut
2913
2914 sub expand_component_module {
2915     my ($class, $module) = @_;
2916     return Devel::InnerPackage::list_packages( $module );
2917 }
2918
2919 =head2 $c->setup_component
2920
2921 =cut
2922
2923 sub setup_component {
2924     my( $class, $component ) = @_;
2925
2926 return sub {
2927     unless ( $component->can( 'COMPONENT' ) ) {
2928         return $component;
2929     }
2930
2931     my $suffix = Catalyst::Utils::class2classsuffix( $component );
2932     my $config = $class->config->{ $suffix } || {};
2933     # Stash catalyst_component_name in the config here, so that custom COMPONENT
2934     # methods also pass it. local to avoid pointlessly shitting in config
2935     # for the debug screen, as $component is already the key name.
2936     local $config->{catalyst_component_name} = $component;
2937
2938     my $instance = eval {
2939       $component->COMPONENT( $class, $config );
2940     } || do {
2941       my $error = $@;
2942       chomp $error;
2943       Catalyst::Exception->throw(
2944         message => qq/Couldn't instantiate component "$component", "$error"/
2945       );
2946     };
2947
2948     unless (blessed $instance) {
2949         my $metaclass = Moose::Util::find_meta($component);
2950         my $method_meta = $metaclass->find_method_by_name('COMPONENT');
2951         my $component_method_from = $method_meta->associated_metaclass->name;
2952         my $value = defined($instance) ? $instance : 'undef';
2953         Catalyst::Exception->throw(
2954             message =>
2955             qq/Couldn't instantiate component "$component", COMPONENT() method (from $component_method_from) didn't return an object-like value (value was $value)./
2956         );
2957     }
2958
2959 my @expanded_components = $instance->can('expand_modules')
2960   ? $instance->expand_modules( $component, $config )
2961   : $class->expand_component_module( $component, $config );
2962 for my $component (@expanded_components) {
2963   next if $class->components->{ $component };
2964   $class->components->{ $component } = $class->setup_component($component);
2965 }
2966
2967     return $instance;
2968 }
2969
2970 }
2971
2972 =head2 $c->setup_dispatcher
2973
2974 Sets up dispatcher.
2975
2976 =cut
2977
2978 sub setup_dispatcher {
2979     my ( $class, $dispatcher ) = @_;
2980
2981     if ($dispatcher) {
2982         $dispatcher = 'Catalyst::Dispatcher::' . $dispatcher;
2983     }
2984
2985     if ( my $env = Catalyst::Utils::env_value( $class, 'DISPATCHER' ) ) {
2986         $dispatcher = 'Catalyst::Dispatcher::' . $env;
2987     }
2988
2989     unless ($dispatcher) {
2990         $dispatcher = $class->dispatcher_class;
2991     }
2992
2993     load_class($dispatcher);
2994
2995     # dispatcher instance
2996     $class->dispatcher( $dispatcher->new );
2997 }
2998
2999 =head2 $c->setup_engine
3000
3001 Sets up engine.
3002
3003 =cut
3004
3005 sub engine_class {
3006     my ($class, $requested_engine) = @_;
3007
3008     if (!$class->engine_loader || $requested_engine) {
3009         $class->engine_loader(
3010             Catalyst::EngineLoader->new({
3011                 application_name => $class,
3012                 (defined $requested_engine
3013                      ? (catalyst_engine_class => $requested_engine) : ()),
3014             }),
3015         );
3016     }
3017
3018     $class->engine_loader->catalyst_engine_class;
3019 }
3020
3021 sub setup_engine {
3022     my ($class, $requested_engine) = @_;
3023
3024     my $engine = do {
3025         my $loader = $class->engine_loader;
3026
3027         if (!$loader || $requested_engine) {
3028             $loader = Catalyst::EngineLoader->new({
3029                 application_name => $class,
3030                 (defined $requested_engine
3031                      ? (requested_engine => $requested_engine) : ()),
3032             }),
3033
3034             $class->engine_loader($loader);
3035         }
3036
3037         $loader->catalyst_engine_class;
3038     };
3039
3040     # Don't really setup_engine -- see _setup_psgi_app for explanation.
3041     return if $class->loading_psgi_file;
3042
3043     load_class($engine);
3044
3045     if ($ENV{MOD_PERL}) {
3046         my $apache = $class->engine_loader->auto;
3047
3048         my $meta = find_meta($class);
3049         my $was_immutable = $meta->is_immutable;
3050         my %immutable_options = $meta->immutable_options;
3051         $meta->make_mutable if $was_immutable;
3052
3053         $meta->add_method(handler => sub {
3054             my $r = shift;
3055             my $psgi_app = $class->_finalized_psgi_app;
3056             $apache->call_app($r, $psgi_app);
3057         });
3058
3059         $meta->make_immutable(%immutable_options) if $was_immutable;
3060     }
3061
3062     $class->engine( $engine->new );
3063
3064     return;
3065 }
3066
3067 ## This exists just to supply a prebuild psgi app for mod_perl and for the
3068 ## build in server support (back compat support for pre psgi port behavior).
3069 ## This is so that we don't build a new psgi app for each request when using
3070 ## the mod_perl handler or the built in servers (http and fcgi, etc).
3071
3072 sub _finalized_psgi_app {
3073     my ($app) = @_;
3074
3075     unless ($app->_psgi_app) {
3076         my $psgi_app = $app->_setup_psgi_app;
3077         $app->_psgi_app($psgi_app);
3078     }
3079
3080     return $app->_psgi_app;
3081 }
3082
3083 ## Look for a psgi file like 'myapp_web.psgi' (if the app is MyApp::Web) in the
3084 ## home directory and load that and return it (just assume it is doing the
3085 ## right thing :) ).  If that does not exist, call $app->psgi_app, wrap that
3086 ## in default_middleware and return it ( this is for backward compatibility
3087 ## with pre psgi port behavior ).
3088
3089 sub _setup_psgi_app {
3090     my ($app) = @_;
3091
3092     for my $home (Path::Class::Dir->new($app->config->{home})) {
3093         my $psgi_file = $home->file(
3094             Catalyst::Utils::appprefix($app) . '.psgi',
3095         );
3096
3097         next unless -e $psgi_file;
3098
3099         # If $psgi_file calls ->setup_engine, it's doing so to load
3100         # Catalyst::Engine::PSGI. But if it does that, we're only going to
3101         # throw away the loaded PSGI-app and load the 5.9 Catalyst::Engine
3102         # anyway. So set a flag (ick) that tells setup_engine not to populate
3103         # $c->engine or do any other things we might regret.
3104
3105         $app->loading_psgi_file(1);
3106         my $psgi_app = Plack::Util::load_psgi($psgi_file);
3107         $app->loading_psgi_file(0);
3108
3109         return $psgi_app
3110             unless $app->engine_loader->needs_psgi_engine_compat_hack;
3111
3112         warn <<"EOW";
3113 Found a legacy Catalyst::Engine::PSGI .psgi file at ${psgi_file}.
3114
3115 Its content has been ignored. Please consult the Catalyst::Upgrading
3116 documentation on how to upgrade from Catalyst::Engine::PSGI.
3117 EOW
3118     }
3119
3120     return $app->apply_default_middlewares($app->psgi_app);
3121 }
3122
3123 =head2 $c->apply_default_middlewares
3124
3125 Adds the following L<Plack> middlewares to your application, since they are
3126 useful and commonly needed:
3127
3128 L<Plack::Middleware::LighttpdScriptNameFix> (if you are using Lighttpd),
3129 L<Plack::Middleware::IIS6ScriptNameFix> (always applied since this middleware
3130 is smart enough to conditionally apply itself).
3131
3132 We will also automatically add L<Plack::Middleware::ReverseProxy> if we notice
3133 that your HTTP $env variable C<REMOTE_ADDR> is '127.0.0.1'.  This is usually
3134 an indication that your server is running behind a proxy frontend.  However in
3135 2014 this is often not the case.  We preserve this code for backwards compatibility
3136 however I B<highly> recommend that if you are running the server behind a front
3137 end proxy that you clearly indicate so with the C<using_frontend_proxy> configuration
3138 setting to true for your environment configurations that run behind a proxy.  This
3139 way if you change your front end proxy address someday your code would inexplicably
3140 stop working as expected.
3141
3142 Additionally if we detect we are using Nginx, we add a bit of custom middleware
3143 to solve some problems with the way that server handles $ENV{PATH_INFO} and
3144 $ENV{SCRIPT_NAME}.
3145
3146 Please B<NOTE> that if you do use C<using_frontend_proxy> the middleware is now
3147 adding via C<registered_middleware> rather than this method.
3148
3149 If you are using Lighttpd or IIS6 you may wish to apply these middlewares.  In
3150 general this is no longer a common case but we have this here for backward
3151 compatibility.
3152
3153 =cut
3154
3155
3156 sub apply_default_middlewares {
3157     my ($app, $psgi_app) = @_;
3158
3159     # Don't add this conditional IF we are explicitly saying we want the
3160     # frontend proxy support.  We don't need it here since if that is the
3161     # case it will be always loaded in the default_middleware.
3162
3163     unless($app->config->{using_frontend_proxy}) {
3164       $psgi_app = Plack::Middleware::Conditional->wrap(
3165           $psgi_app,
3166           builder   => sub { Plack::Middleware::ReverseProxy->wrap($_[0]) },
3167           condition => sub {
3168               my ($env) = @_;
3169               return if $app->config->{ignore_frontend_proxy};
3170               return $env->{REMOTE_ADDR} eq '127.0.0.1';
3171           },
3172       );
3173     }
3174
3175     # If we're running under Lighttpd, swap PATH_INFO and SCRIPT_NAME
3176     # http://lists.scsys.co.uk/pipermail/catalyst/2006-June/008361.html
3177     $psgi_app = Plack::Middleware::Conditional->wrap(
3178         $psgi_app,
3179         builder   => sub { Plack::Middleware::LighttpdScriptNameFix->wrap($_[0]) },
3180         condition => sub {
3181             my ($env) = @_;
3182             return unless $env->{SERVER_SOFTWARE} && $env->{SERVER_SOFTWARE} =~ m!lighttpd[-/]1\.(\d+\.\d+)!;
3183             return unless $1 < 4.23;
3184             1;
3185         },
3186     );
3187
3188     # we're applying this unconditionally as the middleware itself already makes
3189     # sure it doesn't fuck things up if it's not running under one of the right
3190     # IIS versions
3191     $psgi_app = Plack::Middleware::IIS6ScriptNameFix->wrap($psgi_app);
3192
3193     # And another IIS issue, this time with IIS7.
3194     $psgi_app = Plack::Middleware::Conditional->wrap(
3195         $psgi_app,
3196         builder => sub { Plack::Middleware::IIS7KeepAliveFix->wrap($_[0]) },
3197         condition => sub {
3198             my ($env) = @_;
3199             return $env->{SERVER_SOFTWARE} && $env->{SERVER_SOFTWARE} =~ m!IIS/7\.[0-9]!;
3200         },
3201     );
3202
3203     return $psgi_app;
3204 }
3205
3206 =head2 App->psgi_app
3207
3208 =head2 App->to_app
3209
3210 Returns a PSGI application code reference for the catalyst application
3211 C<$c>. This is the bare application created without the C<apply_default_middlewares>
3212 method called.  We do however apply C<registered_middleware> since those are
3213 integral to how L<Catalyst> functions.  Also, unlike starting your application
3214 with a generated server script (via L<Catalyst::Devel> and C<catalyst.pl>) we do
3215 not attempt to return a valid L<PSGI> application using any existing C<${myapp}.psgi>
3216 scripts in your $HOME directory.
3217
3218 B<NOTE> C<apply_default_middlewares> was originally created when the first PSGI
3219 port was done for v5.90000.  These are middlewares that are added to achieve
3220 backward compatibility with older applications.  If you start your application
3221 using one of the supplied server scripts (generated with L<Catalyst::Devel> and
3222 the project skeleton script C<catalyst.pl>) we apply C<apply_default_middlewares>
3223 automatically.  This was done so that pre and post PSGI port applications would
3224 work the same way.
3225
3226 This is what you want to be using to retrieve the PSGI application code
3227 reference of your Catalyst application for use in a custom F<.psgi> or in your
3228 own created server modules.
3229
3230 =cut
3231
3232 *to_app = \&psgi_app;
3233
3234 sub psgi_app {
3235     my ($app) = @_;
3236     my $psgi = $app->engine->build_psgi_app($app);
3237     return $app->Catalyst::Utils::apply_registered_middleware($psgi);
3238 }
3239
3240 =head2 $c->setup_home
3241
3242 Sets up the home directory.
3243
3244 =cut
3245
3246 sub setup_home {
3247     my ( $class, $home ) = @_;
3248
3249     if ( my $env = Catalyst::Utils::env_value( $class, 'HOME' ) ) {
3250         $home = $env;
3251     }
3252
3253     $home ||= Catalyst::Utils::home($class);
3254
3255     if ($home) {
3256         #I remember recently being scolded for assigning config values like this
3257         $class->config->{home} ||= $home;
3258         $class->config->{root} ||= Path::Class::Dir->new($home)->subdir('root');
3259     }
3260 }
3261
3262 =head2 $c->setup_encoding
3263
3264 Sets up the input/output encoding. See L<ENCODING>
3265
3266 =cut
3267
3268 sub setup_encoding {
3269     my $c = shift;
3270     if( exists($c->config->{encoding}) && !defined($c->config->{encoding}) ) {
3271         # Ok, so the user has explicitly said "I don't want encoding..."
3272         return;
3273     } else {
3274       my $enc = defined($c->config->{encoding}) ?
3275         delete $c->config->{encoding} : 'UTF-8'; # not sure why we delete it... (JNAP)
3276       $c->encoding($enc);
3277     }
3278 }
3279
3280 =head2 handle_unicode_encoding_exception
3281
3282 Hook to let you customize how encoding errors are handled.  By default
3283 we just throw an exception.  Receives a hashref of debug information.
3284 Example:
3285
3286     $c->handle_unicode_encoding_exception({
3287         param_value => $value,
3288         error_msg => $_,
3289             encoding_step => 'params',
3290         });
3291
3292 =cut
3293
3294 sub handle_unicode_encoding_exception {
3295     my ( $self, $exception_ctx ) = @_;
3296     die $exception_ctx->{error_msg};
3297 }
3298
3299 # Some unicode helpers cargo culted from the old plugin.  These could likely
3300 # be neater.
3301
3302 sub _handle_unicode_decoding {
3303     my ( $self, $value ) = @_;
3304
3305     return unless defined $value;
3306
3307     ## I think this mess is to support the old nested
3308     if ( ref $value eq 'ARRAY' ) {
3309         foreach ( @$value ) {
3310             $_ = $self->_handle_unicode_decoding($_);
3311         }
3312         return $value;
3313     }
3314     elsif ( ref $value eq 'HASH' ) {
3315         foreach (keys %$value) {
3316             my $encoded_key = $self->_handle_param_unicode_decoding($_);
3317             $value->{$encoded_key} = $self->_handle_unicode_decoding($value->{$_});
3318
3319             # If the key was encoded we now have two (the original and current so
3320             # delete the original.
3321             delete $value->{$_} if $_ ne $encoded_key;
3322         }
3323         return $value;
3324     }
3325     else {
3326         return $self->_handle_param_unicode_decoding($value);
3327     }
3328 }
3329
3330 sub _handle_param_unicode_decoding {
3331     my ( $self, $value ) = @_;
3332     return unless defined $value; # not in love with just ignoring undefs - jnap
3333     return $value if blessed($value); #don't decode when the value is an object.
3334
3335     my $enc = $self->encoding;
3336     return try {
3337       $enc->decode( $value, $self->_encode_check );
3338     }
3339     catch {
3340         $self->handle_unicode_encoding_exception({
3341             param_value => $value,
3342             error_msg => $_,
3343             encoding_step => 'params',
3344         });
3345     };
3346 }
3347
3348 =head2 $c->setup_log
3349
3350 Sets up log by instantiating a L<Catalyst::Log|Catalyst::Log> object and
3351 passing it to C<log()>. Pass in a comma-delimited list of levels to set the
3352 log to.
3353
3354 This method also installs a C<debug> method that returns a true value into the
3355 catalyst subclass if the "debug" level is passed in the comma-delimited list,
3356 or if the C<$CATALYST_DEBUG> environment variable is set to a true value.
3357
3358 Note that if the log has already been setup, by either a previous call to
3359 C<setup_log> or by a call such as C<< __PACKAGE__->log( MyLogger->new ) >>,
3360 that this method won't actually set up the log object.
3361
3362 =cut
3363
3364 sub setup_log {
3365     my ( $class, $levels ) = @_;
3366
3367     $levels ||= '';
3368     $levels =~ s/^\s+//;
3369     $levels =~ s/\s+$//;
3370     my %levels = map { $_ => 1 } split /\s*,\s*/, $levels;
3371
3372     my $env_debug = Catalyst::Utils::env_value( $class, 'DEBUG' );
3373     if ( defined $env_debug ) {
3374         $levels{debug} = 1 if $env_debug; # Ugly!
3375         delete($levels{debug}) unless $env_debug;
3376     }
3377
3378     unless ( $class->log ) {
3379         $class->log( Catalyst::Log->new(keys %levels) );
3380     }
3381
3382     if ( $levels{debug} ) {
3383         Class::MOP::get_metaclass_by_name($class)->add_method('debug' => sub { 1 });
3384         $class->log->debug('Debug messages enabled');
3385     }
3386 }
3387
3388 =head2 $c->setup_plugins
3389
3390 Sets up plugins.
3391
3392 =cut
3393
3394 =head2 $c->setup_stats
3395
3396 Sets up timing statistics class.
3397
3398 =cut
3399
3400 sub setup_stats {
3401     my ( $class, $stats ) = @_;
3402
3403     Catalyst::Utils::ensure_class_loaded($class->stats_class);
3404
3405     my $env = Catalyst::Utils::env_value( $class, 'STATS' );
3406     if ( defined($env) ? $env : ($stats || $class->debug ) ) {
3407         Class::MOP::get_metaclass_by_name($class)->add_method('use_stats' => sub { 1 });
3408         $class->log->debug('Statistics enabled');
3409     }
3410 }
3411
3412
3413 =head2 $c->registered_plugins
3414
3415 Returns a sorted list of the plugins which have either been stated in the
3416 import list.
3417
3418 If passed a given plugin name, it will report a boolean value indicating
3419 whether or not that plugin is loaded.  A fully qualified name is required if
3420 the plugin name does not begin with C<Catalyst::Plugin::>.
3421
3422  if ($c->registered_plugins('Some::Plugin')) {
3423      ...
3424  }
3425
3426 =cut
3427
3428 {
3429
3430     sub registered_plugins {
3431         my $proto = shift;
3432         return sort keys %{ $proto->_plugins } unless @_;
3433         my $plugin = shift;
3434         return 1 if exists $proto->_plugins->{$plugin};
3435         return exists $proto->_plugins->{"Catalyst::Plugin::$plugin"};
3436     }
3437
3438     sub _register_plugin {
3439         my ( $proto, $plugin, $instant ) = @_;
3440         my $class = ref $proto || $proto;
3441
3442         load_class( $plugin );
3443         $class->log->warn( "$plugin inherits from 'Catalyst::Component' - this is deprecated and will not work in 5.81" )
3444             if $plugin->isa( 'Catalyst::Component' );
3445         my $plugin_meta = Moose::Meta::Class->create($plugin);
3446         if (!$plugin_meta->has_method('new')
3447             && ( $plugin->isa('Class::Accessor::Fast') || $plugin->isa('Class::Accessor') ) ) {
3448             $plugin_meta->add_method('new', Moose::Object->meta->get_method('new'))
3449         }
3450         if (!$instant && !$proto->_plugins->{$plugin}) {
3451             my $meta = Class::MOP::get_metaclass_by_name($class);
3452             $meta->superclasses($plugin, $meta->superclasses);
3453         }
3454         $proto->_plugins->{$plugin} = 1;
3455         return $class;
3456     }
3457
3458     sub _default_plugins { return qw() }
3459
3460     sub setup_plugins {
3461         my ( $class, $plugins ) = @_;
3462
3463         $class->_plugins( {} ) unless $class->_plugins;
3464         $plugins = [ grep {
3465             m/Unicode::Encoding/ ? do {
3466                 $class->log->warn(
3467                     'Unicode::Encoding plugin is auto-applied,'
3468                     . ' please remove this from your appclass'
3469                     . ' and make sure to define "encoding" config'
3470                 );
3471                 unless (exists $class->config->{'encoding'}) {
3472                   $class->config->{'encoding'} = 'UTF-8';
3473                 }
3474                 () }
3475                 : $_
3476         } @$plugins ];
3477         push @$plugins, $class->_default_plugins;
3478         $plugins = Data::OptList::mkopt($plugins || []);
3479
3480         my @plugins = map {
3481             [ Catalyst::Utils::resolve_namespace(
3482                   $class . '::Plugin',
3483                   'Catalyst::Plugin', $_->[0]
3484               ),
3485               $_->[1],
3486             ]
3487          } @{ $plugins };
3488
3489         for my $plugin ( reverse @plugins ) {
3490             load_class($plugin->[0], $plugin->[1]);
3491             my $meta = find_meta($plugin->[0]);
3492             next if $meta && $meta->isa('Moose::Meta::Role');
3493
3494             $class->_register_plugin($plugin->[0]);
3495         }
3496
3497         my @roles =
3498             map  { $_->[0]->name, $_->[1] }
3499             grep { blessed($_->[0]) && $_->[0]->isa('Moose::Meta::Role') }
3500             map  { [find_meta($_->[0]), $_->[1]] }
3501             @plugins;
3502
3503         Moose::Util::apply_all_roles(
3504             $class => @roles
3505         ) if @roles;
3506     }
3507 }
3508
3509 =head2 default_middleware
3510
3511 Returns a list of instantiated PSGI middleware objects which is the default
3512 middleware that is active for this application (taking any configuration
3513 options into account, excluding your custom added middleware via the C<psgi_middleware>
3514 configuration option).  You can override this method if you wish to change
3515 the default middleware (although do so at risk since some middleware is vital
3516 to application function.)
3517
3518 The current default middleware list is:
3519
3520       Catalyst::Middleware::Stash
3521       Plack::Middleware::HTTPExceptions
3522       Plack::Middleware::RemoveRedundantBody
3523       Plack::Middleware::FixMissingBodyInRedirect
3524       Plack::Middleware::ContentLength
3525       Plack::Middleware::MethodOverride
3526       Plack::Middleware::Head
3527
3528 If the configuration setting C<using_frontend_proxy> is true we add:
3529
3530       Plack::Middleware::ReverseProxy
3531
3532 If the configuration setting C<using_frontend_proxy_path> is true we add:
3533
3534       Plack::Middleware::ReverseProxyPath
3535
3536 But B<NOTE> that L<Plack::Middleware::ReverseProxyPath> is not a dependency of the
3537 L<Catalyst> distribution so if you want to use this option you should add it to
3538 your project distribution file.
3539
3540 These middlewares will be added at L</setup_middleware> during the
3541 L</setup> phase of application startup.
3542
3543 =cut
3544
3545 sub default_middleware {
3546     my $class = shift;
3547     my @mw = (
3548       Catalyst::Middleware::Stash->new,
3549       Plack::Middleware::HTTPExceptions->new,
3550       Plack::Middleware::RemoveRedundantBody->new,
3551       Plack::Middleware::FixMissingBodyInRedirect->new,
3552       Plack::Middleware::ContentLength->new,
3553       Plack::Middleware::MethodOverride->new,
3554       Plack::Middleware::Head->new);
3555
3556     if($class->config->{using_frontend_proxy}) {
3557         push @mw, Plack::Middleware::ReverseProxy->new;
3558     }
3559
3560     if($class->config->{using_frontend_proxy_path}) {
3561         if(Class::Load::try_load_class('Plack::Middleware::ReverseProxyPath')) {
3562             push @mw, Plack::Middleware::ReverseProxyPath->new;
3563         } else {
3564           $class->log->error("Cannot use configuration 'using_frontend_proxy_path' because 'Plack::Middleware::ReverseProxyPath' is not installed");
3565         }
3566     }
3567
3568     return @mw;
3569 }
3570
3571 =head2 registered_middlewares
3572
3573 Read only accessor that returns an array of all the middleware in the order
3574 that they were added (which is the REVERSE of the order they will be applied).
3575
3576 The values returned will be either instances of L<Plack::Middleware> or of a
3577 compatible interface, or a coderef, which is assumed to be inlined middleware
3578
3579 =head2 setup_middleware (?@middleware)
3580
3581 Read configuration information stored in configuration key C<psgi_middleware> or
3582 from passed @args.
3583
3584 See under L</CONFIGURATION> information regarding C<psgi_middleware> and how
3585 to use it to enable L<Plack::Middleware>
3586
3587 This method is automatically called during 'setup' of your application, so
3588 you really don't need to invoke it.  However you may do so if you find the idea
3589 of loading middleware via configuration weird :).  For example:
3590
3591     package MyApp;
3592
3593     use Catalyst;
3594
3595     __PACKAGE__->setup_middleware('Head');
3596     __PACKAGE__->setup;
3597
3598 When we read middleware definitions from configuration, we reverse the list
3599 which sounds odd but is likely how you expect it to work if you have prior
3600 experience with L<Plack::Builder> or if you previously used the plugin
3601 L<Catalyst::Plugin::EnableMiddleware> (which is now considered deprecated)
3602
3603 So basically your middleware handles an incoming request from the first
3604 registered middleware, down and handles the response from the last middleware
3605 up.
3606
3607 =cut
3608
3609 sub registered_middlewares {
3610     my $class = shift;
3611     if(my $middleware = $class->_psgi_middleware) {
3612         my @mw = ($class->default_middleware, @$middleware);
3613
3614         if($class->config->{using_frontend_proxy}) {
3615           push @mw, Plack::Middleware::ReverseProxy->new;
3616         }
3617
3618         return @mw;
3619     } else {
3620         die "You cannot call ->registered_middlewares until middleware has been setup";
3621     }
3622 }
3623
3624 sub setup_middleware {
3625     my $class = shift;
3626     my @middleware_definitions;
3627
3628     # If someone calls this method you can add middleware with args.  However if its
3629     # called without an arg we need to setup the configuration middleware.
3630     if(@_) {
3631       @middleware_definitions = reverse(@_);
3632     } else {
3633       @middleware_definitions = reverse(@{$class->config->{'psgi_middleware'}||[]})
3634         unless $class->finalized_default_middleware;
3635       $class->finalized_default_middleware(1); # Only do this once, just in case some people call setup over and over...
3636     }
3637
3638     my @middleware = ();
3639     while(my $next = shift(@middleware_definitions)) {
3640         if(ref $next) {
3641             if(Scalar::Util::blessed $next && $next->can('wrap')) {
3642                 push @middleware, $next;
3643             } elsif(ref $next eq 'CODE') {
3644                 push @middleware, $next;
3645             } elsif(ref $next eq 'HASH') {
3646                 my $namespace = shift @middleware_definitions;
3647                 my $mw = $class->Catalyst::Utils::build_middleware($namespace, %$next);
3648                 push @middleware, $mw;
3649             } else {
3650               die "I can't handle middleware definition ${\ref $next}";
3651             }
3652         } else {
3653           my $mw = $class->Catalyst::Utils::build_middleware($next);
3654           push @middleware, $mw;
3655         }
3656     }
3657
3658     my @existing = @{$class->_psgi_middleware || []};
3659     $class->_psgi_middleware([@middleware,@existing,]);
3660 }
3661
3662 =head2 registered_data_handlers
3663
3664 A read only copy of registered Data Handlers returned as a Hash, where each key
3665 is a content type and each value is a subref that attempts to decode that content
3666 type.
3667
3668 =head2 setup_data_handlers (?@data_handler)
3669
3670 Read configuration information stored in configuration key C<data_handlers> or
3671 from passed @args.
3672
3673 See under L</CONFIGURATION> information regarding C<data_handlers>.
3674
3675 This method is automatically called during 'setup' of your application, so
3676 you really don't need to invoke it.
3677
3678 =head2 default_data_handlers
3679
3680 Default Data Handlers that come bundled with L<Catalyst>.  Currently there are
3681 only two default data handlers, for 'application/json' and an alternative to
3682 'application/x-www-form-urlencoded' which supposed nested form parameters via
3683 L<CGI::Struct> or via L<CGI::Struct::XS> IF you've installed it.
3684
3685 The 'application/json' data handler is used to parse incoming JSON into a Perl
3686 data structure.  It used either L<JSON::MaybeXS> or L<JSON>, depending on which
3687 is installed.  This allows you to fail back to L<JSON:PP>, which is a Pure Perl
3688 JSON decoder, and has the smallest dependency impact.
3689
3690 Because we don't wish to add more dependencies to L<Catalyst>, if you wish to
3691 use this new feature we recommend installing L<JSON> or L<JSON::MaybeXS> in
3692 order to get the best performance.  You should add either to your dependency
3693 list (Makefile.PL, dist.ini, cpanfile, etc.)
3694
3695 =cut
3696
3697 sub registered_data_handlers {
3698     my $class = shift;
3699     if(my $data_handlers = $class->_data_handlers) {
3700         return %$data_handlers;
3701     } else {
3702         $class->setup_data_handlers;
3703         return $class->registered_data_handlers;
3704     }
3705 }
3706
3707 sub setup_data_handlers {
3708     my ($class, %data_handler_callbacks) = @_;
3709     %data_handler_callbacks = (
3710       %{$class->default_data_handlers},
3711       %{$class->config->{'data_handlers'}||+{}},
3712       %data_handler_callbacks);
3713
3714     $class->_data_handlers(\%data_handler_callbacks);
3715 }
3716
3717 sub default_data_handlers {
3718     my ($class) = @_;
3719     return +{
3720       'application/x-www-form-urlencoded' => sub {
3721           my ($fh, $req) = @_;
3722           my $params = $req->_use_hash_multivalue ? $req->body_parameters->mixed : $req->body_parameters;
3723           Class::Load::load_first_existing_class('CGI::Struct::XS', 'CGI::Struct')
3724             ->can('build_cgi_struct')->($params);
3725       },
3726       'application/json' => sub {
3727           my ($fh, $req) = @_;
3728           my $parser = Class::Load::load_first_existing_class('JSON::MaybeXS', 'JSON');
3729           my $slurped;
3730           return eval {
3731             local $/;
3732             $slurped = $fh->getline;
3733             $parser->can("decode_json")->($slurped); # decode_json does utf8 decoding for us
3734           } || Catalyst::Exception->throw(sprintf "Error Parsing POST '%s', Error: %s", (defined($slurped) ? $slurped : 'undef') ,$@);
3735         },
3736     };
3737 }
3738
3739 sub _handle_http_exception {
3740     my ( $self, $error ) = @_;
3741     if (
3742            !$self->config->{always_catch_http_exceptions}
3743         && blessed $error
3744         && (
3745             $error->can('as_psgi')
3746             || (   $error->can('code')
3747                 && $error->code =~ m/^[1-5][0-9][0-9]$/ )
3748         )
3749       )
3750     {
3751         return 1;
3752     }
3753 }
3754
3755 =head2 $c->stack
3756
3757 Returns an arrayref of the internal execution stack (actions that are
3758 currently executing).
3759
3760 =head2 $c->stats
3761
3762 Returns the current timing statistics object. By default Catalyst uses
3763 L<Catalyst::Stats|Catalyst::Stats>, but can be set otherwise with
3764 L<< stats_class|/"$c->stats_class" >>.
3765
3766 Even if L<< -Stats|/"-Stats" >> is not enabled, the stats object is still
3767 available. By enabling it with C< $c->stats->enabled(1) >, it can be used to
3768 profile explicitly, although MyApp.pm still won't profile nor output anything
3769 by itself.
3770
3771 =head2 $c->stats_class
3772
3773 Returns or sets the stats (timing statistics) class. L<Catalyst::Stats|Catalyst::Stats> is used by default.
3774
3775 =head2 $app->stats_class_traits
3776
3777 A arrayref of L<Moose::Role>s that are applied to the stats_class before creating it.
3778
3779 =head2 $app->composed_stats_class
3780
3781 this is the stats_class composed with any 'stats_class_traits'.
3782
3783 =head2 $c->use_stats
3784
3785 Returns 1 when L<< stats collection|/"-Stats" >> is enabled.
3786
3787 Note that this is a static method, not an accessor and should be overridden
3788 by declaring C<sub use_stats { 1 }> in your MyApp.pm, not by calling C<< $c->use_stats(1) >>.
3789
3790 =cut
3791
3792 sub use_stats { 0 }
3793
3794
3795 =head2 $c->write( $data )
3796
3797 Writes $data to the output stream. When using this method directly, you
3798 will need to manually set the C<Content-Length> header to the length of
3799 your output data, if known.
3800
3801 =cut
3802
3803 sub write {
3804     my $c = shift;
3805
3806     # Finalize headers if someone manually writes output (for compat)
3807     $c->finalize_headers;
3808
3809     return $c->response->write( @_ );
3810 }
3811
3812 =head2 version
3813
3814 Returns the Catalyst version number. Mostly useful for "powered by"
3815 messages in template systems.
3816
3817 =cut
3818
3819 sub version { return $Catalyst::VERSION }
3820
3821 =head1 CONFIGURATION
3822
3823 There are a number of 'base' config variables which can be set:
3824
3825 =over
3826
3827 =item *
3828
3829 C<always_catch_http_exceptions> - As of version 5.90060 Catalyst
3830 rethrows errors conforming to the interface described by
3831 L<Plack::Middleware::HTTPExceptions> and lets the middleware deal with it.
3832 Set true to get the deprecated behaviour and have Catalyst catch HTTP exceptions.
3833
3834 =item *
3835
3836 C<default_model> - The default model picked if you say C<< $c->model >>. See L<< /$c->model($name) >>.
3837
3838 =item *
3839
3840 C<default_view> - The default view to be rendered or returned when C<< $c->view >> is called. See L<< /$c->view($name) >>.
3841
3842 =item *
3843
3844 C<disable_component_resolution_regex_fallback> - Turns
3845 off the deprecated component resolution functionality so
3846 that if any of the component methods (e.g. C<< $c->controller('Foo') >>)
3847 are called then regex search will not be attempted on string values and
3848 instead C<undef> will be returned.
3849
3850 =item *
3851
3852 C<home> - The application home directory. In an uninstalled application,
3853 this is the top level application directory. In an installed application,
3854 this will be the directory containing C<< MyApp.pm >>.
3855
3856 =item *
3857
3858 C<ignore_frontend_proxy> - See L</PROXY SUPPORT>
3859
3860 =item *
3861
3862 C<name> - The name of the application in debug messages and the debug and
3863 welcome screens
3864
3865 =item *
3866
3867 C<parse_on_demand> - The request body (for example file uploads) will not be parsed
3868 until it is accessed. This allows you to (for example) check authentication (and reject
3869 the upload) before actually receiving all the data. See L</ON-DEMAND PARSER>
3870
3871 =item *
3872
3873 C<root> - The root directory for templates. Usually this is just a
3874 subdirectory of the home directory, but you can set it to change the
3875 templates to a different directory.
3876
3877 =item *
3878
3879 C<search_extra> - Array reference passed to Module::Pluggable to for additional
3880 namespaces from which components will be loaded (and constructed and stored in
3881 C<< $c->components >>).
3882
3883 =item *
3884
3885 C<show_internal_actions> - If true, causes internal actions such as C<< _DISPATCH >>
3886 to be shown in hit debug tables in the test server.
3887
3888 =item *
3889
3890 C<use_request_uri_for_path> - Controls if the C<REQUEST_URI> or C<PATH_INFO> environment
3891 variable should be used for determining the request path.
3892
3893 Most web server environments pass the requested path to the application using environment variables,
3894 from which Catalyst has to reconstruct the request base (i.e. the top level path to / in the application,
3895 exposed as C<< $c->request->base >>) and the request path below that base.
3896
3897 There are two methods of doing this, both of which have advantages and disadvantages. Which method is used
3898 is determined by the C<< $c->config(use_request_uri_for_path) >> setting (which can either be true or false).
3899
3900 =over
3901
3902 =item use_request_uri_for_path => 0
3903
3904 This is the default (and the) traditional method that Catalyst has used for determining the path information.
3905 The path is generated from a combination of the C<PATH_INFO> and C<SCRIPT_NAME> environment variables.
3906 The allows the application to behave correctly when C<mod_rewrite> is being used to redirect requests
3907 into the application, as these variables are adjusted by mod_rewrite to take account for the redirect.
3908
3909 However this method has the major disadvantage that it is impossible to correctly decode some elements
3910 of the path, as RFC 3875 says: "C<< Unlike a URI path, the PATH_INFO is not URL-encoded, and cannot
3911 contain path-segment parameters. >>" This means PATH_INFO is B<always> decoded, and therefore Catalyst
3912 can't distinguish / vs %2F in paths (in addition to other encoded values).
3913
3914 =item use_request_uri_for_path => 1
3915
3916 This method uses the C<REQUEST_URI> and C<SCRIPT_NAME> environment variables. As C<REQUEST_URI> is never
3917 decoded, this means that applications using this mode can correctly handle URIs including the %2F character
3918 (i.e. with C<AllowEncodedSlashes> set to C<On> in Apache).
3919
3920 Given that this method of path resolution is provably more correct, it is recommended that you use
3921 this unless you have a specific need to deploy your application in a non-standard environment, and you are
3922 aware of the implications of not being able to handle encoded URI paths correctly.
3923
3924 However it also means that in a number of cases when the app isn't installed directly at a path, but instead
3925 is having paths rewritten into it (e.g. as a .cgi/fcgi in a public_html directory, with mod_rewrite in a
3926 .htaccess file, or when SSI is used to rewrite pages into the app, or when sub-paths of the app are exposed
3927 at other URIs than that which the app is 'normally' based at with C<mod_rewrite>), the resolution of
3928 C<< $c->request->base >> will be incorrect.
3929
3930 =back
3931
3932 =item *
3933
3934 C<using_frontend_proxy> - See L</PROXY SUPPORT>.
3935
3936 =item *
3937
3938 C<using_frontend_proxy_path> - Enabled L<Plack::Middleware::ReverseProxyPath> on your application (if
3939 installed, otherwise log an error).  This is useful if your application is not running on the
3940 'root' (or /) of your host server.  B<NOTE> if you use this feature you should add the required
3941 middleware to your project dependency list since its not automatically a dependency of L<Catalyst>.
3942 This has been done since not all people need this feature and we wish to restrict the growth of
3943 L<Catalyst> dependencies.
3944
3945 =item *
3946
3947 C<encoding> - See L</ENCODING>
3948
3949 This now defaults to 'UTF-8'.  You my turn it off by setting this configuration
3950 value to undef.
3951
3952 =item *
3953
3954 C<abort_chain_on_error_fix>
3955
3956 When there is an error in an action chain, the default behavior is to continue
3957 processing the remaining actions and then catch the error upon chain end.  This
3958 can lead to running actions when the application is in an unexpected state.  If
3959 you have this issue, setting this config value to true will promptly exit a
3960 chain when there is an error raised in any action (thus terminating the chain
3961 early.)
3962
3963 use like:
3964
3965     __PACKAGE__->config(abort_chain_on_error_fix => 1);
3966
3967 In the future this might become the default behavior.
3968
3969 =item *
3970
3971 C<use_hash_multivalue_in_request>
3972
3973 In L<Catalyst::Request> the methods C<query_parameters>, C<body_parametes>
3974 and C<parameters> return a hashref where values might be scalar or an arrayref
3975 depending on the incoming data.  In many cases this can be undesirable as it
3976 leads one to writing defensive code like the following:
3977
3978     my ($val) = ref($c->req->parameters->{a}) ?
3979       @{$c->req->parameters->{a}} :
3980         $c->req->parameters->{a};
3981
3982 Setting this configuration item to true will make L<Catalyst> populate the
3983 attributes underlying these methods with an instance of L<Hash::MultiValue>
3984 which is used by L<Plack::Request> and others to solve this very issue.  You
3985 may prefer this behavior to the default, if so enable this option (be warned
3986 if you enable it in a legacy application we are not sure if it is completely
3987 backwardly compatible).
3988
3989 =item *
3990
3991 C<skip_complex_post_part_handling>
3992
3993 When creating body parameters from a POST, if we run into a multpart POST
3994 that does not contain uploads, but instead contains inlined complex data
3995 (very uncommon) we cannot reliably convert that into field => value pairs.  So
3996 instead we create an instance of L<Catalyst::Request::PartData>.  If this causes
3997 issue for you, you can disable this by setting C<skip_complex_post_part_handling>
3998 to true (default is false).
3999
4000 =item *
4001
4002 C<skip_body_param_unicode_decoding>
4003
4004 Generally we decode incoming POST params based on your declared encoding (the
4005 default for this is to decode UTF-8).  If this is causing you trouble and you
4006 do not wish to turn all encoding support off (with the C<encoding> configuration
4007 parameter) you may disable this step atomically by setting this configuration
4008 parameter to true.
4009
4010 =item *
4011
4012 C<do_not_decode_query>
4013
4014 If true, then do not try to character decode any wide characters in your
4015 request URL query or keywords.  Most readings of the relevent specifications
4016 suggest these should be UTF-* encoded, which is the default that L<Catalyst>
4017 will use, hwoever if you are creating a lot of URLs manually or have external
4018 evil clients, this might cause you trouble.  If you find the changes introduced
4019 in Catalyst version 5.90080+ break some of your query code, you may disable
4020 the UTF-8 decoding globally using this configuration.
4021
4022 This setting takes precedence over C<default_query_encoding> and
4023 C<decode_query_using_global_encoding>
4024
4025 =item *
4026
4027 C<default_query_encoding>
4028
4029 By default we decode query and keywords in your request URL using UTF-8, which
4030 is our reading of the relevent specifications.  This setting allows one to
4031 specify a fixed value for how to decode your query.  You might need this if
4032 you are doing a lot of custom encoding of your URLs and not using UTF-8.
4033
4034 This setting take precedence over C<decode_query_using_global_encoding>.
4035
4036 =item *
4037
4038 C<decode_query_using_global_encoding>
4039
4040 Setting this to true will default your query decoding to whatever your
4041 general global encoding is (the default is UTF-8).
4042
4043 =item *
4044
4045 C<use_chained_args_0_special_case>
4046
4047 In older versions of Catalyst, when more than one action matched the same path
4048 AND all those matching actions declared Args(0), we'd break the tie by choosing
4049 the first action defined.  We now normalized how Args(0) works so that it
4050 follows the same rule as Args(N), which is to say when we need to break a tie
4051 we choose the LAST action defined.  If this breaks your code and you don't
4052 have time to update to follow the new normalized approach, you may set this
4053 value to true and it will globally revert to the original chaining behavior.
4054
4055 =item *
4056
4057 C<psgi_middleware> - See L<PSGI MIDDLEWARE>.
4058
4059 =item *
4060
4061 C<data_handlers> - See L<DATA HANDLERS>.
4062
4063 =back
4064
4065 =head1 EXCEPTIONS
4066
4067 Generally when you throw an exception inside an Action (or somewhere in
4068 your stack, such as in a model that an Action is calling) that exception
4069 is caught by Catalyst and unless you either catch it yourself (via eval
4070 or something like L<Try::Tiny> or by reviewing the L</error> stack, it
4071 will eventually reach L</finalize_errors> and return either the debugging
4072 error stack page, or the default error page.  However, if your exception
4073 can be caught by L<Plack::Middleware::HTTPExceptions>, L<Catalyst> will
4074 instead rethrow it so that it can be handled by that middleware (which
4075 is part of the default middleware).  For example this would allow
4076
4077     use HTTP::Throwable::Factory 'http_throw';
4078
4079     sub throws_exception :Local {
4080       my ($self, $c) = @_;
4081
4082       http_throw(SeeOther => { location =>
4083         $c->uri_for($self->action_for('redirect')) });
4084
4085     }
4086
4087 =head1 INTERNAL ACTIONS
4088
4089 Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>,
4090 C<_ACTION>, and C<_END>. These are by default not shown in the private
4091 action table, but you can make them visible with a config parameter.
4092
4093     MyApp->config(show_internal_actions => 1);
4094
4095 =head1 ON-DEMAND PARSER
4096
4097 The request body is usually parsed at the beginning of a request,
4098 but if you want to handle input yourself, you can enable on-demand
4099 parsing with a config parameter.
4100
4101     MyApp->config(parse_on_demand => 1);
4102
4103 =head1 PROXY SUPPORT
4104
4105 Many production servers operate using the common double-server approach,
4106 with a lightweight frontend web server passing requests to a larger
4107 backend server. An application running on the backend server must deal
4108 with two problems: the remote user always appears to be C<127.0.0.1> and
4109 the server's hostname will appear to be C<localhost> regardless of the
4110 virtual host that the user connected through.
4111
4112 Catalyst will automatically detect this situation when you are running
4113 the frontend and backend servers on the same machine. The following
4114 changes are made to the request.
4115
4116     $c->req->address is set to the user's real IP address, as read from
4117     the HTTP X-Forwarded-For header.
4118
4119     The host value for $c->req->base and $c->req->uri is set to the real
4120     host, as read from the HTTP X-Forwarded-Host header.
4121
4122 Additionally, you may be running your backend application on an insecure
4123 connection (port 80) while your frontend proxy is running under SSL.  If there
4124 is a discrepancy in the ports, use the HTTP header C<X-Forwarded-Port> to
4125 tell Catalyst what port the frontend listens on.  This will allow all URIs to
4126 be created properly.
4127
4128 In the case of passing in:
4129
4130     X-Forwarded-Port: 443
4131
4132 All calls to C<uri_for> will result in an https link, as is expected.
4133
4134 Obviously, your web server must support these headers for this to work.
4135
4136 In a more complex server farm environment where you may have your
4137 frontend proxy server(s) on different machines, you will need to set a
4138 configuration option to tell Catalyst to read the proxied data from the
4139 headers.
4140
4141     MyApp->config(using_frontend_proxy => 1);
4142
4143 If you do not wish to use the proxy support at all, you may set:
4144
4145     MyApp->config(ignore_frontend_proxy => 0);
4146
4147 =head2 Note about psgi files
4148
4149 Note that if you supply your own .psgi file, calling
4150 C<< MyApp->psgi_app(@_); >>, then B<this will not happen automatically>.
4151
4152 You either need to apply L<Plack::Middleware::ReverseProxy> yourself
4153 in your psgi, for example:
4154
4155     builder {
4156         enable "Plack::Middleware::ReverseProxy";
4157         MyApp->psgi_app
4158     };
4159
4160 This will unconditionally add the ReverseProxy support, or you need to call
4161 C<< $app = MyApp->apply_default_middlewares($app) >> (to conditionally
4162 apply the support depending upon your config).
4163
4164 See L<Catalyst::PSGI> for more information.
4165
4166 =head1 THREAD SAFETY
4167
4168 Catalyst has been tested under Apache 2's threading C<mpm_worker>,
4169 C<mpm_winnt>, and the standalone forking HTTP server on Windows. We
4170 believe the Catalyst core to be thread-safe.
4171
4172 If you plan to operate in a threaded environment, remember that all other
4173 modules you are using must also be thread-safe. Some modules, most notably
4174 L<DBD::SQLite>, are not thread-safe.
4175
4176 =head1 DATA HANDLERS
4177
4178 The L<Catalyst::Request> object uses L<HTTP::Body> to populate 'classic' HTML
4179 form parameters and URL search query fields.  However it has become common
4180 for various alternative content types to be PUT or POSTed to your controllers
4181 and actions.  People working on RESTful APIs, or using AJAX often use JSON,
4182 XML and other content types when communicating with an application server.  In
4183 order to better support this use case, L<Catalyst> defines a global configuration
4184 option, C<data_handlers>, which lets you associate a content type with a coderef
4185 that parses that content type into something Perl can readily access.
4186
4187     package MyApp::Web;
4188
4189     use Catalyst;
4190     use JSON::Maybe;
4191
4192     __PACKAGE__->config(
4193       data_handlers => {
4194         'application/json' => sub { local $/; decode_json $_->getline },
4195       },
4196       ## Any other configuration.
4197     );
4198
4199     __PACKAGE__->setup;
4200
4201 By default L<Catalyst> comes with a generic JSON data handler similar to the
4202 example given above, which uses L<JSON::Maybe> to provide either L<JSON::PP>
4203 (a pure Perl, dependency free JSON parser) or L<Cpanel::JSON::XS> if you have
4204 it installed (if you want the faster XS parser, add it to you project Makefile.PL
4205 or dist.ini, cpanfile, etc.)
4206
4207 The C<data_handlers> configuration is a hashref whose keys are HTTP Content-Types
4208 (matched against the incoming request type using a regexp such as to be case
4209 insensitive) and whose values are coderefs that receive a localized version of
4210 C<$_> which is a filehandle object pointing to received body.
4211
4212 This feature is considered an early access release and we reserve the right
4213 to alter the interface in order to provide a performant and secure solution to
4214 alternative request body content.  Your reports welcomed!
4215
4216 =head1 PSGI MIDDLEWARE
4217
4218 You can define middleware, defined as L<Plack::Middleware> or a compatible
4219 interface in configuration.  Your middleware definitions are in the form of an
4220 arrayref under the configuration key C<psgi_middleware>.  Here's an example
4221 with details to follow:
4222
4223     package MyApp::Web;
4224
4225     use Catalyst;
4226     use Plack::Middleware::StackTrace;
4227
4228     my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
4229
4230     __PACKAGE__->config(
4231       'psgi_middleware', [
4232         'Debug',
4233         '+MyApp::Custom',
4234         $stacktrace_middleware,
4235         'Session' => {store => 'File'},
4236         sub {
4237           my $app = shift;
4238           return sub {
4239             my $env = shift;
4240             $env->{myapp.customkey} = 'helloworld';
4241             $app->($env);
4242           },
4243         },
4244       ],
4245     );
4246
4247     __PACKAGE__->setup;
4248
4249 So the general form is:
4250
4251     __PACKAGE__->config(psgi_middleware => \@middleware_definitions);
4252
4253 Where C<@middleware> is one or more of the following, applied in the REVERSE of
4254 the order listed (to make it function similarly to L<Plack::Builder>:
4255
4256 Alternatively, you may also define middleware by calling the L</setup_middleware>
4257 package method:
4258
4259     package MyApp::Web;
4260
4261     use Catalyst;
4262
4263     __PACKAGE__->setup_middleware( \@middleware_definitions);
4264     __PACKAGE__->setup;
4265
4266 In the case where you do both (use 'setup_middleware' and configuration) the
4267 package call to setup_middleware will be applied earlier (in other words its
4268 middleware will wrap closer to the application).  Keep this in mind since in
4269 some cases the order of middleware is important.
4270
4271 The two approaches are not exclusive.
4272
4273 =over 4
4274
4275 =item Middleware Object
4276
4277 An already initialized object that conforms to the L<Plack::Middleware>
4278 specification:
4279
4280     my $stacktrace_middleware = Plack::Middleware::StackTrace->new;
4281
4282     __PACKAGE__->config(
4283       'psgi_middleware', [
4284         $stacktrace_middleware,
4285       ]);
4286
4287
4288 =item coderef
4289
4290 A coderef that is an inlined middleware:
4291
4292     __PACKAGE__->config(
4293       'psgi_middleware', [
4294         sub {
4295           my $app = shift;
4296           return sub {
4297             my $env = shift;
4298             if($env->{PATH_INFO} =~m/forced/) {
4299               Plack::App::File
4300                 ->new(file=>TestApp->path_to(qw/share static forced.txt/))
4301                 ->call($env);
4302             } else {
4303               return $app->($env);
4304             }
4305          },
4306       },
4307     ]);
4308
4309
4310
4311 =item a scalar
4312
4313 We assume the scalar refers to a namespace after normalizing it using the
4314 following rules:
4315
4316 (1) If the scalar is prefixed with a "+" (as in C<+MyApp::Foo>) then the full string
4317 is assumed to be 'as is', and we just install and use the middleware.
4318
4319 (2) If the scalar begins with "Plack::Middleware" or your application namespace
4320 (the package name of your Catalyst application subclass), we also assume then
4321 that it is a full namespace, and use it.
4322
4323 (3) Lastly, we then assume that the scalar is a partial namespace, and attempt to
4324 resolve it first by looking for it under your application namespace (for example
4325 if you application is "MyApp::Web" and the scalar is "MyMiddleware", we'd look
4326 under "MyApp::Web::Middleware::MyMiddleware") and if we don't find it there, we
4327 will then look under the regular L<Plack::Middleware> namespace (i.e. for the
4328 previous we'd try "Plack::Middleware::MyMiddleware").  We look under your application
4329 namespace first to let you 'override' common L<Plack::Middleware> locally, should
4330 you find that a good idea.
4331
4332 Examples:
4333
4334     package MyApp::Web;
4335
4336     __PACKAGE__->config(
4337       'psgi_middleware', [
4338         'Debug',  ## MyAppWeb::Middleware::Debug->wrap or Plack::Middleware::Debug->wrap
4339         'Plack::Middleware::Stacktrace', ## Plack::Middleware::Stacktrace->wrap
4340         '+MyApp::Custom',  ## MyApp::Custom->wrap
4341       ],
4342     );
4343
4344 =item a scalar followed by a hashref
4345
4346 Just like the previous, except the following C<HashRef> is used as arguments
4347 to initialize the middleware object.
4348
4349     __PACKAGE__->config(
4350       'psgi_middleware', [
4351          'Session' => {store => 'File'},
4352     ]);
4353
4354 =back
4355
4356 Please see L<PSGI> for more on middleware.
4357
4358 =head1 ENCODING
4359
4360 Starting in L<Catalyst> version 5.90080 encoding is automatically enabled
4361 and set to encode all body responses to UTF8 when possible and applicable.
4362 Following is documentation on this process.  If you are using an older
4363 version of L<Catalyst> you should review documentation for that version since
4364 a lot has changed.
4365
4366 By default encoding is now 'UTF-8'.  You may turn it off by setting
4367 the encoding configuration to undef.
4368
4369     MyApp->config(encoding => undef);
4370
4371 This is recommended for temporary backwards compatibility only.
4372
4373 Encoding is automatically applied when the content-type is set to
4374 a type that can be encoded.  Currently we encode when the content type
4375 matches the following regular expression:
4376
4377     $content_type =~ /^text|xml$|javascript$/
4378
4379 Encoding is set on the application, but it is copied to the context object
4380 so that you can override it on a request basis.
4381
4382 Be default we don't automatically encode 'application/json' since the most
4383 common approaches to generating this type of response (Either via L<Catalyst::View::JSON>
4384 or L<Catalyst::Action::REST>) will do so already and we want to avoid double
4385 encoding issues.
4386
4387 If you are producing JSON response in an unconventional manner (such
4388 as via a template or manual strings) you should perform the UTF8 encoding
4389 manually as well such as to conform to the JSON specification.
4390
4391 NOTE: We also examine the value of $c->response->content_encoding.  If
4392 you set this (like for example 'gzip', and manually gzipping the body)
4393 we assume that you have done all the necessary encoding yourself, since
4394 we cannot encode the gzipped contents.  If you use a plugin like
4395 L<Catalyst::Plugin::Compress> you need to update to a modern version in order
4396 to have this function correctly  with the new UTF8 encoding code, or you
4397 can use L<Plack::Middleware::Deflater> or (probably best) do your compression on
4398 a front end proxy.
4399
4400 =head2 Methods
4401
4402 =over 4
4403
4404 =item encoding
4405
4406 Returns an instance of an C<Encode> encoding
4407
4408     print $c->encoding->name
4409
4410 =item handle_unicode_encoding_exception ($exception_context)
4411
4412 Method called when decoding process for a request fails.
4413
4414 An C<$exception_context> hashref is provided to allow you to override the
4415 behaviour of your application when given data with incorrect encodings.
4416
4417 The default method throws exceptions in the case of invalid request parameters
4418 (resulting in a 500 error), but ignores errors in upload filenames.
4419
4420 The keys passed in the C<$exception_context> hash are:
4421
4422 =over
4423
4424 =item param_value
4425
4426 The value which was not able to be decoded.
4427
4428 =item error_msg
4429
4430 The exception received from L<Encode>.
4431
4432 =item encoding_step
4433
4434 What type of data was being decoded. Valid values are (currently)
4435 C<params> - for request parameters / arguments / captures
4436 and C<uploads> - for request upload filenames.
4437
4438 =back
4439
4440 =back
4441
4442 =head1 SUPPORT
4443
4444 IRC:
4445
4446     Join #catalyst on irc.perl.org.
4447
4448 Mailing Lists:
4449
4450     http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
4451     http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
4452
4453 Web:
4454
4455     http://catalyst.perl.org
4456
4457 Wiki:
4458
4459     http://dev.catalyst.perl.org
4460
4461 =head1 SEE ALSO
4462
4463 =head2 L<Task::Catalyst> - All you need to start with Catalyst
4464
4465 =head2 L<Catalyst::Manual> - The Catalyst Manual
4466
4467 =head2 L<Catalyst::Component>, L<Catalyst::Controller> - Base classes for components
4468
4469 =head2 L<Catalyst::Engine> - Core engine
4470
4471 =head2 L<Catalyst::Log> - Log class.
4472
4473 =head2 L<Catalyst::Request> - Request object
4474
4475 =head2 L<Catalyst::Response> - Response object
4476
4477 =head2 L<Catalyst::Test> - The test suite.
4478
4479 =head1 PROJECT FOUNDER
4480
4481 sri: Sebastian Riedel <sri@cpan.org>
4482
4483 =head1 CONTRIBUTORS
4484
4485 abw: Andy Wardley
4486
4487 acme: Leon Brocard <leon@astray.com>
4488
4489 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
4490
4491 andrewalker: André Walker <andre@cpan.org>
4492
4493 Andrew Bramble
4494
4495 Andrew Ford E<lt>A.Ford@ford-mason.co.ukE<gt>
4496
4497 Andrew Ruthven
4498
4499 andyg: Andy Grundman <andy@hybridized.org>
4500
4501 audreyt: Audrey Tang
4502
4503 bricas: Brian Cassidy <bricas@cpan.org>
4504
4505 Caelum: Rafael Kitover <rkitover@io.com>
4506
4507 chansen: Christian Hansen
4508
4509 chicks: Christopher Hicks
4510
4511 Chisel Wright C<pause@herlpacker.co.uk>
4512
4513 Danijel Milicevic C<me@danijel.de>
4514
4515 davewood: David Schmidt <davewood@cpan.org>
4516
4517 David Kamholz E<lt>dkamholz@cpan.orgE<gt>
4518
4519 David Naughton, C<naughton@umn.edu>
4520
4521 David E. Wheeler
4522
4523 dhoss: Devin Austin <dhoss@cpan.org>
4524
4525 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
4526
4527 Drew Taylor
4528
4529 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
4530
4531 esskar: Sascha Kiefer
4532
4533 fireartist: Carl Franks <cfranks@cpan.org>
4534
4535 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
4536
4537 gabb: Danijel Milicevic
4538
4539 Gary Ashton Jones
4540
4541 Gavin Henry C<ghenry@perl.me.uk>
4542
4543 Geoff Richards
4544
4545 groditi: Guillermo Roditi <groditi@gmail.com>
4546
4547 hobbs: Andrew Rodland <andrew@cleverdomain.org>
4548
4549 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
4550
4551 jcamacho: Juan Camacho
4552
4553 jester: Jesse Sheidlower C<jester@panix.com>
4554
4555 jhannah: Jay Hannah <jay@jays.net>
4556
4557 Jody Belka
4558
4559 Johan Lindstrom
4560
4561 jon: Jon Schutz <jjschutz@cpan.org>
4562
4563 Jonathan Rockway C<< <jrockway@cpan.org> >>
4564
4565 Kieren Diment C<kd@totaldatasolution.com>
4566
4567 konobi: Scott McWhirter <konobi@cpan.org>
4568
4569 marcus: Marcus Ramberg <mramberg@cpan.org>
4570
4571 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
4572
4573 mgrimes: Mark Grimes <mgrimes@cpan.org>
4574
4575 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
4576
4577 mugwump: Sam Vilain
4578
4579 naughton: David Naughton
4580
4581 ningu: David Kamholz <dkamholz@cpan.org>
4582
4583 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
4584
4585 numa: Dan Sully <daniel@cpan.org>
4586
4587 obra: Jesse Vincent
4588
4589 Octavian Rasnita
4590
4591 omega: Andreas Marienborg
4592
4593 Oleg Kostyuk <cub.uanic@gmail.com>
4594
4595 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
4596
4597 rafl: Florian Ragwitz <rafl@debian.org>
4598
4599 random: Roland Lammel <lammel@cpan.org>
4600
4601 Robert Sedlacek C<< <rs@474.at> >>
4602
4603 SpiceMan: Marcel Montes
4604
4605 sky: Arthur Bergman
4606
4607 szbalint: Balint Szilakszi <szbalint@cpan.org>
4608
4609 t0m: Tomas Doran <bobtfish@bobtfish.net>
4610
4611 Ulf Edvinsson
4612
4613 vanstyn: Henry Van Styn <vanstyn@cpan.org>
4614
4615 Viljo Marrandi C<vilts@yahoo.com>
4616
4617 Will Hawes C<info@whawes.co.uk>
4618
4619 willert: Sebastian Willert <willert@cpan.org>
4620
4621 wreis: Wallace Reis <wreis@cpan.org>
4622
4623 Yuval Kogman, C<nothingmuch@woobling.org>
4624
4625 rainboxx: Matthias Dietrich, C<perl@rainboxx.de>
4626
4627 dd070: Dhaval Dhanani <dhaval070@gmail.com>
4628
4629 Upasana <me@upasana.me>
4630
4631 John Napiorkowski (jnap) <jjnapiork@cpan.org>
4632
4633 =head1 COPYRIGHT
4634
4635 Copyright (c) 2005-2015, the above named PROJECT FOUNDER and CONTRIBUTORS.
4636
4637 =head1 LICENSE
4638
4639 This library is free software. You can redistribute it and/or modify it under
4640 the same terms as Perl itself.
4641
4642 =cut
4643
4644 no Moose;
4645
4646 __PACKAGE__->meta->make_immutable;
4647
4648 1;