lib/Catalyst.pm

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