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