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 = sub { 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 =item nginx - local to Catalyst
  78
  79 =back
  80
  81 If you override the default by providing your own C<< .psgi >> file,
  82 then none of these things will be done automatically for you by the PSGI
  83 application returned when you call C<< MyApp->psgi_app >>. Thus, if you
  84 need any of this functionality, you'll need to implement this in your
  85 C<< .psgi >> file yourself.
  86
  87 An apply_default_middlewares method is supplied to wrap your application
  88 in the default middlewares if you want this behaviour and you are providing
  89 your own .psgi file.
  90
  91 =head1 SEE ALSO
  92
  93 L<Catalyst::Upgrading>, L<Plack>, L<PSGI::FAQ>, L<PSGI>.
  94
  95 =head1 AUTHORS
  96
  97 Catalyst Contributors, see Catalyst.pm
  98
  99 =head1 COPYRIGHT
 100
 101 This library is free software. You can redistribute it and/or modify
 102 it under the same terms as Perl itself.
 103
 104 =cut