NAME¶
Plack::Middleware::Static - serve static files with Plack
SYNOPSIS¶
use Plack::Builder;
builder {
enable "Plack::Middleware::Static",
path => qr{^/(images|js|css)/}, root => './htdocs/';
$app;
};
DESCRIPTION¶
This middleware allows your Plack-based application to serve static files.
Note that if you are building an app using Plack::App::URLMap, you should
consider using Plack::App::File to serve static files instead. This makes the
overall routing of your application simpler to understand.
With this middleware, if a static file exists for the requested path, it will be
served. If it does not exist, by default this middleware returns a 404, but
you can set the "pass_through" option to change this behavior.
If the requested document is not within the "root" or the file is
there but not readable, this middleware will return a 403 Forbidden response.
The content type returned will be determined from the file extension by using
Plack::MIME or using "content_type".
CONFIGURATIONS¶
- path, root
-
enable "Plack::Middleware::Static",
path => qr{^/static/}, root => 'htdocs/';
The "path" option specifies the URL pattern (regular expression)
or a callback to match against requests. If the <path> option
matches, the middleware looks in "root" to find the static files
to serve. The default value of "root" is the current directory.
This example configuration serves "/static/foo.jpg" from
"htdocs/static/foo.jpg". Note that the matched portion of the
path, "/static/", still appears in the locally mapped path under
"root". If you don't want this to happen, you can use a callback
to munge the path as you match it:
enable "Plack::Middleware::Static",
path => sub { s!^/static/!! }, root => 'static-files/';
The callback should operate on $_ and return a true or false value. Any
changes it makes to $_ are used when looking for the static file in the
"root".
The configuration above serves "/static/foo.png" from
"static-files/foo.png", not
"static-files/static/foo.png". The callback specified in the
"path" option matches against $_ munges this value using
"s///". The substitution operator returns the number of matches
it made, so it will return true when the path matches
"^/static".
For more complex static handling in the "path" callback, in
addition to $_ being set the callback receives two arguments,
"PATH_INFO" (same as $_) and $env.
If you want to map multiple static directories from different roots, simply
add this middleware multiple times with different configuration
options.
- pass_through
- When this option is set to a true value, then this
middleware will never return a 404 if it cannot find a matching file.
Instead, it will simply pass the request on to the application it is
wrapping.
- content_type
- The "content_type" option can be used to provide
access to a different MIME database than Plack::MIME. Plack::MIME works
fast and good for a list of well known file endings, but if you need a
more accurate content based checking you can use modules like
File::MimeInfo or File::MMagic for example. The callback should work on
$_[0] which is the filename of the file.
AUTHOR¶
Tokuhiro Matsuno, Tatsuhiko Miyagawa
SEE ALSO¶
Plack::Middleware Plack::Builder