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

perl v5.38.2                                       2024-01-20                     Plack::Middleware::Static(3pm)