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