Catalyst::PSGI - How Catalyst and PSGI work together

       Catalyst Contributors, see Catalyst.pm

       This  library  is  free  software.  You can redistribute it and/or modify it under the same terms as Perl
       itself.

perl v5.40.0                                       2024-11-15                                Catalyst::PSGI(3pm)

       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 Catalyst::Upgrading for specifics about your web server
       deployment).

       Catalyst::PSGI - How Catalyst and PSGI work together

       Catalyst::Upgrading, Plack, PSGI::FAQ, PSGI.

       The PSGI 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.). Plack is an implementation of the PSGI
       specification for running Perl applications.

       Catalyst used to contain an entire set of "Catalyst::Engine::XXXX" classes to handle various web servers
       and environments (e.g. CGI, FastCGI, mod_perl) etc.

       This has been changed in Catalyst 5.9 so that all of that work is done by Catalyst implementing the PSGI
       specification, using Plack's adaptors to implement that functionality.

       This means that we can share common code, and share fixes for specific web servers.

Whatisa.psgifile?
       A ".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 "myapp.psgi" file in the root of
       your application.

   WhywouldIwanttowritemyown.psgifile?
       Writing your own .psgi file allows you to use the alternate plackup command to start your application,
       and allows you to add classes and extensions that implement Plack::Middleware, such as
       Plack::Middleware::ErrorDocument or Plack::Middleware::AccessLog.

       The simplest ".psgi" file for an application called "TestApp" would be:

           use strict;
           use warnings;
           use TestApp;

           my $app = TestApp->psgi_app(@_);

       Note that Catalyst will apply a number of middleware components for you automatically, and these willnot
       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:
       <http://search.cpan.org/dist/Plack/lib/Plack.pm#.psgi_files>

   Whatisinthe.psgifileCatalystgeneratesbydefault?
       Catalyst generates an application which, if the "using_frontend_proxy" setting is on, is wrapped in
       Plack::Middleware::ReverseProxy, and contains some engine-specific fixes for uniform behaviour, as
       contained in:

       Plack::Middleware::LighttpdScriptNameFix
       Plack::Middleware::IIS6ScriptNameFix

       If  you  override  the default by providing your own ".psgi" file, then none of these things will be done
       automatically for you by the PSGI application returned when you call "MyApp->psgi_app". Thus, if you need
       any of this functionality, you'll need to implement this in your ".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(@_));