package Catalyst::Plugin::Static::Simple;
-use strict;
-use warnings;
-use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
+use Moose::Role;
use File::stat;
use File::Spec ();
use IO::File ();
use MIME::Types ();
+use MooseX::Types::Moose qw/ArrayRef Str/;
+use Catalyst::Utils;
+use namespace::autoclean;
-our $VERSION = '0.16';
+our $VERSION = '0.35';
-__PACKAGE__->mk_accessors( qw/_static_file _static_debug_message/ );
+has _static_file => ( is => 'rw' );
+has _static_debug_message => ( is => 'rw', isa => ArrayRef[Str] );
-sub prepare_action {
+after setup_finalize => sub {
+ my $c = shift;
+
+ # New: Turn off new 'autoflush' flag in logger (see Catalyst::Log).
+ # This is needed to surpress output of debug log messages for
+ # static requests:
+ $c->log->autoflush(0) if $c->log->can('autoflush');
+};
+
+before prepare_action => sub {
my $c = shift;
my $path = $c->req->path;
- my $config = $c->config->{static};
-
+ my $config = $c->config->{'Plugin::Static::Simple'};
+
$path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
# is the URI in a static-defined path?
foreach my $dir ( @{ $config->{dirs} } ) {
my $dir_re = quotemeta $dir;
- my $re = ( $dir =~ m{^qr/}xms ) ? eval $dir : qr/^${dir_re}/;
- if ($@) {
- $c->error( "Error compiling static dir regex '$dir': $@" );
+
+ # strip trailing slashes, they'll be added in our regex
+ $dir_re =~ s{/$}{};
+
+ my $re;
+
+ if ( $dir =~ m{^qr/}xms ) {
+ $re = eval $dir;
+
+ if ($@) {
+ $c->error( "Error compiling static dir regex '$dir': $@" );
+ }
+ }
+ else {
+ $re = qr{^${dir_re}/};
}
+
if ( $path =~ $re ) {
if ( $c->_locate_static_file( $path, 1 ) ) {
$c->_debug_msg( 'from static directory' )
$c->_debug_msg( "404: file not found: $path" )
if $config->{debug};
$c->res->status( 404 );
+ $c->res->content_type( 'text/html' );
}
}
}
-
+
# Does the path have an extension?
- if ( $path =~ /.*\.(\S{1,})$/xms ) {
+ if ( $path =~ /\.([^\/\\]+)$/m ) {
# and does it exist?
$c->_locate_static_file( $path );
}
-
- return $c->NEXT::ACTUAL::prepare_action(@_);
-}
+};
-sub dispatch {
+around dispatch => sub {
+ my $orig = shift;
my $c = shift;
-
+
return if ( $c->res->status != 200 );
-
+
if ( $c->_static_file ) {
- if ( $c->config->{static}{no_logs} && $c->log->can('abort') ) {
+ if ( $c->config->{'Plugin::Static::Simple'}->{no_logs} && $c->log->can('abort') ) {
$c->log->abort( 1 );
}
return $c->_serve_static;
}
else {
- return $c->NEXT::ACTUAL::dispatch(@_);
+ return $c->$orig(@_);
}
-}
+};
-sub finalize {
+before finalize => sub {
my $c = shift;
-
+
# display all log messages
- if ( $c->config->{static}{debug} && scalar @{$c->_debug_msg} ) {
+ if ( $c->config->{'Plugin::Static::Simple'}->{debug} && scalar @{$c->_debug_msg} ) {
$c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
}
-
- return $c->NEXT::ACTUAL::finalize(@_);
-}
+};
-sub setup {
+before setup_finalize => sub {
my $c = shift;
-
- $c->NEXT::setup(@_);
-
- if ( Catalyst->VERSION le '5.33' ) {
- require File::Slurp;
+
+ $c->log->warn("Deprecated 'static' config key used, please use the key 'Plugin::Static::Simple' instead")
+ if exists $c->config->{static};
+
+ if (exists $c->config->{static}->{include_path}) {
+ $c->config->{'Plugin::Static::Simple'}->{include_path} = [
+ @{$c->config->{'Plugin::Static::Simple'}->{include_path} || []},
+ @{delete $c->config->{static}->{include_path} || []}
+ ];
}
- my $config = $c->config->{static} ||= {};
-
+ my $config
+ = $c->config->{'Plugin::Static::Simple'}
+ = $c->config->{'static'}
+ = Catalyst::Utils::merge_hashes(
+ $c->config->{'Plugin::Static::Simple'} || {},
+ $c->config->{static} || {}
+ );
+
$config->{dirs} ||= [];
$config->{include_path} ||= [ $c->config->{root} ];
$config->{mime_types} ||= {};
$config->{ignore_dirs} ||= [];
$config->{debug} ||= $c->debug;
$config->{no_logs} = 1 unless defined $config->{no_logs};
-
+ $config->{no_logs} = 0 if $config->{logging};
+
# load up a MIME::Types object, only loading types with
# at least 1 file extension
$config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
-
- # preload the type index hash so it's not built on the first request
- $config->{mime_types_obj}->create_type_index;
-}
+};
# Search through all included directories for the static file
# Based on Template Toolkit INCLUDE_PATH code
sub _locate_static_file {
my ( $c, $path, $in_static_dir ) = @_;
-
+
$path = File::Spec->catdir(
- File::Spec->no_upwards( File::Spec->splitdir( $path ) )
+ File::Spec->no_upwards( File::Spec->splitdir( $path ) )
);
-
- my $config = $c->config->{static};
+
+ my $config = $c->config->{'Plugin::Static::Simple'};
my @ipaths = @{ $config->{include_path} };
my $dpaths;
my $count = 64; # maximum number of directories to search
-
+
DIR_CHECK:
while ( @ipaths && --$count) {
my $dir = shift @ipaths || next DIR_CHECK;
-
+
if ( ref $dir eq 'CODE' ) {
eval { $dpaths = &$dir( $c ) };
if ($@) {
} else {
$dir =~ s/(\/|\\)$//xms;
if ( -d $dir && -f $dir . '/' . $path ) {
-
+
# Don't ignore any files in static dirs defined with 'dirs'
unless ( $in_static_dir ) {
# do we need to ignore the file?
next DIR_CHECK;
}
}
-
+
# do we need to ignore based on extension?
for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
}
}
}
-
+
$c->_debug_msg( 'Serving ' . $dir . '/' . $path )
if $config->{debug};
return $c->_static_file( $dir . '/' . $path );
}
}
}
-
+
return;
}
sub _serve_static {
my $c = shift;
-
- my $full_path = $c->_static_file;
+ my $config = $c->config->{'Plugin::Static::Simple'};
+
+ my $full_path = shift || $c->_static_file;
my $type = $c->_ext_to_type( $full_path );
my $stat = stat $full_path;
$c->res->headers->content_type( $type );
$c->res->headers->content_length( $stat->size );
$c->res->headers->last_modified( $stat->mtime );
+ # Tell Firefox & friends its OK to cache, even over SSL:
+ $c->res->headers->header('Cache-control' => 'public');
+ # Optionally, set a fixed expiry time:
+ if ($config->{expires}) {
+ $c->res->headers->expires(time() + $config->{expires});
+ }
- if ( Catalyst->VERSION le '5.33' ) {
- # old File::Slurp method
- my $content = File::Slurp::read_file( $full_path );
- $c->res->body( $content );
+ my $fh = IO::File->new( $full_path, 'r' );
+ if ( defined $fh ) {
+ binmode $fh;
+ $c->res->body( $fh );
}
else {
- # new method, pass an IO::File object to body
- my $fh = IO::File->new( $full_path, 'r' );
- if ( defined $fh ) {
- binmode $fh;
- $c->res->body( $fh );
- }
- else {
- Catalyst::Exception->throw(
- message => "Unable to open $full_path for reading" );
- }
+ Catalyst::Exception->throw(
+ message => "Unable to open $full_path for reading" );
}
-
+
return 1;
}
+sub serve_static_file {
+ my ( $c, $full_path ) = @_;
+
+ my $config = $c->config->{'Plugin::Static::Simple'};
+
+ if ( -e $full_path ) {
+ $c->_debug_msg( "Serving static file: $full_path" )
+ if $config->{debug};
+ }
+ else {
+ $c->_debug_msg( "404: file not found: $full_path" )
+ if $config->{debug};
+ $c->res->status( 404 );
+ $c->res->content_type( 'text/html' );
+ return;
+ }
+
+ $c->_serve_static( $full_path );
+}
+
# looks up the correct MIME type for the current file extension
sub _ext_to_type {
my ( $c, $full_path ) = @_;
-
- my $config = $c->config->{static};
-
+
+ my $config = $c->config->{'Plugin::Static::Simple'};
+
if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
my $ext = $1;
- my $type = $config->{mime_types}{$ext}
+ my $type = $config->{mime_types}{$ext}
|| $config->{mime_types_obj}->mimeTypeOf( $ext );
if ( $type ) {
$c->_debug_msg( "as $type" ) if $config->{debug};
sub _debug_msg {
my ( $c, $msg ) = @_;
-
+
if ( !defined $c->_static_debug_message ) {
$c->_static_debug_message( [] );
}
-
+
if ( $msg ) {
push @{ $c->_static_debug_message }, $msg;
}
-
+
return $c->_static_debug_message;
}
=head1 SYNOPSIS
- use Catalyst;
- MyApp->setup( qw/Static::Simple/ );
- # that's it; static content is automatically served by
- # Catalyst, though you can configure things or bypass
- # Catalyst entirely in a production environment
+ 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)
=head1 DESCRIPTION
Note that actions mapped to paths using periods (.) will still operate
properly.
+If the plugin can not find the file, the request is dispatched to your
+application instead. This means you are responsible for generating a
+C<404> error if your application can not process the request:
+
+ # 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. In a production
environment, you will probably want to use your webserver to deliver
static content; for an example see L<USING WITH APACHE>, below.
-=head1 DEFAULT BEHAVIOR
+=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
=head1 ADVANCED CONFIGURATION
Configuration is completely optional and is specified within
-C<MyApp-E<gt>config-E<gt>{static}>. If you use any of these options,
+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
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>{static}-E<gt>{no_logs}> to 0.
+C<MyApp-E<gt>config-E<gt>{Plugin::Static::Simple}-E<gt>{logging}> to 1.
=head2 Forcing directories into static mode
that should always be served in static mode. Regular expressions may be
specified using C<qr//>.
- MyApp->config->{static}->{dirs} = [
- 'static',
- qr/^(images|css)/,
- ];
+ MyApp->config(
+ 'Plugin::Static::Simple' => {
+ dirs => [
+ 'static',
+ qr/^(images|css)/,
+ ],
+ }
+ );
=head2 Including additional directories
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->{static}->{include_path} = [
- '/path/to/overlay',
- \&incpath_generator,
- MyApp->config->{root}
- ];
-
+ 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
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.
If you wish to define your own extensions to ignore, use the
C<ignore_extensions> option:
- MyApp->config->{static}->{ignore_extensions}
- = [ qw/html asp php/ ];
-
+ 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
directory paths to ignore. If using C<include_path>, the path will be
checked against every included path.
- MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
-
+ 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:
/dynamic/path/tmpl
/dynamic/path/css
/your/app/home/root/tmpl
- /your/app/home/root/css
+ /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->{static}->{mime_types} = {
- jpg => 'image/jpg',
- png => 'image/png',
- };
+ 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
Enable additional debugging information printed in the Catalyst log. This
is automatically enabled when running Catalyst in -Debug mode.
- MyApp->config->{static}->{debug} = 1;
-
+ 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. 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.
+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 /static>
+ <Location /myapp/static>
SetHandler default-handler
</Location>
application, and it will continue to function on a development server,
or using Catalyst's built-in server.
+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 C<catalyst.pl> script, with a main directory
+under which is a C<lib/> directory for module files and a C<root/>
+directory for templates and static files). 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>
+
+If you are running in a VirtualHost, you can just set the DocumentRoot
+location to the location of your root directory; see
+L<Catalyst::Engine::Apache2::MP20>.
+
+=head1 PUBLIC METHODS
+
+=head2 serve_static_file $file_path
+
+Will serve the file located in $file_path statically. This is useful when
+you need to autogenerate them if they don't exist, or they are 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);
+ }
+
=head1 INTERNAL EXTENDED METHODS
Static::Simple extends the following steps in the Catalyst process.
-=head2 prepare_action
+=head2 prepare_action
C<prepare_action> is used to first check if the request path is a static
file. If so, we skip all other C<prepare_action> steps to improve
C<setup> initializes all default values.
+=head1 DEPRECATIONS
+
+The old style of configuration using the C<'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 C<'Plugin::Static::Simple'>
+key.
+
+Be aware that if the C<'include_path'> key under C<'static'> exists at all, it
+will be merged with any content of the same key under
+C<'Plugin::Static::Simple'>. Be careful not to set this to a non-arrayref,
+therefore.
+
=head1 SEE ALSO
-L<Catalyst>, L<Catalyst::Plugin::Static>,
+L<Catalyst>, L<Catalyst::Plugin::Static>,
L<http://www.iana.org/assignments/media-types/>
=head1 AUTHOR
=head1 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>
+
=head1 THANKS
The authors of Catalyst::Plugin::Static:
=head1 COPYRIGHT
+Copyright (c) 2005 - 2011
+the Catalyst::Plugin::Static::Simple L</AUTHOR> and L</CONTRIBUTORS>
+as listed above.
+
+=head1 LICENSE
+
This program is free software, you can redistribute it and/or modify it under
the same terms as Perl itself.