lib/Catalyst/PSGI.pod

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