README
1NAME
2
3 Plack - Perl Superglue for Web frameworks and Web Servers (PSGI
4 toolkit)
5
6DESCRIPTION
7
8 Plack is a set of tools for using the PSGI stack. It contains
9 middleware components, a reference server and utilities for Web
10 application frameworks. Plack is like Ruby's Rack or Python's Paste for
11 WSGI.
12
13 See PSGI for the PSGI specification and PSGI::FAQ to know what PSGI and
14 Plack are and why we need them.
15
16MODULES AND UTILITIES
17
18 Plack::Handler
19
20 Plack::Handler and its subclasses contains adapters for web servers. We
21 have adapters for the built-in standalone web server
22 HTTP::Server::PSGI, CGI, FCGI, Apache1, Apache2 and
23 HTTP::Server::Simple included in the core Plack distribution.
24
25 There are also many HTTP server implementations on CPAN that have Plack
26 handlers.
27
28 See Plack::Handler when writing your own adapters.
29
30 Plack::Loader
31
32 Plack::Loader is a loader to load one Plack::Handler adapter and run a
33 PSGI application code reference with it.
34
35 Plack::Util
36
37 Plack::Util contains a lot of utility functions for server implementors
38 as well as middleware authors.
39
40 .psgi files
41
42 A PSGI application is a code reference but it's not easy to pass code
43 reference via the command line or configuration files, so Plack uses a
44 convention that you need a file named app.psgi or similar, which would
45 be loaded (via perl's core function do) to return the PSGI application
46 code reference.
47
48 # Hello.psgi
49 my $app = sub {
50 my $env = shift;
51 # ...
52 return [ $status, $headers, $body ];
53 };
54
55 If you use a web framework, chances are that they provide a helper
56 utility to automatically generate these .psgi files for you, such as:
57
58 # MyApp.psgi
59 use MyApp;
60 my $app = sub { MyApp->run_psgi(@_) };
61
62 It's important that the return value of .psgi file is the code
63 reference. See eg/dot-psgi directory for more examples of .psgi files.
64
65 plackup, Plack::Runner
66
67 plackup is a command line launcher to run PSGI applications from
68 command line using Plack::Loader to load PSGI backends. It can be used
69 to run standalone servers and FastCGI daemon processes. Other server
70 backends like Apache2 needs a separate configuration but .psgi
71 application file can still be the same.
72
73 If you want to write your own frontend that replaces, or adds
74 functionalities to plackup, take a look at the Plack::Runner module.
75
76 Plack::Middleware
77
78 PSGI middleware is a PSGI application that wraps an existing PSGI
79 application and plays both side of application and servers. From the
80 servers the wrapped code reference still looks like and behaves exactly
81 the same as PSGI applications.
82
83 Plack::Middleware gives you an easy way to wrap PSGI applications with
84 a clean API, and compatibility with Plack::Builder DSL.
85
86 Plack::Builder
87
88 Plack::Builder gives you a DSL that you can enable Middleware in .psgi
89 files to wrap existent PSGI applications.
90
91 Plack::Request, Plack::Response
92
93 Plack::Request gives you a nice wrapper API around PSGI $env hash to
94 get headers, cookies and query parameters much like Apache::Request in
95 mod_perl.
96
97 Plack::Response does the same to construct the response array
98 reference.
99
100 Plack::Test
101
102 Plack::Test is a unified interface to test your PSGI application using
103 standard HTTP::Request and HTTP::Response pair with simple callbacks.
104
105 Plack::Test::Suite
106
107 Plack::Test::Suite is a test suite to test a new PSGI server backend.
108
109CONTRIBUTING
110
111 Patches and Bug Fixes
112
113 Small patches and bug fixes can be either submitted via nopaste on IRC
114 irc://irc.perl.org/#plack or the github issue tracker
115 <http://github.com/plack/Plack/issues>. Forking on github is another
116 good way if you intend to make larger fixes.
117
118 See also http://contributing.appspot.com/plack when you think this
119 document is terribly outdated.
120
121 Module Namespaces
122
123 Modules added to the Plack:: sub-namespaces should be reasonably
124 generic components which are useful as building blocks and not just
125 simply using Plack.
126
127 Middleware authors are free to use the Plack::Middleware:: namespace
128 for their middleware components. Middleware must be written in the
129 pipeline style such that they can chained together with other
130 middleware components. The Plack::Middleware:: modules in the core
131 distribution are good examples of such modules. It is recommended that
132 you inherit from Plack::Middleware for these types of modules.
133
134 Not all middleware components are wrappers, but instead are more like
135 endpoints in a middleware chain. These types of components should use
136 the Plack::App:: namespace. Again, look in the core modules to see
137 excellent examples of these (Plack::App::File, Plack::App::Directory,
138 etc.). It is recommended that you inherit from Plack::Component for
139 these types of modules.
140
141 DO NOT USE Plack:: namespace to build a new web application or a
142 framework. It's like naming your application under CGI:: namespace if
143 it's supposed to run on CGI and that is a really bad choice and would
144 confuse people badly.
145
146AUTHOR
147
148 Tatsuhiko Miyagawa
149
150COPYRIGHT
151
152 The following copyright notice applies to all the files provided in
153 this distribution, including binary files, unless explicitly noted
154 otherwise.
155
156 Copyright 2009-2013 Tatsuhiko Miyagawa
157
158CORE DEVELOPERS
159
160 Tatsuhiko Miyagawa (miyagawa)
161
162 Tokuhiro Matsuno (tokuhirom)
163
164 Jesse Luehrs (doy)
165
166 Tomas Doran (bobtfish)
167
168 Graham Knop (haarg)
169
170CONTRIBUTORS
171
172 Yuval Kogman (nothingmuch)
173
174 Kazuhiro Osawa (Yappo)
175
176 Kazuho Oku
177
178 Florian Ragwitz (rafl)
179
180 Chia-liang Kao (clkao)
181
182 Masahiro Honma (hiratara)
183
184 Daisuke Murase (typester)
185
186 John Beppu
187
188 Matt S Trout (mst)
189
190 Shawn M Moore (Sartak)
191
192 Stevan Little
193
194 Hans Dieter Pearcey (confound)
195
196 mala
197
198 Mark Stosberg
199
200 Aaron Trevena
201
202SEE ALSO
203
204 The PSGI specification upon which Plack is based.
205
206 http://plackperl.org/
207
208 The Plack wiki: https://github.com/plack/Plack/wiki
209
210 The Plack FAQ: https://github.com/plack/Plack/wiki/Faq
211
212LICENSE
213
214 This library is free software; you can redistribute it and/or modify it
215 under the same terms as Perl itself.
216
217