Plack::Builder(3pm)

1Plack::Builder(3)     User Contributed Perl Documentation    Plack::Builder(3)
2
3
4

NAME

6       Plack::Builder - OO and DSL to enable Plack Middlewares
7

SYNOPSIS

9         # in .psgi
10         use Plack::Builder;
11
12         my $app = sub { ... };
13
14         builder {
15             enable "Plack::Middleware::Foo";
16             enable "Plack::Middleware::Bar", opt => "val";
17             enable "Plack::Middleware::Baz";
18             $app;
19         };
20
21         # use URLMap
22
23         builder {
24             mount "/foo" => builder {
25                 enable "Plack::Middleware::Foo";
26                 $app;
27             };
28
29             mount "/bar" => $app2;
30             mount "http://example.com/" => builder { $app3 };
31         };
32
33         # using OO interface
34
35         my $builder = Plack::Builder->new();
36         $builder->add_middleware('Foo', opt => 1);
37         $app = $builder->mount('/app' => $app);
38         $app = $builder->to_app($app);
39

DESCRIPTION

41       Plack::Builder gives you a quick domain specific language (DSL) to wrap
42       your application with Plack::Middleware subclasses. The middleware
43       you're trying to use should use Plack::Middleware as a base class to
44       use this DSL, inspired by Rack::Builder.
45
46       Whenever you call "enable" on any middleware, the middleware app is
47       pushed to the stack inside the builder, and then reversed when it
48       actually creates a wrapped application handler, so:
49
50         builder {
51             enable "Plack::Middleware::Foo";
52             enable "Plack::Middleware::Bar", opt => "val";
53             $app;
54         };
55
56       is syntactically equal to:
57
58         $app = Plack::Middleware::Bar->wrap($app, opt => "val");
59         $app = Plack::Middleware::Foo->wrap($app);
60
61       In other words, you're supposed to "enable" middleware from outer to
62       inner.
63

INLINE MIDDLEWARE

65       Plack::Builder allows you to code middleware inline using a nested code
66       reference.
67
68       If the first argument to "enable" is a code reference, it will be
69       passed an $app and is supposed to return another code reference which
70       is PSGI application that consumes $env in runtime. So:
71
72         builder {
73             enable sub {
74                 my $app = shift;
75                 sub {
76                     my $env = shift;
77                     # do preprocessing
78                     my $res = $app->($env);
79                     # do postprocessing
80                     return $res;
81                 };
82             };
83             $app;
84         };
85
86       is equal to:
87
88         my $mw = sub {
89             my $app = shift;
90             sub { my $env = shift; $app->($env) };
91         };
92
93         $app = $mw->($app);
94

URLMap support

96       Plack::Builder has a native support for Plack::App::URLMap with "mount"
97       method.
98
99         use Plack::Builder;
100         my $app = builder {
101             mount "/foo" => $app1;
102             mount "/bar" => builder {
103                 enable "Plack::Middleware::Foo";
104                 $app2;
105             };
106         };
107
108       See Plack::App::URLMap's "map" method to see what they mean. With
109       builder you can't use "map" as a DSL, for the obvious reason :)
110
111       NOTE: Once you use "mount" in your builder code, you have to use
112       "mount" for all the paths, including the root path ("/"). You can't
113       have the default app in the last line of "builder" like:
114
115         my $app = sub {
116             my $env = shift;
117             ...
118         };
119
120         builder {
121             mount "/foo" => sub { ... };
122             $app; # THIS DOESN'T WORK
123         };
124
125       You'll get warnings saying that your mount configuration will be
126       ignored. Instead you should use "mount "/" => ..." in the last line to
127       set the default fallback app.
128
129         builder {
130             mount "/foo" => sub { ... };
131             mount "/" => $app;
132         }
133
134       Note that the "builder" DSL returns a whole new PSGI application, which
135       means
136
137       ·   "builder { ... }" should normally the last statement of a ".psgi"
138           file, because the return value of "builder" is the application that
139           actually is executed.
140
141       ·   You can nest your "builder" block, mixed with "mount" (see URLMap
142           support above):
143
144             builder {
145                 mount "/foo" => builder {
146                     mount "/bar" => $app;
147                 }
148             }
149
150           will locate the $app under "/foo/bar" since the inner "builder"
151           block puts it under "/bar" and it results a new PSGI application
152           which is located under "/foo" because of the outer "builder" block.
153

CONDITIONAL MIDDLEWARE SUPPORT

155       You can use "enable_if" to conditionally enable middleware based on the
156       runtime environment. See Plack::Middleware::Conditional for details.
157

NAME

SYNOPSIS

DESCRIPTION

INLINE MIDDLEWARE

URLMap support

CONDITIONAL MIDDLEWARE SUPPORT

SEE ALSO