SYNOPSIS
# in .psgi
use Plack::Builder;
my $app = sub { ... };
builder {
enable "Deflater";
enable "Session", store => "File";
enable "Debug", panels => [ qw(DBITrace Memory Timer) ];
enable "+My::Plack::Middleware";
$app;
};
# use URLMap
builder {
mount "/foo" => builder {
enable "Foo";
$app;
};
mount "/bar" => $app2;
mount "http://example.com/" => builder { $app3 };
};
# using OO interface
my $builder = Plack::Builder->new;
$builder->add_middleware('Foo', opt => 1);
$builder->add_middleware('Bar');
$builder->wrap($app);
DESCRIPTION
Plack::Builder gives you a quick domain specific language (DSL) to wrap your application with Plack::Middleware subclasses. The middleware you're trying to use should use Plack::Middleware as a base class to use this DSL, inspired by Rack::Builder.Whenever you call "enable" on any middleware, the middleware app is pushed to the stack inside the builder, and then reversed when it actually creates a wrapped application handler. "Plack::Middleware::" is added as a prefix by default. So:
builder { enable "Foo"; enable "Bar", opt => "val"; $app; };
is syntactically equal to:
$app = Plack::Middleware::Bar->wrap($app, opt => "val"); $app = Plack::Middleware::Foo->wrap($app);
In other words, you're supposed to "enable" middleware from outer to inner.
INLINE MIDDLEWARE
Plack::Builder allows you to code middleware inline using a nested code reference.If the first argument to "enable" is a code reference, it will be passed an $app and should return another code reference which is a PSGI application that consumes $env at runtime. So:
builder { enable sub { my $app = shift; sub { my $env = shift; # do preprocessing my $res = $app->($env); # do postprocessing return $res; }; }; $app; };
is equal to:
my $mw = sub { my $app = shift; sub { my $env = shift; $app->($env) }; }; $app = $mw->($app);
URLMap support
Plack::Builder has a native support for Plack::App::URLMap via the "mount" method.
use Plack::Builder; my $app = builder { mount "/foo" => $app1; mount "/bar" => builder { enable "Foo"; $app2; }; };
See Plack::App::URLMap's "map" method to see what they mean. With "builder" you can't use "map" as a DSL, for the obvious reason :)
NOTE: Once you use "mount" in your builder code, you have to use "mount" for all the paths, including the root path ("/"). You can't have the default app in the last line of "builder" like:
my $app = sub { my $env = shift; ... }; builder { mount "/foo" => sub { ... }; $app; # THIS DOESN'T WORK };
You'll get warnings saying that your mount configuration will be ignored. Instead you should use "mount "/" => ..." in the last line to set the default fallback app.
builder { mount "/foo" => sub { ... }; mount "/" => $app; }
Note that the "builder" DSL returns a whole new PSGI application, which means
- "builder { ... }" should normally the last statement of a ".psgi" file, because the return value of "builder" is the application that is actually executed.
-
You can nest your "builder" blocks, mixed with "mount" statements (see ``URLMap support''
above):
builder { mount "/foo" => builder { mount "/bar" => $app; } }
will locate the $app under "/foo/bar", since the inner "builder" block puts it under "/bar" and it results in a new PSGI application which is located under "/foo" because of the outer "builder" block.
CONDITIONAL MIDDLEWARE SUPPORT
You can use "enable_if" to conditionally enable middleware based on the runtime environment.
builder { enable_if { $_[0]->{REMOTE_ADDR} eq '127.0.0.1' } 'StackTrace', force => 1; $app; };
See Plack::Middleware::Conditional for details.
OBJECT ORIENTED INTERFACE
Object oriented interface supports the same functionality with the DSL version in a clearer interface, probably with more typing required.
# With mount my $builder = Plack::Builder->new; $builder->add_middleware('Foo', opt => 1); $builder->mount('/foo' => $foo_app); $builder->mount('/' => $root_app); $builder->to_app; # Nested builders. Equivalent to: # builder { # mount '/foo' => builder { # enable 'Foo'; # $app; # }; # mount '/' => $app2; # }; my $builder_out = Plack::Builder->new; my $builder_in = Plack::Builder->new; $builder_in->add_middleware('Foo'); $builder_out->mount("/foo" => $builder_in->wrap($app)); $builder_out->mount("/" => $app2); $builder_out->to_app; # conditional. You can also directly use Plack::Middleware::Conditional my $builder = Plack::Builder->new; $builder->add_middleware_if(sub { $_[0]->{REMOTE_ADDR} eq '127.0.0.1' }, 'StackTrace'); $builder->wrap($app);