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