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