lib/Catalyst.pm

   1 package Catalyst;
   2
   3 use Moose;
   4 use Moose::Meta::Class ();
   5 extends 'Catalyst::Component';
   6 use Moose::Util qw/find_meta/;
   7 use namespace::clean -except => 'meta';
   8 use Catalyst::Exception;
   9 use Catalyst::Exception::Detach;
  10 use Catalyst::Exception::Go;
  11 use Catalyst::Log;
  12 use Catalyst::Request;
  13 use Catalyst::Request::Upload;
  14 use Catalyst::Response;
  15 use Catalyst::Utils;
  16 use Catalyst::Controller;
  17 use Data::OptList;
  18 use 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.90015';
 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
 135     # FIXME
 136     # what is this for?
 137     # we call setup_home on import AND on ->setup
 138     # is there a reason for it?
 139     # anyway there is no point for setup_home without setup_config() so...
 140     $caller->setup_config;
 141     $caller->setup_home;
 142 }
 143
 144 sub MODIFY_CODE_ATTRIBUTES {
 145     Catalyst::Exception->throw(
 146         "Catalyst applications (aka MyApp) cannot be controllers anymore. " .
 147         "That has been deprecated and removed. You should create a " .
 148         "controller class called Root.pm, and move relevant code to that class."
 149     );
 150 }
 151
 152
 153 sub _application { $_[0] }
 154
 155 =encoding utf8
 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     if ($class->config->{case_sensitive}) {
1028         $class->log->warn($class . "->config->{case_sensitive} is set.");
1029         $class->log->warn("This setting is deprecated and planned to be removed in Catalyst 5.81.");
1030     }
1031
1032     $class->setup_finalize;
1033     # Should be the last thing we do so that user things hooking
1034     # setup_finalize can log..
1035     $class->log->_flush() if $class->log->can('_flush');
1036     return 1; # Explicit return true as people have __PACKAGE__->setup as the last thing in their class. HATE.
1037 }
1038
1039 =head2 $app->setup_finalize
1040
1041 A hook to attach modifiers to. This method does not do anything except set the
1042 C<setup_finished> accessor.
1043
1044 Applying method modifiers to the C<setup> method doesn't work, because of quirky things done for plugin setup.
1045
1046 Example:
1047
1048     after setup_finalize => sub {
1049         my $app = shift;
1050
1051         ## do stuff here..
1052     };
1053
1054 =cut
1055
1056 sub setup_finalize {
1057     my ($class) = @_;
1058     $class->setup_finished(1);
1059 }
1060
1061 =head2 $c->uri_for( $path?, @args?, \%query_values? )
1062
1063 =head2 $c->uri_for( $action, \@captures?, @args?, \%query_values? )
1064
1065 Constructs an absolute L<URI> object based on the application root, the
1066 provided path, and the additional arguments and query parameters provided.
1067 When used as a string, provides a textual URI.  If you need more flexibility
1068 than this (i.e. the option to provide relative URIs etc.) see
1069 L<Catalyst::Plugin::SmartURI>.
1070
1071 If no arguments are provided, the URI for the current action is returned.
1072 To return the current action and also provide @args, use
1073 C<< $c->uri_for( $c->action, @args ) >>.
1074
1075 If the first argument is a string, it is taken as a public URI path relative
1076 to C<< $c->namespace >> (if it doesn't begin with a forward slash) or
1077 relative to the application root (if it does). It is then merged with
1078 C<< $c->request->base >>; any C<@args> are appended as additional path
1079 components; and any C<%query_values> are appended as C<?foo=bar> parameters.
1080
1081 If the first argument is a L<Catalyst::Action> it represents an action which
1082 will have its path resolved using C<< $c->dispatcher->uri_for_action >>. The
1083 optional C<\@captures> argument (an arrayref) allows passing the captured
1084 variables that are needed to fill in the paths of Chained and Regex actions;
1085 once the path is resolved, C<uri_for> continues as though a path was
1086 provided, appending any arguments or parameters and creating an absolute
1087 URI.
1088
1089 The captures for the current request can be found in
1090 C<< $c->request->captures >>, and actions can be resolved using
1091 C<< Catalyst::Controller->action_for($name) >>. If you have a private action
1092 path, use C<< $c->uri_for_action >> instead.
1093
1094   # Equivalent to $c->req->uri
1095   $c->uri_for($c->action, $c->req->captures,
1096       @{ $c->req->args }, $c->req->params);
1097
1098   # For the Foo action in the Bar controller
1099   $c->uri_for($c->controller('Bar')->action_for('Foo'));
1100
1101   # Path to a static resource
1102   $c->uri_for('/static/images/logo.png');
1103
1104 =cut
1105
1106 sub uri_for {
1107     my ( $c, $path, @args ) = @_;
1108
1109     if (blessed($path) && $path->isa('Catalyst::Controller')) {
1110         $path = $path->path_prefix;
1111         $path =~ s{/+\z}{};
1112         $path .= '/';
1113     }
1114
1115     undef($path) if (defined $path && $path eq '');
1116
1117     my $params =
1118       ( scalar @args && ref $args[$#args] eq 'HASH' ? pop @args : {} );
1119
1120     carp "uri_for called with undef argument" if grep { ! defined $_ } @args;
1121     foreach my $arg (@args) {
1122         utf8::encode($arg) if utf8::is_utf8($arg);
1123         $arg =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1124     }
1125
1126     if ( blessed($path) ) { # action object
1127         s|/|%2F|g for @args;
1128         my $captures = [ map { s|/|%2F|g; $_; }
1129                         ( scalar @args && ref $args[0] eq 'ARRAY'
1130                          ? @{ shift(@args) }
1131                          : ()) ];
1132
1133         foreach my $capture (@$captures) {
1134             utf8::encode($capture) if utf8::is_utf8($capture);
1135             $capture =~ s/([^$URI::uric])/$URI::Escape::escapes{$1}/go;
1136         }
1137
1138         my $action = $path;
1139         # ->uri_for( $action, \@captures_and_args, \%query_values? )
1140         if( !@args && $action->number_of_args ) {
1141             my $expanded_action = $c->dispatcher->expand_action( $action );
1142
1143             my $num_captures = $expanded_action->number_of_captures;
1144             unshift @args, splice @$captures, $num_captures;
1145         }
1146
1147        $path = $c->dispatcher->uri_for_action($action, $captures);
1148         if (not defined $path) {
1149             $c->log->debug(qq/Can't find uri_for action '$action' @$captures/)
1150                 if $c->debug;
1151             return undef;
1152         }
1153         $path = '/' if $path eq '';
1154     }
1155
1156     unshift(@args, $path);
1157
1158     unless (defined $path && $path =~ s!^/!!) { # in-place strip
1159         my $namespace = $c->namespace;
1160         if (defined $path) { # cheesy hack to handle path '../foo'
1161            $namespace =~ s{(?:^|/)[^/]+$}{} while $args[0] =~ s{^\.\./}{};
1162         }
1163         unshift(@args, $namespace || '');
1164     }
1165
1166     # join args with '/', or a blank string
1167     my $args = join('/', grep { defined($_) } @args);
1168     $args =~ s/\?/%3F/g; # STUPID STUPID SPECIAL CASE
1169     $args =~ s!^/+!!;
1170     my $base = $c->req->base;
1171     my $class = ref($base);
1172     $base =~ s{(?<!/)$}{/};
1173
1174     my $query = '';
1175
1176     if (my @keys = keys %$params) {
1177       # somewhat lifted from URI::_query's query_form
1178       $query = '?'.join('&', map {
1179           my $val = $params->{$_};
1180           s/([;\/?:@&=+,\$\[\]%])/$URI::Escape::escapes{$1}/go;
1181           s/ /+/g;
1182           my $key = $_;
1183           $val = '' unless defined $val;
1184           (map {
1185               my $param = "$_";
1186               utf8::encode( $param ) if utf8::is_utf8($param);
1187               # using the URI::Escape pattern here so utf8 chars survive
1188               $param =~ s/([^A-Za-z0-9\-_.!~*'() ])/$URI::Escape::escapes{$1}/go;
1189               $param =~ s/ /+/g;
1190               "${key}=$param"; } ( ref $val eq 'ARRAY' ? @$val : $val ));
1191       } @keys);
1192     }
1193
1194     my $res = bless(\"${base}${args}${query}", $class);
1195     $res;
1196 }
1197
1198 =head2 $c->uri_for_action( $path, \@captures_and_args?, @args?, \%query_values? )
1199
1200 =head2 $c->uri_for_action( $action, \@captures_and_args?, @args?, \%query_values? )
1201
1202 =over
1203
1204 =item $path
1205
1206 A private path to the Catalyst action you want to create a URI for.
1207
1208 This is a shortcut for calling C<< $c->dispatcher->get_action_by_path($path)
1209 >> and passing the resulting C<$action> and the remaining arguments to C<<
1210 $c->uri_for >>.
1211
1212 You can also pass in a Catalyst::Action object, in which case it is passed to
1213 C<< $c->uri_for >>.
1214
1215 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.
1216
1217 For example, if the action looks like:
1218
1219  package MyApp::Controller::Users;
1220
1221  sub lst : Path('the-list') {}
1222
1223 You can use:
1224
1225  $c->uri_for_action('/users/lst')
1226
1227 and it will create the URI /users/the-list.
1228
1229 =item \@captures_and_args?
1230
1231 Optional array reference of Captures (i.e. C<<CaptureArgs or $c->req->captures>)
1232 and arguments to the request. Usually used with L<Catalyst::DispatchType::Chained>
1233 to interpolate all the parameters in the URI.
1234
1235 =item @args?
1236
1237 Optional list of extra arguments - can be supplied in the
1238 C<< \@captures_and_args? >> array ref, or here - whichever is easier for your
1239 code.
1240
1241 Your action can have zero, a fixed or a variable number of args (e.g.
1242 C<< Args(1) >> for a fixed number or C<< Args() >> for a variable number)..
1243
1244 =item \%query_values?
1245
1246 Optional array reference of query parameters to append. E.g.
1247
1248   { foo => 'bar' }
1249
1250 will generate
1251
1252   /rest/of/your/uri?foo=bar
1253
1254 =back
1255
1256 =cut
1257
1258 sub uri_for_action {
1259     my ( $c, $path, @args ) = @_;
1260     my $action = blessed($path)
1261       ? $path
1262       : $c->dispatcher->get_action_by_path($path);
1263     unless (defined $action) {
1264       croak "Can't find action for path '$path'";
1265     }
1266     return $c->uri_for( $action, @args );
1267 }
1268
1269 =head2 $c->welcome_message
1270
1271 Returns the Catalyst welcome HTML page.
1272
1273 =cut
1274
1275 sub welcome_message {
1276     my $c      = shift;
1277     my $name   = $c->config->{name};
1278     my $logo   = $c->uri_for('/static/images/catalyst_logo.png');
1279     my $prefix = Catalyst::Utils::appprefix( ref $c );
1280     $c->response->content_type('text/html; charset=utf-8');
1281     return <<"EOF";
1282 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1283     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1284 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
1285     <head>
1286     <meta http-equiv="Content-Language" content="en" />
1287     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
1288         <title>$name on Catalyst $VERSION</title>
1289         <style type="text/css">
1290             body {
1291                 color: #000;
1292                 background-color: #eee;
1293             }
1294             div#content {
1295                 width: 640px;
1296                 margin-left: auto;
1297                 margin-right: auto;
1298                 margin-top: 10px;
1299                 margin-bottom: 10px;
1300                 text-align: left;
1301                 background-color: #ccc;
1302                 border: 1px solid #aaa;
1303             }
1304             p, h1, h2 {
1305                 margin-left: 20px;
1306                 margin-right: 20px;
1307                 font-family: verdana, tahoma, sans-serif;
1308             }
1309             a {
1310                 font-family: verdana, tahoma, sans-serif;
1311             }
1312             :link, :visited {
1313                     text-decoration: none;
1314                     color: #b00;
1315                     border-bottom: 1px dotted #bbb;
1316             }
1317             :link:hover, :visited:hover {
1318                     color: #555;
1319             }
1320             div#topbar {
1321                 margin: 0px;
1322             }
1323             pre {
1324                 margin: 10px;
1325                 padding: 8px;
1326             }
1327             div#answers {
1328                 padding: 8px;
1329                 margin: 10px;
1330                 background-color: #fff;
1331                 border: 1px solid #aaa;
1332             }
1333             h1 {
1334                 font-size: 0.9em;
1335                 font-weight: normal;
1336                 text-align: center;
1337             }
1338             h2 {
1339                 font-size: 1.0em;
1340             }
1341             p {
1342                 font-size: 0.9em;
1343             }
1344             p img {
1345                 float: right;
1346                 margin-left: 10px;
1347             }
1348             span#appname {
1349                 font-weight: bold;
1350                 font-size: 1.6em;
1351             }
1352         </style>
1353     </head>
1354     <body>
1355         <div id="content">
1356             <div id="topbar">
1357                 <h1><span id="appname">$name</span> on <a href="http://catalyst.perl.org">Catalyst</a>
1358                     $VERSION</h1>
1359              </div>
1360              <div id="answers">
1361                  <p>
1362                  <img src="$logo" alt="Catalyst Logo" />
1363                  </p>
1364                  <p>Welcome to the  world of Catalyst.
1365                     This <a href="http://en.wikipedia.org/wiki/MVC">MVC</a>
1366                     framework will make web development something you had
1367                     never expected it to be: Fun, rewarding, and quick.</p>
1368                  <h2>What to do now?</h2>
1369                  <p>That really depends  on what <b>you</b> want to do.
1370                     We do, however, provide you with a few starting points.</p>
1371                  <p>If you want to jump right into web development with Catalyst
1372                     you might want to start with a tutorial.</p>
1373 <pre>perldoc <a href="https://metacpan.org/module/Catalyst::Manual::Tutorial">Catalyst::Manual::Tutorial</a></code>
1374 </pre>
1375 <p>Afterwards you can go on to check out a more complete look at our features.</p>
1376 <pre>
1377 <code>perldoc <a href="https://metacpan.org/module/Catalyst::Manual::Intro">Catalyst::Manual::Intro</a>
1378 <!-- Something else should go here, but the Catalyst::Manual link seems unhelpful -->
1379 </code></pre>
1380                  <h2>What to do next?</h2>
1381                  <p>Next it's time to write an actual application. Use the
1382                     helper scripts to generate <a href="https://metacpan.org/search?q=Catalyst%3A%3AController">controllers</a>,
1383                     <a href="https://metacpan.org/search?q=Catalyst%3A%3AModel">models</a>, and
1384                     <a href="https://metacpan.org/search?q=Catalyst%3A%3AView">views</a>;
1385                     they can save you a lot of work.</p>
1386                     <pre><code>script/${prefix}_create.pl --help</code></pre>
1387                     <p>Also, be sure to check out the vast and growing
1388                     collection of <a href="http://search.cpan.org/search?query=Catalyst">plugins for Catalyst on CPAN</a>;
1389                     you are likely to find what you need there.
1390                     </p>
1391
1392                  <h2>Need help?</h2>
1393                  <p>Catalyst has a very active community. Here are the main places to
1394                     get in touch with us.</p>
1395                  <ul>
1396                      <li>
1397                          <a href="http://dev.catalyst.perl.org">Wiki</a>
1398                      </li>
1399                      <li>
1400                          <a href="http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst">Mailing-List</a>
1401                      </li>
1402                      <li>
1403                          <a href="irc://irc.perl.org/catalyst">IRC channel #catalyst on irc.perl.org</a>
1404                      </li>
1405                  </ul>
1406                  <h2>In conclusion</h2>
1407                  <p>The Catalyst team hopes you will enjoy using Catalyst as much
1408                     as we enjoyed making it. Please contact us if you have ideas
1409                     for improvement or other feedback.</p>
1410              </div>
1411          </div>
1412     </body>
1413 </html>
1414 EOF
1415 }
1416
1417 =head2 run_options
1418
1419 Contains a hash of options passed from the application script, including
1420 the original ARGV the script received, the processed values from that
1421 ARGV and any extra arguments to the script which were not processed.
1422
1423 This can be used to add custom options to your application's scripts
1424 and setup your application differently depending on the values of these
1425 options.
1426
1427 =head1 INTERNAL METHODS
1428
1429 These methods are not meant to be used by end users.
1430
1431 =head2 $c->components
1432
1433 Returns a hash of components.
1434
1435 =cut
1436
1437 sub components {
1438     my ( $class, $comps ) = @_;
1439
1440     # people create components calling this sub directly, before setup
1441     $class->setup_config unless $class->container;
1442
1443     my $container = $class->container;
1444
1445     if ( $comps ) {
1446         $container->add_component( $_ ) for keys %$comps;
1447     }
1448
1449     return $container->get_all_components($class);
1450 }
1451
1452 =head2 $c->context_class
1453
1454 Returns or sets the context class.
1455
1456 =head2 $c->counter
1457
1458 Returns a hashref containing coderefs and execution counts (needed for
1459 deep recursion detection).
1460
1461 =head2 $c->depth
1462
1463 Returns the number of actions on the current internal execution stack.
1464
1465 =head2 $c->dispatch
1466
1467 Dispatches a request to actions.
1468
1469 =cut
1470
1471 sub dispatch { my $c = shift; $c->dispatcher->dispatch( $c, @_ ) }
1472
1473 =head2 $c->dispatcher_class
1474
1475 Returns or sets the dispatcher class.
1476
1477 =head2 $c->dump_these
1478
1479 Returns a list of 2-element array references (name, structure) pairs
1480 that will be dumped on the error page in debug mode.
1481
1482 =cut
1483
1484 sub dump_these {
1485     my $c = shift;
1486     [ Request => $c->req ],
1487     [ Response => $c->res ],
1488     [ Stash => $c->stash ],
1489     [ Config => $c->config ];
1490 }
1491
1492 =head2 $c->engine_class
1493
1494 Returns or sets the engine class.
1495
1496 =head2 $c->execute( $class, $coderef )
1497
1498 Execute a coderef in given class and catch exceptions. Errors are available
1499 via $c->error.
1500
1501 =cut
1502
1503 sub execute {
1504     my ( $c, $class, $code ) = @_;
1505     $class = $c->component($class) || $class;
1506     $c->state(0);
1507
1508     if ( $c->depth >= $RECURSION ) {
1509         my $action = $code->reverse();
1510         $action = "/$action" unless $action =~ /->/;
1511         my $error = qq/Deep recursion detected calling "${action}"/;
1512         $c->log->error($error);
1513         $c->error($error);
1514         $c->state(0);
1515         return $c->state;
1516     }
1517
1518     my $stats_info = $c->_stats_start_execute( $code ) if $c->use_stats;
1519
1520     push( @{ $c->stack }, $code );
1521
1522     no warnings 'recursion';
1523     # N.B. This used to be combined, but I have seen $c get clobbered if so, and
1524     #      I have no idea how, ergo $ret (which appears to fix the issue)
1525     eval { my $ret = $code->execute( $class, $c, @{ $c->req->args } ) || 0; $c->state( $ret ) };
1526
1527     $c->_stats_finish_execute( $stats_info ) if $c->use_stats and $stats_info;
1528
1529     my $last = pop( @{ $c->stack } );
1530
1531     if ( my $error = $@ ) {
1532         if ( blessed($error) and $error->isa('Catalyst::Exception::Detach') ) {
1533             $error->rethrow if $c->depth > 1;
1534         }
1535         elsif ( blessed($error) and $error->isa('Catalyst::Exception::Go') ) {
1536             $error->rethrow if $c->depth > 0;
1537         }
1538         else {
1539             unless ( ref $error ) {
1540                 no warnings 'uninitialized';
1541                 chomp $error;
1542                 my $class = $last->class;
1543                 my $name  = $last->name;
1544                 $error = qq/Caught exception in $class->$name "$error"/;
1545             }
1546             $c->error($error);
1547         }
1548         $c->state(0);
1549     }
1550     return $c->state;
1551 }
1552
1553 sub _stats_start_execute {
1554     my ( $c, $code ) = @_;
1555     my $appclass = ref($c) || $c;
1556     return if ( ( $code->name =~ /^_.*/ )
1557         && ( !$appclass->config->{show_internal_actions} ) );
1558
1559     my $action_name = $code->reverse();
1560     $c->counter->{$action_name}++;
1561
1562     my $action = $action_name;
1563     $action = "/$action" unless $action =~ /->/;
1564
1565     # determine if the call was the result of a forward
1566     # this is done by walking up the call stack and looking for a calling
1567     # sub of Catalyst::forward before the eval
1568     my $callsub = q{};
1569     for my $index ( 2 .. 11 ) {
1570         last
1571         if ( ( caller($index) )[0] eq 'Catalyst'
1572             && ( caller($index) )[3] eq '(eval)' );
1573
1574         if ( ( caller($index) )[3] =~ /forward$/ ) {
1575             $callsub = ( caller($index) )[3];
1576             $action  = "-> $action";
1577             last;
1578         }
1579     }
1580
1581     my $uid = $action_name . $c->counter->{$action_name};
1582
1583     # is this a root-level call or a forwarded call?
1584     if ( $callsub =~ /forward$/ ) {
1585         my $parent = $c->stack->[-1];
1586
1587         # forward, locate the caller
1588         if ( defined $parent && exists $c->counter->{"$parent"} ) {
1589             $c->stats->profile(
1590                 begin  => $action,
1591                 parent => "$parent" . $c->counter->{"$parent"},
1592                 uid    => $uid,
1593             );
1594         }
1595         else {
1596
1597             # forward with no caller may come from a plugin
1598             $c->stats->profile(
1599                 begin => $action,
1600                 uid   => $uid,
1601             );
1602         }
1603     }
1604     else {
1605
1606         # root-level call
1607         $c->stats->profile(
1608             begin => $action,
1609             uid   => $uid,
1610         );
1611     }
1612     return $action;
1613
1614 }
1615
1616 sub _stats_finish_execute {
1617     my ( $c, $info ) = @_;
1618     $c->stats->profile( end => $info );
1619 }
1620
1621 =head2 $c->finalize
1622
1623 Finalizes the request.
1624
1625 =cut
1626
1627 sub finalize {
1628     my $c = shift;
1629
1630     for my $error ( @{ $c->error } ) {
1631         $c->log->error($error);
1632     }
1633
1634     # Allow engine to handle finalize flow (for POE)
1635     my $engine = $c->engine;
1636     if ( my $code = $engine->can('finalize') ) {
1637         $engine->$code($c);
1638     }
1639     else {
1640
1641         $c->finalize_uploads;
1642
1643         # Error
1644         if ( $#{ $c->error } >= 0 ) {
1645             $c->finalize_error;
1646         }
1647
1648         $c->finalize_headers unless $c->response->finalized_headers;
1649
1650         # HEAD request
1651         if ( $c->request->method eq 'HEAD' ) {
1652             $c->response->body('');
1653         }
1654
1655         $c->finalize_body;
1656     }
1657
1658     $c->log_response;
1659
1660     if ($c->use_stats) {
1661         my $elapsed = sprintf '%f', $c->stats->elapsed;
1662         my $av = $elapsed == 0 ? '??' : sprintf '%.3f', 1 / $elapsed;
1663         $c->log->info(
1664             "Request took ${elapsed}s ($av/s)\n" . $c->stats->report . "\n" );
1665     }
1666
1667     return $c->response->status;
1668 }
1669
1670 =head2 $c->finalize_body
1671
1672 Finalizes body.
1673
1674 =cut
1675
1676 sub finalize_body { my $c = shift; $c->engine->finalize_body( $c, @_ ) }
1677
1678 =head2 $c->finalize_cookies
1679
1680 Finalizes cookies.
1681
1682 =cut
1683
1684 sub finalize_cookies { my $c = shift; $c->engine->finalize_cookies( $c, @_ ) }
1685
1686 =head2 $c->finalize_error
1687
1688 Finalizes error.
1689
1690 =cut
1691
1692 sub finalize_error { my $c = shift; $c->engine->finalize_error( $c, @_ ) }
1693
1694 =head2 $c->finalize_headers
1695
1696 Finalizes headers.
1697
1698 =cut
1699
1700 sub finalize_headers {
1701     my $c = shift;
1702
1703     my $response = $c->response; #accessor calls can add up?
1704
1705     # Check if we already finalized headers
1706     return if $response->finalized_headers;
1707
1708     # Handle redirects
1709     if ( my $location = $response->redirect ) {
1710         $c->log->debug(qq/Redirecting to "$location"/) if $c->debug;
1711         $response->header( Location => $location );
1712
1713         if ( !$response->has_body ) {
1714             # Add a default body if none is already present
1715             $response->body(<<"EOF");
1716 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
1717 <html xmlns="http://www.w3.org/1999/xhtml">
1718   <head>
1719     <title>Moved</title>
1720   </head>
1721   <body>
1722      <p>This item has moved <a href="$location">here</a>.</p>
1723   </body>
1724 </html>
1725 EOF
1726             $response->content_type('text/html; charset=utf-8');
1727         }
1728     }
1729
1730     # Content-Length
1731     if ( defined $response->body && length $response->body && !$response->content_length ) {
1732
1733         # get the length from a filehandle
1734         if ( blessed( $response->body ) && $response->body->can('read') || ref( $response->body ) eq 'GLOB' )
1735         {
1736             my $size = -s $response->body;
1737             if ( $size ) {
1738                 $response->content_length( $size );
1739             }
1740             else {
1741                 $c->log->warn('Serving filehandle without a content-length');
1742             }
1743         }
1744         else {
1745             # everything should be bytes at this point, but just in case
1746             $response->content_length( length( $response->body ) );
1747         }
1748     }
1749
1750     # Errors
1751     if ( $response->status =~ /^(1\d\d|[23]04)$/ ) {
1752         $response->headers->remove_header("Content-Length");
1753         $response->body('');
1754     }
1755
1756     $c->finalize_cookies;
1757
1758     $c->response->finalize_headers();
1759
1760     # Done
1761     $response->finalized_headers(1);
1762 }
1763
1764 =head2 $c->finalize_output
1765
1766 An alias for finalize_body.
1767
1768 =head2 $c->finalize_read
1769
1770 Finalizes the input after reading is complete.
1771
1772 =cut
1773
1774 sub finalize_read { my $c = shift; $c->engine->finalize_read( $c, @_ ) }
1775
1776 =head2 $c->finalize_uploads
1777
1778 Finalizes uploads. Cleans up any temporary files.
1779
1780 =cut
1781
1782 sub finalize_uploads { my $c = shift; $c->engine->finalize_uploads( $c, @_ ) }
1783
1784 =head2 $c->get_action( $action, $namespace )
1785
1786 Gets an action in a given namespace.
1787
1788 =cut
1789
1790 sub get_action { my $c = shift; $c->dispatcher->get_action(@_) }
1791
1792 =head2 $c->get_actions( $action, $namespace )
1793
1794 Gets all actions of a given name in a namespace and all parent
1795 namespaces.
1796
1797 =cut
1798
1799 sub get_actions { my $c = shift; $c->dispatcher->get_actions( $c, @_ ) }
1800
1801 =head2 $app->handle_request( @arguments )
1802
1803 Called to handle each HTTP request.
1804
1805 =cut
1806
1807 sub handle_request {
1808     my ( $class, @arguments ) = @_;
1809
1810     # Always expect worst case!
1811     my $status = -1;
1812     try {
1813         if ($class->debug) {
1814             my $secs = time - $START || 1;
1815             my $av = sprintf '%.3f', $COUNT / $secs;
1816             my $time = localtime time;
1817             $class->log->info("*** Request $COUNT ($av/s) [$$] [$time] ***");
1818         }
1819
1820         my $c = $class->prepare(@arguments);
1821         $c->dispatch;
1822         $status = $c->finalize;
1823     }
1824     catch {
1825         chomp(my $error = $_);
1826         $class->log->error(qq/Caught exception in engine "$error"/);
1827     };
1828
1829     $COUNT++;
1830
1831     if(my $coderef = $class->log->can('_flush')){
1832         $class->log->$coderef();
1833     }
1834     return $status;
1835 }
1836
1837 =head2 $class->prepare( @arguments )
1838
1839 Creates a Catalyst context from an engine-specific request (Apache, CGI,
1840 etc.).
1841
1842 =cut
1843
1844 has _uploadtmp => (
1845     is => 'ro',
1846     predicate => '_has_uploadtmp',
1847 );
1848
1849 sub prepare {
1850     my ( $class, @arguments ) = @_;
1851
1852     # XXX
1853     # After the app/ctxt split, this should become an attribute based on something passed
1854     # into the application.
1855     $class->context_class( ref $class || $class ) unless $class->context_class;
1856
1857     my $uploadtmp = $class->config->{uploadtmp};
1858     my $c = $class->context_class->new({ $uploadtmp ? (_uploadtmp => $uploadtmp) : ()});
1859
1860     $c->response->_context($c);
1861
1862     #surely this is not the most efficient way to do things...
1863     $c->stats($class->stats_class->new)->enable($c->use_stats);
1864     if ( $c->debug || $c->config->{enable_catalyst_header} ) {
1865         $c->res->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
1866     }
1867
1868     try {
1869         # Allow engine to direct the prepare flow (for POE)
1870         if ( my $prepare = $c->engine->can('prepare') ) {
1871             $c->engine->$prepare( $c, @arguments );
1872         }
1873         else {
1874             $c->prepare_request(@arguments);
1875             $c->prepare_connection;
1876             $c->prepare_query_parameters;
1877             $c->prepare_headers; # Just hooks, no longer needed - they just
1878             $c->prepare_cookies; # cause the lazy attribute on req to build
1879             $c->prepare_path;
1880
1881             # Prepare the body for reading, either by prepare_body
1882             # or the user, if they are using $c->read
1883             $c->prepare_read;
1884
1885             # Parse the body unless the user wants it on-demand
1886             unless ( ref($c)->config->{parse_on_demand} ) {
1887                 $c->prepare_body;
1888             }
1889         }
1890         $c->prepare_action;
1891     }
1892     # VERY ugly and probably shouldn't rely on ->finalize actually working
1893     catch {
1894         # failed prepare is always due to an invalid request, right?
1895         $c->response->status(400);
1896         $c->response->content_type('text/plain');
1897         $c->response->body('Bad Request');
1898         # Note we call finalize and then die here, which escapes
1899         # finalize being called in the enclosing block..
1900         # It in fact couldn't be called, as we don't return $c..
1901         # This is a mess - but I'm unsure you can fix this without
1902         # breaking compat for people doing crazy things (we should set
1903         # the 400 and just return the ctx here IMO, letting finalize get called
1904         # above...
1905         $c->finalize;
1906         die $_;
1907     };
1908
1909     $c->log_request;
1910
1911     return $c;
1912 }
1913
1914 =head2 $c->prepare_action
1915
1916 Prepares action. See L<Catalyst::Dispatcher>.
1917
1918 =cut
1919
1920 sub prepare_action { my $c = shift; $c->dispatcher->prepare_action( $c, @_ ) }
1921
1922 =head2 $c->prepare_body
1923
1924 Prepares message body.
1925
1926 =cut
1927
1928 sub prepare_body {
1929     my $c = shift;
1930
1931     return if $c->request->_has_body;
1932
1933     # Initialize on-demand data
1934     $c->engine->prepare_body( $c, @_ );
1935     $c->prepare_parameters;
1936     $c->prepare_uploads;
1937 }
1938
1939 =head2 $c->prepare_body_chunk( $chunk )
1940
1941 Prepares a chunk of data before sending it to L<HTTP::Body>.
1942
1943 See L<Catalyst::Engine>.
1944
1945 =cut
1946
1947 sub prepare_body_chunk {
1948     my $c = shift;
1949     $c->engine->prepare_body_chunk( $c, @_ );
1950 }
1951
1952 =head2 $c->prepare_body_parameters
1953
1954 Prepares body parameters.
1955
1956 =cut
1957
1958 sub prepare_body_parameters {
1959     my $c = shift;
1960     $c->engine->prepare_body_parameters( $c, @_ );
1961 }
1962
1963 =head2 $c->prepare_connection
1964
1965 Prepares connection.
1966
1967 =cut
1968
1969 sub prepare_connection {
1970     my $c = shift;
1971     # XXX - This is called on the engine (not the request) to maintain
1972     #       Engine::PSGI back compat.
1973     $c->engine->prepare_connection($c);
1974 }
1975
1976 =head2 $c->prepare_cookies
1977
1978 Prepares cookies by ensuring that the attribute on the request
1979 object has been built.
1980
1981 =cut
1982
1983 sub prepare_cookies { my $c = shift; $c->request->cookies }
1984
1985 =head2 $c->prepare_headers
1986
1987 Prepares request headers by ensuring that the attribute on the request
1988 object has been built.
1989
1990 =cut
1991
1992 sub prepare_headers { my $c = shift; $c->request->headers }
1993
1994 =head2 $c->prepare_parameters
1995
1996 Prepares parameters.
1997
1998 =cut
1999
2000 sub prepare_parameters {
2001     my $c = shift;
2002     $c->prepare_body_parameters;
2003     $c->engine->prepare_parameters( $c, @_ );
2004 }
2005
2006 =head2 $c->prepare_path
2007
2008 Prepares path and base.
2009
2010 =cut
2011
2012 sub prepare_path { my $c = shift; $c->engine->prepare_path( $c, @_ ) }
2013
2014 =head2 $c->prepare_query_parameters
2015
2016 Prepares query parameters.
2017
2018 =cut
2019
2020 sub prepare_query_parameters {
2021     my $c = shift;
2022
2023     $c->engine->prepare_query_parameters( $c, @_ );
2024 }
2025
2026 =head2 $c->log_request
2027
2028 Writes information about the request to the debug logs.  This includes:
2029
2030 =over 4
2031
2032 =item * Request method, path, and remote IP address
2033
2034 =item * Query keywords (see L<Catalyst::Request/query_keywords>)
2035
2036 =item * Request parameters
2037
2038 =item * File uploads
2039
2040 =back
2041
2042 =cut
2043
2044 sub log_request {
2045     my $c = shift;
2046
2047     return unless $c->debug;
2048
2049     my($dump) = grep {$_->[0] eq 'Request' } $c->dump_these;
2050     my $request = $dump->[1];
2051
2052     my ( $method, $path, $address ) = ( $request->method, $request->path, $request->address );
2053     $method ||= '';
2054     $path = '/' unless length $path;
2055     $address ||= '';
2056     $c->log->debug(qq/"$method" request for "$path" from "$address"/);
2057
2058     $c->log_request_headers($request->headers);
2059
2060     if ( my $keywords = $request->query_keywords ) {
2061         $c->log->debug("Query keywords are: $keywords");
2062     }
2063
2064     $c->log_request_parameters( query => $request->query_parameters, $request->_has_body ? (body => $request->body_parameters) : () );
2065
2066     $c->log_request_uploads($request);
2067 }
2068
2069 =head2 $c->log_response
2070
2071 Writes information about the response to the debug logs by calling
2072 C<< $c->log_response_status_line >> and C<< $c->log_response_headers >>.
2073
2074 =cut
2075
2076 sub log_response {
2077     my $c = shift;
2078
2079     return unless $c->debug;
2080
2081     my($dump) = grep {$_->[0] eq 'Response' } $c->dump_these;
2082     my $response = $dump->[1];
2083
2084     $c->log_response_status_line($response);
2085     $c->log_response_headers($response->headers);
2086 }
2087
2088 =head2 $c->log_response_status_line($response)
2089
2090 Writes one line of information about the response to the debug logs.  This includes:
2091
2092 =over 4
2093
2094 =item * Response status code
2095
2096 =item * Content-Type header (if present)
2097
2098 =item * Content-Length header (if present)
2099
2100 =back
2101
2102 =cut
2103
2104 sub log_response_status_line {
2105     my ($c, $response) = @_;
2106
2107     $c->log->debug(
2108         sprintf(
2109             'Response Code: %s; Content-Type: %s; Content-Length: %s',
2110             $response->status                            || 'unknown',
2111             $response->headers->header('Content-Type')   || 'unknown',
2112             $response->headers->header('Content-Length') || 'unknown'
2113         )
2114     );
2115 }
2116
2117 =head2 $c->log_response_headers($headers);
2118
2119 Hook method which can be wrapped by plugins to log the response headers.
2120 No-op in the default implementation.
2121
2122 =cut
2123
2124 sub log_response_headers {}
2125
2126 =head2 $c->log_request_parameters( query => {}, body => {} )
2127
2128 Logs request parameters to debug logs
2129
2130 =cut
2131
2132 sub log_request_parameters {
2133     my $c          = shift;
2134     my %all_params = @_;
2135
2136     return unless $c->debug;
2137
2138     my $column_width = Catalyst::Utils::term_width() - 44;
2139     foreach my $type (qw(query body)) {
2140         my $params = $all_params{$type};
2141         next if ! keys %$params;
2142         my $t = Text::SimpleTable->new( [ 35, 'Parameter' ], [ $column_width, 'Value' ] );
2143         for my $key ( sort keys %$params ) {
2144             my $param = $params->{$key};
2145             my $value = defined($param) ? $param : '';
2146             $t->row( $key, ref $value eq 'ARRAY' ? ( join ', ', @$value ) : $value );
2147         }
2148         $c->log->debug( ucfirst($type) . " Parameters are:\n" . $t->draw );
2149     }
2150 }
2151
2152 =head2 $c->log_request_uploads
2153
2154 Logs file uploads included in the request to the debug logs.
2155 The parameter name, filename, file type, and file size are all included in
2156 the debug logs.
2157
2158 =cut
2159
2160 sub log_request_uploads {
2161     my $c = shift;
2162     my $request = shift;
2163     return unless $c->debug;
2164     my $uploads = $request->uploads;
2165     if ( keys %$uploads ) {
2166         my $t = Text::SimpleTable->new(
2167             [ 12, 'Parameter' ],
2168             [ 26, 'Filename' ],
2169             [ 18, 'Type' ],
2170             [ 9,  'Size' ]
2171         );
2172         for my $key ( sort keys %$uploads ) {
2173             my $upload = $uploads->{$key};
2174             for my $u ( ref $upload eq 'ARRAY' ? @{$upload} : ($upload) ) {
2175                 $t->row( $key, $u->filename, $u->type, $u->size );
2176             }
2177         }
2178         $c->log->debug( "File Uploads are:\n" . $t->draw );
2179     }
2180 }
2181
2182 =head2 $c->log_request_headers($headers);
2183
2184 Hook method which can be wrapped by plugins to log the request headers.
2185 No-op in the default implementation.
2186
2187 =cut
2188
2189 sub log_request_headers {}
2190
2191 =head2 $c->log_headers($type => $headers)
2192
2193 Logs L<HTTP::Headers> (either request or response) to the debug logs.
2194
2195 =cut
2196
2197 sub log_headers {
2198     my $c       = shift;
2199     my $type    = shift;
2200     my $headers = shift;    # an HTTP::Headers instance
2201
2202     return unless $c->debug;
2203
2204     my $column_width = Catalyst::Utils::term_width() - 28;
2205     my $t = Text::SimpleTable->new( [ 15, 'Header Name' ], [ $column_width, 'Value' ] );
2206     $headers->scan(
2207         sub {
2208             my ( $name, $value ) = @_;
2209             $t->row( $name, $value );
2210         }
2211     );
2212     $c->log->debug( ucfirst($type) . " Headers:\n" . $t->draw );
2213 }
2214
2215
2216 =head2 $c->prepare_read
2217
2218 Prepares the input for reading.
2219
2220 =cut
2221
2222 sub prepare_read { my $c = shift; $c->engine->prepare_read( $c, @_ ) }
2223
2224 =head2 $c->prepare_request
2225
2226 Prepares the engine request.
2227
2228 =cut
2229
2230 sub prepare_request { my $c = shift; $c->engine->prepare_request( $c, @_ ) }
2231
2232 =head2 $c->prepare_uploads
2233
2234 Prepares uploads.
2235
2236 =cut
2237
2238 sub prepare_uploads {
2239     my $c = shift;
2240
2241     $c->engine->prepare_uploads( $c, @_ );
2242 }
2243
2244 =head2 $c->prepare_write
2245
2246 Prepares the output for writing.
2247
2248 =cut
2249
2250 sub prepare_write { my $c = shift; $c->engine->prepare_write( $c, @_ ) }
2251
2252 =head2 $c->request_class
2253
2254 Returns or sets the request class. Defaults to L<Catalyst::Request>.
2255
2256 =head2 $c->response_class
2257
2258 Returns or sets the response class. Defaults to L<Catalyst::Response>.
2259
2260 =head2 $c->read( [$maxlength] )
2261
2262 Reads a chunk of data from the request body. This method is designed to
2263 be used in a while loop, reading C<$maxlength> bytes on every call.
2264 C<$maxlength> defaults to the size of the request if not specified.
2265
2266 You have to set C<< MyApp->config(parse_on_demand => 1) >> to use this
2267 directly.
2268
2269 Warning: If you use read(), Catalyst will not process the body,
2270 so you will not be able to access POST parameters or file uploads via
2271 $c->request.  You must handle all body parsing yourself.
2272
2273 =cut
2274
2275 sub read { my $c = shift; return $c->request->read( @_ ) }
2276
2277 =head2 $c->run
2278
2279 Starts the engine.
2280
2281 =cut
2282
2283 sub run {
2284   my $app = shift;
2285   $app->_make_immutable_if_needed;
2286   $app->engine_loader->needs_psgi_engine_compat_hack ?
2287     $app->engine->run($app, @_) :
2288       $app->engine->run( $app, $app->_finalized_psgi_app, @_ );
2289 }
2290
2291 sub _make_immutable_if_needed {
2292     my $class = shift;
2293     my $meta = Class::MOP::get_metaclass_by_name($class);
2294     my $isa_ca = $class->isa('Class::Accessor::Fast') || $class->isa('Class::Accessor');
2295     if (
2296         $meta->is_immutable
2297         && ! { $meta->immutable_options }->{replace_constructor}
2298         && $isa_ca
2299     ) {
2300         warn("You made your application class ($class) immutable, "
2301             . "but did not inline the\nconstructor. "
2302             . "This will break catalyst, as your app \@ISA "
2303             . "Class::Accessor(::Fast)?\nPlease pass "
2304             . "(replace_constructor => 1)\nwhen making your class immutable.\n");
2305     }
2306     unless ($meta->is_immutable) {
2307         # XXX - FIXME warning here as you should make your app immutable yourself.
2308         $meta->make_immutable(
2309             replace_constructor => 1,
2310         );
2311     }
2312 }
2313
2314 =head2 $c->set_action( $action, $code, $namespace, $attrs )
2315
2316 Sets an action in a given namespace.
2317
2318 =cut
2319
2320 sub set_action { my $c = shift; $c->dispatcher->set_action( $c, @_ ) }
2321
2322 =head2 $c->setup_actions($component)
2323
2324 Sets up actions for a component.
2325
2326 =cut
2327
2328 sub setup_actions { my $c = shift; $c->dispatcher->setup_actions( $c, @_ ) }
2329
2330 =head2 $c->setup_config
2331
2332 =cut
2333
2334 sub setup_config {
2335     my $class = shift;
2336
2337     my %args = %{ $class->config || {} };
2338
2339     my $container_class;
2340
2341     if ( exists $args{container_class} ) {
2342         $container_class = delete $args{container_class};
2343         Class::MOP::load_class($container_class);
2344     }
2345     else {
2346         $container_class = Class::MOP::load_first_existing_class("${class}::Container", 'Catalyst::IOC::Container');
2347     }
2348
2349     my $container = $container_class->new( %args, name => $class );
2350     $class->container($container);
2351
2352     my $config = $container->resolve( service => 'config' );
2353     $class->config($config);
2354     $class->finalize_config; # back-compat
2355 }
2356
2357 =head2 $c->finalize_config
2358
2359 =cut
2360
2361 sub finalize_config { }
2362
2363 =head2 $c->setup_components
2364
2365 This method is called internally to set up the application's components.
2366
2367 It finds modules by calling the L<locate_components> method, expands them to
2368 package names with the $container->expand_component_module method, and then
2369 installs each component into the application.
2370
2371 The C<setup_components> config option is passed to both of the above methods.
2372
2373 =cut
2374
2375 sub setup_components { shift->container->setup_components }
2376
2377 =head2 locate_components
2378
2379 =cut
2380
2381 sub locate_components {
2382     my $class = shift;
2383
2384     $class->log->warn('The locate_components method has been deprecated.');
2385     $class->log->warn('Please read Catalyst::IOC::Container documentation to');
2386     $class->log->warn('update your application.');
2387
2388     # XXX think about ditching this sort entirely
2389     return sort { length $a <=> length $b }
2390         @{ $class->container->resolve( service => 'locate_components' ) };
2391 }
2392
2393 =head2 $c->setup_dispatcher
2394
2395 Sets up dispatcher.
2396
2397 =cut
2398
2399 sub setup_dispatcher {
2400     my ( $class, $dispatcher ) = @_;
2401
2402     if ($dispatcher) {
2403         $dispatcher = 'Catalyst::Dispatcher::' . $dispatcher;
2404     }
2405
2406     if ( my $env = Catalyst::Utils::env_value( $class, 'DISPATCHER' ) ) {
2407         $dispatcher = 'Catalyst::Dispatcher::' . $env;
2408     }
2409
2410     unless ($dispatcher) {
2411         $dispatcher = $class->dispatcher_class;
2412     }
2413
2414     Class::MOP::load_class($dispatcher);
2415
2416     # dispatcher instance
2417     $class->dispatcher( $dispatcher->new );
2418 }
2419
2420 =head2 $c->setup_engine
2421
2422 Sets up engine.
2423
2424 =cut
2425
2426 sub engine_class {
2427     my ($class, $requested_engine) = @_;
2428
2429     if (!$class->engine_loader || $requested_engine) {
2430         $class->engine_loader(
2431             Catalyst::EngineLoader->new({
2432                 application_name => $class,
2433                 (defined $requested_engine
2434                      ? (catalyst_engine_class => $requested_engine) : ()),
2435             }),
2436         );
2437     }
2438
2439     $class->engine_loader->catalyst_engine_class;
2440 }
2441
2442 sub setup_engine {
2443     my ($class, $requested_engine) = @_;
2444
2445     my $engine = do {
2446         my $loader = $class->engine_loader;
2447
2448         if (!$loader || $requested_engine) {
2449             $loader = Catalyst::EngineLoader->new({
2450                 application_name => $class,
2451                 (defined $requested_engine
2452                      ? (requested_engine => $requested_engine) : ()),
2453             }),
2454
2455             $class->engine_loader($loader);
2456         }
2457
2458         $loader->catalyst_engine_class;
2459     };
2460
2461     # Don't really setup_engine -- see _setup_psgi_app for explanation.
2462     return if $class->loading_psgi_file;
2463
2464     Class::MOP::load_class($engine);
2465
2466     if ($ENV{MOD_PERL}) {
2467         my $apache = $class->engine_loader->auto;
2468
2469         my $meta = find_meta($class);
2470         my $was_immutable = $meta->is_immutable;
2471         my %immutable_options = $meta->immutable_options;
2472         $meta->make_mutable if $was_immutable;
2473
2474         $meta->add_method(handler => sub {
2475             my $r = shift;
2476             my $psgi_app = $class->_finalized_psgi_app;
2477             $apache->call_app($r, $psgi_app);
2478         });
2479
2480         $meta->make_immutable(%immutable_options) if $was_immutable;
2481     }
2482
2483     $class->engine( $engine->new );
2484
2485     return;
2486 }
2487
2488 sub _finalized_psgi_app {
2489     my ($app) = @_;
2490
2491     unless ($app->_psgi_app) {
2492         my $psgi_app = $app->_setup_psgi_app;
2493         $app->_psgi_app($psgi_app);
2494     }
2495
2496     return $app->_psgi_app;
2497 }
2498
2499 sub _setup_psgi_app {
2500     my ($app) = @_;
2501
2502     for my $home (Path::Class::Dir->new($app->config->{home})) {
2503         my $psgi_file = $home->file(
2504             Catalyst::Utils::appprefix($app) . '.psgi',
2505         );
2506
2507         next unless -e $psgi_file;
2508
2509         # If $psgi_file calls ->setup_engine, it's doing so to load
2510         # Catalyst::Engine::PSGI. But if it does that, we're only going to
2511         # throw away the loaded PSGI-app and load the 5.9 Catalyst::Engine
2512         # anyway. So set a flag (ick) that tells setup_engine not to populate
2513         # $c->engine or do any other things we might regret.
2514
2515         $app->loading_psgi_file(1);
2516         my $psgi_app = Plack::Util::load_psgi($psgi_file);
2517         $app->loading_psgi_file(0);
2518
2519         return $psgi_app
2520             unless $app->engine_loader->needs_psgi_engine_compat_hack;
2521
2522         warn <<"EOW";
2523 Found a legacy Catalyst::Engine::PSGI .psgi file at ${psgi_file}.
2524
2525 Its content has been ignored. Please consult the Catalyst::Upgrading
2526 documentation on how to upgrade from Catalyst::Engine::PSGI.
2527 EOW
2528     }
2529
2530     return $app->apply_default_middlewares($app->psgi_app);
2531 }
2532
2533 =head2 $c->apply_default_middlewares
2534
2535 Adds the following L<Plack> middlewares to your application, since they are
2536 useful and commonly needed:
2537
2538 L<Plack::Middleware::ReverseProxy>, (conditionally added based on the status
2539 of your $ENV{REMOTE_ADDR}, and can be forced on with C<using_frontend_proxy>
2540 or forced off with C<ignore_frontend_proxy>), L<Plack::Middleware::LighttpdScriptNameFix>
2541 (if you are using Lighttpd), L<Plack::Middleware::IIS6ScriptNameFix> (always
2542 applied since this middleware is smart enough to conditionally apply itself).
2543
2544 Additionally if we detect we are using Nginx, we add a bit of custom middleware
2545 to solve some problems with the way that server handles $ENV{PATH_INFO} and
2546 $ENV{SCRIPT_NAME}
2547
2548 =cut
2549
2550
2551 sub apply_default_middlewares {
2552     my ($app, $psgi_app) = @_;
2553
2554     $psgi_app = Plack::Middleware::Conditional->wrap(
2555         $psgi_app,
2556         builder   => sub { Plack::Middleware::ReverseProxy->wrap($_[0]) },
2557         condition => sub {
2558             my ($env) = @_;
2559             return if $app->config->{ignore_frontend_proxy};
2560             return $env->{REMOTE_ADDR} eq '127.0.0.1'
2561                 || $app->config->{using_frontend_proxy};
2562         },
2563     );
2564
2565     # If we're running under Lighttpd, swap PATH_INFO and SCRIPT_NAME
2566     # http://lists.scsys.co.uk/pipermail/catalyst/2006-June/008361.html
2567     $psgi_app = Plack::Middleware::Conditional->wrap(
2568         $psgi_app,
2569         builder   => sub { Plack::Middleware::LighttpdScriptNameFix->wrap($_[0]) },
2570         condition => sub {
2571             my ($env) = @_;
2572             return unless $env->{SERVER_SOFTWARE} && $env->{SERVER_SOFTWARE} =~ m!lighttpd[-/]1\.(\d+\.\d+)!;
2573             return unless $1 < 4.23;
2574             1;
2575         },
2576     );
2577
2578     # we're applying this unconditionally as the middleware itself already makes
2579     # sure it doesn't fuck things up if it's not running under one of the right
2580     # IIS versions
2581     $psgi_app = Plack::Middleware::IIS6ScriptNameFix->wrap($psgi_app);
2582
2583     return $psgi_app;
2584 }
2585
2586 =head2 $c->psgi_app
2587
2588 Returns a PSGI application code reference for the catalyst application
2589 C<$c>. This is the bare application without any middlewares
2590 applied. C<${myapp}.psgi> is not taken into account.
2591
2592 This is what you want to be using to retrieve the PSGI application code
2593 reference of your Catalyst application for use in F<.psgi> files.
2594
2595 =cut
2596
2597 sub psgi_app {
2598     my ($app) = @_;
2599     return $app->engine->build_psgi_app($app);
2600 }
2601
2602 =head2 $c->setup_home
2603
2604 Sets up the home directory.
2605
2606 =cut
2607
2608 sub setup_home {
2609     my ( $class, $home_flag ) = @_;
2610
2611     my $home = $class->container->resolve(
2612         service    => 'home',
2613         parameters => {
2614             home_flag => $home_flag
2615         },
2616     );
2617
2618     if ($home) {
2619         #I remember recently being scolded for assigning config values like this
2620         $class->config->{home} ||= $home;
2621         $class->config->{root} ||= $class->container->resolve(service => 'root_dir');
2622     }
2623 }
2624
2625 =head2 $c->setup_log
2626
2627 Sets up log by instantiating a L<Catalyst::Log|Catalyst::Log> object and
2628 passing it to C<log()>. Pass in a comma-delimited list of levels to set the
2629 log to.
2630
2631 This method also installs a C<debug> method that returns a true value into the
2632 catalyst subclass if the "debug" level is passed in the comma-delimited list,
2633 or if the C<$CATALYST_DEBUG> environment variable is set to a true value.
2634
2635 Note that if the log has already been setup, by either a previous call to
2636 C<setup_log> or by a call such as C<< __PACKAGE__->log( MyLogger->new ) >>,
2637 that this method won't actually set up the log object.
2638
2639 =cut
2640
2641 sub setup_log {
2642     my ( $class, $levels ) = @_;
2643
2644     $levels ||= '';
2645     $levels =~ s/^\s+//;
2646     $levels =~ s/\s+$//;
2647     my %levels = map { $_ => 1 } split /\s*,\s*/, $levels;
2648
2649     my $env_debug = Catalyst::Utils::env_value( $class, 'DEBUG' );
2650     if ( defined $env_debug ) {
2651         $levels{debug} = 1 if $env_debug; # Ugly!
2652         delete($levels{debug}) unless $env_debug;
2653     }
2654
2655     unless ( $class->log ) {
2656         $class->log( Catalyst::Log->new(keys %levels) );
2657     }
2658
2659     if ( $levels{debug} ) {
2660         Class::MOP::get_metaclass_by_name($class)->add_method('debug' => sub { 1 });
2661         $class->log->debug('Debug messages enabled');
2662     }
2663 }
2664
2665 =head2 $c->setup_plugins
2666
2667 Sets up plugins.
2668
2669 =cut
2670
2671 =head2 $c->setup_stats
2672
2673 Sets up timing statistics class.
2674
2675 =cut
2676
2677 sub setup_stats {
2678     my ( $class, $stats ) = @_;
2679
2680     Catalyst::Utils::ensure_class_loaded($class->stats_class);
2681
2682     my $env = Catalyst::Utils::env_value( $class, 'STATS' );
2683     if ( defined($env) ? $env : ($stats || $class->debug ) ) {
2684         Class::MOP::get_metaclass_by_name($class)->add_method('use_stats' => sub { 1 });
2685         $class->log->debug('Statistics enabled');
2686     }
2687 }
2688
2689
2690 =head2 $c->registered_plugins
2691
2692 Returns a sorted list of the plugins which have either been stated in the
2693 import list.
2694
2695 If passed a given plugin name, it will report a boolean value indicating
2696 whether or not that plugin is loaded.  A fully qualified name is required if
2697 the plugin name does not begin with C<Catalyst::Plugin::>.
2698
2699  if ($c->registered_plugins('Some::Plugin')) {
2700      ...
2701  }
2702
2703 =cut
2704
2705 {
2706
2707     sub registered_plugins {
2708         my $proto = shift;
2709         return sort keys %{ $proto->_plugins } unless @_;
2710         my $plugin = shift;
2711         return 1 if exists $proto->_plugins->{$plugin};
2712         return exists $proto->_plugins->{"Catalyst::Plugin::$plugin"};
2713     }
2714
2715     sub _register_plugin {
2716         my ( $proto, $plugin, $instant ) = @_;
2717         my $class = ref $proto || $proto;
2718
2719         Class::MOP::load_class( $plugin );
2720         $class->log->warn( "$plugin inherits from 'Catalyst::Component' - this is deprecated and will not work in 5.81" )
2721             if $plugin->isa( 'Catalyst::Component' );
2722         my $plugin_meta = Moose::Meta::Class->create($plugin);
2723         if (!$plugin_meta->has_method('new')
2724             && ( $plugin->isa('Class::Accessor::Fast') || $plugin->isa('Class::Accessor') ) ) {
2725             $plugin_meta->add_method('new', Moose::Object->meta->get_method('new'))
2726         }
2727         if (!$instant && !$proto->_plugins->{$plugin}) {
2728             my $meta = Class::MOP::get_metaclass_by_name($class);
2729             $meta->superclasses($plugin, $meta->superclasses);
2730         }
2731         $proto->_plugins->{$plugin} = 1;
2732         return $class;
2733     }
2734
2735     sub setup_plugins {
2736         my ( $class, $plugins ) = @_;
2737
2738         $class->_plugins( {} ) unless $class->_plugins;
2739         $plugins = Data::OptList::mkopt($plugins || []);
2740
2741         my @plugins = map {
2742             [ Catalyst::Utils::resolve_namespace(
2743                   $class . '::Plugin',
2744                   'Catalyst::Plugin', $_->[0]
2745               ),
2746               $_->[1],
2747             ]
2748          } @{ $plugins };
2749
2750         for my $plugin ( reverse @plugins ) {
2751             Class::MOP::load_class($plugin->[0], $plugin->[1]);
2752             my $meta = find_meta($plugin->[0]);
2753             next if $meta && $meta->isa('Moose::Meta::Role');
2754
2755             $class->_register_plugin($plugin->[0]);
2756         }
2757
2758         my @roles =
2759             map  { $_->[0]->name, $_->[1] }
2760             grep { blessed($_->[0]) && $_->[0]->isa('Moose::Meta::Role') }
2761             map  { [find_meta($_->[0]), $_->[1]] }
2762             @plugins;
2763
2764         Moose::Util::apply_all_roles(
2765             $class => @roles
2766         ) if @roles;
2767     }
2768 }
2769
2770 =head2 $c->stack
2771
2772 Returns an arrayref of the internal execution stack (actions that are
2773 currently executing).
2774
2775 =head2 $c->stats
2776
2777 Returns the current timing statistics object. By default Catalyst uses
2778 L<Catalyst::Stats|Catalyst::Stats>, but can be set otherwise with
2779 L<< stats_class|/"$c->stats_class" >>.
2780
2781 Even if L<< -Stats|/"-Stats" >> is not enabled, the stats object is still
2782 available. By enabling it with C< $c->stats->enabled(1) >, it can be used to
2783 profile explicitly, although MyApp.pm still won't profile nor output anything
2784 by itself.
2785
2786 =head2 $c->stats_class
2787
2788 Returns or sets the stats (timing statistics) class. L<Catalyst::Stats|Catalyst::Stats> is used by default.
2789
2790 =head2 $c->use_stats
2791
2792 Returns 1 when L<< stats collection|/"-Stats" >> is enabled.
2793
2794 Note that this is a static method, not an accessor and should be overridden
2795 by declaring C<sub use_stats { 1 }> in your MyApp.pm, not by calling C<< $c->use_stats(1) >>.
2796
2797 =cut
2798
2799 sub use_stats { 0 }
2800
2801
2802 =head2 $c->write( $data )
2803
2804 Writes $data to the output stream. When using this method directly, you
2805 will need to manually set the C<Content-Length> header to the length of
2806 your output data, if known.
2807
2808 =cut
2809
2810 sub write {
2811     my $c = shift;
2812
2813     # Finalize headers if someone manually writes output (for compat)
2814     $c->finalize_headers;
2815
2816     return $c->response->write( @_ );
2817 }
2818
2819 =head2 version
2820
2821 Returns the Catalyst version number. Mostly useful for "powered by"
2822 messages in template systems.
2823
2824 =cut
2825
2826 sub version { return $Catalyst::VERSION }
2827
2828 =head1 CONFIGURATION
2829
2830 There are a number of 'base' config variables which can be set:
2831
2832 =over
2833
2834 =item *
2835
2836 C<default_model> - The default model picked if you say C<< $c->model >>. See L<< /$c->model($name) >>.
2837
2838 =item *
2839
2840 C<default_view> - The default view to be rendered or returned when C<< $c->view >> is called. See L<< /$c->view($name) >>.
2841
2842 =item *
2843
2844 C<home> - The application home directory. In an uninstalled application,
2845 this is the top level application directory. In an installed application,
2846 this will be the directory containing C<< MyApp.pm >>.
2847
2848 =item *
2849
2850 C<ignore_frontend_proxy> - See L</PROXY SUPPORT>
2851
2852 =item *
2853
2854 C<name> - The name of the application in debug messages and the debug and
2855 welcome screens
2856
2857 =item *
2858
2859 C<parse_on_demand> - The request body (for example file uploads) will not be parsed
2860 until it is accessed. This allows you to (for example) check authentication (and reject
2861 the upload) before actually receiving all the data. See L</ON-DEMAND PARSER>
2862
2863 =item *
2864
2865 C<root> - The root directory for templates. Usually this is just a
2866 subdirectory of the home directory, but you can set it to change the
2867 templates to a different directory.
2868
2869 =item *
2870
2871 C<show_internal_actions> - If true, causes internal actions such as C<< _DISPATCH >>
2872 to be shown in hit debug tables in the test server.
2873
2874 =item *
2875
2876 C<use_request_uri_for_path> - Controls if the C<REQUEST_URI> or C<PATH_INFO> environment
2877 variable should be used for determining the request path.
2878
2879 Most web server environments pass the requested path to the application using environment variables,
2880 from which Catalyst has to reconstruct the request base (i.e. the top level path to / in the application,
2881 exposed as C<< $c->request->base >>) and the request path below that base.
2882
2883 There are two methods of doing this, both of which have advantages and disadvantages. Which method is used
2884 is determined by the C<< $c->config(use_request_uri_for_path) >> setting (which can either be true or false).
2885
2886 =over
2887
2888 =item use_request_uri_for_path => 0
2889
2890 This is the default (and the) traditional method that Catalyst has used for determining the path information.
2891 The path is generated from a combination of the C<PATH_INFO> and C<SCRIPT_NAME> environment variables.
2892 The allows the application to behave correctly when C<mod_rewrite> is being used to redirect requests
2893 into the application, as these variables are adjusted by mod_rewrite to take account for the redirect.
2894
2895 However this method has the major disadvantage that it is impossible to correctly decode some elements
2896 of the path, as RFC 3875 says: "C<< Unlike a URI path, the PATH_INFO is not URL-encoded, and cannot
2897 contain path-segment parameters. >>" This means PATH_INFO is B<always> decoded, and therefore Catalyst
2898 can't distinguish / vs %2F in paths (in addition to other encoded values).
2899
2900 =item use_request_uri_for_path => 1
2901
2902 This method uses the C<REQUEST_URI> and C<SCRIPT_NAME> environment variables. As C<REQUEST_URI> is never
2903 decoded, this means that applications using this mode can correctly handle URIs including the %2F character
2904 (i.e. with C<AllowEncodedSlashes> set to C<On> in Apache).
2905
2906 Given that this method of path resolution is provably more correct, it is recommended that you use
2907 this unless you have a specific need to deploy your application in a non-standard environment, and you are
2908 aware of the implications of not being able to handle encoded URI paths correctly.
2909
2910 However it also means that in a number of cases when the app isn't installed directly at a path, but instead
2911 is having paths rewritten into it (e.g. as a .cgi/fcgi in a public_html directory, with mod_rewrite in a
2912 .htaccess file, or when SSI is used to rewrite pages into the app, or when sub-paths of the app are exposed
2913 at other URIs than that which the app is 'normally' based at with C<mod_rewrite>), the resolution of
2914 C<< $c->request->base >> will be incorrect.
2915
2916 =back
2917
2918 =item *
2919
2920 C<using_frontend_proxy> - See L</PROXY SUPPORT>.
2921
2922 =back
2923
2924 =head1 INTERNAL ACTIONS
2925
2926 Catalyst uses internal actions like C<_DISPATCH>, C<_BEGIN>, C<_AUTO>,
2927 C<_ACTION>, and C<_END>. These are by default not shown in the private
2928 action table, but you can make them visible with a config parameter.
2929
2930     MyApp->config(show_internal_actions => 1);
2931
2932 =head1 ON-DEMAND PARSER
2933
2934 The request body is usually parsed at the beginning of a request,
2935 but if you want to handle input yourself, you can enable on-demand
2936 parsing with a config parameter.
2937
2938     MyApp->config(parse_on_demand => 1);
2939
2940 =head1 PROXY SUPPORT
2941
2942 Many production servers operate using the common double-server approach,
2943 with a lightweight frontend web server passing requests to a larger
2944 backend server. An application running on the backend server must deal
2945 with two problems: the remote user always appears to be C<127.0.0.1> and
2946 the server's hostname will appear to be C<localhost> regardless of the
2947 virtual host that the user connected through.
2948
2949 Catalyst will automatically detect this situation when you are running
2950 the frontend and backend servers on the same machine. The following
2951 changes are made to the request.
2952
2953     $c->req->address is set to the user's real IP address, as read from
2954     the HTTP X-Forwarded-For header.
2955
2956     The host value for $c->req->base and $c->req->uri is set to the real
2957     host, as read from the HTTP X-Forwarded-Host header.
2958
2959 Additionally, you may be running your backend application on an insecure
2960 connection (port 80) while your frontend proxy is running under SSL.  If there
2961 is a discrepancy in the ports, use the HTTP header C<X-Forwarded-Port> to
2962 tell Catalyst what port the frontend listens on.  This will allow all URIs to
2963 be created properly.
2964
2965 In the case of passing in:
2966
2967     X-Forwarded-Port: 443
2968
2969 All calls to C<uri_for> will result in an https link, as is expected.
2970
2971 Obviously, your web server must support these headers for this to work.
2972
2973 In a more complex server farm environment where you may have your
2974 frontend proxy server(s) on different machines, you will need to set a
2975 configuration option to tell Catalyst to read the proxied data from the
2976 headers.
2977
2978     MyApp->config(using_frontend_proxy => 1);
2979
2980 If you do not wish to use the proxy support at all, you may set:
2981
2982     MyApp->config(ignore_frontend_proxy => 0);
2983
2984 =head2 Note about psgi files
2985
2986 Note that if you supply your own .psgi file, calling
2987 C<< MyApp->psgi_app(@_); >>, then B<this will not happen automatically>.
2988
2989 You either need to apply L<Plack::Middleware::ReverseProxy> yourself
2990 in your psgi, for example:
2991
2992     builder {
2993         enable "Plack::Middleware::ReverseProxy";
2994         MyApp->psgi_app
2995     };
2996
2997 This will unconditionally add the ReverseProxy support, or you need to call
2998 C<< $app = MyApp->apply_default_middlewares($app) >> (to conditionally
2999 apply the support depending upon your config).
3000
3001 See L<Catalyst::PSGI> for more information.
3002
3003 =head1 THREAD SAFETY
3004
3005 Catalyst has been tested under Apache 2's threading C<mpm_worker>,
3006 C<mpm_winnt>, and the standalone forking HTTP server on Windows. We
3007 believe the Catalyst core to be thread-safe.
3008
3009 If you plan to operate in a threaded environment, remember that all other
3010 modules you are using must also be thread-safe. Some modules, most notably
3011 L<DBD::SQLite>, are not thread-safe.
3012
3013 =head1 SUPPORT
3014
3015 IRC:
3016
3017     Join #catalyst on irc.perl.org.
3018
3019 Mailing Lists:
3020
3021     http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst
3022     http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst-dev
3023
3024 Web:
3025
3026     http://catalyst.perl.org
3027
3028 Wiki:
3029
3030     http://dev.catalyst.perl.org
3031
3032 =head1 SEE ALSO
3033
3034 =head2 L<Task::Catalyst> - All you need to start with Catalyst
3035
3036 =head2 L<Catalyst::Manual> - The Catalyst Manual
3037
3038 =head2 L<Catalyst::Component>, L<Catalyst::Controller> - Base classes for components
3039
3040 =head2 L<Catalyst::Engine> - Core engine
3041
3042 =head2 L<Catalyst::Log> - Log class.
3043
3044 =head2 L<Catalyst::Request> - Request object
3045
3046 =head2 L<Catalyst::Response> - Response object
3047
3048 =head2 L<Catalyst::Test> - The test suite.
3049
3050 =head1 PROJECT FOUNDER
3051
3052 sri: Sebastian Riedel <sri@cpan.org>
3053
3054 =head1 CONTRIBUTORS
3055
3056 abw: Andy Wardley
3057
3058 acme: Leon Brocard <leon@astray.com>
3059
3060 abraxxa: Alexander Hartmaier <abraxxa@cpan.org>
3061
3062 Andrew Bramble
3063
3064 Andrew Ford E<lt>A.Ford@ford-mason.co.ukE<gt>
3065
3066 Andrew Ruthven
3067
3068 André Walker
3069
3070 andyg: Andy Grundman <andy@hybridized.org>
3071
3072 audreyt: Audrey Tang
3073
3074 bricas: Brian Cassidy <bricas@cpan.org>
3075
3076 Caelum: Rafael Kitover <rkitover@io.com>
3077
3078 chansen: Christian Hansen
3079
3080 chicks: Christopher Hicks
3081
3082 Chisel Wright C<pause@herlpacker.co.uk>
3083
3084 Danijel Milicevic C<me@danijel.de>
3085
3086 David Kamholz E<lt>dkamholz@cpan.orgE<gt>
3087
3088 David Naughton, C<naughton@umn.edu>
3089
3090 David E. Wheeler
3091
3092 dhoss: Devin Austin <dhoss@cpan.org>
3093
3094 dkubb: Dan Kubb <dan.kubb-cpan@onautopilot.com>
3095
3096 Drew Taylor
3097
3098 dwc: Daniel Westermann-Clark <danieltwc@cpan.org>
3099
3100 esskar: Sascha Kiefer
3101
3102 fireartist: Carl Franks <cfranks@cpan.org>
3103
3104 frew: Arthur Axel "fREW" Schmidt <frioux@gmail.com>
3105
3106 gabb: Danijel Milicevic
3107
3108 Gary Ashton Jones
3109
3110 Gavin Henry C<ghenry@perl.me.uk>
3111
3112 Geoff Richards
3113
3114 groditi: Guillermo Roditi <groditi@gmail.com>
3115
3116 hobbs: Andrew Rodland <andrew@cleverdomain.org>
3117
3118 ilmari: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
3119
3120 jcamacho: Juan Camacho
3121
3122 jester: Jesse Sheidlower C<jester@panix.com>
3123
3124 jhannah: Jay Hannah <jay@jays.net>
3125
3126 Jody Belka
3127
3128 Johan Lindstrom
3129
3130 jon: Jon Schutz <jjschutz@cpan.org>
3131
3132 Jonathan Rockway C<< <jrockway@cpan.org> >>
3133
3134 Kieren Diment C<kd@totaldatasolution.com>
3135
3136 konobi: Scott McWhirter <konobi@cpan.org>
3137
3138 marcus: Marcus Ramberg <mramberg@cpan.org>
3139
3140 miyagawa: Tatsuhiko Miyagawa <miyagawa@bulknews.net>
3141
3142 mst: Matt S. Trout <mst@shadowcatsystems.co.uk>
3143
3144 mugwump: Sam Vilain
3145
3146 naughton: David Naughton
3147
3148 ningu: David Kamholz <dkamholz@cpan.org>
3149
3150 nothingmuch: Yuval Kogman <nothingmuch@woobling.org>
3151
3152 numa: Dan Sully <daniel@cpan.org>
3153
3154 obra: Jesse Vincent
3155
3156 Octavian Rasnita
3157
3158 omega: Andreas Marienborg
3159
3160 Oleg Kostyuk <cub.uanic@gmail.com>
3161
3162 phaylon: Robert Sedlacek <phaylon@dunkelheit.at>
3163
3164 rafl: Florian Ragwitz <rafl@debian.org>
3165
3166 random: Roland Lammel <lammel@cpan.org>
3167
3168 Robert Sedlacek C<< <rs@474.at> >>
3169
3170 SpiceMan: Marcel Montes
3171
3172 sky: Arthur Bergman
3173
3174 szbalint: Balint Szilakszi <szbalint@cpan.org>
3175
3176 t0m: Tomas Doran <bobtfish@bobtfish.net>
3177
3178 Ulf Edvinsson
3179
3180 Viljo Marrandi C<vilts@yahoo.com>
3181
3182 Will Hawes C<info@whawes.co.uk>
3183
3184 willert: Sebastian Willert <willert@cpan.org>
3185
3186 wreis: Wallace Reis <wallace@reis.org.br>
3187
3188 Yuval Kogman, C<nothingmuch@woobling.org>
3189
3190 rainboxx: Matthias Dietrich, C<perl@rainboxx.de>
3191
3192 dd070: Dhaval Dhanani <dhaval070@gmail.com>
3193
3194 =head1 COPYRIGHT
3195
3196 Copyright (c) 2005, the above named PROJECT FOUNDER and CONTRIBUTORS.
3197
3198 =head1 LICENSE
3199
3200 This library is free software. You can redistribute it and/or modify it under
3201 the same terms as Perl itself.
3202
3203 =cut
3204
3205 no Moose;
3206
3207 __PACKAGE__->meta->make_immutable;
3208
3209 1;