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