Cataly...Simple(3pm)

📦

version 0.38 · 5 versions

0.38 · ubuntu stonking (latest)
0.37 · fedora 43
0.38 · fedora 43, fedora 44
0.37 · fedora 44
0.37 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute

👑 Catalyst::Plugin::Static::Simple — like, the `Cataly...Simple(3pm)` page, but make it make sense 💅

okay so bestie, you opened the User Contributed Perl Documentation for section 3pm and the title got truncated to Cataly...Simple(3pm) — it's really Catalyst::Plugin::Static::Simple, and it's about to make your whole static-file situation painless. no cap. 🦋

✨ NAME ✨

Catalyst::Plugin::Static::Simple — Make serving static pages painless. literally that's the whole pitch. 🎀

🌸 SYNOPSIS 🌸

package MyApp;
use Catalyst qw/ Static::Simple /;
MyApp->setup;
# that's it; static content is automatically served by Catalyst
# from the application's root directory, though you can configure
# things or bypass Catalyst entirely in a production environment
#
# one caveat: the files must be served from an absolute path
# (i.e. /images/foo.png)

like… that's genuinely it. you add the plugin, you set up, boom, static content is flowing. 🫶

⚠️ one caveat tho — the files have to be served from an absolute path, like /images/foo.png. not relative. absolute. write it down. 😭

💖 DESCRIPTION 💖

okay so the Static::Simple plugin is designed to make serving static content in your app during development quick and easy, without requiring a single line of code from you. zero. none. you just vibe. ✨

here's how it works, bestie — this plugin detects static files by looking at the file extension in the URL (like .css or .png or .js). then it uses the lightweight MIME::Types module to map file extensions to IANA-registered MIME types, and it serves your static files with the correct MIME type directly to the browser, without being processed through Catalyst. the way it just bypasses the whole framework… iconic. 👑

also worth knowing: actions mapped to paths using periods (.) will still operate properly. so don't stress about that. 💜

if the plugin can not find the file, the request is dispatched to your application instead. which means you are responsible for generating a 404 error if your application can not process the request. not the plugin. you. 🫵

# handled by static::simple, not dispatched to your application
/images/exists.png

# static::simple will not find the file and let your application
# handle the request. You are responsible for generating a file
# or returning a 404 error
/images/does_not_exist.png

