[catagits/Catalyst-Runtime.git] / lib / Catalyst / Plugin / Static / Simple.pm

package Catalyst::Plugin::Static::Simple;

use strict;
use warnings;
use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
use File::stat;
use File::Spec::Functions qw/catdir no_upwards splitdir/;
use IO::File;
use MIME::Types;
use NEXT;

our $VERSION = '0.11';

__PACKAGE__->mk_classdata( qw/_static_mime_types/ );
__PACKAGE__->mk_accessors( qw/_static_file
                              _static_debug_message/ );

sub prepare_action {
    my $c = shift;
    my $path = $c->req->path;

    # is the URI in a static-defined path?
    foreach my $dir ( @{ $c->config->{static}->{dirs} } ) {
        my $re = ( $dir =~ /^qr\//xms ) ? eval $dir : qr/^${dir}/;
        if ($@) {
            $c->error( "Error compiling static dir regex '$dir': $@" );
        }
        if ( $path =~ $re ) {
            if ( $c->_locate_static_file ) {
                $c->_debug_msg( 'from static directory' )
                    if ( $c->config->{static}->{debug} );
                return;
            } else {
                $c->_debug_msg( "404: file not found: $path" )
                    if ( $c->config->{static}->{debug} );
                $c->res->status( 404 );
                return;
            }
        }
    }
    
    # Does the path have an extension?
    if ( $path =~ /.*\.(\S{1,})$/xms ) {
        # and does it exist?
        return if ( $c->_locate_static_file );
    }
    
    return $c->NEXT::ACTUAL::prepare_action(@_);
}

sub dispatch {
    my $c = shift;
    
    return if ( $c->res->status != 200 );
    
    if ( $c->_static_file ) {
        if ( $c->config->{static}->{no_logs} && $c->log->can('abort') ) {
           $c->log->abort( 1 );
        }
        return $c->_serve_static;
    }
    else {
        return $c->NEXT::ACTUAL::dispatch(@_);
    }
}

sub finalize {
    my $c = shift;
    
    # display all log messages
    if ( $c->config->{static}->{debug} && scalar @{$c->_debug_msg} ) {
        $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
    }
    
    if ( $c->res->status =~ /^(1\d\d|[23]04)$/xms ) {
        $c->res->headers->remove_content_headers;
        return $c->finalize_headers;
    }
    
    return $c->NEXT::ACTUAL::finalize(@_);
}

sub setup {
    my $c = shift;
    
    $c->NEXT::setup(@_);
    
    if ( Catalyst->VERSION le '5.33' ) {
        require File::Slurp;
    }
    
    $c->config->{static}->{dirs} ||= [];
    $c->config->{static}->{include_path} ||= [ $c->config->{root} ];
    $c->config->{static}->{mime_types} ||= {};
    $c->config->{static}->{ignore_extensions} ||= [ qw/tt tt2 html xhtml/ ];
    $c->config->{static}->{ignore_dirs} ||= [];
    $c->config->{static}->{debug} ||= $c->debug;
    if ( ! defined $c->config->{static}->{no_logs} ) {
        $c->config->{static}->{no_logs} = 1;
    }    
    
    # load up a MIME::Types object, only loading types with
    # at least 1 file extension
    $c->_static_mime_types( MIME::Types->new( only_complete => 1 ) );
    
    # preload the type index hash so it's not built on the first request
    $c->_static_mime_types->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 = shift;
    
    my $path = catdir(no_upwards(splitdir( $c->req->path )));
    
    my @ipaths = @{ $c->config->{static}->{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 ($@) {
                $c->log->error( 'Static::Simple: include_path error: ' . $@ );
            } else {
                unshift @ipaths, @$dpaths;
                next DIR_CHECK;
            }
        } else {
            $dir =~ s/\/$//xms;
            if ( -d $dir && -f $dir . '/' . $path ) {
                
                # do we need to ignore the file?
                for my $ignore ( @{ $c->config->{static}->{ignore_dirs} } ) {
                    $ignore =~ s{/$}{};
                    if ( $path =~ /^$ignore\// ) {
                        $c->_debug_msg( "Ignoring directory `$ignore`" )
                            if ( $c->config->{static}->{debug} );
                        next DIR_CHECK;
                    }
                }
                
                # do we need to ignore based on extension?
                for my $ignore_ext 
                    ( @{ $c->config->{static}->{ignore_extensions} } ) {
                        if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
                            $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
                                if ( $c->config->{static}->{debug} );
                            next DIR_CHECK;
                        }
                }
                
                $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
                    if ( $c->config->{static}->{debug} );
                return $c->_static_file( $dir . '/' . $path );
            }
        }
    }
    
    return;
}

