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