[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 IO::File;
use MIME::Types;
use NEXT;

if ( Catalyst->VERSION le '5.33' ) {
    require File::Slurp;
}

our $VERSION = '0.11';

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

# 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.
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(@_);
}

# dispatch takes the file found during prepare_action and serves it
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(@_);
    }
}

# finalize serves up final header information
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(@_);
    
    $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 = $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;

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