lib/Catalyst.pm

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