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