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=a05e0023bbe4518005b457c2c6917853feeeeb2f;hp=1aec1f8a89063a7e3b64b8a8c3993967bfe55db5;hb=199731fb710c6a165793f055f85de60539039dfe;hpb=b28a5d4a5369ac92ab38e57bb59660d768a71cb6 diff --git a/lib/Catalyst/PSGI.pod b/lib/Catalyst/PSGI.pod index 1aec1f8..a05e002 100644 --- a/lib/Catalyst/PSGI.pod +++ b/lib/Catalyst/PSGI.pod @@ -6,29 +6,45 @@ 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 an +implementation of the PSGI specification for running Perl applications. -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: @@ -36,27 +52,21 @@ The simplest C<.psgi> file for an application called C would be: use warnings; use TestApp; - my $app = sub { TestApp->psgi_app(@_) }; + my $app = 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 file Catalyst generates by default? -=head2 What is in the .psgi 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 +setting is on, is wrapped in L, and +contains some engine-specific fixes for uniform behaviour, as contained +in: =over @@ -64,20 +74,27 @@ engine specific fixes for uniform behaviour, as contained in: =item L -=item nginx - local to Catalyst - =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 your own .psgi file. +This means that the auto-generated (no .psgi file) code looks something +like this: + + use strict; + use warnings; + use TestApp; + + my $app = TestApp->apply_default_middlewares(TestApp->psgi_app(@_)); + =head1 SEE ALSO L, L, L, L.