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