sub _serve_static {
    my $c = shift;
    
    my $path = $c->req->path;    
    my $type = $c->_ext_to_type;
    
    my $full_path = $c->_static_file;
    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 );

    if ( Catalyst->VERSION le '5.33' ) {
        # old File::Slurp method
        my $content = File::Slurp::read_file( $full_path );
        $c->res->body( $content );
    }
    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" );
        }
    }
    
    return 1;
}

# looks up the correct MIME type for the current file extension
sub _ext_to_type {
    my $c = shift;
    my $path = $c->req->path;
    
    if ( $path =~ /.*\.(\S{1,})$/xms ) {
        my $ext = $1;
        my $user_types = $c->config->{static}->{mime_types};
        my $type = $user_types->{$ext} 
                || $c->_static_mime_types->mimeTypeOf( $ext );
        if ( $type ) {
            $c->_debug_msg( "as $type" )
                if ( $c->config->{static}->{debug} );            
            return ( ref $type ) ? $type->type : $type;
        }
        else {
            $c->_debug_msg( "as text/plain (unknown extension $ext)" )
                if ( $c->config->{static}->{debug} );
            return 'text/plain';
        }
    }
    else {
        $c->_debug_msg( 'as text/plain (no extension)' )
            if ( $c->config->{static}->{debug} );
        return 'text/plain';
    }
}

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;
}

1;
__END__

=head1 NAME

Catalyst::Plugin::Static::Simple - Make serving static pages painless.

=head1 SYNOPSIS

    use Catalyst;
    MyApp->setup( qw/Static::Simple/ );

=head1 DESCRIPTION

The Static::Simple plugin is designed to make serving static content in your
application during development quick and easy, without requiring a single
line of code from you.

It will detect static files used in your application by looking for file
extensions in the URI.  By default, you can simply load this plugin and it
will immediately begin serving your static files with the correct MIME type.
The light-weight MIME::Types module is used to map file extensions to
IANA-registered MIME types.

Note that actions mapped to paths using periods (.) will still operate
properly.

You may further tweak the operation by adding configuration options, described
below.

=head1 ADVANCED CONFIGURATION

Configuration is completely optional and is specified within 
MyApp->config->{static}.  If you use any of these options, the module will
probably feel less "simple" to you!

=head2 Aborting request logging

Since Catalyst 5.50, there has been added support for dropping logging for a 
request. This is enabled by default for static files, as static requests tend
to clutter the log output.  However, if you want logging of static requests, 
you can enable it by setting MyApp->config->{static}->{no_logs} to 0.

