X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=lib%2FCatalyst%2FPSGI.pod;h=b12b76b271053c71d07aa07e134e7888882a1655;hp=1aec1f8a89063a7e3b64b8a8c3993967bfe55db5;hb=e60068484721132e6fe1855f53f9542d8bb17a35;hpb=2f3f09d4356a6b6c23455b66bf76d8b954522ffc diff --git a/lib/Catalyst/PSGI.pod b/lib/Catalyst/PSGI.pod index 1aec1f8..b12b76b 100644 --- a/lib/Catalyst/PSGI.pod +++ b/lib/Catalyst/PSGI.pod @@ -6,29 +6,46 @@ Catalyst::PSGI - How Catalyst and PSGI work together =head1 SYNOPSIS -Catalyst used to contain a whole set of C<< Catalyst::Engine::XXXX >> classes to -adapt to various different web servers, and environments (e.g. CGI, FastCGI, mod_perl) -etc. +The L specification defines an interface between web servers and +Perl-based web applications and frameworks. It supports the writing of +portable applications that can be run using various methods (as a +standalone server, or using mod_perl, FastCGI, etc.). L is a set +of middleware tools for running Perl applications compatible with the +PSGI specification. -This has been changed so that all of that work is done by Catalyst just implementing -the L specification, and using L's adaptors to implement that functionality. +Catalyst used to contain an entire set of C<< Catalyst::Engine::XXXX >> +classes to handle various web servers and environments (e.g. CGI, +FastCGI, mod_perl) etc. -This means that we can share common code, and fixes for specific web servers. +This has been changed in Catalyst 5.9 so that all of that work is done +by Catalyst implementing the L specification, using L's +adaptors to implement that functionality. + +This means that we can share common code, and share fixes for specific +web servers. =head1 I already have an application -If you already have a Catalyst application, then this means very little, and you should be -able to upgrade to the latest release with little or no trouble (See notes in L -for specifics about your web server deployment). +If you already have a Catalyst application, then you should be able to +upgrade to the latest release with little or no trouble (see the notes +in L for specifics about your web server +deployment). =head1 Writing your own PSGI file. -=head2 What is a .psgi file +=head2 What is a .psgi file? + +A C<< .psgi >> file lets you control how your application code reference +is built. Catalyst will automatically handle this for you, but it's +possible to do it manually by creating a C file in the root +of your application. -A C<< .psgi >> file lets you manually controll how your application code reference is built. +=head2 Why would I want to write my own .psgi file? -Catalyst normally takes care of this for you, but it's possible to do it manually by -creating a C file in the root of your application. +Writing your own .psgi file allows you to use the alternate L command +to start your application, and allows you to add classes and extensions +that implement L, such as L +or L. The simplest C<.psgi> file for an application called C would be: @@ -38,25 +55,19 @@ The simplest C<.psgi> file for an application called C would be: my $app = sub { TestApp->psgi_app(@_) }; -It should be noted that Catalyst may apply a number of middleware components for -you automatically, and these B be applied if you manually create -a psgi file yourself. Details of these middlewares can be found below. +Note that Catalyst will apply a number of middleware components for you +automatically, and these B be applied if you manually create a +psgi file yourself. Details of these components can be found below. Additional information about psgi files can be found at: L -=head2 Why would I want to make a .psgi file? - -Writing your own .psgi file allows you to use the alternate L command -to start your application, and allows you to add classes and extensions -that implement L, such as L, -or L. - -=head2 What is in the .psgi Catalyst generates by default? +=head2 What is in the .psgi file Catalyst generates by default? -Catalyst generates an application which, if the C<< using_frontend_proxy >> -setting is on, is wrapped in L, and contains some -engine specific fixes for uniform behaviour, as contained in: +Catalyst generates an application which, if the C<< using_frontend_proxy +>> setting is on, is wrapped in L, and +contains some engine-specific fixes for uniform behaviour, as contained +in: =over @@ -68,11 +79,11 @@ engine specific fixes for uniform behaviour, as contained in: =back -If you override the default by providing your own C<< .psgi >> file, then -none of these things will be done automatically for you by the PSGI -application returned when you call C<< MyApp->psgi_app >>, and if you need -any of this functionality, you'll need to implement this in your C<< .psgi >> -file yourself. +If you override the default by providing your own C<< .psgi >> file, +then none of these things will be done automatically for you by the PSGI +application returned when you call C<< MyApp->psgi_app >>. Thus, if you +need any of this functionality, you'll need to implement this in your +C<< .psgi >> file yourself. An apply_default_middlewares method is supplied to wrap your application in the default middlewares if you want this behaviour and you are providing