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