lib/Catalyst.pm

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