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