lib/Catalyst.pm

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