Catalyst-Plugin-Static-Simple
view release on metacpan or search on metacpan
lib/Catalyst/Plugin/Static/Simple.pm view on Meta::CPAN
=head1 DEFAULT BEHAVIOUR
By default, Static::Simple will deliver all files having extensions
(that is, bits of text following a period (C<.>)), I<except> files
having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
C<xhtml>. These files, and all files without extensions, will be
processed through Catalyst. If L<MIME::Types> doesn't recognize an
extension, it will be served as C<text/plain>.
To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
and C<xhtml> I<will not> be served statically by default, they will be
processed by Catalyst. Thus if you want to use C<.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 I<will> be served statically, so if you're using any other
extension for template files, you should also change the configuration.
Logging of static files is turned off by default.
=head1 ADVANCED CONFIGURATION
Configuration is completely optional and is specified within
C<MyApp-E<gt>config-E<gt>{Plugin::Static::Simple}>. If you use any of these options,
this module will probably feel less "simple" to you!
=head2 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. However, if you want to enable logging of static
requests, you can do so by setting
C<MyApp-E<gt>config-E<gt>{Plugin::Static::Simple}-E<gt>{logging}> to 1.
=head2 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 C<qr//>.
MyApp->config(
'Plugin::Static::Simple' => {
dirs => [
'static',
qr/^(images|css)/,
],
}
);
=head2 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. Note that your root directory is B<not> automatically
added to the search path when you specify an C<include_path>. You should
use C<MyApp-E<gt>config-E<gt>{root}> to add it.
MyApp->config(
'Plugin::Static::Simple' => {
include_path => [
'/path/to/overlay',
\&incpath_generator,
MyApp->config->{root},
],
},
);
With the above setting, a request for the file C</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<$c> object as a
parameter and should return a reference to a list of directories. Errors can
be reported using C<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).
For example:
sub incpath_generator {
my $c = shift;
if ( $c->session->{customer_dir} ) {
return [ $c->session->{customer_dir} ];
} else {
die "No customer dir defined.";
}
}
=head2 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 C<tmpl>, C<tt>, C<tt2>, C<html>, and
C<xhtml> will be ignored by Static::Simple in the interest of security.
If you wish to define your own extensions to ignore, use the
C<ignore_extensions> option:
MyApp->config(
'Plugin::Static::Simple' => {
ignore_extensions => [ qw/html asp php/ ],
},
);
=head2 Ignoring entire directories
To prevent an entire directory from being served statically, you can use
the C<ignore_dirs> option. This option contains a list of relative
directory paths to ignore. If using C<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 C<include_path> setting, this
C<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
=head2 Custom MIME types
To override or add to the default MIME types set by the L<MIME::Types>
module, you may enter your own extension to MIME type mapping.
MyApp->config(
'Plugin::Static::Simple' => {
mime_types => {
jpg => 'image/jpg',
png => 'image/png',
},
},
);
=head2 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.
},
);
=head2 Compatibility with other plugins
Since version 0.12, Static::Simple plays nice with other plugins. It no
longer short-circuits the C<prepare_action> stage as it was causing too
many compatibility issues with other plugins.
=head2 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,
},
);
=head1 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
( run in 1.554 second using v1.01-cache-2.11-cpan-75ffa21a3d4 )