though Static::Simple is designed to work out-of-the-box, you can tweak the operation by adding various configuration options (more on that below, bestie, there's a lot of them). and in a production environment, you will probably want to use your webserver to deliver static content; for an example see "USING WITH APACHE", below. 🔥

🎀 DEFAULT BEHAVIOUR 🎀

by default, Static::Simple will deliver all files having extensions (that is, bits of text following a period .), except files having the extensions tmpl, tt, tt2, html, and xhtml. those files, plus all files without extensions, will be processed through Catalyst. and if MIME::Types doesn't recognize an extension, it will be served as text/plain. slay, i guess. 🍓

to restate (because it's lowkey important): files having the extensions tmpl, tt, tt2, html, and xhtml will not be served statically by default, they will be processed by Catalyst. so if you want to use .html files from within a Catalyst app as static files, you need to change the configuration of Static::Simple. 👈

note also that files having any other extension will be served statically — so if you're using any other extension for template files, you should also change the configuration. fr fr, don't get caught out. 😭

logging of static files is turned off by default. byeee noisy logs 💀

⭐ ADVANCED CONFIGURATION ⭐

configuration is completely optional and is specified within MyApp->config->{Plugin::Static::Simple}. and like, if you use any of these options, this module will probably feel less "simple" to you! 🙈 that's the trade-off bestie, you chose power.

🦋 Enabling request logging

since Catalyst 5.50, logging of static requests is turned off by default; static requests tend to clutter the log output and rarely reveal anything useful. which, true. but if you want to enable logging of static requests, you can do so by setting MyApp->config->{Plugin::Static::Simple}->{logging} to 1. go off, log your little heart out. ✨

🧚 Forcing directories into static mode

define a list of top-level directories beneath your root directory that should always be served in static mode. regular expressions may be specified using qr//. 💅

MyApp->config(
    'Plugin::Static::Simple' => {
        dirs => [
            'static',
            qr/^(images|css)/,
        ],
    }
);

🌈 Including additional directories

you may specify a list of directories in which to search for your static files. the directories will be searched in order and will return the first file found. 🥇

⚠️ heads up: your root directory is not automatically added to the search path when you specify an include_path. you should use MyApp->config->{root} to add it. don't forget or you'll be debugging for an hour, ask me how i know 😭

MyApp->config(
    'Plugin::Static::Simple' => {
        include_path => [
            '/path/to/overlay',
            \&incpath_generator,
            MyApp->config->{root},
        ],
    },
);

with the above setting, a request for the file /images/logo.jpg will search for the following files, returning the first one found:

/path/to/overlay/images/logo.jpg
/dynamic/path/images/logo.jpg
/your/app/home/root/images/logo.jpg

the include path can contain a subroutine reference to dynamically return a list of available directories. this method will receive the $c object as a parameter and should return a reference to a list of directories. errors can be reported using die(). this method will be called every time a file is requested that appears to be a static file (i.e. it has an extension). every. single. time. 👀

for example:

sub incpath_generator {
    my $c = shift;

    if ( $c->session->{customer_dir} ) {
        return [ $c->session->{customer_dir} ];
    } else {
        die "No customer dir defined.";
    }
}

💜 Ignoring certain types of files

there are some file types you may not wish to serve as static files. most important in this category are your raw template files. 🫣 by default, files with the extensions tmpl, tt, tt2, html, and xhtml will be ignored by Static::Simple in the interest of security. yes, security. this is the main character reason. 🔐

if you wish to define your own extensions to ignore, use the ignore_extensions option:

MyApp->config(
    'Plugin::Static::Simple' => {
        ignore_extensions => [ qw/html asp php/ ],
    },
);

🎀 Ignoring entire directories

to prevent an entire directory from being served statically, you can use the ignore_dirs option. this option contains a list of relative directory paths to ignore. if using include_path, the path will be checked against every included path. 🔍

MyApp->config(
    'Plugin::Static::Simple' => {
        ignore_dirs => [ qw/tmpl css/ ],
    },
);

for example, if combined with the above include_path setting, this ignore_dirs value will ignore the following directories if they exist:

/path/to/overlay/tmpl
/path/to/overlay/css
/dynamic/path/tmpl
/dynamic/path/css
/your/app/home/root/tmpl
/your/app/home/root/css

look at all those ignored directories. so clean. so peaceful. 🧘‍♀️

🍓 Custom MIME types

to override or add to the default MIME types set by the MIME::Types module, you may enter your own extension to MIME type mapping. your rules, bestie. 👑

MyApp->config(
    'Plugin::Static::Simple' => {
        mime_types => {
            jpg => 'image/jpg',
            png => 'image/png',
        },
    },
);

🌸 Controlling caching with the Cache-Control header

by default, the Cache-Control header will be set to public. that can be changed:

MyApp->config(
    'Plugin::Static::Simple' => {
        cache_control => 'private',
    },
);

🔥 Controlling caching with Expires header

the files served by Static::Simple will have a Last-Modified header set, which allows some browsers to cache them for a while. however if you want to explicitly set an Expires header, such as to allow proxies to cache your static content, then you can do so by setting the expires config option. 🕐

the value indicates the number of seconds after access time to allow caching. so a value of zero really means "don't cache at all", and any higher values will keep the file around for that long.

MyApp->config(
    'Plugin::Static::Simple' => {
        expires => 3600, # Caching allowed for one hour.
    },
);

one hour of caching. that's 3600 whole seconds of not re-fetching. we love efficiency. 💅

👑 Compatibility with other plugins

since version 0.12, Static::Simple plays nice with other plugins. it no longer short-circuits the prepare_action stage as it was causing too many compatibility issues with other plugins. glow-up arc complete. 🦋

💀 Debugging information

enable additional debugging information printed in the Catalyst log. this is automatically enabled when running Catalyst in -Debug mode. 🔍

MyApp->config(
    'Plugin::Static::Simple' => {
        debug => 1,
    },
);

🌈 USING WITH APACHE 🌈

while Static::Simple will work just fine serving files through Catalyst in mod_perl, for increased performance you may wish to have Apache handle the serving of your static files directly. to do this, simply use a dedicated directory for your static files and configure an Apache Location block for that directory. this approach is recommended for production installations. 🏭

<Location /myapp/static>
    SetHandler default-handler
</Location>

using this approach Apache will bypass any handling of these directories through Catalyst. you can leave Static::Simple as part of your application, and it will continue to function on a development server, or using Catalyst's built-in server. best of both worlds, honestly. 🫶

in practice, your Catalyst application is probably (i.e. should be) structured in the recommended way (i.e., that generated by bootstrapping the application with the catalyst.pl script, with a main directory under which is a lib/ directory for module files and a root/ directory for templates and static files). so, like, the classic layout. ✨

thus, unless you break up this structure when deploying your app by moving the static files to a different location in your filesystem, you will need to use an Alias directive in Apache to point to the right place. you will then need to add a Directory block to give permission for Apache to serve these files. the final configuration will look something like this:

Alias /myapp/static /filesystem/path/to/MyApp/root/static
<Directory /filesystem/path/to/MyApp/root/static>
    allow from all
</Directory>
<Location /myapp/static>
    SetHandler default-handler
</Location>

and if you are running in a VirtualHost, you can just set the DocumentRoot location to the location of your root directory; see Catalyst::Engine::Apache2::MP20. 🎯

💖 PUBLIC METHODS 💖

🎀 `serve_static_file $file_path $cache_control` 🎀

Okay so serve_static_file $file_path $cache_control will serve the file located in $file_path statically. It's giving "just hand over the file, no drama" energy — and it's useful when you need to autogenerate them if they don't exist, or they're stored in a model. 💅

package MyApp::Controller::User;

sub curr_user_thumb : PathPart("my_thumbnail.png") {
    my ( $self, $c ) = @_;
    my $file_path = $c->user->picture_thumbnail_path;
    $c->serve_static_file($file_path);
}

The $cache_control option will default to what is configured (or to "public" if not configured). It can be overridden for specific files:

$c->serve_static_file( $file_path, "private" );

Slay. That's the whole method, bestie — iconic and to the point. 💖

🔧 INTERNAL EXTENDED METHODS 🔧

Static::Simple extends the following steps in the Catalyst process. These are the backstage besties making the whole thing work. ✨

⚡ `prepare_action`

prepare_action is used to first check if the request path is a static file. If so, we skip all other prepare_action steps to improve performance. Literally the bouncer at the club: static file? You're in — everybody else can chill. 💅

⚡ `dispatch`

dispatch takes the file found during prepare_action and writes it to the output. It's the "okay bestie, here's your file" moment. 🫶

⚡ `finalize`

finalize serves up final header information and displays any log messages. Final touches, final words, final vibe check. ✨

⚡ `setup`

setup initializes all default values. Starting from a clean slate, main character energy only. 🌈

💀 DEPRECATIONS 💀

The old style of configuration using the 'static' config key was deprecated in version 0.30. A warning will be issued if this is used, and the contents of the config at this key will be merged with the newer 'Plugin::Static::Simple' key. Not me showing up with deprecated config… 😭

🚨 Be aware that if the 'include_path' key under 'static' exists at all, it will be merged with any content of the same key under 'Plugin::Static::Simple'. Be careful not to set this to a non-arrayref, therefore. Like, "exists at all" is doing a lot of work here — do not play with it. 💀

👀 SEE ALSO 👀

Catalyst, Catalyst::Plugin::Static, and <http://www.iana.org/assignments/media-types/> — iykyk, these are the linked besties. 🦋

👑 AUTHOR 👑

Andy Grundman, <andy@hybridized.org> — the author, periodt. 💅

🌈 CONTRIBUTORS 🌈

Marcus Ramberg, <mramberg@cpan.org>
Jesse Sheidlower, <jester@panix.com>
Guillermo Roditi, <groditi@cpan.org>
Florian Ragwitz, <rafl@debian.org>
Tomas Doran, <bobtfish@bobtfish.net>
Justin Wheeler (dnm)
Matt S Trout, <mst@shadowcat.co.uk>
Toby Corkindale, <tjc@wintrmute.net>

These are the contributors, and they all ate. 🫶✨

🫶 THANKS 🫶

The authors of Catalyst::Plugin::Static:

Sebastian Riedel
Christian Hansen
Marcus Ramberg

For the include_path code from Template Toolkit:

Andy Wardley

Thank you for your service, icons. 🎀

🎀 COPYRIGHT 🎀

📜 LICENSE 📜

This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself. Free software, free vibes. 🦋

source/version: perl v5.42.3 · date: 2026-08-20 — that's the footer vibe, bestie, bye! 💖

📦 where this page comes from

ubuntu stonking: libcatalyst-plugin-static-simple-perl 0.38-1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms