lib/Catalyst/PSGI.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Catalyst::PSGI - How Catalyst and PSGI work together
   6
   7 =head1 SYNOPSIS
   8
   9 The L<PSGI> specification defines an interface between web servers and
  10 Perl-based web applications and frameworks. It supports the writing of
  11 portable applications that can be run using various methods (as a
  12 standalone server, or using mod_perl, FastCGI, etc.). L<Plack> is an
  13 implementation of the PSGI specification for running Perl applications.
  14
  15 Catalyst used to contain an entire set of C<< Catalyst::Engine::XXXX >>
  16 classes to handle various web servers and environments (e.g. CGI,
  17 FastCGI, mod_perl) etc.
  18
  19 This has been changed in Catalyst 5.9 so that all of that work is done
  20 by Catalyst implementing the L<PSGI> specification, using L<Plack>'s
  21 adaptors to implement that functionality.
  22
  23 This means that we can share common code, and share fixes for specific
  24 web servers.
  25
  26 =head1 I already have an application
  27
  28 If you already have a Catalyst application, then you should be able to
  29 upgrade to the latest release with little or no trouble (see the notes
  30 in L<Catalyst::Upgrading> for specifics about your web server
  31 deployment).
  32
  33 =head1 Writing your own PSGI file.
  34
  35 =head2 What is a .psgi file?
  36
  37 A C<< .psgi >> file lets you control how your application code reference
  38 is built. Catalyst will automatically handle this for you, but it's
  39 possible to do it manually by creating a C<myapp.psgi> file in the root
  40 of your application.
  41
  42 =head2 Why would I want to write my own .psgi file?
  43
  44 Writing your own .psgi file allows you to use the alternate L<plackup> command
  45 to start your application, and allows you to add classes and extensions
  46 that implement L<Plack::Middleware>, such as L<Plack::Middleware::ErrorDocument>
  47 or L<Plack::Middleware::AccessLog>.
  48
  49 The simplest C<.psgi> file for an application called C<TestApp> would be:
  50
  51     use strict;
  52     use warnings;
  53     use TestApp;
  54
  55     my $app = TestApp->psgi_app(@_);
  56
  57 Note that Catalyst will apply a number of middleware components for you
  58 automatically, and these B<will not> be applied if you manually create a
  59 psgi file yourself. Details of these components can be found below.
  60
  61 Additional information about psgi files can be found at:
  62 L<http://search.cpan.org/dist/Plack/lib/Plack.pm#.psgi_files>
  63
  64 =head2 What is in the .psgi file Catalyst generates by default?
  65
  66 Catalyst generates an application which, if the C<using_frontend_proxy>
  67 setting is on, is wrapped in L<Plack::Middleware::ReverseProxy>, and
  68 contains some engine-specific fixes for uniform behaviour, as contained
  69 in:
  70
  71 =over
  72
  73 =item L<Plack::Middleware::LighttpdScriptNameFix>
  74
  75 =item L<Plack::Middleware::IIS6ScriptNameFix>
  76
  77 =back
  78
  79 If you override the default by providing your own C<< .psgi >> file,
  80 then none of these things will be done automatically for you by the PSGI
  81 application returned when you call C<< MyApp->psgi_app >>. Thus, if you
  82 need any of this functionality, you'll need to implement this in your
  83 C<< .psgi >> file yourself.
  84
  85 An apply_default_middlewares method is supplied to wrap your application
  86 in the default middlewares if you want this behaviour and you are providing
  87 your own .psgi file.
  88
  89 This means that the auto-generated (no .psgi file) code looks something
  90 like this:
  91
  92     use strict;
  93     use warnings;
  94     use TestApp;
  95
  96     my $app = TestApp->apply_default_middlewares(TestApp->psgi_app(@_));
  97
  98 =head1 SEE ALSO
  99
 100 L<Catalyst::Upgrading>, L<Plack>, L<PSGI::FAQ>, L<PSGI>.
 101
 102 =head1 AUTHORS
 103
 104 Catalyst Contributors, see Catalyst.pm
 105
 106 =head1 COPYRIGHT
 107
 108 This library is free software. You can redistribute it and/or modify
 109 it under the same terms as Perl itself.
 110
 111 =cut