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