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