=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 qr//.

    MyApp->config->{static}->{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 include_path.  You should use
MyApp->config->{root} to add it.

    MyApp->config->{static}->{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).

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 tt, tt2, html, and xhtml will be ignored by Static::Simple
in the interest of security.  If you wish to define your own extensions to
ignore, use the ignore_extensions option:

    MyApp->config->{static}->{ignore_extensions} = [ qw/tt tt2 html xhtml/ ];
    
=head2 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->{static}->{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    

=head2 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. 

    MyApp->config->{static}->{mime_types} = {
        jpg => 'image/jpg',
        png => 'image/png',
    };

=head2 Bypassing other plugins

This plugin checks for a static file in the prepare_action stage.  If the
request is for a static file, it will bypass all remaining prepare_action
steps.  This means that by placing Static::Simple before all other plugins,
they will not execute when a static file is found.  This can be helpful by
skipping session cookie checks for example.  Or, if you want some plugins
to run even on static files, list them before Static::Simple.

Currently, work done by plugins in any other prepare method will execute
normally.

=head2 Debugging information

Enable additional debugging information printed in the Catalyst log.  This
is automatically enabled when running Catalyst in -Debug mode.

    MyApp->config->{static}->{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.

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

=head1 INTERNAL EXTENDED METHODS

Static::Simple extends the following steps in the Catalyst process.

=head2 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.

=head2 dispatch

dispatch takes the file found during prepare_action and writes it to the
output.

=head2 finalize

finalize serves up final header information and displays any log messages.

=head2 setup

setup initializes all default values.

=head1 SEE ALSO

L<Catalyst>, L<Catalyst::Plugin::Static>, 
L<http://www.iana.org/assignments/media-types/>

=head1 AUTHOR

Andy Grundman, <andy@hybridized.org>

=head1 CONTRIBUTORS

Marcus Ramberg, <mramberg@cpan.org>

=head1 THANKS

The authors of Catalyst::Plugin::Static:

    Sebastian Riedel
    Christian Hansen
    Marcus Ramberg

For the include_path code from Template Toolkit:

    Andy Wardley

=head1 COPYRIGHT

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

=cut
Commit	Line	Data
a9b78939	1	package Catalyst::Plugin::Static::Simple;
	2
	3	use strict;
	4	use warnings;
	5	use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
	6	use File::stat;
df755a7a	7	use File::Spec::Functions qw/catdir no_upwards splitdir/;
04e5fb83	8	use IO::File;
a9b78939	9	use MIME::Types;
	10	use NEXT;
	11
04e5fb83	12	our $VERSION = '0.11';
a9b78939	13
	14	__PACKAGE__->mk_classdata( qw/_static_mime_types/ );
	15	__PACKAGE__->mk_accessors( qw/_static_file
	16	_static_debug_message/ );
	17
a9b78939	18	sub prepare_action {
	19	my $c = shift;
	20	my $path = $c->req->path;
	21
	22	# is the URI in a static-defined path?
	23	foreach my $dir ( @{ $c->config->{static}->{dirs} } ) {
	24	my $re = ( $dir =~ /^qr\//xms ) ? eval $dir : qr/^${dir}/;
	25	if ($@) {
	26	$c->error( "Error compiling static dir regex '$dir': $@" );
	27	}
	28	if ( $path =~ $re ) {
	29	if ( $c->_locate_static_file ) {
	30	$c->_debug_msg( 'from static directory' )
	31	if ( $c->config->{static}->{debug} );
	32	return;
	33	} else {
	34	$c->_debug_msg( "404: file not found: $path" )
	35	if ( $c->config->{static}->{debug} );
	36	$c->res->status( 404 );
	37	return;
	38	}
	39	}
	40	}
	41
	42	# Does the path have an extension?
	43	if ( $path =~ /.*\.(\S{1,})$/xms ) {
	44	# and does it exist?
	45	return if ( $c->_locate_static_file );
	46	}
	47
	48	return $c->NEXT::ACTUAL::prepare_action(@_);
	49	}
	50
a9b78939	51	sub dispatch {
	52	my $c = shift;
	53
	54	return if ( $c->res->status != 200 );
	55
	56	if ( $c->_static_file ) {
	57	if ( $c->config->{static}->{no_logs} && $c->log->can('abort') ) {
	58	$c->log->abort( 1 );
	59	}
	60	return $c->_serve_static;
	61	}
	62	else {
	63	return $c->NEXT::ACTUAL::dispatch(@_);
	64	}
	65	}
	66
a9b78939	67	sub finalize {
	68	my $c = shift;
	69
	70	# display all log messages
	71	if ( $c->config->{static}->{debug} && scalar @{$c->_debug_msg} ) {
	72	$c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
	73	}
	74
	75	if ( $c->res->status =~ /^(1\d\d\|[23]04)$/xms ) {
	76	$c->res->headers->remove_content_headers;
	77	return $c->finalize_headers;
	78	}
	79
	80	return $c->NEXT::ACTUAL::finalize(@_);
	81	}
	82
	83	sub setup {
	84	my $c = shift;
	85
	86	$c->NEXT::setup(@_);
	87
5c19e800	88	if ( Catalyst->VERSION le '5.33' ) {
	89	require File::Slurp;
	90	}
	91
a9b78939	92	$c->config->{static}->{dirs} \|\|= [];
	93	$c->config->{static}->{include_path} \|\|= [ $c->config->{root} ];
	94	$c->config->{static}->{mime_types} \|\|= {};
	95	$c->config->{static}->{ignore_extensions} \|\|= [ qw/tt tt2 html xhtml/ ];
	96	$c->config->{static}->{ignore_dirs} \|\|= [];
	97	$c->config->{static}->{debug} \|\|= $c->debug;
	98	if ( ! defined $c->config->{static}->{no_logs} ) {
	99	$c->config->{static}->{no_logs} = 1;
5c19e800	100	}
a9b78939	101
	102	# load up a MIME::Types object, only loading types with
	103	# at least 1 file extension
	104	$c->_static_mime_types( MIME::Types->new( only_complete => 1 ) );
	105
	106	# preload the type index hash so it's not built on the first request
	107	$c->_static_mime_types->create_type_index;
	108	}
	109
	110	# Search through all included directories for the static file
	111	# Based on Template Toolkit INCLUDE_PATH code
	112	sub _locate_static_file {
	113	my $c = shift;
	114
df755a7a	115	my $path = catdir(no_upwards(splitdir( $c->req->path )));
a9b78939	116
	117	my @ipaths = @{ $c->config->{static}->{include_path} };
	118	my $dpaths;
	119	my $count = 64; # maximum number of directories to search
	120
	121	DIR_CHECK:
	122	while ( @ipaths && --$count) {
	123	my $dir = shift @ipaths \|\| next DIR_CHECK;
	124
	125	if ( ref $dir eq 'CODE' ) {
	126	eval { $dpaths = &$dir( $c ) };
	127	if ($@) {
	128	$c->log->error( 'Static::Simple: include_path error: ' . $@ );
	129	} else {
	130	unshift @ipaths, @$dpaths;
	131	next DIR_CHECK;
	132	}
	133	} else {
	134	$dir =~ s/\/$//xms;
	135	if ( -d $dir && -f $dir . '/' . $path ) {
	136
	137	# do we need to ignore the file?
	138	for my $ignore ( @{ $c->config->{static}->{ignore_dirs} } ) {
	139	$ignore =~ s{/$}{};
	140	if ( $path =~ /^$ignore\// ) {
	141	$c->_debug_msg( "Ignoring directory `$ignore`" )
	142	if ( $c->config->{static}->{debug} );
	143	next DIR_CHECK;
	144	}
	145	}
	146
	147	# do we need to ignore based on extension?
	148	for my $ignore_ext
	149	( @{ $c->config->{static}->{ignore_extensions} } ) {
	150	if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
	151	$c->_debug_msg( "Ignoring extension `$ignore_ext`" )
	152	if ( $c->config->{static}->{debug} );
	153	next DIR_CHECK;
	154	}
	155	}
	156
	157	$c->_debug_msg( 'Serving ' . $dir . '/' . $path )
	158	if ( $c->config->{static}->{debug} );
	159	return $c->_static_file( $dir . '/' . $path );
	160	}
	161	}
	162	}
	163
	164	return;
	165	}
	166
	167	sub _serve_static {
	168	my $c = shift;
	169
	170	my $path = $c->req->path;
	171	my $type = $c->_ext_to_type;
	172
	173	my $full_path = $c->_static_file;
	174	my $stat = stat $full_path;
	175
a9b78939	176	$c->res->headers->content_type( $type );
	177	$c->res->headers->content_length( $stat->size );
	178	$c->res->headers->last_modified( $stat->mtime );
	179
	180	if ( Catalyst->VERSION le '5.33' ) {
	181	# old File::Slurp method
	182	my $content = File::Slurp::read_file( $full_path );
04e5fb83	183	$c->res->body( $content );
a9b78939	184	}
a9b78939	185	else {
04e5fb83	186	# new method, pass an IO::File object to body
	187	my $fh = IO::File->new( $full_path, 'r' );
	188	if ( defined $fh ) {
5c19e800	189	binmode $fh;
04e5fb83	190	$c->res->body( $fh );
	191	}
	192	else {
	193	Catalyst::Exception->throw(
a9b78939	194	message => "Unable to open $full_path for reading" );
a9b78939	195	}
a9b78939	196	}
	197
	198	return 1;
	199	}
	200
	201	# looks up the correct MIME type for the current file extension
	202	sub _ext_to_type {
	203	my $c = shift;
	204	my $path = $c->req->path;
	205
	206	if ( $path =~ /.*\.(\S{1,})$/xms ) {
	207	my $ext = $1;
	208	my $user_types = $c->config->{static}->{mime_types};
	209	my $type = $user_types->{$ext}
	210	\|\| $c->_static_mime_types->mimeTypeOf( $ext );
	211	if ( $type ) {
	212	$c->_debug_msg( "as $type" )
	213	if ( $c->config->{static}->{debug} );
04e5fb83	214	return ( ref $type ) ? $type->type : $type;
a9b78939	215	}
	216	else {
	217	$c->_debug_msg( "as text/plain (unknown extension $ext)" )
	218	if ( $c->config->{static}->{debug} );
	219	return 'text/plain';
	220	}
	221	}
	222	else {
	223	$c->_debug_msg( 'as text/plain (no extension)' )
	224	if ( $c->config->{static}->{debug} );
	225	return 'text/plain';
	226	}
	227	}
	228
	229	sub _debug_msg {
	230	my ( $c, $msg ) = @_;
	231
	232	if ( !defined $c->_static_debug_message ) {
	233	$c->_static_debug_message( [] );
	234	}
	235
	236	if ( $msg ) {
	237	push @{ $c->_static_debug_message }, $msg;
	238	}
	239
	240	return $c->_static_debug_message;
	241	}
	242
	243	1;
	244	__END__
	245
	246	=head1 NAME
	247
	248	Catalyst::Plugin::Static::Simple - Make serving static pages painless.
	249
	250	=head1 SYNOPSIS
	251
	252	use Catalyst;
	253	MyApp->setup( qw/Static::Simple/ );
	254
	255	=head1 DESCRIPTION
	256
	257	The Static::Simple plugin is designed to make serving static content in your
	258	application during development quick and easy, without requiring a single
	259	line of code from you.
	260
	261	It will detect static files used in your application by looking for file
	262	extensions in the URI. By default, you can simply load this plugin and it
	263	will immediately begin serving your static files with the correct MIME type.
	264	The light-weight MIME::Types module is used to map file extensions to
	265	IANA-registered MIME types.
	266
	267	Note that actions mapped to paths using periods (.) will still operate
	268	properly.
	269
	270	You may further tweak the operation by adding configuration options, described
	271	below.
	272
	273	=head1 ADVANCED CONFIGURATION
	274
	275	Configuration is completely optional and is specified within
	276	MyApp->config->{static}. If you use any of these options, the module will
	277	probably feel less "simple" to you!
	278
279	=head2 Aborting request logging
280
281	Since Catalyst 5.50, there has been added support for dropping logging for a
282	request. This is enabled by default for static files, as static requests tend
283	to clutter the log output. However, if you want logging of static requests,
284	you can enable it by setting MyApp->config->{static}->{no_logs} to 0.
285
286	=head2 Forcing directories into static mode
287
288	Define a list of top-level directories beneath your 'root' directory that
289	should always be served in static mode. Regular expressions may be
290	specified using qr//.
291
292	MyApp->config->{static}->{dirs} = [
293	'static',
294	qr/^(images\|css)/,
295	];
296
297	=head2 Including additional directories
298
299	You may specify a list of directories in which to search for your static
300	files. The directories will be searched in order and will return the first
301	file found. Note that your root directory is B<not> automatically added to
302	the search path when you specify an include_path. You should use
303	MyApp->config->{root} to add it.
304
305	MyApp->config->{static}->{include_path} = [
306	'/path/to/overlay',
307	\&incpath_generator,
308	MyApp->config->{root}
309	];
310
311	With the above setting, a request for the file /images/logo.jpg will search
312	for the following files, returning the first one found:
313
314	/path/to/overlay/images/logo.jpg
315	/dynamic/path/images/logo.jpg
316	/your/app/home/root/images/logo.jpg
317
318	The include path can contain a subroutine reference to dynamically return a
319	list of available directories. This method will receive the $c object as a
320	parameter and should return a reference to a list of directories. Errors can
321	be reported using die(). This method will be called every time a file is
322	requested that appears to be a static file (i.e. it has an extension).
323
324	For example:
325
326	sub incpath_generator {
327	my $c = shift;
328
329	if ( $c->session->{customer_dir} ) {
330	return [ $c->session->{customer_dir} ];
331	} else {
332	die "No customer dir defined.";
333	}
334	}
335
336	=head2 Ignoring certain types of files
337
338	There are some file types you may not wish to serve as static files. Most
339	important in this category are your raw template files. By default, files
340	with the extensions tt, tt2, html, and xhtml will be ignored by Static::Simple
341	in the interest of security. If you wish to define your own extensions to
342	ignore, use the ignore_extensions option:
343
344	MyApp->config->{static}->{ignore_extensions} = [ qw/tt tt2 html xhtml/ ];
345
346	=head2 Ignoring entire directories
347
348	To prevent an entire directory from being served statically, you can use the
349	ignore_dirs option. This option contains a list of relative directory paths
350	to ignore. If using include_path, the path will be checked against every
351	included path.
352
353	MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
354
355	For example, if combined with the above include_path setting, this
356	ignore_dirs value will ignore the following directories if they exist:
357
358	/path/to/overlay/tmpl
359	/path/to/overlay/css
360	/dynamic/path/tmpl
361	/dynamic/path/css
362	/your/app/home/root/tmpl
363	/your/app/home/root/css
364
365	=head2 Custom MIME types
366
367	To override or add to the default MIME types set by the MIME::Types module,
368	you may enter your own extension to MIME type mapping.
369
370	MyApp->config->{static}->{mime_types} = {
371	jpg => 'image/jpg',
372	png => 'image/png',
373	};
374
375	=head2 Bypassing other plugins
376
377	This plugin checks for a static file in the prepare_action stage. If the
378	request is for a static file, it will bypass all remaining prepare_action
379	steps. This means that by placing Static::Simple before all other plugins,
380	they will not execute when a static file is found. This can be helpful by
381	skipping session cookie checks for example. Or, if you want some plugins
382	to run even on static files, list them before Static::Simple.
383
384	Currently, work done by plugins in any other prepare method will execute
385	normally.
386
387	=head2 Debugging information
388
389	Enable additional debugging information printed in the Catalyst log. This
390	is automatically enabled when running Catalyst in -Debug mode.
391
392	MyApp->config->{static}->{debug} = 1;
393
394	=head1 USING WITH APACHE
395
396	While Static::Simple will work just fine serving files through Catalyst in
397	mod_perl, for increased performance, you may wish to have Apache handle the
398	serving of your static files. To do this, simply use a dedicated directory
399	for your static files and configure an Apache Location block for that
400	directory. This approach is recommended for production installations.
401
402	<Location /static>
403	SetHandler default-handler
404	</Location>
405
5c19e800	406	=head1 INTERNAL EXTENDED METHODS
	407
	408	Static::Simple extends the following steps in the Catalyst process.
	409
	410	=head2 prepare_action
	411
	412	prepare_action is used to first check if the request path is a static file.
	413	If so, we skip all other prepare_action steps to improve performance.
	414
	415	=head2 dispatch
	416
	417	dispatch takes the file found during prepare_action and writes it to the
	418	output.
	419
	420	=head2 finalize
	421
	422	finalize serves up final header information and displays any log messages.
	423
	424	=head2 setup
	425
	426	setup initializes all default values.
	427
a9b78939	428	=head1 SEE ALSO
	429
	430	L<Catalyst>, L<Catalyst::Plugin::Static>,
	431	L<http://www.iana.org/assignments/media-types/>
	432
	433	=head1 AUTHOR
	434
	435	Andy Grundman, <andy@hybridized.org>
	436
	437	=head1 CONTRIBUTORS
	438
	439	Marcus Ramberg, <mramberg@cpan.org>
	440
	441	=head1 THANKS
	442
	443	The authors of Catalyst::Plugin::Static:
	444
	445	Sebastian Riedel
	446	Christian Hansen
	447	Marcus Ramberg
	448
	449	For the include_path code from Template Toolkit:
	450
	451	Andy Wardley
	452
	453	=head1 COPYRIGHT
	454
	455	This program is free software, you can redistribute it and/or modify it under
	456	the same terms as Perl itself.
	457
	458	=cut