5 Catalyst::PSGI - How Catalyst and PSGI work together
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)
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.
16 This means that we can share common code, and fixes for specific web servers.
18 =head1 I already have an application
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).
24 =head1 Writing your own PSGI file.
26 =head2 What is a .psgi file
28 A C<< .psgi >> file lets you manually controll how your application code reference is built.
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.
33 The simplest C<.psgi> file for an application called C<TestApp> would be:
39 my $app = sub { TestApp->psgi_app(@_) };
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.
45 Additional information about psgi files can be found at:
46 L<http://search.cpan.org/dist/Plack/lib/Plack.pm#.psgi_files>
48 =head2 Why would I want to make a .psgi file?
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>.
55 =head2 What is in the .psgi Catalyst generates by default?
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:
63 =item L<Plack::Middleware::LighttpdScriptNameFix>
65 =item L<Plack::Middleware::IIS6ScriptNameFix>
67 =item nginx - local to Catalyst
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 >>
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
83 L<Catalyst::Upgrading>, L<Plack>, L<PSGI::FAQ>, L<PSGI>.
87 Catalyst Contributors, see Catalyst.pm
91 This library is free software. You can redistribute it and/or modify
92 it under the same terms as Perl itself.